[Bug] animations using baselib's creature visuals system break when ritsulib is enabled

[OceanUwU]

Area

Other

Severity

Broken feature

What happened?

when using baselib's ncreaturevisuals system for a character animation using AnimationTree to control an AnimationPlayer, if ritsulib is enabled it stops using the animationtree and seems to directly call the animationplayer

baselib's CustomAnimationPatch.SendTriggerToOtherAnimators seems to not get called whatsoever

Steps to reproduce

1. make a character visuals scene using animationtree and animationplayer, using xfade transitions between animations
2. make a baselib customcharactermodel and override CustomVisualPath to point to that scene
3. play the character and try to trigger an "attack" or "hurt" animation, the animation will play but if ritsulib is enabled the xfade transition will be completely ignored

Expected behavior

No response

Logs / stack trace

RitsuLib version

No response

Environment

No response

[ritsukage-local-analyzer]

Warning

此分析由 AI 自动生成，仅供开发者参考，最终判断请以人工确认为准。如有疑问建议结合本地环境进一步复现确认。

摘要

该问题很可能是 RitsuLib 与 BaseLib 在 NCreature.SetAnimationTrigger 上的非 Spine 动画播放逻辑发生拦截冲突：RitsuLib 先消费了触发器并直接驱动 AnimationPlayer，导致 BaseLib 的 AnimationTree/xfade 路径没有机会运行。影响范围主要是使用 BaseLib NCreatureVisuals + AnimationTree 状态机的角色/生物视觉，表现为动画能播但过渡被跳过；建议按高优先级兼容性缺陷处理。

重点结论

项目	结论
简单介绍	启用 RitsuLib 后，基于 BaseLib ncreaturevisuals 的 AnimationTree 过渡不生效，攻击/受击等动画退化为直接播放 AnimationPlayer 动画。
可能原因	高置信度：RitsuLib 的 ModCreatureCombatAnimationPlaybackPatch.Prefix 会在非 Spine 生物上调用自己的 Godot 动画回退并返回 false，而该回退只查找 AnimationPlayer/AnimatedSprite2D，不支持 BaseLib 优先使用的 AnimationTree。
可能解决方案	维护者可让 RitsuLib 在检测到 BaseLib AnimationTree/自定义动画处理器时让渡给 BaseLib，或在 RitsuLib 的非 Spine Godot 播放器中加入 AnimationTree 支持并优先于 AnimationPlayer。
需要补充	需要报告者补充 RitsuLib 版本、STS2/BaseLib 版本、环境，以及最小复现场景或日志；不过现有描述已经足以定位到同一方法上的补丁兼容问题。

展开详细分析、证据与验证

问题描述

期望行为

• BaseLib NCreatureVisuals 场景中由 AnimationTree 控制 AnimationPlayer，触发 attack、hurt 等状态时应走状态机过渡并保留 xfade。

实际行为

• 启用 RitsuLib 后动画仍会播放，但 xfade 过渡被完全忽略。
• 报告者观察到 BaseLib 的 CustomAnimationPatch.SendTriggerToOtherAnimators 似乎没有被调用。

复现步骤

1. 制作一个角色视觉场景，同时包含 AnimationTree 和 AnimationPlayer，并用 AnimationTree 的状态机/xfade 在动画间过渡。
2. 制作 BaseLib CustomCharacterModel，覆盖 CustomVisualPath 指向该场景。
3. 进入角色并触发 attack 或 hurt；启用 RitsuLib 时动画播放但 xfade 被忽略。

日志、附件与原文摘录

• 原文：if ritsulib is enabled it stops using the animationtree and seems to directly call the animationplayer
  • 要点：问题不是动画缺失，而是播放路径从 AnimationTree 变成了直接 AnimationPlayer.Play。
• 原文：baselib's CustomAnimationPatch.SendTriggerToOtherAnimators seems to not get called whatsoever
  • 要点：同一触发点可能被 RitsuLib 的 Harmony prefix 消费，BaseLib prefix 未能接管。

详细分析依据

• RitsuLib 在 src/Scaffolding/Characters/Patches/ModCreatureCombatAnimationPlaybackPatch.cs:90–99 patch NCreature.SetAnimationTrigger：如果未路由到 RitsuLib ModAnimStateMachine 且生物不是 Spine，就调用 ModCreatureVisualPlayback.TryPlayFromCreatureAnimatorTrigger；成功时 prefix 返回 false，会跳过原始方法。
• RitsuLib 的 Godot 动画回退在 src/Scaffolding/Characters/Visuals/ModCreatureVisualPlayback.cs:555–560 构建 handler，只查找 AnimationPlayer 和 AnimatedSprite2D；实际播放在 src/Scaffolding/Characters/Visuals/ModCreatureVisualPlayback.cs:581–599 直接调用 AnimationPlayer.Play(name)。
• BaseLib 对同一场景的预期路径不同：sts-2-baselib/Utils/CustomAnimation.cs:43–49 重新查找动画源时先找 AnimationTree，再找 AnimationPlayer；sts-2-baselib/Utils/CustomAnimation.cs:54–77 的 UseAnimationTree 会通过 AnimationNodeStateMachinePlayback.Travel(name) 切换状态，因此可保留状态机转场/xfade。
• BaseLib 的 sts-2-baselib/Patches/UI/CustomAnimationPatch.cs:59–78 也 patch NCreature.SetAnimationTrigger，对非 Spine 生物调用 CustomAnimation.PlayCustomAnimation。若 RitsuLib prefix 先成功并返回 false，BaseLib 的同点处理就可能不执行或无法改变结果；这与报告者“BaseLib patch 没被调用”的观察一致。
• 不确定点：未在本次只读分析中运行游戏复现，也未看到报告者提供具体 RitsuLib/BaseLib/STS2 版本；Harmony prefix 顺序还需在实际加载组合下确认。但代码层面的能力差异（RitsuLib 不处理 AnimationTree、BaseLib 优先处理 AnimationTree）已经能解释“直接调用 AnimationPlayer、忽略 xfade”的表现。

反馈规范性提醒

维度	状态
复现步骤	已提供：步骤能描述最小机制，但缺少可直接运行的最小场景/示例 mod。
期望/实际	含糊：实际行为清楚；Expected behavior 模板项为空，期望需从正文推断为“保留 AnimationTree xfade”。
环境与版本	缺失：RitsuLib 版本、BaseLib/STS2 版本、操作系统均未提供。
日志/附件	缺失：日志块为空，未附截图、视频或示例工程。
标题与背景	已提供：标题和正文能准确指向 BaseLib creature visuals 与 RitsuLib 兼容冲突。

详细验证建议

• 用最小 BaseLib 角色场景复现：AnimationTree 根为 AnimationNodeStateMachine，同名 attack/hurt 状态配置明显 xfade。
• 分别在仅 BaseLib、BaseLib+RitsuLib 两种加载组合下触发 Attack/Hit，确认是否只有后者跳过 xfade。
• 给 ModCreatureCombatAnimationPlaybackPatch.Prefix、ModCreatureVisualPlayback.BuildGodotAnimHandler 和 BaseLib CustomAnimation.PlayCustomAnimation 加临时日志，确认触发顺序与实际选择的 handler。
• 临时修改 RitsuLib handler 查找顺序：先识别 AnimationTree 并调用 Travel(name)，再回退到 AnimationPlayer；验证 xfade 是否恢复。
• 若采用“让渡给 BaseLib”的方案，验证 RitsuLib 自有非 Spine AnimationPlayer/AnimatedSprite2D 视觉仍能正常播放。

风险与未决

• 增加 AnimationTree 支持时需保持 RitsuLib 自有 ModAnimStateMachine 优先级，避免破坏已选择接入 RitsuLib 状态机的 mod。
• 若只是调整 Harmony priority/ordering，可能仍无法覆盖未安装或未启用 BaseLib 的场景；更稳妥的修复是 RitsuLib 自身支持 AnimationTree 或在检测到 BaseLib 自定义动画能力时显式让渡。
• 需要确认该问题是否只影响玩家角色，还是同样影响 BaseLib 自定义怪物的 CustomVisualPath。

---

English translation

Summary

This is likely an interception conflict between RitsuLib and BaseLib on non-Spine playback through NCreature.SetAnimationTrigger: RitsuLib consumes the trigger first and drives AnimationPlayer directly, so BaseLib's AnimationTree/xfade path never gets a chance to run. The impact is mainly on character/creature visuals using BaseLib NCreatureVisuals plus an AnimationTree state machine: animations still play, but transitions are skipped; this should be handled as a high-priority compatibility bug.

Key Takeaways

Item	Conclusion
Brief description	With RitsuLib enabled, BaseLib ncreaturevisuals transitions driven by AnimationTree stop working, and attack/hurt animations degrade to direct AnimationPlayer playback.
Likely cause	High confidence: RitsuLib's ModCreatureCombatAnimationPlaybackPatch.Prefix calls its own Godot animation fallback for non-Spine creatures and returns false; that fallback only looks for AnimationPlayer/AnimatedSprite2D, not the AnimationTree path that BaseLib prefers.
Possible fix	Maintainers can make RitsuLib yield when a BaseLib AnimationTree/custom animation handler is present, or add AnimationTree support to RitsuLib's non-Spine Godot playback and prioritize it before AnimationPlayer.
More information needed	The reporter should add the RitsuLib version, STS2/BaseLib versions, environment, and a minimal reproduction scene or logs; however, the current report is already enough to narrow the issue to compatibility around the same patched method.

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

• In a BaseLib NCreatureVisuals scene, AnimationTree should control AnimationPlayer, and triggering states such as attack or hurt should go through the state-machine transition while preserving xfade.

Actual Behavior

• With RitsuLib enabled, the animation still plays, but the xfade transition is completely ignored.
• The reporter observed that BaseLib's CustomAnimationPatch.SendTriggerToOtherAnimators appears not to be called.

Steps to Reproduce

1. Create a character visuals scene with both AnimationTree and AnimationPlayer, using AnimationTree state-machine/xfade transitions between animations.
2. Create a BaseLib CustomCharacterModel and override CustomVisualPath to point at that scene.
3. Play the character and trigger attack or hurt; with RitsuLib enabled, the animation plays but xfade is ignored.

Logs, Attachments, and Original Excerpts

• Original: if ritsulib is enabled it stops using the animationtree and seems to directly call the animationplayer
  • Point: the problem is not a missing animation, but that playback switches from AnimationTree to direct AnimationPlayer.Play.
• Original: baselib's CustomAnimationPatch.SendTriggerToOtherAnimators seems to not get called whatsoever
  • Point: the same trigger point may be consumed by RitsuLib's Harmony prefix before BaseLib can take over.

Detailed Analysis Basis

• RitsuLib patches NCreature.SetAnimationTrigger in src/Scaffolding/Characters/Patches/ModCreatureCombatAnimationPlaybackPatch.cs:90–99: if it does not route to a RitsuLib ModAnimStateMachine and the creature is not Spine-backed, it calls ModCreatureVisualPlayback.TryPlayFromCreatureAnimatorTrigger; when that succeeds, the prefix returns false, skipping the original method.
• RitsuLib's Godot animation fallback builds its handler in src/Scaffolding/Characters/Visuals/ModCreatureVisualPlayback.cs:555–560, where it only looks for AnimationPlayer and AnimatedSprite2D; actual playback in src/Scaffolding/Characters/Visuals/ModCreatureVisualPlayback.cs:581–599 directly calls AnimationPlayer.Play(name).
• BaseLib expects a different path for this kind of scene: sts-2-baselib/Utils/CustomAnimation.cs:43–49 rechecks animation sources by looking for AnimationTree first, then AnimationPlayer; sts-2-baselib/Utils/CustomAnimation.cs:54–77 uses AnimationNodeStateMachinePlayback.Travel(name) in UseAnimationTree, which preserves state-machine transitions/xfade.
• BaseLib also patches NCreature.SetAnimationTrigger in sts-2-baselib/Patches/UI/CustomAnimationPatch.cs:59–78 and calls CustomAnimation.PlayCustomAnimation for non-Spine creatures. If RitsuLib's prefix succeeds first and returns false, BaseLib's same-method handling may not run or may no longer affect the result; this matches the reporter's observation that the BaseLib patch does not get called.
• Uncertainty: this read-only triage did not run the game, and the reporter did not provide exact RitsuLib/BaseLib/STS2 versions. Harmony prefix ordering still needs confirmation in the actual mod load combination. Even so, the code-level capability gap—RitsuLib does not handle AnimationTree, while BaseLib prioritizes it—explains the observed “direct AnimationPlayer, xfade ignored” behavior.

Issue Quality Reminder

Dimension	Status
Reproduction steps	Provided: the steps describe the minimal mechanism, but no directly runnable minimal scene/example mod is attached.
Expected/actual	Ambiguous: actual behavior is clear; the Expected behavior template field is empty, so the expected behavior must be inferred as “preserve AnimationTree xfade.”
Environment and versions	Missing: RitsuLib version, BaseLib/STS2 versions, and OS are not provided.
Logs/attachments	Missing: the log block is empty, with no screenshot, video, or example project attached.
Title and background	Provided: the title and body accurately point to a BaseLib creature visuals compatibility conflict with RitsuLib.

Detailed Verification Suggestions

• Reproduce with a minimal BaseLib character scene: AnimationTree root is AnimationNodeStateMachine, and same-name attack/hurt states have an obvious xfade.
• Trigger Attack/Hit under two load combinations—BaseLib only, and BaseLib+RitsuLib—and confirm whether only the latter skips xfade.
• Add temporary logs to ModCreatureCombatAnimationPlaybackPatch.Prefix, ModCreatureVisualPlayback.BuildGodotAnimHandler, and BaseLib CustomAnimation.PlayCustomAnimation to confirm trigger order and the selected handler.
• Temporarily change RitsuLib's handler lookup order to detect AnimationTree first and call Travel(name) before falling back to AnimationPlayer; verify whether xfade is restored.
• If the chosen fix is to yield to BaseLib, verify that RitsuLib-owned non-Spine AnimationPlayer/AnimatedSprite2D visuals still play correctly.

Risks and Open Questions

• Adding AnimationTree support must preserve RitsuLib's own ModAnimStateMachine priority, so mods that explicitly opted into RitsuLib's state machine do not regress.
• Merely adjusting Harmony priority/ordering may still fail in scenes where BaseLib is absent or disabled; the more robust fix is for RitsuLib to support AnimationTree itself or explicitly yield when BaseLib custom animation support is detected.
• It still needs confirmation whether this affects only player characters or also BaseLib custom monsters using CustomVisualPath.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#87 · 退出码 0 · 进程 135.68s
• gpt-5.5(high) · API 133368ms · 17 轮 · ↓56060 ↑5742 · 缓存读373760 写0 · $0.6107
• MCP available: management tools exposed to Claude.

[BAKAOLC]

I've been sick, so I apologize for the delayed response. I've made some minor modifications to fix a few bugs; they are currently in the dev branch. I'm not sure if the issue has been resolved, but if possible, could you try the dev build later?