模组角色系统开发指南：自定义卡池与资源路径配置

在模组开发框架中，角色的实现并非单一类所能承载。所有角色的基类是一个名为 CharacterModel 的抽象类，但仅继承该类远不足以构建一个可正常游玩的角色。一个完整可玩的角色需要同时定义三套池化资源：角色卡池、角色遗物池与角色药水池。三者各司其职，共同决定角色在战斗、奖励与商店等环节中可获取的内容。

本文将聚焦于角色卡池的定义方式与资源路径约定，同时对遗物池与药水池的职责进行说明，帮助开发者建立清晰的角色构建思路。

一、角色构成的三大支柱

在深入卡池细节之前，有必要先理解角色定义的完整结构。CharacterModel 作为抽象基类，规定了角色所需的核心接口，而真正填充内容的则是以下三个池化模型：

• 角色卡池（CardPoolModel）：定义该角色在游戏中可获取的全部卡牌，决定卡牌掉落、奖励与商店中的卡牌来源。
• 角色遗物池（RelicPoolModel）：定义该角色可获取的遗物集合，影响精英战、宝箱与商店中的遗物生成。
• 角色药水池（PotionPoolModel）：定义该角色可获取的药水种类，决定药水掉落与商店药水栏位。

三者缺一不可。若仅定义角色基类而未提供池化资源，角色在选择界面可能出现异常，或在对局中无法获得任何卡牌与遗物。因此，自定义角色的第一步，就是为这三类池分别实现具体子类。

二、角色卡池的继承与定义

角色卡池均继承自 CardPoolModel 抽象类。以下是一个完整的卡池实现示例，展示了需要重写的核心属性与生成方法：

public sealed class WatcherCardPool : CardPoolModel
{
    public override string Title => "watcher";
    public override string EnergyColorName => "watcher";
    public override string CardFrameMaterialPath => "card_frame_purple";
    public override Color DeckEntryCardColor => new Color("#C546EC");
    public override Color EnergyOutlineColor => new Color("785490");
    public override bool IsColorless => false;
    protected override CardModel[] GenerateAllCards()
    {
        return new CardModel[]
        {
            ModelDb.Card<StrikeIronclad>(),
            ModelDb.Card<DefendIronclad>(),
        };
    }
}

这段代码虽短，但每个成员都承担着明确的职责。下面逐一展开说明。

三、卡池核心属性详解

1. Title：卡池标识与资源路径的锚点

Title 属性表示该卡池的标题名称。它并非仅用于界面展示，更关键的作用在于影响卡面图资源的查找路径。

在自定义卡牌的机制中，卡面肖像图默认从以下路径加载：

res://images/atlases/card_atlas.sprites/<卡池名称>/<卡牌ID的小写表示>.tres

其中 <卡池名称> 即对应 Title 属性的值。这意味着，若将 Title 设为 "watcher"，则所有属于该卡池的卡牌肖像图都会在 card_atlas.sprites/watcher/ 目录下查找。若该目录缺失或文件名不匹配，卡面将无法正确显示。

因此，Title 不仅是逻辑标识，更是资源组织的命名空间。建议在命名时使用小写、无空格的英文标识符，并与实际资源目录保持一致。

2. EnergyColorName：能量图标的资源键

EnergyColorName 属性指定卡牌左上角能量图标的资源名称。游戏会按照以下路径寻找对应资源：

res://images/atlases/ui_atlas.sprites/card/energy_<EnergyColorName>.tres

例如，当 EnergyColorName 为 "watcher" 时，游戏会加载 energy_watcher.tres 作为能量图标。该属性直接影响卡牌在手牌中的视觉呈现，是区分不同角色卡池的重要视觉标识之一。

需要注意的是，能量图标通常需要与卡牌整体配色协调。若角色拥有独特的能量主题色，应确保图标资源在色调上与卡框、能量描边保持一致。

3. CardFrameMaterialPath：卡牌边框的着色器材质

CardFrameMaterialPath 属性指定卡牌边框所使用的着色器材质资源名称。游戏会在以下路径加载：

res://materials/cards/frames/<CardFrameMaterialPath>_mat.tres

该材质决定了整个卡面的边框颜色与渲染效果。例如，"card_frame_purple" 会对应加载紫色边框材质。这是角色视觉风格最直接的体现之一，不同角色往往使用不同颜色的边框材质加以区分。

在实现自定义角色时，若希望拥有独特的卡框效果，可以基于现有材质创建新的着色器材质，并将其放置在约定目录下，再通过该属性引用。

4. DeckEntryCardColor：缩略卡牌的底色

DeckEntryCardColor 属性控制卡池中卡牌在牌堆列表、抽牌堆、弃牌堆等界面中以缩略形式显示时的底色。当一张卡牌被打出后化作缩略卡牌，其背景色即由此属性决定。

该颜色通常与角色主题色一致，以便玩家在快速浏览牌堆时能通过颜色迅速识别卡牌归属。示例中使用 new Color("#C546EC") 定义了一个紫色调，与整体视觉风格呼应。

5. EnergyOutlineColor：能量数字的描边色

EnergyOutlineColor 属性控制卡牌左上角能量数字或星星数字的描边颜色。描边的作用是在不同背景下保证数字的可读性，同时也承担一定的装饰功能。

该颜色应与能量图标及卡框形成足够的对比，避免出现数字难以辨认的情况。示例中的 new Color("785490") 是一个偏暗的紫色，与亮色数字主体形成层次。

6. IsColorless：无色卡池标识

IsColorless 属性表示当前卡池是否为无色卡池。无色卡池通常用于通用卡牌或特殊机制，其卡牌不归属于任何特定角色。对于普通角色卡池，该属性应设为 false。

若将该属性误设为 true，可能导致卡牌在奖励与商店中的生成逻辑出现偏差，因此需要根据实际设计意图谨慎设置。

7. GenerateAllCards：卡牌集合的生成入口

GenerateAllCards 方法用于指定当前自定义卡组中的所有卡牌，返回一个 CardModel 数组。这是卡池的核心内容所在——所有属于该角色的卡牌都必须在此处注册。

示例中使用了两张占位卡牌：

return new CardModel[]
{
    ModelDb.Card<StrikeIronclad>(),
    ModelDb.Card<DefendIronclad>(),
};

在实际开发中，应将占位符替换为自定义卡牌类型。每张卡牌需先完成自身定义，再通过 ModelDb.Card<T>() 注册到卡池中。需要注意的是，该方法返回的数组应包含该角色所有可获取的卡牌，遗漏会导致对应卡牌无法在游戏中出现。

四、卡池资源的配置与路径约定

除了代码层面的定义，资源文件的组织同样关键。以下路径约定需要在项目中严格遵循：

资源类型	路径模板
卡面肖像图	res://images/atlases/card_atlas.sprites/<卡池名称>/<卡牌ID小写>.tres
能量图标	res://images/atlases/ui_atlas.sprites/card/energy_<EnergyColorName>.tres
卡框材质	res://materials/cards/frames/<CardFrameMaterialPath>_mat.tres
能量图标大图	自定义路径，无强制限制

其中，能量图标的大图可以放置在自定义路径下，例如 res://images/ui/energys/watcher_energy_icon.png。该大图通常用于角色选择界面或能量指示器等场景，其路径不受引擎约定限制，开发者可根据项目结构自行安排。

需要特别注意的是，卡面肖像图与能量图标的图集资源需要正确导入并配置为图集（Atlas）格式，否则运行时可能无法按预期切割与索引。建议在导入设置中确认区域划分与命名一致性。

五、遗物池与药水池的简要说明

虽然本文重点在卡池，但一个完整角色同样离不开遗物池与药水池的定义。二者的实现模式与卡池类似：

• 遗物池继承自 RelicPoolModel，需重写遗物集合的生成方法，并配置对应的遗物图标与描述资源。
• 药水池继承自 PotionPoolModel，需指定该角色可获取的药水类型，并确保药水图标与效果定义完整。

三者共同构成角色的内容边界。若仅定义卡池而忽略遗物与药水，角色在对局中将无法获得相应奖励，影响游玩完整性。

六、实践建议与常见问题

在实现自定义角色卡池时，以下几点值得留意：

1. 命名一致性：Title、EnergyColorName 与资源目录名应保持统一，减少路径查找错误。
2. 资源完整性：确保每张注册卡牌都有对应的肖像图资源，否则会出现空白卡面。
3. 颜色协调：DeckEntryCardColor 与 EnergyOutlineColor 应与卡框材质、能量图标形成统一的视觉语言。
4. 占位符替换：开发初期可使用现有卡牌作为占位，但发布前必须替换为自定义卡牌。
5. 池化资源齐全：不要遗漏遗物池与药水池的定义，否则角色功能不完整。

结语

自定义角色的实现，本质上是围绕 CharacterModel 基类构建三套池化资源，并通过属性配置将代码逻辑与美术资源关联起来。卡池作为其中最核心的一环，其 Title、EnergyColorName、CardFrameMaterialPath 等属性分别对应不同的资源路径与视觉表现。理解这些属性的作用机制与路径约定，是构建一个视觉统一、功能完整的模组角色的基础。

建议开发者在实现过程中，先确保卡池逻辑正确、资源路径无误，再逐步扩展遗物与药水池，最终完成角色的整体构建。