RitsuLib

外观

资源配置与回退规则 ​

本文是资源配置结构、占位角色回退与资源路径诊断的参考文档。

RitsuLib 使用资源配置对象来描述可覆写的美术、场景、材质以及相关资源。

为什么要有资源配置对象 ​

RitsuLib 选择把它们组织成记录类型形式的资源配置，因为这样更适合长期扩展：

  • 相关资源会自然聚合在一起
  • 局部覆写时可读性更高
  • 回退合并规则更明确
  • 从默认依赖占位角色的旧框架迁移时，也不用放弃结构化设计

角色资源配置结构 ​

CharacterAssetProfile 被拆成多个嵌套记录类型：

  • CharacterSceneAssetSet
  • CharacterUiAssetSet
  • CharacterVfxAssetSet
  • CharacterSpineAssetSet
  • CharacterAudioAssetSet
  • CharacterMultiplayerAssetSet

例如：

csharp
public override CharacterAssetProfile AssetProfile => new(
    Scenes: new(
        VisualsPath: "res://MyMod/scenes/character/my_character.tscn",
        EnergyCounterPath: "res://MyMod/ui/energy/my_energy_counter.tscn"),
    Ui: new(
        IconTexturePath: "res://MyMod/ui/top_panel/icon.png",
        MapMarkerPath: "res://MyMod/map/map_marker.png"),
    Audio: new(
        AttackSfx: "event:/sfx/characters/my_character/attack"));

占位角色回退 ​

ModCharacterTemplate 现在提供：

csharp
public virtual string? PlaceholderCharacterId => "ironclad";

它的行为是：

  • 先读取你显式写下的 AssetProfile
  • 缺失项再从 CharacterAssetProfiles.FromCharacterId(PlaceholderCharacterId) 补齐
  • 如果 PlaceholderCharacterId 为 null，则彻底关闭回退

角色资源配置如何合并 ​

RitsuLib 对角色资源配置的合并是"按类别、按字段"进行的。

这意味着：

  • 你提供一个自定义 Scenes 记录，不会影响 Ui
  • 你只写 RestSiteAnimPath，不会把 MerchantAnimPath 清空
  • 你只写 AttackSfx，不会把其余默认音效抹掉

CharacterAssetProfiles 辅助 API ​

CharacterAssetProfiles 提供了这些工具方法：

  • FromCharacterId(string)
  • Ironclad() / Silent() / Defect() / Regent() / Necrobinder()
  • Resolve(profile, placeholderCharacterId)
  • Merge(fallback, profile)
  • FillMissingFrom(...)
  • WithPlaceholder(...)
  • WithScenes(...)、WithUi(...)、WithVfx(...)、WithSpine(...)、WithAudio(...)、WithMultiplayer(...)

其他内容的资源配置 ​

RitsuLib 也为其他内容提供了类似的资源配置记录类型：

  • CardAssetProfile
  • RelicAssetProfile
  • PowerAssetProfile
  • OrbAssetProfile
  • PotionAssetProfile
  • AfflictionAssetProfile
  • EnchantmentAssetProfile
  • ActAssetProfile

路径辅助工厂 ​

对于符合原版命名习惯的资源布局，RitsuLib 提供了几个常用辅助方法：

  • CharacterAssetProfiles.FromCharacterId(...)
  • ContentAssetProfiles.Card(...)
  • ContentAssetProfiles.Relic(...)
  • ContentAssetProfiles.Power(...)
  • ContentAssetProfiles.Orb(...)
  • ContentAssetProfiles.Potion(...)
  • ContentAssetProfiles.Affliction(...)
  • ContentAssetProfiles.Enchantment(...)
  • ContentAssetProfiles.Act(...)

能量球场景、大能量图标、文本图标是三层能力 ​

RitsuLib 明确把它们拆开：

  • CustomEnergyCounterPath：完整战斗能量球场景
  • BigEnergyIconPath：通过 EnergyIconHelper 解析的大图标
  • TextEnergyIconPath：富文本描述里的小图标

缺失路径诊断 ​

RitsuLib 现在通过 AssetPathDiagnostics 统一校验资源路径覆写。

当前行为：

  • 路径为空 -> 忽略 override
  • 路径存在 -> 使用 override
  • 路径不存在 -> 输出一次警告，并回退到原始资源

推荐的角色资源写法 ​

对大多数自定义角色，比较推荐的模式是：

  1. 保留 PlaceholderCharacterId = "ironclad"，或者改成你想继承风格的基础角色
  2. 只覆写真正自定义的资源
  3. 能量图标相关优先放在 pool 级 BigEnergyIconPath / TextEnergyIconPath
  4. 只有真的要换完整能量球 UI 时，再使用 CustomEnergyCounterPath