Cinematic Camera

插件

· 作者 Frqme

此插件允许你创建电影级别的摄像机,并让玩家按照这些路径移动。

0 本站下载 0 关注 更新于 7 个月前

最新 3 · 1.21.11 · Paper

一键开服(送7天)

? CinematicCamera 插件 — 完整自述文件

一个适用于 Minecraft(Paper/Spigot)的插件,用于创建带有旋转、速度区域、关键帧效果等功能的平滑电影式摄像机路径。


目录

  1. 快速开始
  2. 工作原理 — 核心架构
  3. 命令参考
  4. 移除关键帧 (removekeyframe)
  5. 关键帧类型 — 完整参考
  6. 速度区域
  7. 自动播放触发器
  8. 播放系统 — 代码中的实现方式
  9. 路径插值 — Catmull-Rom 样条曲线
  10. 摄像机旋转插值
  11. 状态管理映射
  12. 完整工作流程示例
  13. Tab 补全

快速开始

  1. 运行 /cinematicwand 获取法杖物品(烈焰棒)。
  2. 走到某个位置并左键点击以添加航点。摄像机的偏航角(水平旋转)和俯仰角(垂直旋转)会随每个航点一起保存。
  3. 在所需路径上至少添加 2 个或更多航点。
  4. 运行 /cinematic save mypath normal 将其保存为命名路径。
  5. 运行 /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) 时:

  1. 玩家被添加到 playingCinematic,其游戏模式/位置/飞行状态被保存。
  2. 他们被设置为 SPECTATOR(旁观者)模式并具有无限期的 INVISIBILITY(隐身)。
  3. 他们被传送到 waypoints.get(0)。
  4. 运行 path.generateSmoothPath() 并生成 List<CameraFrame>。
  5. 构建一个 Map<Integer, Keyframe>,将每个关键帧映射到其在平滑路径中的索引(waypointIndex * basePointsPerSegment)。
  6. 调度一个 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

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源