SQDCLib

一、实体动画事件 新增 AnimationCue（entity / controller / name / loop / speed）和 AnimationBridge。CutsceneEvent 加 animation 字段。

依赖方式：纯反射 + 可选声明。AnimationBridge 用 Class.forName("software.bernie.geckolib.animatable.GeoAnimatable") 在类初始化时探测一次，拿到就缓存 Class 和 Method，拿不到就 available() 返回 false。整个库没有任何一处编译期引用 GeckoLib，所以没装时既不会 NoClassDefFoundError 也不会加载它的类。neoforge.mods.toml 里加了 type="optional" 的软依赖声明。

实体选择支持 @player / @self（演出目标玩家）、@nearest（16 格内最近的非玩家实体）、以及完整的原版选择器 @e[type=...]——后者用 EntitySelectorParser 实例化解析，不是静态方法，这个我踩过一次。

loop 字段目前不生效，这点要明说：GeckoLib 的循环开关在动画定义（Animation 对象）里，不在 AnimationController 上，反射够不着。speed 是尽力而为——反射拿到 controller 就设，拿不到就按动画原速播。字段先留在 schema 里占位。

二、对话双模式 DialogueDefinition 加 mode（ambient 默认 / cinematic），speaker 从 Optional<Component> 变成 Speaker(name, portrait)。JSON 层用 Codec.either 兼容：有 name 字段走新格式，否则当纯文本组件解析，旧数据包不用改。

两种模式的取舍是被一个客户端限制逼出来的：玩家要能走动就不能开 Screen，开了 Screen 就收不到移动输入（Minecraft.setScreen 会释放所有按键）。所以：

cinematic → 开 Screen，鼠标点选项，玩家不能动。压暗层 + 全宽黑幕，黑幕只占底部三分之一，中间留给演出。 ambient → 不开 Screen，走 LayeredDraw 注册的 GUI 层，玩家正常走动，选项用数字键 1–9。 渲染代码是共用的：DialoguePanel 持有打字机状态、可点区域、布局和绘制，DialogueScreen（cinematic）和 DialogueOverlay（ambient）只是两个宿主。头像贴图按 assets/<ns>/textures/gui/portrait/<path>.png 取，画成 32×32。

三、玩家替身 新增 StandInCue（hide + keys）和 ClientStandIn。

不生成实体，纯客户端渲染：Minecraft.getInstance().getEntityModels().bakeLayer(ModelLayers.PLAYER) 拿一个 PlayerModel，在 RenderLevelStageEvent.AFTER_ENTITIES 阶段手动推矩阵、绑玩家自己的皮肤纹理（player.getSkin().texture()）画出去。真玩家用 RenderPlayerEvent.Pre 取消渲染来隐藏。因此替身没有碰撞、没有 AI、服务端不知道它存在，也不需要注册实体或同步。

关键帧复用现成的 Timeline.locate 做时间定位，位置和 yaw_offset 插值，motion 在帧之间切换（idle / walk / wave / point / look_up / bow，直接改 ModelPart 的 xRot / zRot）。

PlayerAnimator 评估结论：不引入。 它是绑定在真玩家实体上的动画系统（靠资源包定义 + 实体混入驱动），而替身要的恰恰是"真玩家隐形 + 一个纯客户端模型"，两者模型对不上；引入它还得额外维护动画资源格式。走位、转身、举手这几个需求用 ModelPart 直接驱动完全够。

四、QTE 新增 QteCue + QteStartPayload（S2C）+ QteResultPayload（C2S）+ ClientQte。服务端在 Session 里挂一个 PendingQte（带 id 和截止 tick），客户端按映射名比对按键。

按键比对的是 KeyMapping 不是物理键位，所以玩家改过键之后按新键依然算成功。时间到没响应算失败，跳过演出算成功——两条路径都保证 on_success / on_fail 之一必然执行，场景不会卡在等输入上。optional 字段只影响作者怎么组织数据（默认分支 vs 失败分支），引擎行为不变。