快速上手

从零开始：创建项目 → 编写最小模组 → 打包 → 加载到游戏

从这里开始

按你的目标选一条路，每条都能一路走到可运行的结果：

第一次写模组，直接进 教程目录，按顺序做前两篇即可跑通「编译 → 加载 → 看到自己的代码执行」。

什么是 Theseus 模组

Theseus 模组系统允许你用 Java 为游戏编写扩展。模组可以：

• 注册新内容：自定义音符类型、游戏模式、判定等级、谱面扩展段
• 覆盖渲染：隐藏原版 HUD 组件并在画面上自绘
• 修改判定：调整判定窗口、改写判定结果、注册新的判定等级
• 监听事件：订阅游玩事件（判定、连击、开始/结束）与全局事件
• 控制游戏状态：暂停/恢复/变速/跳转、压入自定义场景、播放音效
• 与玩家交互：向玩家展示提示 / 弹窗信息、解锁收集品、注册自定义音频

所有 API 位于 com.seecmd.mod.api 包中；自 3.0 起公共签名冻结（3.x 内只增不破）。

最快路径：官方模板（推荐）

不需要从零搭工程、不需要装 Maven、不需要配置依赖——下载模板，解压即用。

1. 下载 mods-template.zip（已内含 mod-api-3.2.jar、build.bat 与可直接运行的 ExampleMod 示例）并解压。
2. 编辑 build.bat 顶部的变量：MOD_ID、MOD_NAME、MOD_VERSION、MOD_CLASS（指向你的入口类）与 API_VERSION（期望的 mod-api 主版本）。
3. 在 src\main\java 下写你的模组代码（参考模板里的 ExampleMod），资源放 src\main\resources。
4. 双击 build.bat，产物在 target\<MOD_ID>-<MOD_VERSION>.jar。
5. 把 jar 复制到游戏的 mods\ 目录，启动游戏，模组即被加载。

你唯一需要的环境是 JDK 17+（安装时勾选「加入 PATH」即可）。其余全部由模板代劳。

最小模组只需实现 Mod 接口：

package com.example.helloworld;

import com.seecmd.mod.api.Mod;
import com.seecmd.mod.api.ModContext;
import com.seecmd.mod.api.ModInfo;

import java.util.List;

public class HelloWorldMod implements Mod {

    @Override
    public ModInfo info() {
        return ModInfo.of(
                "com_example_helloworld",   // id：小写下划线
                "Hello World",              // 显示名
                "0.1.0",                    // 版本
                List.of("Alice"),           // 作者
                "最小模组示例"               // 描述
        );
    }

    @Override
    public void onInit(ModContext ctx) {
        // 注册表冻结之后调用：读配置、读资源、订阅事件、建缓存都放这里
        ctx.getLogger().info("Hello World 模组已初始化");
        // 向玩家展示提示：toast 数秒后自动消失；重要信息可用 ctx.notifier().dialog("...", 5000)
        ctx.notifier().info("Hello World 模组已初始化");
    }
}

Mod.info() 是唯一必须实现的方法。需要注册自有内容（音符类型 / 游戏模式 / 判定等级 / 渲染滤镜等）时，覆写 onPreInit(ModContext) 并在 ctx.registries() 里注册——注册窗口一次性打开，冻结后（onInit 及之后）再注册会抛 RegistryFrozenException。需要参与游玩（覆盖渲染 / 修改判定 / 监听事件）时，改实现 GameplayMod 接口（继承自 Mod），并在 onInit 里经 ctx.eventBus() 订阅事件。ModContext 是模组的「工具箱」：日志、数据目录、配置、统一注册表入口（ctx.registries()）、能力注入、用户通知等，见 API 参考。

验证模组已加载

模组加载成功时，控制台会打印模组日志（[com_example_helloworld] Hello World 模组已加载），游戏内也会弹出你通过 notifier() 发送的提示。若什么都没发生：

• 确认 jar 放在 mods\ 目录（与游戏 data\ 同级）。
• 确认 jar 的 META-INF/MANIFEST.MF 含 Seecmd-Mod-Class（模板已自动生成，改类名时记得同步 build.bat 的 MOD_CLASS）。
• 查看游戏日志是否有模组加载报错。

进阶：手工搭建工程

如果你已有自己的构建体系（Maven / Gradle / IDE），也可以手工引入依赖。

重要：依赖 scope 必须为 provided（Maven）或 compileOnly（Gradle）。API 由宿主在运行期提供，模组 jar 不得把宿主类打进去。

第一步：安装 mod-api 到本地仓库（只需一次）

从 这里 下载 jar，执行：

mvn install:install-file -Dfile=mod-api-3.2.jar -DgroupId=com.seecmd -DartifactId=mod-api -Dversion=3.2 -Dpackaging=jar

第二步：声明依赖

Maven 示例：

<dependencies>
    <dependency>
        <groupId>com.seecmd</groupId>
        <artifactId>mod-api</artifactId>
        <version>3.2</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle 示例：

dependencies {
    compileOnly 'com.seecmd:mod-api:3.2'
    compileOnly 'com.google.code.gson:gson:2.10.1'
}

打包：编译后打包为标准 jar，manifest 必须包含以下条目：

Manifest-Version: 1.0
Seecmd-Mod-Id: com_example_helloworld
Seecmd-Mod-Class: com.example.helloworld.HelloWorldMod
Seecmd-Mod-Name: Hello World
Seecmd-Mod-Version: 0.1.0
Seecmd-Mod-Authors: Alice
Seecmd-Mod-Description: 一个示例模组，演示 Theseus 模组 API 基础用法
Seecmd-Api-Version: 3.2

Seecmd-Api-Version 声明你期望的模组 API 主版本（当前为 3.2）：与宿主支持的模组 API 主版本不一致时拒绝加载并明确提示；键缺失则按宿主当前支持的模组 API 版本处理。建议显式写上。

完整配置参考模板中的 pom.xml（已配置好 maven-jar-plugin 的 manifest 生成）。

加载到游戏

1. 把打包好的 xxx.jar 放进游戏工作目录下的 mods/ 文件夹（与 data/ 同级）。
2. 启动游戏，加载器自动扫描 mods/ 目录，读取 manifest 定位入口类并注册。
3. 模组数据目录在 data/mods/<modId>/（首次访问自动创建）。
4. 模组默认禁用——新放入的 jar 不会自动生效，需在游戏的模组列表（模组菜单）中手动启用。启用状态持久化在 userdata/settings.json 的 enabledMods，也可用外置工具 mods/mod-manager.jar 管理。

模组 id 命名规范

• 小写下划线，如 com_example_helloworld。
• 不得以 builtin_ 开头（保留给内置模组）。
• 建议使用反向域名前缀避免冲突。

文档导览

文档站按「开始 → 教程 → 开发指南 → API 参考 → 资源 / 架构」组织，左侧目录可逐级展开。

教程（按任务，共 12 篇）

每篇是一个能独立做出结果的小项目，含原理速讲、分步操作、运行检查点与完整代码。建议按顺序：

教程讲「怎么做成」，开发指南讲「机制与工程细节」。做完教程再回来查指南，会顺很多。

开发指南（分主题，共 12 篇）

API 参考（每个类型一页）

签名权威、每个类/接口单独一页，页内每个方法都有签名、行为说明与可抄用示例；按包分类挂在左侧「API 参考」下。常用入口：

• 写模组入口：ModContext、ModInfo、生命周期：四个阶段
• 注册内容：ModRegistries、Registry
• 自定义音符：NoteTypeDefinition、NoteData
• 渲染：RenderCanvas、RenderContext、ResourceManager
• 事件：事件总表
• 能力：CapabilityRegistry、GameStateAccess、GameplayHud

其他

按你的情况选择路径：

• 想写 Java 模组 → 进 教程目录，从「序章：把环境搭起来」开始；需要机制细节时再查 开发指南。
• 不想写代码 → 先看 THS 简易语言；只做皮肤等替换资源，直接看 资源制作指南。
• 想制作谱面 → 直接看 制谱器使用指南。
• 需要精确签名 → 以 API 参考 的类型页为准（签名与发布 jar 由机械校验保持同步，当前 major 线内只增不破）。