Content Authoring

RitsuLib offers two normal registration styles. Treat them as peers:

Attribute registration requires the mod assembly to be registered once:

ModTypeDiscoveryHub.RegisterModAssembly("MyMod", Assembly.GetExecutingAssembly());

If the annotated class lives in a helper assembly that the game does not map to your manifest id, add [RitsuLibOwnedBy("MyMod")] to the class or register that assembly with ModTypeDiscoveryHub.RegisterModAssembly(...).

RitsuLib 提供两种常规注册风格，它们是平级入口：

注解注册需要先注册 Mod 程序集：

ModTypeDiscoveryHub.RegisterModAssembly("MyMod", Assembly.GetExecutingAssembly());

如果注解类位于游戏无法映射到你的 manifest id 的辅助程序集，可以给类加 [RitsuLibOwnedBy("MyMod")]，或为该程序集调用 ModTypeDiscoveryHub.RegisterModAssembly(...)。

Put the attribute on the concrete model type. Abstract classes are skipped.

[RegisterCard(typeof(MyCardPool))]
public sealed class MyStrike
    : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

[RegisterRelic(typeof(MyRelicPool))]
public sealed class MyStarterRelic : ModRelicTemplate
{
}

[RegisterCharacter]
public sealed class MyCharacter
    : ModCharacterTemplate<MyCardPool, MyRelicPool, MyPotionPool>
{
}

Pool-backed model attributes support stable entry overrides:

[RegisterCard(typeof(MyCardPool), StableEntryStem = "my_strike")]
public sealed class RenamedStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

Use FullPublicEntry only for compatibility with an already published full entry. Do not set StableEntryStem and FullPublicEntry together.

Common content attributes:

Every auto-registration attribute has Order. Lower values run earlier within the same phase. For starter cards, relics, and potions, the same Order is also stored on the starter entry; starter lists are resolved by Order, then by registration order.

Starter example:

[RegisterCard(typeof(MyCardPool))]
[RegisterCharacterStarterCard(typeof(MyCharacter), 4, Order = 10)]
public sealed class MyStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

Use abstract base class attributes only with Inherit = true. The base class itself is not registered; each concrete derived type receives the inherited registration unless it declares an equivalent direct attribute.

[RegisterCard(typeof(MyCardPool), Inherit = true)]
public abstract class MySkillCardBase
    : ModCardTemplate(1, CardType.Skill, CardRarity.Common, TargetType.Self)
{
}

public sealed class MyBlock : MySkillCardBase
{
}

Do not put StableEntryStem or FullPublicEntry on an inherited base attribute unless every derived type is intended to share the same public entry. That is almost always wrong. Put stable entry overrides on the concrete class instead.

把注解放在具体模型类型上。抽象类会被跳过。

[RegisterCard(typeof(MyCardPool))]
public sealed class MyStrike
    : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

[RegisterRelic(typeof(MyRelicPool))]
public sealed class MyStarterRelic : ModRelicTemplate
{
}

[RegisterCharacter]
public sealed class MyCharacter
    : ModCharacterTemplate<MyCardPool, MyRelicPool, MyPotionPool>
{
}

带池的模型注解支持稳定 Entry 覆写：

[RegisterCard(typeof(MyCardPool), StableEntryStem = "my_strike")]
public sealed class RenamedStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

FullPublicEntry 只用于兼容已经发布过的完整 Entry。不要同时设置 StableEntryStem 和 FullPublicEntry。

常用内容注解：

所有自动注册注解都有 Order。同一注册阶段内，值越小越早执行。对于初始卡牌、初始遗物和初始药水，同一个 Order 也会写入 starter 条目；最终 starter 列表按 Order 排序，再按注册顺序排列。

Starter 示例：

[RegisterCard(typeof(MyCardPool))]
[RegisterCharacterStarterCard(typeof(MyCharacter), 4, Order = 10)]
public sealed class MyStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

抽象基类上的注册注解只有设置 Inherit = true 才会传给具体派生类。抽象基类本身不会被注册；每个具体派生类会获得继承来的注册，除非它声明了等价的直接注解。

[RegisterCard(typeof(MyCardPool), Inherit = true)]
public abstract class MySkillCardBase
    : ModCardTemplate(1, CardType.Skill, CardRarity.Common, TargetType.Self)
{
}

public sealed class MyBlock : MySkillCardBase
{
}

不要在继承型基类注解上设置 StableEntryStem 或 FullPublicEntry，除非你真的希望每个派生类型共享同一个公开 Entry。这几乎总是错误的。稳定 Entry 覆写应写在具体类上。

Use a content pack when a batch is more readable than scattered attributes.

RitsuLibFramework.CreateContentPack("MyMod")
    .Card<MyCardPool, MyStrike>()
    .Relic<MyRelicPool, MyStarterRelic>()
    .Potion<MyPotionPool, MyPotion>()
    .Power<MyPower>()
    .ActEvent<MyAct, MyEvent>()
    .CardKeywordOwnedByLocNamespace("bleeding")
    .Apply();

Important pack methods:

Do not register the same model through attributes and a content pack unless you intentionally want idempotent duplicate handling. Pick one source of truth for each content family.

当集中批次比散落注解更易读时，使用 content pack。

RitsuLibFramework.CreateContentPack("MyMod")
    .Card<MyCardPool, MyStrike>()
    .Relic<MyRelicPool, MyStarterRelic>()
    .Potion<MyPotionPool, MyPotion>()
    .Power<MyPower>()
    .ActEvent<MyAct, MyEvent>()
    .CardKeywordOwnedByLocNamespace("bleeding")
    .Apply();

重要 pack 方法：

不要让同一个模型同时由注解和 content pack 注册，除非你明确接受重复注册被跳过。每类内容最好有一个清晰的来源。

Templates are optional base classes that provide RitsuLib conventions and hooks:

Most display text still belongs in localization JSON. Do not add fake Title or Description overrides to models whose base game class already reads LocString from its table.

模板是可选基类，用来提供 RitsuLib 约定和钩子：

大多数显示文本仍然应写在本地化 JSON 里。游戏基类已经从 LocString 表读取文本时，不要在模型上编造不存在的 Title 或 Description 覆写。

RitsuLib-owned pool content gets a fixed public entry:

<MODID>_<CATEGORY>_<TYPENAME>

MyMod + card + MyStrike becomes:

MY_MOD_CARD_MY_STRIKE

The entry is used by saves, model ids, localization keys, asset defaults, unlock rules, and cross-mod references. Treat it as stable after release.

Use StableEntryStem / ModelPublicEntryOptions.FromStem(...) when a type was renamed but the published entry must stay the same:

[RegisterCard(typeof(MyCardPool), StableEntryStem = "my_strike")]
public sealed class RenamedStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

Avoid all-uppercase CLR type names such as TESTCARD. Vanilla entry parsing can split those names incorrectly; in current 0.105.x behavior, TESTCARD can become T_ES_TC_AR_D. Prefer TestCard, and prefer UrlParser over URLParser.

RitsuLib 自有的池内容会得到固定公开 Entry：

<MODID>_<CATEGORY>_<TYPENAME>

MyMod 下的卡牌 MyStrike 会变成：

MY_MOD_CARD_MY_STRIKE

Entry 会用于存档、模型 ID、本地化 key、资源默认路径、解锁规则和跨 Mod 引用。发布后应视为稳定 ID。

类型改名但已发布 Entry 必须保持不变时，使用 StableEntryStem / ModelPublicEntryOptions.FromStem(...)：

[RegisterCard(typeof(MyCardPool), StableEntryStem = "my_strike")]
public sealed class RenamedStrike : ModCardTemplate(1, CardType.Attack, CardRarity.Common, TargetType.SingleEnemy)
{
}

避免使用 TESTCARD 这类全大写 CLR 类型名。游戏原版 Entry 解析会在某些情形下错误拆分这种名称；当前 0.105.x 行为里，TESTCARD 可能变成 T_ES_TC_AR_D。请写 TestCard；名称中有缩写时，也优先写 UrlParser 而不是 URLParser。