2026-04-02 sync

Author: REME

_config.kira.yml

@@ -32,10 +32,57 @@ docsTree:
                 [
                     { title: 01 环境配置, path: /docs/01-env-setup/ },
                     {
-                        title: 02 安装、看源码、修改,
+                        title: 02 常见问题,
                         path: /docs/02-install-view-source-and-patch/,
                     },
-                    { title: 03 BaseLib, path: /docs/03-baselib/ },
+                    {
+                        title: 03 BaseLib,
+                        open: true,
+                        children:
+                            [
+                                { title: 00 总览, path: /docs/03-baselib/ },
+                                {
+                                    title: 01 添加卡牌,
+                                    path: /docs/03-01-add-card/,
+                                },
+                                {
+                                    title: 02 自定义模组配置,
+                                    path: /docs/03-02-mod-config/,
+                                },
+                                {
+                                    title: 03 添加新遗物,
+                                    path: /docs/03-03-add-relic/,
+                                },
+                                {
+                                    title: 04 添加卡牌属性,
+                                    path: /docs/03-04-card-properties/,
+                                },
+                                {
+                                    title: 05 添加新能力,
+                                    path: /docs/03-05-add-power/,
+                                },
+                                {
+                                    title: 06 添加新药水,
+                                    path: /docs/03-06-add-potion/,
+                                },
+                                {
+                                    title: 07 添加先古之民,
+                                    path: /docs/03-07-add-ancient/,
+                                },
+                                {
+                                    title: 08 添加充能球,
+                                    path: /docs/03-08-add-orb/,
+                                },
+                                {
+                                    title: 09 局内保存,
+                                    path: /docs/03-09-run-save/,
+                                },
+                                {
+                                    title: 10 mod联动,
+                                    path: /docs/03-10-mod-integration/,
+                                },
+                            ],
+                    },
                     { title: 04 添加新人物, path: /docs/04-add-new-character/ },
                     {
                         title: 05 变量与描述,

source/_posts/01-env-setup.md

@@ -177,4 +177,8 @@ public class Entry
 
 ## 运行并验证
 
-运行游戏。第一次会提示是否开启mod，选择是，然后游戏会关闭，打开第二次即可，如果右下角显示“已加载模组”即加载成功。如果发现存档丢失，看下一章。
+运行游戏。第一次会提示是否开启mod，选择是，然后游戏会关闭，打开第二次即可，如果右下角显示“已加载模组”即加载成功。如果发现存档丢失，看下一章。
+
+## 不启动Godot打包（可选）
+
+Godot支持命令行导出pck（首先你需要添加一个导出配置），例如使用终端命令：`"{你的godot.exe的路径}" --headless --export-pack "{你的导出配置的名字，例如Windows Desktop}" "{杀戮尖塔根目录}/mods/{你的modid}/{你的modid}.pck"`，参考 https://docs.godotengine.org/zh-cn/4.x/tutorials/editor/command_line_tutorial.html#exporting 。你可以把这个命令保存成一个cmd或者csproj里的target，自行搜索相关配置说明。

source/_posts/02-install-view-source-and-patch.md

@@ -53,6 +53,8 @@ https://github.com/GDRETools/gdsdecomp
 
 开启了模组，按下`~`（tab上方那个键）即可打开控制台。输入`help`即可查看命令。例如`card SURVIVOR`是把一张生存者加入手中。
 
+你可以查询一个命令的帮助，使用`help card`等。
+
 ## DEBUG
 
 尖塔根目录有许多`launch_xxx.bat`，选择一个合适的，右键记事本编辑，在其中加一个`--log`，例如`@echo off
@@ -62,4 +64,20 @@ https://github.com/GDRETools/gdsdecomp
 
 ## 本地联机测试
 
-复制出两个新的`bat`，其中一个添加`--fastmp=host`参数，作为主机，另一个添加`--fastmp=join -clientId=1001`参数，作为非主机玩家。当然你可以添加更多，记得修改`clientId`。
+复制出两个新的`bat`，其中一个添加`--fastmp=host`参数，作为主机，另一个添加`--fastmp=join -clientId=1001`参数，作为非主机玩家。当然你可以添加更多，记得修改`clientId`。
+
+如果你打完一层遇到保存问题，记得以管理员模式启动bat。
+
+## 项目改名
+
+<b>以下修改的都建议使用一个名字</b>。
+
+* 打开`project.godot`，修改`config/name`以及`project/assembly_name`。
+
+* 把`{modid}.csproj`的名字修改成你想要的。
+
+* 把`{modid}.json`的名字修改成你想要的。以及里面的`id`部分。
+
+* 把`{modid}.sln`的名字修改成你想要的。
+
+* 然后重新打包。不要忘记把你之前名字的mod删了。

source/_posts/03-01-add-card.md

@@ -0,0 +1,160 @@
+---
+title: 03-01 添加卡牌
+date: 2026-04-02 00:00:00
+permalink: docs/03-01-add-card/
+categories:
+- Basics
+---
+## 代码
+
+创建一个新的`Cards`文件夹方便管理，并创建新的`cs`文件，例如`TestCard.cs`。
+
+```csharp
+using BaseLib.Abstracts;
+using BaseLib.Utils;
+using MegaCrit.Sts2.Core.Commands;
+using MegaCrit.Sts2.Core.Entities.Cards;
+using MegaCrit.Sts2.Core.GameActions.Multiplayer;
+using MegaCrit.Sts2.Core.Localization.DynamicVars;
+using MegaCrit.Sts2.Core.Models.CardPools;
+using MegaCrit.Sts2.Core.ValueProps;
+
+namespace Test.Scripts.Cards;
+
+// 加入哪个卡池
+[Pool(typeof(ColorlessCardPool))]
+public class TestCard : CustomCardModel
+{
+    // 基础耗能
+    private const int energyCost = 1;
+    // 卡牌类型
+    private const CardType type = CardType.Attack;
+    // 卡牌稀有度
+    private const CardRarity rarity = CardRarity.Common;
+    // 目标类型（AnyEnemy表示任意敌人）
+    private const TargetType targetType = TargetType.AnyEnemy;
+    // 是否在卡牌图鉴中显示
+    private const bool shouldShowInCardLibrary = true;
+
+    // 卡牌的基础属性（例如这里是12点伤害）
+    protected override IEnumerable<DynamicVar> CanonicalVars => [new DamageVar(12, ValueProp.Move)];
+
+    public TestCard() : base(energyCost, type, rarity, targetType, shouldShowInCardLibrary)
+    {
+    }
+
+    // 打出时的效果逻辑
+    protected override async Task OnPlay(PlayerChoiceContext choiceContext, CardPlay cardPlay)
+    {
+        await DamageCmd.Attack(DynamicVars.Damage.BaseValue) // 造成伤害，数值来源于卡牌的基础伤害属性
+            .FromCard(this) // 伤害来源于这张卡牌
+            .Targeting(cardPlay.Target) // 伤害目标是玩家选择的目标
+            .Execute(choiceContext);
+    }
+
+    // 升级后的效果逻辑
+    protected override void OnUpgrade()
+    {
+        DynamicVars.Damage.UpgradeValueBy(4); // 升级后增加4点伤害
+    }
+}
+```
+
+* `CanonicalVars`翻译是“规范值”，指卡牌的基础数值。添加一个`DamageVar`意为指定卡牌的基础伤害是多少，例如这里是`12`。
+
+* `ValueProp`表示数值的属性，例如`ValueProp.Move`表示是通过卡牌造成的伤害/格挡，`ValueProp.Unpowered`表示不受修正影响（如力量等），`ValueProp.Unblockable`表示伤害不可被格挡，`ValueProp.SkipHurtAnim`表示跳过受伤动画。这是一个bitflag类型的枚举，你可以进行组合，例如`ValueProp.Unblockable | ValueProp.Unpowered`，不可被格挡也不受修正影响。
+
+* 尖塔2使用了`async`和`await`来控制效果逻辑顺序执行，比如选择一张牌时就一直`await`不让后续代码执行，和尖塔1的`action`类似的生态位。此处的`OnPlay`中写了一个造成单体伤害的指令。
+
+* 想做什么样的卡牌，看原版代码哪张有类似的效果，参考即可。
+
+* 添加一个`Pool`的attribute，并指定要添加的颜色卡池，然后会自动注册。
+* 继承`CustomCardModel`而不是`CardModel`。
+* <b>注意</b>：通过`baselib`添加卡牌，其id会变成`{命名空间第一段大写}-{原卡牌id}`，例如`namespace Test.Scripts;`取`TEST`，原始卡牌id为`TEST-CARD`，是`TestCard`的大写snake-case，最后变成`TEST-TEST_CARD`。
+
+## 卡图
+
+可以通过在卡牌类中添加一个表达式属性来添加卡牌，这样的话可以任意指定位置：`public override string PortraitPath => $"res://{modid}/images/cards/{Id.Entry.ToLowerInvariant()}.png";`，
+如果这样，那么路径就是`test/images/cards/test-test_card.png`（是你类名的`snake_case`命名风格加前缀，例如`TestCard`即为`test-test_card`）。当然按你的喜好组织资源路径也可。
+
+> 或者你也可以使用`public override string PortraitPath => $"res://{modid}/images/cards/{nameof(TestCard)}.png";`，这样更方便，卡图名字设置为`TestCard.png`就行。
+
+`modId`即为你`{modId}.json`中填写的。<b>不是你的根目录，而是一个新文件夹。</b>
+
+
+卡图任意尺寸都可，且不需要裁剪，官方使用的尺寸是普通卡1000x760，先古卡606x852。
+
+```csharp
+public class TestCard : TestCardModel
+{
+    private const int energyCost = 1;
+    private const CardType type = CardType.Attack;
+    private const CardRarity rarity = CardRarity.Common;
+    private const TargetType targetType = TargetType.AnyEnemy;
+    private const bool shouldShowInCardLibrary = true;
+
+    protected override IEnumerable<DynamicVar> CanonicalVars => [new DamageVar(12, ValueProp.Move)];
+
+    // 添加这一行，指定卡牌立绘路径，这里是test/images/cards/TestCard.png
+    public override string PortraitPath => $"res://test/images/cards/{nameof(TestCard)}.png";
+
+    public TestCard() : base(energyCost, type, rarity, targetType, shouldShowInCardLibrary)
+    {
+    }
+}
+```
+
+![示例卡图](../../images/image10.png)
+
+你也可以通过新增一个`abstract`类，避免每张卡都写一遍卡图路径，并且方便管理一些自定义功能。
+
+```csharp
+public abstract class TestCardModel : CardModel
+{
+    public override string PortraitPath => $"res://test/images/cards/{GetType().Name}.png";
+
+    public TestCardModel(int energyCost, CardType type, CardRarity rarity, TargetType targetType, bool shouldShowInCardLibrary) : base(energyCost, type, rarity, targetType, shouldShowInCardLibrary)
+    {
+    }
+}
+
+public class TestCard : TestCardModel {}
+```
+
+## 文本
+
+此外还需要本地化文件。创建一个`{modId}/localization/{Language}/cards.json`。
+* `modId`即为你`{modId}.json`中填写的。<b>不是你的根目录，而是一个新文件夹。</b>
+* `Language`可以写`zhs`表示简体中文。填写`{CardId}.title`（卡牌名）和`{CardId}.description`（卡牌描述）：
+
+```json
+{
+    "TEST-TEST_CARD.title": "测试卡牌",
+    "TEST-TEST_CARD.description": "造成{Damage:diff()}点伤害。"
+}
+```
+
+编译打包`dll`和`pck`后打开游戏。如果你在对应池子中看到卡牌说明成功了。如果没有任何卡牌（或者一张在左上角的卡牌）说明出问题了。
+
+按`~`打开控制台输入`card TEST-TEST_CARD`获得这张卡。
+
+![示例卡牌](../../images/image11.png)
+
+## 最终项目参考
+
+如果报错，回头看看。最终项目结构参考：
+
+```
+Test (你的项目文件夹)
+├── Scripts (你的脚本文件夹，随意)
+│   ├── TestCard.cs
+│   └── Entry.cs
+└── Test (不要忘了这一层文件夹，是你的modid)
+    ├── images
+    │   └── cards
+    │       └── test-test_card.png
+    └── localization
+        └── zhs
+            └── cards.json
+```
+

source/_posts/03-02-mod-config.md

@@ -0,0 +1,33 @@
+---
+title: 03-02 自定义模组配置
+date: 2026-04-02 00:00:00
+permalink: docs/03-02-mod-config/
+categories:
+- Basics
+---
+* 要使用此功能，需要先放一张图片到`{modId}\mod_image.png`作为mod图标，尺寸任意，否则会由于报错不显示配置。
+* 添加一个继承`SimpleModConfig`（或者是`ModConfig`如果你想要更复杂的设置）的类，在其中添加`public static bool`变量。支持`bool`，`double`，`enum`，`int`，`string`。
+* 在初始化函数调用`ModConfigRegistry.Register`。字符串写你的`modId`。
+
+```csharp
+[ModInitializer("Init")]
+public class Entry
+{
+    public static void Init()
+    {
+        ModConfigRegistry.Register("test", new ModConfig());
+    }
+}
+
+public class ModConfig : SimpleModConfig
+{
+    public static bool Test1 { get; set; } = true;
+    public static bool Test2 { get; set; } = false;
+    public static bool Test3 { get; set; } = true;
+}
+```
+
+![示例配置](../../images/image12.png)
+
+更多请参考`baselib`的`BaseLibConfig`类。
+

source/_posts/03-03-add-relic.md

@@ -0,0 +1,49 @@
+---
+title: 03-03 添加新遗物
+date: 2026-04-02 00:00:00
+permalink: docs/03-03-add-relic/
+categories:
+- Basics
+---
+和添加卡牌类似。先新建一个类。
+
+```csharp
+// 加入哪个遗物池，此处为通用
+[Pool(typeof(SharedRelicPool))]
+public class TestRelic : CustomRelicModel
+{
+    // 稀有度
+    public override RelicRarity Rarity => RelicRarity.Common;
+
+    // 遗物的数值。替换本地化中的{Cards}。
+    protected override IEnumerable<DynamicVar> CanonicalVars => [new CardsVar(1)];
+
+    // 小图标
+    public override string PackedIconPath => $"res://test/images/relics/{Id.Entry.ToLowerInvariant()}.png";
+    // 轮廓图标
+    protected override string PackedIconOutlinePath => $"res://test/images/relics/{Id.Entry.ToLowerInvariant()}.png";
+    // 大图标
+    protected override string BigIconPath => $"res://test/images/relics/{Id.Entry.ToLowerInvariant()}.png";
+
+    public override async Task AfterPlayerTurnStart(PlayerChoiceContext choiceContext, Player player)
+    {
+        // 这里的DynamicVars.Cards.IntValue为上面设置的CardsVar的数值。
+        await CardPileCmd.Draw(choiceContext, DynamicVars.Cards.IntValue, player);
+    }
+}
+```
+
+然后放一张图片`test/images/relics/test_relic.png`。路径不一定是`test`，组织风格自定义，参考上面卡图部分。这里偷懒三张图片用了一样的，可以自己修改。
+
+![示例遗物](../../images/image13.png)
+
+然后写一个本地化文件，`{modId}/localization/{Language}/relics.json`。
+
+```json
+{
+  "TEST-TEST_RELIC.title": "测试遗物",
+  "TEST-TEST_RELIC.description": "每回合开始时，抽[blue]{Cards}[/blue]张牌。",
+  "TEST-TEST_RELIC.flavor": "觉得很眼熟？"
+}
+```
+