跳至主要內容

12. Mod模组系统设计

EVOCOSMOS2026/4/14大约 10 分钟

Mod模组系统设计

Mod（模组）是玩家或社区开发者给游戏添加新内容的扩展包。想想《我的世界》的 Mod 生态——有人加新方块，有人加新怪物，有人改整个游戏玩法。一个好的 Mod 系统能让你的游戏"寿命"延长好几倍，因为社区会不断创造新内容。

本章你将学到

  • Mod 系统的设计思路与架构
  • Mod 资源包结构设计
  • Mod 加载器实现（扫描、解析、加载）
  • Mod API 设计（给 Mod 暴露哪些接口）
  • Mod 冲突处理
  • 工坊系统集成思路

Mod 系统设计思路

核心原则

一个好的 Mod 系统应该遵循以下原则：

  1. 隔离性：每个 Mod 运行在独立环境中，一个 Mod 崩溃不影响其他 Mod 和游戏本身
  2. 可扩展性：Mod 可以添加新内容，也可以修改已有内容
  3. 有序性：Mod 之间有加载顺序，确保依赖关系正确
  4. 安全性：限制 Mod 能做的事情，防止恶意代码

Mod 资源包结构

每个 Mod 是一个独立的文件夹（或压缩包），包含资源文件和描述信息。

mods/
├── my_weapon_pack/              # Mod 根目录
│   ├── manifest.json            # Mod 描述文件（必须）
│   ├── preview.png              # Mod 预览图
│   ├── scripts/                 # Mod 脚本
│   │   ├── weapon_loader.gd     # 脚本文件
│   │   └── special_sword.gd
│   ├── assets/                  # Mod 资源
│   │   ├── models/              # 3D 模型
│   │   │   └── flame_sword.glb
│   │   ├── textures/            # 贴图
│   │   │   └── flame_sword.png
│   │   └── sounds/              # 音效
│   │       └── flame_slash.ogg
│   └── data/                    # Mod 数据
│       ├── weapons.json         # 武器数据定义
│       └── recipes.json         # 合成配方

manifest.json 格式

{
    "id": "my_weapon_pack",
    "name": "烈焰武器包",
    "version": "1.2.0",
    "game_version": ">=1.0.0",
    "author": "ModderName",
    "description": "添加5把全新火焰主题武器",
    "dependencies": [
        { "id": "core_api", "version": ">=1.0.0" }
    ],
    "load_after": ["core_api", "base_weapons"],
    "entry_script": "scripts/weapon_loader.gd",
    "tags": ["weapons", "combat"]
}

Mod 加载器实现

Mod 加载器是整个系统的核心，负责扫描、解析、排序和加载所有 Mod。

C#
using Godot;
using System.Collections.Generic;
using System.Linq;
using System.Text.Json;

public class ModInfo
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Version { get; set; }
    public string GameVersion { get; set; }
    public string Author { get; set; }
    public string Description { get; set; }
    public List<ModDependency> Dependencies { get; set; } = new();
    public List<string> LoadAfter { get; set; } = new();
    public string EntryScript { get; set; }
    public string ModPath { get; set; }
    public bool IsLoaded { get; set; }
    public bool HasError { get; set; }
    public string ErrorMessage { get; set; }
}

public class ModDependency
{
    public string Id { get; set; }
    public string Version { get; set; }
}

public partial class ModLoader : Node
{
    private const string MODS_DIR = "user://mods/";
    private Dictionary<string, ModInfo> _loadedMods = new();
    private List<string> _loadOrder = new();

    // 信号：Mod 相关事件
    [Signal] public delegate void ModLoadedEventHandler(string modId);
    [Signal] public delegate void ModLoadFailedEventHandler(string modId, string error);

    public override void _Ready()
    {
        DirAccess.MakeDirRecursiveAbsolute(MODS_DIR);
    }

    /// <summary>
    /// 扫描并加载所有 Mod
    /// </summary>
    public void LoadAllMods()
    {
        GD.Print("--- 开始加载 Mod ---");

        // 第一步：扫描 Mod 目录
        var discoveredMods = ScanModsDirectory();
        GD.Print($"发现 {discoveredMods.Count} 个 Mod");

        // 第二步：解析 manifest
        foreach (var mod in discoveredMods)
        {
            ParseManifest(mod);
        }

        // 第三步：检查依赖关系
        var validMods = discoveredMods.Where(m => !m.HasError).ToList();
        _loadOrder = ResolveLoadOrder(validMods);

        // 第四步：按顺序加载
        foreach (var modId in _loadOrder)
        {
            var mod = validMods.First(m => m.Id == modId);
            LoadMod(mod);
        }

        GD.Print($"--- Mod 加载完成: {_loadedMods.Count}/{discoveredMods.Count} 成功 ---");
    }

    /// <summary>
    /// 扫描 Mod 目录
    /// </summary>
    private List<ModInfo> ScanModsDirectory()
    {
        var mods = new List<ModInfo>();
        var dir = DirAccess.Open(MODS_DIR);

        if (dir == null) return mods;

        dir.ListDirBegin();
        string folderName = dir.GetNext();

        while (folderName != "")
        {
            if (dir.CurrentIsDir() && !folderName.StartsWith("."))
            {
                string manifestPath = MODS_DIR + folderName + "/manifest.json";
                if (FileAccess.FileExists(manifestPath))
                {
                    mods.Add(new ModInfo
                    {
                        Id = folderName,
                        ModPath = MODS_DIR + folderName + "/"
                    });
                }
            }
            folderName = dir.GetNext();
        }

        return mods;
    }

    /// <summary>
    /// 解析 Mod 的 manifest.json
    /// </summary>
    private void ParseManifest(ModInfo mod)
    {
        string manifestPath = mod.ModPath + "manifest.json";
        var file = FileAccess.Open(manifestPath, FileAccess.ModeFlags.Read);

        if (file == null)
        {
            mod.HasError = true;
            mod.ErrorMessage = "无法读取 manifest.json";
            return;
        }

        string json = file.GetAsText();
        file.Close();

        try
        {
            using var doc = JsonDocument.Parse(json);
            var root = doc.RootElement;

            mod.Id = root.GetProperty("id").GetString();
            mod.Name = root.TryGetProperty("name", out var nameEl)
                ? nameEl.GetString() : mod.Id;
            mod.Version = root.TryGetProperty("version", out var verEl)
                ? verEl.GetString() : "0.0.1";
            mod.EntryScript = root.TryGetProperty("entry_script", out var scriptEl)
                ? scriptEl.GetString() : null;

            GD.Print($"  解析 Mod: {mod.Name} v{mod.Version}");
        }
        catch (System.Exception e)
        {
            mod.HasError = true;
            mod.ErrorMessage = $"manifest 解析失败: {e.Message}";
            GD.PrintErr($"  Mod {mod.Id} 解析失败: {e.Message}");
        }
    }

    /// <summary>
    /// 解析加载顺序（拓扑排序）
    /// </summary>
    private List<string> ResolveLoadOrder(List<ModInfo> mods)
    {
        var modMap = mods.ToDictionary(m => m.Id);
        var inDegree = mods.ToDictionary(m => m.Id, m => 0);
        var graph = new Dictionary<string, List<string>>();

        foreach (var mod in mods)
        {
            graph[mod.Id] = new List<string>();
        }

        // 构建依赖图
        foreach (var mod in mods)
        {
            if (mod.LoadAfter != null)
            {
                foreach (var depId in mod.LoadAfter)
                {
                    if (modMap.ContainsKey(depId))
                    {
                        graph[depId].Add(mod.Id);
                        inDegree[mod.Id]++;
                    }
                }
            }
        }

        // 拓扑排序（Kahn 算法）
        var queue = new Queue<string>();
        foreach (var kvp in inDegree)
        {
            if (kvp.Value == 0) queue.Enqueue(kvp.Key);
        }

        var result = new List<string>();
        while (queue.Count > 0)
        {
            string current = queue.Dequeue();
            result.Add(current);

            foreach (var next in graph[current])
            {
                inDegree[next]--;
                if (inDegree[next] == 0)
                    queue.Enqueue(next);
            }
        }

        return result;
    }

    /// <summary>
    /// 加载单个 Mod
    /// </summary>
    private void LoadMod(ModInfo mod)
    {
        GD.Print($"  加载 Mod: {mod.Name}");

        // 注册 Mod 资源路径
        RegisterModResources(mod);

        // 执行 Mod 入口脚本
        if (!string.IsNullOrEmpty(mod.EntryScript))
        {
            string scriptPath = mod.ModPath + mod.EntryScript;
            if (FileAccess.FileExists(scriptPath))
            {
                var script = GD.Load<GDScript>(scriptPath);
                if (script != null)
                {
                    var instance = script.New();
                    if (instance is Node modNode)
                    {
                        AddChild(modNode);
                        modNode.Name = "Mod_" + mod.Id;
                    }
                }
            }
        }

        mod.IsLoaded = true;
        _loadedMods[mod.Id] = mod;
        EmitSignal(SignalName.ModLoaded, mod.Id);
    }

    /// <summary>
    /// 注册 Mod 资源到资源系统
    /// </summary>
    private void RegisterModResources(ModInfo mod)
    {
        // 将 Mod 路径注册到项目设置，使资源可以被引用
        string resourcePath = mod.ModPath + "assets/";
        if (DirAccess.DirExistsAbsolute(resourcePath))
        {
            GD.Print($"    注册资源路径: {resourcePath}");
        }
    }

    /// <summary>
    /// 获取所有已加载的 Mod 信息
    /// </summary>
    public Dictionary<string, ModInfo> GetLoadedMods() => _loadedMods;
}

Mod API 设计

Mod API 是你给 Mod 作者提供的"接口"，告诉他们可以做什么、怎么做。好的 API 应该清晰、稳定、文档完善。

API 设计原则

API 示例：武器注册系统

C#
using Godot;
using System.Collections.Generic;

/// <summary>
/// Mod 可以调用的 API 接口
/// </summary>
public partial class ModAPI : Node
{
    private static ModAPI _instance;
    public static ModAPI Instance => _instance;

    private Dictionary<string, WeaponData> _registeredWeapons = new();

    public override void _Ready()
    {
        _instance = this;
    }

    /// <summary>
    /// Mod 调用此方法注册一把新武器
    /// </summary>
    public void RegisterWeapon(string modId, Dictionary<string, Variant> weaponData)
    {
        string weaponId = (string)weaponData["id"];

        if (_registeredWeapons.ContainsKey(weaponId))
        {
            GD.PrintErr($"武器 ID 冲突: {weaponId}，已被 Mod {_registeredWeapons[weaponId].ModId} 注册");
            return;
        }

        var data = new WeaponData
        {
            Id = weaponId,
            ModId = modId,
            Name = (string)weaponData["name"],
            Damage = (float)weaponData["damage"],
            AttackSpeed = (float)weaponData.GetValueOrDefault("attack_speed", 1.0),
            ModelPath = (string)weaponData.GetValueOrDefault("model_path", ""),
            IconPath = (string)weaponData.GetValueOrDefault("icon_path", ""),
            Description = (string)weaponData.GetValueOrDefault("description", "")
        };

        _registeredWeapons[weaponId] = data;
        GD.Print($"Mod [{modId}] 注册武器: {data.Name} (伤害: {data.Damage})");
    }

    /// <summary>
    /// Mod 调用此方法注册事件钩子
    /// </summary>
    public void RegisterEventHandler(string modId, string eventName, Callable callback)
    {
        GD.Print($"Mod [{modId}] 注册事件: {eventName}");
        // 将回调添加到事件系统
    }

    public WeaponData GetWeapon(string weaponId)
    {
        return _registeredWeapons.GetValueOrDefault(weaponId);
    }

    public Dictionary<string, WeaponData> GetAllWeapons() => _registeredWeapons;
}

public class WeaponData
{
    public string Id { get; set; }
    public string ModId { get; set; }
    public string Name { get; set; }
    public float Damage { get; set; }
    public float AttackSpeed { get; set; }
    public string ModelPath { get; set; }
    public string IconPath { get; set; }
    public string Description { get; set; }
}

Mod 冲突处理

当两个 Mod 修改同一个东西时就会产生冲突。常见的处理策略：

策略说明适用场景
最后加载优先后加载的 Mod 覆盖先加载的简单的覆盖场景
合并把两个 Mod 的修改合并在一起添加型 Mod（都不删除）
用户选择提示用户选择用哪个 Mod 的版本互斥修改
沙箱隔离每个 Mod 看到的是原始数据的副本安全性要求高

防止冲突的最佳实践

  1. 要求 Mod 使用唯一前缀命名（如 modname_weapon_flame_sword）
  2. 在 manifest 中声明 load_after 和 conflicts_with
  3. 提供 Mod 兼容性检查工具
  4. 记录日志，方便排查问题

工坊系统集成思路

如果想让玩家分享和下载 Mod，可以集成一个类似 Steam Workshop 的系统：

实现要点：

  1. Mod 打包：将 Mod 文件夹打包为 .zip 或自定义格式
  2. 上传接口：HTTP POST 上传到服务器
  3. 审核机制：自动扫描 + 人工审核，确保安全
  4. 版本管理：Mod 可以更新，用户可以选择是否更新
  5. 评分评论：社区评分帮助筛选优质 Mod

本章小结

组件职责复杂度
manifest.json描述 Mod 元信息低
Mod 加载器扫描、解析、排序、加载高
Mod API给 Mod 暴露安全接口中
冲突处理器解决 Mod 之间的冲突高
工坊系统Mod 分享平台高

Mod 系统是一个"越早设计越好"的架构决策。如果你的游戏可能有 Mod 社区，在开发初期就规划好 API 边界，比后期改造要轻松得多。

相关章节

最近更新:
贡献者: bobokaka
EVOCOSMOS
Copyright © 2026 EVOCOSMOS