? CinematicCamera 插件 — 完整自述文件
一个适用于 Minecraft(Paper/Spigot)的插件,用于创建带有旋转、速度区域、关键帧效果等功能的平滑电影式摄像机路径。
目录
- 快速开始
- 工作原理 — 核心架构
- 命令参考
- 移除关键帧 (removekeyframe)
- 关键帧类型 — 完整参考
- 速度区域
- 自动播放触发器
- 播放系统 — 代码中的实现方式
- 路径插值 — Catmull-Rom 样条曲线
- 摄像机旋转插值
- 状态管理映射
- 完整工作流程示例
- Tab 补全
快速开始
- 运行
/cinematicwand 获取法杖物品(烈焰棒)。
- 走到某个位置并左键点击以添加航点。摄像机的偏航角(水平旋转)和俯仰角(垂直旋转)会随每个航点一起保存。
- 在所需路径上至少添加 2 个或更多航点。
- 运行
/cinematic save mypath normal 将其保存为命名路径。
- 运行
/cinematic play mypath 观看回放。
工作原理 — 核心架构
该插件是一个名为 CinematicCamera 的单类,它继承自 JavaPlugin 并实现了 Listener 接口。所有状态均存储在内存中的 HashMap/HashSet 字段中(重启之间不会持久化到磁盘)。
核心状态映射
| 字段 |
类型 |
用途 |
paths |
Map<String, CinematicPath> |
所有已保存的电影式路径,按名称索引 |
editors |
Map<UUID, PathEditor> |
每位玩家的活动法杖会话 — 保存其未保存的航点 |
playingCinematic |
Set<UUID> |
当前正在观看电影式路径的玩家 |
originalGameModes |
Map<UUID, GameMode> |
存储玩家在电影式路径开始前的游戏模式,以便后续恢复 |
activeAnimations |
Map<UUID, BukkitTask> |
每位玩家正在运行的 BukkitRunnable 任务 — 用于在停止时取消任务 |
savedLocations |
Map<UUID, Location> |
电影式路径开始前玩家的位置 — 结束时传送回此处 |
savedFlying |
Map<UUID, Boolean> |
玩家在电影式路径开始前是否处于飞行状态 — 结束时恢复 |
awaitingClick |
Set<UUID> |
当前暂停在 PAUSE_CLICK 关键帧上的玩家,等待任何点击操作 |
命令参考
/cinematicwand
给予你烈焰棒法杖物品。
- 左键点击(空气或方块):将当前位置 + 旋转角度添加为航点
- 右键点击:显示当前航点数量及如何保存
- Shift + 右键点击:清除所有当前未保存的航点
/cinematic save <name> <speed>
将当前的航点保存为命名路径。
速度值:
| 输入 |
倍率 |
slow 或 cinematic |
0.3x |
normal 或 medium |
1.0x |
fast |
2.0x |
veryfast 或 rapid |
3.5x |
0.1 – 5.0 |
自定义 |
/cinematic play <name>
开始播放该电影镜头。将您置于旁观者模式,应用隐身效果,传送至第 0 个路标点,并开始动画循环。
/cinematic stop
立即停止电影镜头,取消任务,移除所有效果,并将您传送回保存的位置。
/cinematic list
列出所有已保存的路径,包括其路标点数量、速度、关键帧数量、速度区域数量和自动播放状态。
/cinematic delete <name>
完全删除一条已保存的路径。
/cinematic setspeed <name> <speed>
更改现有路径的基础速度倍率。
/cinematic toggle <name>
切换路径的自动播放触发器开关。开启后,当玩家走到第一个路标点附近 1.5 格范围内时,会自动开始播放电影镜头。
/cinematic clear
清除您当前未保存的法杖路标点(与 Shift+右键点击相同)。
/cinematic settitle <name> <title> [| subtitle]
设置电影镜头开始时显示的标题。
- 使用
| 分隔标题和副标题:/cinematic settitle mypath Welcome | Enjoy the view
/cinematic addkeyframe <name> <waypointIndex> <type> [args...]
添加一个效果关键帧,当相机到达指定的路标点时触发。
/cinematic listkeyframes <name>
列出路径上的所有关键帧,包括其索引、目标点、类型和文本预览。
/cinematic removekeyframe <name> <index>
通过列表索引删除某个关键帧(索引可在 /cinematic listkeyframes 命令的输出中查看)。
/cinematic addzone <name> <startWP> <endWP> <speed>
在两个目标点索引之间添加速度区域。覆盖该段的基础速度。
/cinematic listzones <name>
列出路径上的所有速度区域。
/cinematic removezone <name> <index>
通过列表索引删除某个速度区域。
移除关键帧
这是一个两步操作:
第 1 步 — 查找关键帧索引:
/cinematic listkeyframes spawn
此命令将输出类似以下内容:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[0] wp#2 text_title → Welcome
[1] wp#4 fade_black
[2] wp#6 sound → ENTITY_WITHER...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
第 2 步 — 根据该索引号进行移除:
/cinematic removekeyframe spawn 1
这将移除索引 [1] 处的 fadeblack。
⚠️ 索引是位置性的(0, 1, 2...),移除后索引会发生变化。如果计划继续移除其他关键帧,请在每次移除后重新运行 listkeyframes。
关键帧类型 — 完整参考
使用以下任一类型并通过 /cinematic addkeyframe <path> <waypointIndex> <type> [args] 添加
title
在屏幕上显示标题。
/cinematic addkeyframe mypath 0 title 10 60 20 Welcome to the Tour | Enjoy the view
参数:<淡入持续时间(刻)> <停留持续时间(刻)> <淡出持续时间(刻)> <标题文本> [| 副标题]
代码中的工作原理: 使用 Adventure API Title.title() 调用 player.showTitle(),传入 Title.Times,构建加粗白色标题文本和灰色副标题文本。
actionbar
在操作栏(快捷栏上方)显示文本。
/cinematic addkeyframe mypath 2 actionbar Look to your left!
工作原理: 使用带有黄色调的文本调用 player.sendActionBar()。
chat
向玩家的聊天窗口发送一条以 ✦ 为前缀的消息。
/cinematic addkeyframe mypath 3 chat This is where the story began.
pause
暂停摄像机移动指定的秒数。
/cinematic addkeyframe mypath 4 pause 3
参数:<seconds>
工作原理: 设置 paused = true 和 pauseTicksLeft = seconds * 20。BukkitRunnable 会在计数器归零之前的每一刻提前返回。
click
无限期暂停摄像机,直到玩家点击(任何鼠标按键)。
/cinematic addkeyframe mypath 5 click
工作原理: 将玩家添加到 awaitingClick 集合中并显示操作栏提示。PlayerInteractEvent 处理器会在任何点击时将玩家从该集合中移除。动画循环会检查 awaittingClick.contains(uuid) 并在清除之前提前返回。
sound
在玩家位置播放声音。
/cinematic addkeyframe mypath 6 sound ENTITY_WITHER_SPAWN 1.0 0.8
参数:<SOUND_NAME> [volume] [pitch]
工作原理: 使用 player.playSound()。通过 Registry.SOUNDS.get(NamespacedKey.minecraft(...)) 查找声音名称。如果无效则回退到 BLOCK_NOTE_BLOCK_PLING。
particle
在摄像机周围生成烟花粒子爆发效果。
/cinematic addkeyframe mypath 7 particle
工作原理: 调用 world.spawnParticle(Particle.FIREWORK, location, 40, 1, 1, 1, 0.05)。
shake
通过在微小的随机偏移量之间快速传送摄像机来产生震动效果。
/cinematic addkeyframe mypath 8 shake
工作原理: 安排 10 次 runTaskLater 调用(间隔 1 刻),每次为玩家的位置添加一个小的随机偏移量(每个轴上 -0.1 到 +0.1)并将其传送至该位置。
fadeblack
施加失明效果以使屏幕渐变为黑色。
/cinematic addkeyframe mypath 9 fadeblack 2
参数:<duration seconds>(默认值:2)
工作原理: 施加持续时间为 duration * 20 刻的 PotionEffectType.BLINDNESS 药水效果。
fadewhite
施加发光效果以创建白色闪光/渐变。
/cinematic addkeyframe mypath 10 fadewhite 2
参数:<duration seconds>(默认值:2)
工作原理: 施加持续时间为 duration * 20 刻的 PotionEffectType.GLOWING 药水效果。
lightning
在摄像机位置击打一道仅具视觉效果的闪电。
/cinematic addkeyframe mypath 11 lightning
工作原理: 调用 world.strikeLightningEffect(location) —— 这是仅视觉效果版本(无火焰,无伤害)。
explosion
在摄像机位置创建视觉爆炸效果。
/cinematic addkeyframe mypath 12 explosion
工作原理: 调用 world.createExplosion(location, 0, false, false) —— 力量值为 0 意味着不破坏方块,不引发火灾。
time
立即设置世界时间。
/cinematic addkeyframe mypath 3 time 6000
参数:<0–24000>(0 = 日出,6000 = 正午,12000 = 日落,18000 = 午夜)
工作原理: 调用 world.setTime((long) kf.duration)。
weather
改变世界的天气。
/cinematic addkeyframe mypath 5 weather rain
/cinematic addkeyframe mypath 8 weather clear
/cinematic addkeyframe mypath 10 weather thunder
参数:clear | rain | thunder
工作原理:
clear → world.setStorm(false)
rain → world.setStorm(true)
thunder → world.setStorm(true) + world.setThundering(true)
速度区域 (Speed Zones)
速度区域覆盖特定航点范围内的基础路径速度,让你可以在戏剧性时刻放慢速度,或在无聊段落快进。
/cinematic addzone mypath 0 3 0.3
这会使航点 0–3 以 0.3 倍速播放(非常慢/电影感)。
/cinematic addzone mypath 5 9 3.0
这会使航点 5–9 以 3 倍速播放。
代码中的工作原理: 在 generateSmoothPath() 期间,每个片段 i 检查 speedZones 以查看 i >= zone.startWaypoint && i < zone.endWaypoint。如果找到匹配项,则 pointsInSegment = basePoints / segmentSpeed。更高的速度倍数意味着航点之间的插值点数更少,因此遍历速度更快。每个 CameraFrame 还存储 speedMultiplier,动画循环使用它来跳过帧(index += (1 + skip),其中 skip = speedMultiplier - 1)。
自动播放触发器
当路径启用自动播放时(保存时默认开启),任何走到路径第一个航点 1.5 格 以内的玩家都将自动开始播放电影。
- 切换状态:
/cinematic toggle mypath
- 在
PlayerMoveEvent 中检查 —— 仅在玩家尚未处于电影播放状态时才触发
播放系统 —— 代码工作原理
当调用 playCinematic(player, path) 时:
- 玩家被添加到
playingCinematic,其游戏模式/位置/飞行状态被保存。
- 他们被设置为
SPECTATOR(旁观者)模式并具有无限期的 INVISIBILITY(隐身)。
- 他们被传送到
waypoints.get(0)。
- 运行
path.generateSmoothPath() 并生成 List<CameraFrame>。
- 构建一个
Map<Integer, Keyframe>,将每个关键帧映射到其在平滑路径中的索引(waypointIndex * basePointsPerSegment)。
- 调度一个
BukkitRunnable 每刻(1/20 秒)运行一次。
动画循环内部(每刻):
tick fires
→ if player offline: endCinematic, cancel
→ if timed pause active: decrement counter, return
→ if awaiting click: return
→ if index >= smoothPath.size(): endCinematic, send message, cancel
→ check kfMap for keyframe at current index, apply it
→ if PAUSE_TIMED: set paused=true, set counter, increment index, return
→ if PAUSE_CLICK: add to awaitingClick, increment index, return
→ teleport player to smoothPath.get(index).location (position + yaw/pitch)
→ spawn ambient END_ROD particle every 10 ticks
→ advance index (by 1, or more if speed zone skip > 1)
endCinematic 方法:
- 将玩家从所有状态映射中移除
- 取消 BukkitTask
- 移除药水效果(隐身、失明、发光)
- 清除标题
- 恢复原始游戏模式
- 将玩家传送回其保存的位置
- 恢复飞行状态
路径插值 — Catmull-Rom 样条
原始航点间距较远。为了实现平滑的摄像机移动,插件使用 Catmull-Rom 样条 在它们之间进行插值——这是一种穿过每个控制点的曲线(与贝塞尔曲线不同,后者会被拉向控制点)。
对于从航点 i 到 i+1 的每个线段,使用 4 个控制点:
p0 = 前一个航点(如果在起点则为 p1)
p1 = 当前航点
p2 = 下一个航点
p3 = 下下个航点(如果在终点则为 p2)
按轴(x, y, z)应用的公式为:
x(t) = 0.5 * (
2*p1 +
(-p0 + p2) * t +
(2*p0 - 5*p1 + 4*p2 - p3) * t² +
(-p0 + 3*p1 - 3*p2 + p3) * t³
)
其中 t 在线段范围内从 0.0 变化到 1.0。每个线段的点数计算如下:
basePointsPerSegment = max(10, 60 / speed)
因此在 normal 速度(1.0x)下:每线段 60 个点 = 60 tick = 每个航点到下一个航点耗时 3 秒。在 fast(2.0x)下:30 个点 = 1.5 秒。
摄像机旋转插值
每个航点都存储了放置时玩家的 偏航角(水平方向,0°–360°)和 俯仰角(垂直方向,-90° 至 +90°)。
当法杖记录航点时:
Location loc = player.getLocation().clone(); // 包含偏航角和俯仰角
editor.addWaypoint(loc);
在生成平滑路径期间,相邻航点之间的旋转会进行线性插值:
俯仰角 使用标准线性插值:
float pitch = (float) lerp(p1.getPitch(), p2.getPitch(), t);
// lerp(a, b, t) = a + (b - a) * t
偏航角 使用角度感知的 lerp 以防止反向旋转(例如,从 350° 到 10° 应向前转,而不是向后转 340°):
double lerpAngle(double a, double b, double t) {
double diff = ((b - a + 180) % 360) - 180;
return a + diff * t;
}
这将差值规范化到 -180 到 +180 的范围内,确保旋转始终走最短路径。
状态管理映射
为什么使用 SPECTATOR(旁观者)模式?
处于旁观者模式的玩家可以不受物理干扰地每 tick 自由传送。PlayerMoveEvent 会阻止 X/Y/Z 的移动(同时允许头部旋转),从而防止玩家与 cinematic 对抗。
为什么要保存/恢复游戏模式和位置?
当 cinematic 结束(正常结束或通过 /cinematic stop 停止)时,玩家需要回到确切的位置,并拥有确切的游戏模式。这些会在开始时存储在 originalGameModes 和 savedLocations 中,并在 endCinematic 中检索。
为什么需要 awaitingClick 集合?
动画循环独立于玩家输入每 tick 运行。PAUSE_CLICK 关键帧需要在发生点击之前跨多个 tick 暂停。该集合充当共享标志:动画循环检查它,而 PlayerInteractEvent 清除它。
完整工作流程示例
下面是一个构建戏剧性电影式飞行的完整示例:
# 1. 获取法杖
/cinematicwand
# 2. 走到起始位置,看向你希望摄像机面对的方向,左键点击
# 在你的场景周围添加 5 个或更多航点
# 3. 以慢速保存
/cinematic save myflythrough slow
# 4. 在航点 0 处添加片头标题
/cinematic addkeyframe myflythrough 0 title 10 80 20 Welcome | The story begins here
# 5. 在航点 2 处播放一段戏剧性的音效
/cinematic addkeyframe myflythrough 2 sound ENTITY_WITHER_SPAWN 1.0 0.6
# 6. 在航点 4 处淡出至黑色
/cinematic addkeyframe myflythrough 4 fadeblack 3
# 7. 在航点 5 处将时间设置为日落
/cinematic addkeyframe myflythrough 5 time 12000
# 8. 在航点 3 处暂停摄像机 2 秒
/cinematic addkeyframe myflythrough 3 pause 2
# 9. 使航点 1-2 变慢(戏剧性摇镜)
/cinematic addzone myflythrough 1 2 0.2
# 10. 使航点 5-7 变快(快速飞行)
/cinematic addzone myflythrough 5 7 3.0
# 11. 设置路径的片头标题
/cinematic settitle myflythrough The Great Journey | Act I
# 12. 审查所有内容
/cinematic listkeyframes myflythrough
/cinematic listzones myflythrough
# 13. 播放
/cinematic play myflythrough
# 14. 如果你需要删除关键帧 [1](fadeblack):
/cinematic listkeyframes myflythrough
# → 找到索引,例如 [1]
/cinematic removekeyframe myflythrough 1
Tab 补全
插件提供 /cinematic 的 Tab 补全功能:
- 参数 1:所有子命令名称
- 参数 2(针对路径命令):所有已保存的路径名称
- 参数 3(针对
save/setspeed/addzone):速度预设(slow、normal、fast、veryfast、0.5、1.0 等)
- 参数 3(针对
addkeyframe):航点索引建议(0–5)
- 参数 4(针对
addkeyframe):所有关键帧类型
- 参数 5(针对
addkeyframe weather):clear、rain、thunder
? CinematicCamera Plugin — Full README
A Minecraft (Paper/Spigot) plugin for creating smooth, cinematic camera paths with rotation, speed zones, keyframe effects, and more.
Table of Contents
- Quick Start
- How It Works — Core Architecture
- Commands Reference
- Removing a Keyframe (removekeyframe)
- Keyframe Types — Full Reference
- Speed Zones
- Auto-Play Trigger
- Playback System — How It Works in Code
- Path Interpolation — Catmull-Rom Splines
- Camera Rotation Interpolation
- State Management Maps
- Full Workflow Example
- Tab Completion
Quick Start
- Run
/cinematicwand to get the wand item (a Blaze Rod).
- Walk to a position and Left Click to add a waypoint. Your camera's yaw (horizontal rotation) and pitch (vertical rotation) are saved with each waypoint.
- Add at least 2+ waypoints along your desired path.
- Run
/cinematic save mypath normal to save it.
- Run
/cinematic play mypath to watch it.
How It Works — Core Architecture
The plugin is a single class CinematicCamera that extends JavaPlugin and implements Listener. All state is stored in in-memory HashMap/HashSet fields (no persistence to disk between restarts).
Core State Maps
| Field |
Type |
Purpose |
paths |
Map<String, CinematicPath> |
All saved cinematic paths, keyed by name |
editors |
Map<UUID, PathEditor> |
Active wand sessions per player — holds their unsaved waypoints |
playingCinematic |
Set<UUID> |
Players currently watching a cinematic |
originalGameModes |
Map<UUID, GameMode> |
Stores each player's gamemode before the cinematic starts so it can be restored |
activeAnimations |
Map<UUID, BukkitTask> |
The running BukkitRunnable task for each player — used to cancel on stop |
savedLocations |
Map<UUID, Location> |
Player's location before cinematic — teleported back on end |
savedFlying |
Map<UUID, Boolean> |
Whether the player was flying before — restored on end |
awaitingClick |
Set<UUID> |
Players currently paused on a PAUSE_CLICK keyframe, waiting for any click |
Commands Reference
/cinematicwand
Gives you the Blaze Rod wand item.
- Left Click (air or block): Adds your current position + rotation as a waypoint
- Right Click: Shows current waypoint count and how to save
- Shift + Right Click: Clears all your current unsaved waypoints
/cinematic save <name> <speed>
Saves your current waypoints as a named path.
Speed values:
| Input |
Multiplier |
slow or cinematic |
0.3x |
normal or medium |
1.0x |
fast |
2.0x |
veryfast or rapid |
3.5x |
0.1 – 5.0 |
Custom |
/cinematic play <name>
Starts the cinematic for you. Puts you in SPECTATOR mode, applies invisibility, teleports you to waypoint 0, and begins the animation loop.
/cinematic stop
Immediately stops the cinematic, cancels the task, removes effects, and teleports you back to your saved location.
/cinematic list
Lists all saved paths with their waypoint count, speed, keyframe count, speed zone count, and auto-play status.
/cinematic delete <name>
Removes a saved path entirely.
/cinematic setspeed <name> <speed>
Changes the base speed multiplier of an existing path.
/cinematic toggle <name>
Toggles the auto-play trigger on or off for a path. When on, walking within 1.5 blocks of the first waypoint auto-starts the cinematic.
/cinematic clear
Clears your current unsaved wand waypoints (same as Shift+Right Click).
/cinematic settitle <name> <title> [| subtitle]
Sets the title shown at the beginning of a cinematic.
- Use
| to separate title and subtitle: /cinematic settitle mypath Welcome | Enjoy the view
/cinematic addkeyframe <name> <waypointIndex> <type> [args...]
Adds an effect keyframe that triggers when the camera reaches the given waypoint.
/cinematic listkeyframes <name>
Lists all keyframes on a path with their index, waypoint, type, and text preview.
/cinematic removekeyframe <name> <index>
Removes a keyframe by its list index (shown in /cinematic listkeyframes).
/cinematic addzone <name> <startWP> <endWP> <speed>
Adds a speed zone between two waypoint indices. Overrides the base speed for that segment.
/cinematic listzones <name>
Lists all speed zones on a path.
/cinematic removezone <name> <index>
Removes a speed zone by its list index.
Removing a Keyframe
This is a 2-step process:
Step 1 — Find the keyframe index:
/cinematic listkeyframes spawn
This shows output like:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[0] wp#2 text_title → Welcome
[1] wp#4 fade_black
[2] wp#6 sound → ENTITY_WITHER...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2 — Remove by that index number:
/cinematic removekeyframe spawn 1
This removes the fadeblack at index [1].
⚠️ Indexes are positional (0, 1, 2...) and shift after a removal. Always re-run listkeyframes after removing one if you plan to remove more.
Keyframe Types — Full Reference
Add any of these with /cinematic addkeyframe <path> <waypointIndex> <type> [args]
title
Shows a title on screen.
/cinematic addkeyframe mypath 0 title 10 60 20 Welcome to the Tour | Enjoy the view
Args: <fadeIn ticks> <stay ticks> <fadeOut ticks> <title text> [| subtitle]
How it works in code: Calls player.showTitle() using the Adventure API Title.title() with Title.Times, constructing bold white title text and gray subtitle text.
actionbar
Shows text in the action bar (above the hotbar).
/cinematic addkeyframe mypath 2 actionbar Look to your left!
How it works: Calls player.sendActionBar() with yellow-tinted text.
chat
Sends a ✦ prefixed message to the player's chat.
/cinematic addkeyframe mypath 3 chat This is where the story began.
pause
Pauses the camera movement for a set number of seconds.
/cinematic addkeyframe mypath 4 pause 3
Args: <seconds>
How it works: Sets paused = true and pauseTicksLeft = seconds * 20. The BukkitRunnable returns early every tick until the counter hits 0.
click
Pauses the camera indefinitely until the player clicks (any mouse button).
/cinematic addkeyframe mypath 5 click
How it works: Adds the player to awaitingClick set and shows an action bar prompt. The PlayerInteractEvent handler removes them from the set on any click. The animation loop checks awaitingClick.contains(uuid) and returns early until cleared.
sound
Plays a sound at the player's location.
/cinematic addkeyframe mypath 6 sound ENTITY_WITHER_SPAWN 1.0 0.8
Args: <SOUND_NAME> [volume] [pitch]
How it works: Uses player.playSound(). Sound name is looked up via Registry.SOUNDS.get(NamespacedKey.minecraft(...)). Falls back to BLOCK_NOTE_BLOCK_PLING if invalid.
particle
Spawns a burst of firework particles around the camera.
/cinematic addkeyframe mypath 7 particle
How it works: Calls world.spawnParticle(Particle.FIREWORK, location, 40, 1, 1, 1, 0.05).
shake
Shakes the camera by rapidly teleporting it in tiny random offsets.
/cinematic addkeyframe mypath 8 shake
How it works: Schedules 10 runTaskLater calls (1 tick apart) that each add a small random offset (-0.1 to +0.1 on each axis) to the player's location and teleport them there.
fadeblack
Applies Blindness effect to fade the screen to black.
/cinematic addkeyframe mypath 9 fadeblack 2
Args: <duration seconds> (default: 2)
How it works: Applies PotionEffectType.BLINDNESS for duration * 20 ticks.
fadewhite
Applies Glowing effect to create a white flash/fade.
/cinematic addkeyframe mypath 10 fadewhite 2
Args: <duration seconds> (default: 2)
How it works: Applies PotionEffectType.GLOWING for duration * 20 ticks.
lightning
Strikes a visual-only lightning bolt at the camera position.
/cinematic addkeyframe mypath 11 lightning
How it works: Calls world.strikeLightningEffect(location) — this is the visual-only version (no fire, no damage).
explosion
Creates a visual explosion effect at the camera position.
/cinematic addkeyframe mypath 12 explosion
How it works: Calls world.createExplosion(location, 0, false, false) — power 0 means no block damage, no fire.
time
Sets the world time instantly.
/cinematic addkeyframe mypath 3 time 6000
Args: <0–24000> (0 = sunrise, 6000 = noon, 12000 = sunset, 18000 = midnight)
How it works: Calls world.setTime((long) kf.duration).
weather
Changes the world's weather.
/cinematic addkeyframe mypath 5 weather rain
/cinematic addkeyframe mypath 8 weather clear
/cinematic addkeyframe mypath 10 weather thunder
Args: clear | rain | thunder
How it works:
clear → world.setStorm(false)
rain → world.setStorm(true)
thunder → world.setStorm(true) + world.setThundering(true)
Speed Zones
Speed zones override the base path speed for a specific range of waypoints, letting you slow down for dramatic moments or fast-forward through boring stretches.
/cinematic addzone mypath 0 3 0.3
This makes waypoints 0–3 play at 0.3x speed (very slow/cinematic).
/cinematic addzone mypath 5 9 3.0
This makes waypoints 5–9 play at 3x speed.
How it works in code: During generateSmoothPath(), each segment i checks speedZones to see if i >= zone.startWaypoint && i < zone.endWaypoint. If a match is found, pointsInSegment = basePoints / segmentSpeed. A higher speed multiplier means fewer interpolated points between waypoints, so they're traversed faster. Each CameraFrame also stores speedMultiplier which the animation loop uses to skip frames (index += (1 + skip) where skip = speedMultiplier - 1).
Auto-Play Trigger
When auto-play is enabled on a path (it's on by default when you save), any player who walks within 1.5 blocks of the path's first waypoint will automatically start the cinematic.
- Toggle it:
/cinematic toggle mypath
- Checked in
PlayerMoveEvent — only triggers if the player is not already in a cinematic
Playback System — How It Works in Code
When playCinematic(player, path) is called:
- The player is added to
playingCinematic, their gamemode/location/flying state are saved.
- They're set to
SPECTATOR mode with infinite INVISIBILITY.
- They're teleported to
waypoints.get(0).
path.generateSmoothPath() runs and produces a List<CameraFrame>.
- A
Map<Integer, Keyframe> is built that maps each keyframe to its smooth-path index (waypointIndex * basePointsPerSegment).
- A
BukkitRunnable is scheduled to run every tick (1/20th of a second).
Inside the animation loop (per tick):
tick fires
→ if player offline: endCinematic, cancel
→ if timed pause active: decrement counter, return
→ if awaiting click: return
→ if index >= smoothPath.size(): endCinematic, send message, cancel
→ check kfMap for keyframe at current index, apply it
→ if PAUSE_TIMED: set paused=true, set counter, increment index, return
→ if PAUSE_CLICK: add to awaitingClick, increment index, return
→ teleport player to smoothPath.get(index).location (position + yaw/pitch)
→ spawn ambient END_ROD particle every 10 ticks
→ advance index (by 1, or more if speed zone skip > 1)
The endCinematic method:
- Removes player from all state maps
- Cancels the BukkitTask
- Removes potion effects (Invisibility, Blindness, Glowing)
- Clears title
- Restores original GameMode
- Teleports player back to their saved location
- Restores flying state
Path Interpolation — Catmull-Rom Splines
Raw waypoints are spaced far apart. To get smooth camera movement, the plugin interpolates between them using Catmull-Rom splines — a curve that passes through each control point (unlike Bezier curves which are pulled toward them).
For each segment from waypoint i to i+1, 4 control points are used:
p0 = previous waypoint (or p1 if at start)
p1 = current waypoint
p2 = next waypoint
p3 = waypoint after next (or p2 if at end)
The formula applied per axis (x, y, z):
x(t) = 0.5 * (
2*p1 +
(-p0 + p2) * t +
(2*p0 - 5*p1 + 4*p2 - p3) * t² +
(-p0 + 3*p1 - 3*p2 + p3) * t³
)
Where t goes from 0.0 to 1.0 across the segment. The number of points per segment is:
basePointsPerSegment = max(10, 60 / speed)
So at normal speed (1.0x): 60 points per segment = 60 ticks = 3 seconds per waypoint-to-waypoint. At fast (2.0x): 30 points = 1.5 seconds.
Camera Rotation Interpolation
Each waypoint stores the player's yaw (horizontal, 0°–360°) and pitch (vertical, -90° to +90°) at the time it was placed.
When the wand records a waypoint:
Location loc = player.getLocation().clone(); // includes yaw and pitch
editor.addWaypoint(loc);
During smooth path generation, rotation is linearly interpolated between adjacent waypoints:
Pitch uses standard linear interpolation:
float pitch = (float) lerp(p1.getPitch(), p2.getPitch(), t);
// lerp(a, b, t) = a + (b - a) * t
Yaw uses angle-aware lerp to prevent spinning the wrong way around (e.g., 350° → 10° goes forward, not backward 340°):
double lerpAngle(double a, double b, double t) {
double diff = ((b - a + 180) % 360) - 180;
return a + diff * t;
}
This normalizes the difference to the range -180 to +180, ensuring the rotation always takes the shortest path.
State Management Maps
Why SPECTATOR mode?
Players in SPECTATOR can be freely teleported each tick without physics interference. PlayerMoveEvent blocks X/Y/Z movement (while allowing head rotation) so the player can't fight the cinematic.
Why save/restore gamemode and location?
When the cinematic ends (normally or via /cinematic stop), the player needs to return to exactly where they were with exactly the gamemode they had. These are stored in originalGameModes and savedLocations at start and retrieved in endCinematic.
Why the awaitingClick set?
The animation loop runs every tick independently of player input. The PAUSE_CLICK keyframe needs to pause across ticks until a click happens. The set acts as a shared flag: the animation loop checks it, and PlayerInteractEvent clears it.
Full Workflow Example
Here's a complete example building a dramatic cinematic flythrough:
# 1. Get wand
/cinematicwand
# 2. Walk to starting position, look where you want the camera to face, Left Click
# Add 5+ more waypoints around your scene
# 3. Save at slow speed
/cinematic save myflythrough slow
# 4. Add an intro title at waypoint 0
/cinematic addkeyframe myflythrough 0 title 10 80 20 Welcome | The story begins here
# 5. Play a dramatic sound at waypoint 2
/cinematic addkeyframe myflythrough 2 sound ENTITY_WITHER_SPAWN 1.0 0.6
# 6. Fade to black at waypoint 4
/cinematic addkeyframe myflythrough 4 fadeblack 3
# 7. Set time to sunset at waypoint 5
/cinematic addkeyframe myflythrough 5 time 12000
# 8. Pause the camera at waypoint 3 for 2 seconds
/cinematic addkeyframe myflythrough 3 pause 2
# 9. Make waypoints 1-2 slower (dramatic pan)
/cinematic addzone myflythrough 1 2 0.2
# 10. Make waypoints 5-7 faster (fast flythrough)
/cinematic addzone myflythrough 5 7 3.0
# 11. Set intro title for the path
/cinematic settitle myflythrough The Great Journey | Act I
# 12. Review everything
/cinematic listkeyframes myflythrough
/cinematic listzones myflythrough
# 13. Play it
/cinematic play myflythrough
# 14. If you need to remove keyframe [1] (fadeblack):
/cinematic listkeyframes myflythrough
# → finds index, e.g. [1]
/cinematic removekeyframe myflythrough 1
Tab Completion
The plugin provides tab completion on /cinematic:
- Arg 1: all subcommand names
- Arg 2 (for path commands): all saved path names
- Arg 3 (for
save/setspeed/addzone): speed presets (slow, normal, fast, veryfast, 0.5, 1.0, etc.)
- Arg 3 (for
addkeyframe): waypoint index suggestions (0–5)
- Arg 4 (for
addkeyframe): all keyframe types
- Arg 5 (for
addkeyframe weather): clear, rain, thunder
评论 0
登录后参与评分
还没有评论,来抢沙发吧