Camera System

镜头系统

FPSMatch 提供通用客户端镜头底座，玩法模组负责定义死亡、过场或其他场景。普通玩家视角仍由原版处理；临时场景和受限观战由 CameraDirector 仲裁，CameraBackend 是唯一写入相机实体和自定义姿态的入口。

控制权与生命周期

• CameraSession 是独占句柄。低优先级请求会被拒绝，同级或更高优先级请求会替换当前会话。
• 旧句柄不能关闭后继会话；清理回调只执行一次，清理过程重新申请镜头也不会恢复旧所有者。
• 默认约定死亡场景优先级为 100，比赛过场为 200。场景结束后重新解析当前基础视角，不保存并恢复可能已经失效的旧实体。
• PLAYER_LIFE 会话在重生时结束；SCENE 可以跨过重生。地图重置、退服和世界卸载会释放全部会话。
• 所有客户端镜头 API 都应在客户端主线程调用。服务端仍负责权限、玩家冻结、传送和比赛阶段。

CameraRig

CameraRig.sample(double ticks) 返回 CameraFrame。一帧可包含实体绑定、自定义姿态和淡黑强度；姿态包括位置、yaw、pitch、roll 与可选 FOV。

Rig	用途
FixedRig	固定独立机位。
EntityViewRig	绑定真实实体，适合需要保留 TaCZ 第一人称状态的观战。
OrbitRig	围绕目标旋转，碰墙立即收近，离墙逐渐恢复。
PathRig	在有序关键帧间插值，可配置 look-at；角度跨越 ±180° 时走最短路径。
CollisionRig	装饰其他 rig，把相机约束在锚点到目标机位的可见线段内。

CameraSequence 将多个 shot 组合成时间轴，支持硬切、平滑混合和淡黑切换。实体绑定镜头通常使用硬切或淡黑；平滑混合适用于两个都能提供独立姿态的镜头。

策略与呈现

CameraPolicy 统一声明以下行为：

• 是否阻止移动、交互、观战切换和 F5。
• 是否隐藏手部、HUD、本地玩家模型和 toast。
• 是否抑制原版晃动、TaCZ 后坐力和其他视角效果。

界面中的鼠标操作、Esc、聊天和命令输入会被保留。场景 HUD 通过 CameraOverlayEvent 绘制，每个渲染帧只派发一次。

相机实体切换会让 Minecraft 重置实体后处理。场景可使用 session.onCameraBound(...) 重新安装自己的效果；清理时只释放场景自己持有的资源。

时间轴示例

SequenceClock 是镜头、演员、音效和标记事件共享的 tick 时钟。调度器负责推进时钟，渲染阶段只使用 partial tick 采样。

SequenceClock clock = new SequenceClock();
clock.at(0, true, actors::start);
clock.at(20, false, audio::play);

CameraSequence sequence = new CameraSequence(List.of(
    new CameraSequence.Shot(40, new FixedRig(startPose),
        CameraSequence.Transition.CUT, 0),
    new CameraSequence.Shot(80, pathRig,
        CameraSequence.Transition.BLEND, 10)
));

CameraSession session = CameraDirector.playSequence(
    "mymod:scene",
    CameraDirector.CINEMATIC_PRIORITY,
    sequence,
    CameraPolicy.CINEMATIC,
    clock,
    this::sceneStillValid,
    reason -> cleanupScene()
);

标记可以声明 seek 时是否补执行。持续状态应允许补执行，瞬时音效通常应跳过，避免晚加入或追帧时集中播放旧音效。

观战与业务接入

观战目标数据包始终更新 SpectateState，临时场景期间不会直接抢写相机。场景结束后，Director 根据最新观战状态恢复基础视角。

绑定真实玩家实体的第一人称观战保留 TaCZ 手部和枪械同步；独立机位共用一个由 backend 管理的 marker 实体。BlockOffensive 已使用该系统实现死亡镜头和入场/换边演出。

调试与验证

客户端执行 /fpsm camera 可查看当前镜头状态。gradlew check 中的 cameraSystemCheck 覆盖优先级抢占、旧句柄、清理重入、时钟标记、取消、关键帧和转场。

游戏内还应验证重生、换边、目标卸载或掉线、墙边环绕、F5、聊天/菜单、TaCZ 开镜与后坐力，以及退出重进后是否遗留黑幕或输入限制。