概览

握手方式与版本协商（单独一节）

调用形式

object result = qyxtMod.Call("QYXT", 1, "命令名", 参数1, 参数2, ...);

三个固定前缀参数：

如何判断本模组是否可用

推荐做法：反射拿 Mod 实例 + 探测 Api.GetInfo（因为 Api.GetInfo 不需要世界加载，且在菜单界面即可调用）。

Mod qyxt = null;
if (ModLoader.TryGetMod("QingzhuFengyun", out qyxt))
{
    object raw = qyxt.Call("QYXT", 1, "Api.GetInfo");
    if (raw is Dictionary<string, object> info
        && info.TryGetValue("Ok", out var ok) && ok is true
        && info.TryGetValue("ApiMajor", out var major) && major is int m && m >= 1)
    {
        // API 可用
    }
}

注意：模组内部名（ModLoader.TryGetMod 的第一个参数）源码中未直接以字符串常量出现，Api.GetInfo 返回的 ModName 字段取自 mod.Name，运行时会返回实际内部名。建议 wiki 中注明「以运行时 Api.GetInfo 返回的 ModName 为准」。

统一返回信封

所有接口永远返回一个 Dictionary<string, object>，从不抛异常到调用方（ApiRouter.Dispatch 内部 try/catch 全部兜住，见 ApiRouter.cs:95-106）。

错误码总表（源码原文）

世界状态与执行端要求（重要）

• RequiresWorld 判定：!Main.gameMenu && Main.ActiveWorldFileData != null（AddonApi.cs:28）。

→ 标记 RequiresWorld: true 的接口必须在已加载的世界中调用，主菜单/加载界面调用会返回 WorldNotReady。

• ServerOnly 判定：Main.netMode != 1（即非客户端 = 服务端或单人）。

→ 标记 ServerOnly: true 的接口只能在服务端或单人调用；客户端调用返回 NotAuthority。API 不会自动发包，消息原文强调 no packet is sent automatically.

• 多个返回字段带 IsAuthoritative（值即 Main.netMode != 1），用于让调用方判断数据是否为权威值。

分类一：元数据 / 自省类（2 个）

无需世界，任何时刻可调用。这一组是握手和自文档化的核心。

1. Api.GetInfo

• 参数：无
• 返回值：Dictionary<string, object>，字段如下

• 用途：一句话 —— 让别的模组探测「青元仙途是否装了、APK 版本是多少、支持哪些命令」。
• 源码位置：QingzhuFengyun.Content.Integration/AddonApi.cs:45-52
• 示例代码：

if (ModLoader.TryGetMod("QingzhuFengyun", out Mod qyxt))
{
    if (qyxt.Call("QYXT", 1, "Api.GetInfo") is Dictionary<string, object> info
        && info["Ok"] is true)
    {
        string ver = (string)info["ModVersion"];      // 例如 "2.1.6.10"
        int major  = (int)info["ApiMajor"];            // 1
        int minor  = (int)info["ApiMinor"];            // 0
        string[] cmds = (string[])info["Commands"];    // 全部 13 个命令名
    }
}

• 校验：无参数即无参数校验；仅受通用信封校验（协议名 + 版本号）。

2. Api.GetCommands

• 参数：无
• 返回值：Dictionary<string, object>[]，每个元素是一个「接口自描述」字典：

• 用途：一句话 —— 让别的模组在运行时自动枚举全部接口、参数和执行端要求，做动态适配。
• 源码位置：QingzhuFengyun.Content.Integration/AddonApi.cs:53（实现为 ApiRouter.Describe()，ApiRouter.cs:42-57）
• 示例代码：

var list = (Dictionary<string, object>[])qyxt.Call("QYXT", 1, "Api.GetCommands")["Data"];
foreach (var ep in list)
{
    string name = (string)ep["Name"];
    string[] sig = (string[])ep["Arguments"];
    string ret   = (string)ep["Returns"];
    bool needWorld = (bool)ep["RequiresWorld"];
    bool srvOnly   = (bool)ep["ServerOnly"];
    Mod.Logger.Info($"{name}({string.Join(", ", sig)}) -> {ret}");
}

• 校验：无参数校验。

分类二：规则数据查询类（3 个）

全部不需要世界，属于「静态规则表」，可在主菜单调用。返回内容全部来自枚举与规则表，不含玩家/世界状态。

3. Rules.GetRealms

• 参数：无
• 返回值：Dictionary<string, object>[]，每项字段：

• 用途：一句话 —— 让别的模组读取境界体系、基础门槛和秘窍上限，用于自定义 UI 或平衡换算。
• 源码位置：AddonApi.cs:58-66
• 境界 ID 对照表（源码 CultivationRealm.cs，枚举自 0 递增）：

• BaseAuraThreshold 数值表（源码 CultivationRules.cs:21，BaseThresholds 数组，GetThreshold 的 reducedAfterThreeTurns 传入 false 故无 0.8 折扣）：

• 秘窍上限数值表（源码 CultivationBalance.cs:9-20 等）：

• 示例代码：

var realms = (Dictionary<string, object>[])qyxt.Call("QYXT", 1, "Rules.GetRealms")["Data"];
foreach (var r in realms)
{
    int id = (int)r["Id"];
    string key = (string)r["Key"];
    string name = (string)r["Name"];        // 中文名
    int aperture = (int)r["ApertureLimit"];
}

• 校验：无。

4. Rules.GetSpiritRoots

• 参数：无
• 返回值：Dictionary<string, object>[]（固定 5 项，索引 0–4），每项字段：

• 用途：一句话 —— 让别的模组按官方配色渲染灵根图标/文字，并拿到位标记常量。
• 源码位置：AddonApi.cs:67-80
• 灵根位标记对照表（源码 SpiritRootElement.cs，[Flags]）：

• 示例代码：

var roots = (Dictionary<string, object>[])qyxt.Call("QYXT", 1, "Rules.GetSpiritRoots")["Data"];
foreach (var r in roots)
{
    int mask = (int)r["Mask"];
    string key = (string)r["Key"];
    int[] rgb = (int[])r["Rgb"];   // 与结丹演出同色
}
// 判断玩家是否同时有金、木灵根：
bool metalWood = (mask & 1) != 0 && (mask & 2) != 0;

• 校验：无。

5. Rules.GetTechniques

• 参数：无
• 返回值：Dictionary<string, object>，含三个键，每键是 Dictionary<string, object>[]（元素为 { "Key": string, "Name": string }）：

• 用途：一句话 —— 提供全部功法的稳定键名 → 显示名映射，是 Player.HasSecret 等接口传参的前置查询。
• 源码位置：AddonApi.cs:81-92（辅助方法 Technique 在 :95-102）
• Name 字段来源（CultivationRules.cs:78-178）—— 大部分取物品 DisplayName 的本地化键（跟随语言），少数秘术是硬编码中文字符串，见下表标注：

• 示例代码：

var dict = (Dictionary<string, object>)qyxt.Call("QYXT", 1, "Rules.GetTechniques")["Data"];
var secrets = (Dictionary<string, object>[])dict["Secret"];
foreach (var s in secrets)
    Mod.Logger.Info($"{s["Key"]} = {s["Name"]}");
// 输出形如： SuNuReincarnationArt = 素女轮回功

• 校验：无。

分类三：玩家状态读取类（4 个）

全部 RequiresWorld: true、ServerOnly: false。playerIndex 取值 0 ≤ index < 255，越界返回 OutOfRange；指向的玩家不存在或未激活返回 PlayerInactive。

6. Player.GetSnapshot

• 参数：1 个
• playerIndex:int —— Main.player 数组索引，必填，范围 0–254
• 返回值：Dictionary<string, object>，字段全表：

• 用途：一句话 —— 一次性拿到某个玩家的全部修仙状态，是外部模组做兼容联动/UI 显示的主入口。
• 源码位置：AddonApi.cs:106（注册）+ AddonApi.cs:173-209（PlayerSnapshot 实现）
• 示例代码：

var res = (Dictionary<string, object>)qyxt.Call("QYXT", 1, "Player.GetSnapshot", player.whoAmI);
if ((bool)res["Ok"])
{
    var d = (Dictionary<string, object>)res["Data"];
    Mod.Logger.Info($"境界={d["EffectiveRealm"]} 灵气={d["Aura"]}/{d["AuraStorageCap"]}");
    string[] unlocked = (string[])d["UnlockedSecrets"];
}
else Mod.Logger.Warn($"查询失败 {res["ErrorCode"]}: {res["Message"]}");

• 校验：玩家索引范围 + 玩家激活状态。

7. Player.MeetsRealm

• 参数：3 个
• playerIndex:int —— 玩家索引，必填，0–254
• realmId:int —— 境界 ID，必填，0–8，越界报 OutOfRange
• useNaturalRealm:bool —— true 用自然境界比较，false 用受场景压制后的有效境界
• 返回值：bool（在 Data 中）
• 逻辑：(useNaturalRealm ? NaturalRealm : Realm) >= realmId
• 用途：一句话 —— 让别的模组判断「该玩家是否已达到某境界」，用于门禁、掉落、对话分支。
• 源码位置：AddonApi.cs:107-112（境界校验辅助 GetRealm 在 :148-156）
• 示例代码：

// 该玩家是否至少元婴（Id=4），按有效境界判定
bool ok = (bool)qyxt.Call("QYXT", 1, "Player.MeetsRealm", player.whoAmI, 4, false)["Data"];

// 按自然境界判定（忽略宫殿压制）
bool natural = (bool)qyxt.Call("QYXT", 1, "Player.MeetsRealm", player.whoAmI, 4, true)["Data"];

• 校验：
• realmId 必须 0–8，否则 OutOfRange：Realm ID must be between 0 and 8; True Immortal is a separate state.
• useNaturalRealm 必须是 bool，否则 InvalidArgument：Argument 2 must be Boolean.
• 注意源码中该参数用的是 args.Get<bool>(2)，若传 0/1 整数会报错。

8. Player.GetThreshold

• 参数：2 个
• playerIndex:int —— 0–254
• realmId:int —— 0–8
• 返回值：long —— 计入个人功法修正后的突破所需灵气门槛
• 源码实现链：CultivationPlayer.GetRequiredThreshold(realm)（CultivationPlayer.cs:2090-2102），内部按三转减耗、射手基础功法 ×1.1、射手高阶功法（目标 > 4）×1.2 修正，上限 2000000000
• 用途：一句话 —— 查「这个玩家突破到某境界还差多少灵气」，用于外部 UI 显示进度条。
• 源码位置：AddonApi.cs:113
• ⚠️ 注意：源码 Summary 中文原文明确写道 「不是突破许可判断」 —— 返回的是数值门槛，不代表当前允许突破（世界进度锁等另有限制，见 World.GetProgress 的 RealmCeiling）。
• 示例代码：

long need = (long)qyxt.Call("QYXT", 1, "Player.GetThreshold", player.whoAmI, 5)["Data"];
long aura = (long)((Dictionary<string,object>)qyxt.Call("QYXT",1,"Player.GetSnapshot",player.whoAmI)["Data"])["Aura"];
Mod.Logger.Info($"化神所需 {need}，当前 {aura}");

• 校验：玩家索引、境界 ID 范围。

9. Player.HasSecret

• 参数：2 个
• playerIndex:int —— 0–254
• secretKey:string —— 秘术键名，严格匹配（Enum.TryParse 且 ignoreCase: false），不能是 "None"
• 返回值：bool —— 该秘术是否已解锁
• 用途：一句话 —— 判断玩家是否解锁了某秘术，用于自定义秘籍物品、商店解锁、任务条件。
• 源码位置：AddonApi.cs:114-123
• ⚠️ 语义边界（Summary 中文原文）：「秘术是否已解锁（沿用原有路线条件），不代表已选装或冷却完毕。」 即：解锁 ≠ 当前选装（选装看 Player.GetSnapshot 的 SelectedSecret）。
• 示例代码：

bool has = (bool)qyxt.Call("QYXT", 1, "Player.HasSecret", player.whoAmI, "SwordControlArt")["Data"];

• 校验（严格）：
• 键名必须能被 Enum.TryParse<SecretTechnique> 解析、不等于 None、Enum.IsDefined 通过、且 result.ToString() == 原字符串（即大小写也必须完全一致）
• 失败报 UnknownKey：Unknown secret technique key; query Rules.GetTechniques.
• 传 "none"（小写）或 "None" 都会失败。

分类四：玩家状态写入类（1 个）

10. Player.GrantAura

• 参数：2 个
• playerIndex:int —— 0–254
• baseAmount:long (int accepted) —— 发放的基础灵气量，必须 > 0 且 ≤ 2000000000；int 与 long 都接受
• 返回值：Dictionary<string, object>：

• 用途：一句话 —— 服务端给玩家发放灵气奖励（例如别的模组打完自己的 Boss 给青元仙途灵气）。
• 源码位置：AddonApi.cs:124-145
• 执行端要求：ServerOnly: true —— 只能在服务端或单人调用，客户端调用返回 NotAuthority，且 API 不会自动发包（错误消息原文：Call only on the server or in singleplayer; no packet is sent automatically.）。
• 继承的原有机制（Summary 中文原文）：「服务端发放普通灵气奖励，沿用原有上限、禁用状态、补天丹加成和真仙转化。」
• 走 CultivationPlayer.AddCultivationEnergy（CultivationPlayer.cs:1790-1814）
• 若玩家处于煞魔功激活或 MiaoYinPlayer.ShaLock > 0 → 实际生效 0
• 应用 PermanentAuraGainMultiplier（补天丹加成）后再截断到 20 亿
• 真仙玩家：灵气自动转为仙气（GainImmortalSpiritQiFromAura），Resource 返回 "ImmortalSpiritQi"，仙气上限 1000000（MaLiangPlayer.MaximumImmortalSpiritQi）
• 已达灵气存储上限 → 实际生效 0
• 成功变更会调用 SendState() 同步
• 前置条件校验：玩家必须已学习基础功法，否则 NoBasicTechnique：The player must learn a basic technique first.
• 死亡校验：玩家已死亡 → PlayerDead：Cannot reward a dead player through this API.
• 示例代码：

// 仅服务端执行
if (Main.netMode != NetmodeID.MultiplayerClient)
{
    var res = (Dictionary<string, object>)qyxt.Call("QYXT", 1, "Player.GrantAura", player.whoAmI, 5000L);
    if ((bool)res["Ok"])
    {
        var d = (Dictionary<string, object>)res["Data"];
        long applied = (long)d["Applied"];      // 实际到账（可能被上限截断为 0）
        string res2  = (string)d["Resource"];   // "Aura" 或 "ImmortalSpiritQi"
    }
    else Mod.Logger.Warn($"发放失败 {res["ErrorCode"]}: {res["Message"]}");
}

• 校验清单：玩家索引 → 死亡 → 数值范围（OutOfRange: Amount must be between 1 and 2000000000.）→ 类型（InvalidArgument: Argument 1 must be Int32 or Int64.）→ 基础功法。

分类五：世界与 NPC 查询类（2 个）

11. NPC.GetSnapshot

• 参数：1 个
• npcIndex:int —— Main.npc 数组索引，必填，范围 0 ≤ index < Main.maxNPCs
• 返回值：Dictionary<string, object>：

• 用途：一句话 —— 查询某个存活 NPC 的修仙境界与所属模组，用于跨模组 Boss 强度适配。
• 源码位置：AddonApi.cs:213-236
• ⚠️ 只读保证（Summary 中文原文）：「查询存活 NPC 实例当前境界，不改变其数值。」
• 示例代码：

var res = (Dictionary<string, object>)qyxt.Call("QYXT", 1, "NPC.GetSnapshot", npc.whoAmI);
if ((bool)res["Ok"])
{
    var d = (Dictionary<string, object>)res["Data"];
    int realm = (int)d["Realm"];
    bool boss = (bool)d["IsBoss"];
    string from = (string)d["ModName"];
}

• 校验：索引范围（OutOfRange: NPC index is outside Main.npc.）、NPC 激活状态（NpcInactive: The requested NPC is not active.）。
• 依赖世界状态：RequiresWorld: true。

12. World.GetProgress

• 参数：无
• 返回值：Dictionary<string, object>：

• Bosses 子键全表（源码原文，共 13 项）：

• 用途：一句话 —— 让别的模组读取「这个世界打到哪了」，做进度联动、解锁条件、Boss 前置判断。
• 源码位置：AddonApi.cs:237-257
• 示例代码：

var w = (Dictionary<string,object>)qyxt.Call("QYXT", 1, "World.GetProgress")["Data"];
int ceiling = (int)w["RealmCeiling"];
var bosses = (Dictionary<string,object>)w["Bosses"];
bool killedKingXu = (bool)bosses["KingXu"];

• 校验：无参数；依赖世界状态（RequiresWorld: true，主菜单调用返回 WorldNotReady）。

分类六：内容 ID 查询类（2 个）

均不需要世界，可在主菜单调用。用于把本模组的内部名解析成运行时 ID。

13. Content.Find

• 参数：2 个
• kind:string —— 内容分类，仅接受：Item、NPC、Projectile、Buff、Tile、Wall（区分大小写，见 ContentList 的 switch）
• internalName:string —— 本模组内部名（不带模组前缀）。校验规则：非空白、长度 ≤ 160、不含 /
• 返回值：int —— 该内容的运行时 ID
• 用途：一句话 —— 按内部名拿本模组物品/NPC/弹幕/Buff/物块/墙壁的运行时 ID，用于生成、掉落、判定。
• 源码位置：AddonApi.cs:258-272
• ⚠️ 限制（Summary 中文原文）：「按内部名获取本模组运行时内容 ID；不接受中文名或其他模组。」
• 示例代码：

int itemType = (int)qyxt.Call("QYXT", 1, "Content.Find", "Item", "HeavenBottle")["Data"];
int npcType  = (int)qyxt.Call("QYXT", 1, "Content.Find", "NPC",  "MaLiang")["Data"];
// 生成一个物品：
Item.NewItem(null, (int)player.position.X, (int)player.position.Y, 0, 0, itemType);

• 校验：
• kind 非法 → UnknownKey：Supported kinds: Item, NPC, Projectile, Buff, Tile, Wall.
• internalName 为空/超 160 字符/含 / → InvalidArgument：Use a nonempty local internal name, without a mod prefix.
• 未找到 → NotFound：Content name was not found; query Content.List.

14. Content.List

• 参数：1 个
• kind:string —— 同 Content.Find，仅 Item、NPC、Projectile、Buff、Tile、Wall
• 返回值：Dictionary<string, object>[]，按 Name 做 Ordinal 升序排序，每项字段：

• 用途：一句话 —— 一次性枚举本模组某分类下的全部内容及其运行时 ID，供外部模组建立映射表。
• 源码位置：AddonApi.cs:273（实现在 ContentList，AddonApi.cs:276-299）
• ⚠️ 性能提示（Summary 中文原文）：「枚举本模组 Item/NPC/Projectile/Buff/Tile/Wall 内部名与运行时 ID；勿逐帧调用。」 —— 应在 Mod.Load/PostSetupContent 阶段调用一次并缓存。
• 示例代码：

var items = (Dictionary<string, object>[])qyxt.Call("QYXT", 1, "Content.List", "Item")["Data"];
foreach (var it in items)
{
    string name = (string)it["Name"];
    string full = (string)it["FullName"];   // "QingzhuFengyun/HeavenBottle"
    int id      = (int)it["Id"];
}

• 校验：kind 非法 → UnknownKey：Supported kinds: Item, NPC, Projectile, Buff, Tile, Wall.

完整接口速查表