DLL 用户公共 API

如果你使用的是 MCE 的 Lite、Basic、Pro 或 Online 版本，引擎以编译后的 DLL 形式分发，不包含源代码。本指南说明你可以使用的公共 API 接口，从你自己的 C# 脚本中与 MCE 交互和扩展。

SDK 命名空间

MCE 通过 OpenMon.MCE.SDK 命名空间暴露其公共 API。该命名空间包含干净的接口，提供对引擎子系统的访问，而不会将你的代码耦合到内部实现。

IMonsterCaptureEngine

主入口点。所有其他接口都通过它访问：

using OpenMon.MCE.SDK;

public class MyGameManager : MonoBehaviour
{
    [Inject] private IMonsterCaptureEngine engine;

    private void Start()
    {
        Debug.Log($"MCE Version: {engine.Version}");
        Debug.Log($"Monsters in DB: {engine.Database.MonsterCount}");
        Debug.Log($"Player name: {engine.Player.PlayerName}");
    }
}

属性：

属性	类型	描述
`Database`	`IMonsterDatabase`	怪兽/招式/道具数据库的只读访问
`Battle`	`IBattleSystem`	战斗状态和事件
`Player`	`IPlayerData`	玩家的队伍、金钱、名称、徽章
`SaveSystem`	`ISaveSystem`	存档和读档操作
`Version`	`string`	MCE 引擎版本字符串

IMonsterDatabase

查询怪兽、招式、特性、道具和属性：

IMonsterDatabase db = engine.Database;

// 按图鉴编号获取怪兽
MonsterEntry flameleon = db.GetMonster(152);

// 按名称获取怪兽
MonsterEntry sparkbit = db.GetMonster("Sparkbit");

// 获取所有怪兽
IReadOnlyList<MonsterEntry> allMonsters = db.GetAllMonsters();

// 获取招式
Move thunderbolt = db.GetMove("Thunderbolt");

// 获取所有招式
IReadOnlyList<Move> allMoves = db.GetAllMoves();

// 获取属性克制
float effectiveness = db.GetTypeEffectiveness(
    MonsterType.Electric,
    MonsterType.Water
);
// 返回 2.0（效果拔群）

// 获取所有属性
IReadOnlyList<MonsterType> types = db.GetAllTypes();

// 获取总数
int count = db.MonsterCount;

IBattleSystem

监控战斗状态并响应战斗事件：

IBattleSystem battle = engine.Battle;

// 检查是否正在战斗中
if (battle.IsInBattle)
{
    // 在战斗期间执行某些操作
}

// 订阅战斗事件
battle.OnBattleStarted += HandleBattleStarted;
battle.OnBattleEnded += HandleBattleEnded;

private void HandleBattleStarted()
{
    // 战斗刚开始 - 可能暂停计时器、隐藏 UI 等
}

private void HandleBattleEnded(bool playerWon)
{
    // 战斗结束 - playerWon 告诉你结果
    if (playerWon)
    {
        // 更新自定义胜利计数器、触发成就等
    }
}

IPlayerData

访问玩家的当前状态：

IPlayerData player = engine.Player;

// 玩家的怪兽队伍
Roster roster = player.PlayerRoster;
int teamSize = roster.Count;
MonsterInstance firstMonster = roster[0];

// 玩家的金钱
int money = player.Money;

// 玩家的名称
string name = player.PlayerName;

// 玩家的徽章数量
int badges = player.BadgeCount;

ISaveSystem

控制存档和读档操作：

ISaveSystem saves = engine.SaveSystem;

// 保存到栏位 1
saves.Save(1);

// 从栏位 1 读取
saves.Load(1);

// 检查栏位是否有数据
bool hasData = saves.HasSaveData(1);

// 删除存档数据
saves.DeleteSave(1);

// 监听存档/读档事件
saves.OnSaved += (slot) => Debug.Log($"Saved to slot {slot}");
saves.OnLoaded += (slot) => Debug.Log($"Loaded from slot {slot}");

依赖注入

MCE 使用 Zenject（Extenject）进行依赖注入。要在脚本中访问 SDK 接口，使用 [Inject] 属性：

using Zenject;
using OpenMon.MCE.SDK;

public class MyCustomFeature : MonoBehaviour
{
    [Inject] private IMonsterCaptureEngine engine;
    [Inject] private IMonsterDatabase database;
    [Inject] private IBattleSystem battle;

    // Zenject 会在 Start() 调用前自动注入这些
}

不了解 Zenject？

如果你是依赖注入的新手，这里是简单的说明：在接口类型的私有字段上方添加 [Inject]，Zenject 就会自动填充它。你不需要调用 GetComponent 或 FindObjectOfType。该字段会在 Start() 运行前被填充。

如果你的脚本不是由 Zenject 管理的 MonoBehaviour，可以手动解析：

var engine = ProjectContext.Instance.Container.Resolve<IMonsterCaptureEngine>();

Inspector 可配置选项

许多 MCE 系统通过 Unity Inspector 暴露配置，无需编写代码：

ScriptableObject 配置

资源	用途	位置
`BattleConfigurationFile`	战斗速度、经验值倍率、捕获率	Runtime/Configuration/
`MonsterEntry`	怪兽物种数据	MonsterDatabase/
`Move`	招式定义	MonsterDatabase/Moves/
`WildEncountersSet`	遭遇表	按地图资源
`BattleAI`	AI 策略配置	Battle/AI/

组件配置

大多数 MCE 组件在 Inspector 中暴露关键设置：

PlayerCharacter：行走速度、奔跑速度、是否可以奔跑、是否拥有自行车。
EncounterTile：遭遇率、遭遇配置引用。
BattleLauncher：战斗场景引用、过渡设置。
SceneInfo：地图名称、BGM、区域、默认遭遇。

UnityEvent 和回调

MCE 在其组件上暴露了多个 UnityEvent，你可以在 Inspector 中不编写代码就将它们连接起来：

PlayerCharacter 事件

事件	触发时机
`OnStepTaken`	玩家走一步
`OnDirectionChanged`	玩家改变面向方向
`OnInteraction`	玩家按下互动按钮

Actor 事件

Actor（NPC、物体）有回调事件：

事件	触发时机
`OnInteracted`	玩家与 Actor 交互
`OnGraphCompleted`	CommandGraph 完成执行

在 Inspector 中将你的 MonoBehaviour 拖入事件槽并选择要调用的方法即可连接。

无需源代码扩展 MCE

模式 1：事件监听器

创建一个 MonoBehaviour 监听 MCE 事件并触发你自己的逻辑：

public class AchievementTracker : MonoBehaviour
{
    [Inject] private IBattleSystem battle;
    [Inject] private IPlayerData player;

    private int battlesWon;

    private void OnEnable()
    {
        battle.OnBattleEnded += OnBattleEnded;
    }

    private void OnDisable()
    {
        battle.OnBattleEnded -= OnBattleEnded;
    }

    private void OnBattleEnded(bool playerWon)
    {
        if (playerWon)
        {
            battlesWon++;
            if (battlesWon >= 100)
                UnlockAchievement("Battle Master");
        }
    }
}

模式 2：数据库查询

使用数据库 API 构建自定义功能：

public class TypeMatchupHelper : MonoBehaviour
{
    [Inject] private IMonsterDatabase database;

    public List<MonsterType> GetWeaknesses(MonsterType type)
    {
        var weaknesses = new List<MonsterType>();
        foreach (var attackType in database.GetAllTypes())
        {
            if (database.GetTypeEffectiveness(attackType, type) > 1f)
                weaknesses.Add(attackType);
        }
        return weaknesses;
    }
}

模式 3：存档集成

挂接存档系统处理自定义数据：

public class CustomSaveData : MonoBehaviour
{
    [Inject] private ISaveSystem saveSystem;

    private void OnEnable()
    {
        saveSystem.OnSaved += OnGameSaved;
        saveSystem.OnLoaded += OnGameLoaded;
    }

    private void OnGameSaved(int slot)
    {
        // 将自定义数据与 MCE 存档一起保存
        string json = JsonUtility.ToJson(myCustomData);
        PlayerPrefs.SetString($"custom_data_slot_{slot}", json);
    }

    private void OnGameLoaded(int slot)
    {
        // 加载自定义数据
        string json = PlayerPrefs.GetString($"custom_data_slot_{slot}");
        myCustomData = JsonUtility.FromJson<MyData>(json);
    }
}

模式 4：CommandGraph + 自定义脚本

将 CommandGraph 事件与你的自定义 MonoBehaviour 结合：

创建带有公共方法的脚本。
在 CommandGraph 中，添加 Actor 事件节点。
在 Inspector 中，将事件连接到你脚本的方法。

这让你无需修改 MCE 内部即可从可视化脚本触发自定义 C# 逻辑。

无源代码时的限制

限制	替代方案
修改伤害公式	使用 BattleConfigurationFile 中的配置倍率
添加新战斗模块	使用战斗事件 API 响应战斗状态
更改移动物理	通过 Inspector 调整速度和碰撞参数
添加新 CommandGraph 节点类型	创建通过 Actor 事件触发的自定义 MonoBehaviour
修改 UI 布局	覆盖预制体（如果暴露）或在其上叠加你自己的 UI

需要更多控制权？

如果你发现公共 API 对你的项目过于限制，考虑升级到 Source 版本。它包含完整的 C# 源代码和架构文档，可进行深度定制。

程序集引用

要在脚本中引用 MCE 类型，你的程序集定义（.asmdef）必须引用：

{
    "references": [
        "OpenMon.MCE.Runtime"
    ]
}

如果你没有使用程序集定义，MCE 类型通过 DLL 全局可用。

最佳实践

依赖接口，而非实现。使用 IMonsterCaptureEngine，而非具体类。
取消事件订阅。始终在 OnDisable 或 OnDestroy 中移除事件处理程序以防止内存泄漏。
不要缓存过时数据。每次需要当前数据时查询 SDK，特别是 IPlayerData。
使用 Zenject 注入。避免使用 FindObjectOfType 或单例来访问 MCE。
查阅 API 参考。SDK 接口的每个成员都有 XML 文档。你的 IDE 会显示提示。

SDK 命名空间​

IMonsterCaptureEngine​

IMonsterDatabase​

IBattleSystem​

IPlayerData​

ISaveSystem​

依赖注入​

Inspector 可配置选项​

ScriptableObject 配置​

组件配置​

UnityEvent 和回调​

PlayerCharacter 事件​

Actor 事件​

无需源代码扩展 MCE​

模式 1：事件监听器​

模式 2：数据库查询​

模式 3：存档集成​

模式 4：CommandGraph + 自定义脚本​

无源代码时的限制​

程序集引用​

最佳实践​