🚀 SMALO 开发者极简手册：3 行 import → 一键上架全球

0.1 你只需要写的 5 样东西（最少 3 行 import + 注解 + 基类 + 1 个方法 + 末尾 1 行 SDK 声明）

0.2 完整示例：SmartHelloMod.java（复制粘贴保存即可）

package com.example.smart;

import com.smalo.api.SmartMod;
import com.smalo.api.smart.SmartModBase;
import static com.smalo.api.smart.SmartAPI.*;

// ⭐ 只在这一处配置所有元数据，启动器自动读取并生成 smalo.mod.json
@SmartMod(
    modId               = "smart-hello-mod",
    displayName         = "SmartAPI 你好世界",
    version             = "1.0.0",
    description         = "SmartAPI 单文件极简开发模式的第一个示例",
    author              = "你的名字",
    license             = "MIT",
    supportedMcVersions = { "1.20.1" }
)
public class SmartHelloMod extends SmartModBase {
    @Override
    protected void smartInit() {
        // 🌟 你的全部业务逻辑写在这里！
        log("SmartHelloMod 加载成功！SmartAPI 单文件开发模式编译 ✓");
        api(); // 占位：仅表示你已正式进入 SmartAPI 生态

        // ⭐ 事件订阅（例子：监听任意模组加载事件）
        // bus().subscribe(SomeEvent.class, event -> { ... });

        // ⭐ 自定义事件触发
        // fire(new MyCustomEvent(player));
    }
}

// ======================================================================
// 🎯 ⭐【写在文件最末尾 · SDK 版本绑定声明】1 行搞定！
//    启动器扫描到这一行，自动从全球广场 SDK 仓库拉取对应版本的 smalo-sdk.jar
//    并在内部 javac 编译时自动加到 classpath，你完全不用手动下载/配置任何东西
// ======================================================================
@com.smalo.api.UsesSmaloSDK(version = "2.0.0")

0.3 注解字段说明（@SmartMod 上的属性）

0.4 使用步骤（30 秒完成）

1. 把上面的代码保存为 SmartHelloMod.java（文件名随便，但建议和 public class 同名）
2. 打开 SMALO 启动器 → 直接把 .java 文件拖到启动器窗口上（支持拖拽上传，无需点任何按钮）
3. 弹出「即将编译为模组」确认框 → 确认 modId / 版本 / 支持的 MC 版本 / 落盘目录无误后，点「开始编译」
4. 等进度条走完（解析 → 编译 → 打包 → 落盘），显示 ✅ 编译安装成功 toast，完成！

0.5 编译失败怎么办？

• 红条提示「package com.smalo.api 不存在」 → 点「修复」按钮（你点确认才会重新生成 SDK 引用），启动器按你末尾的 @UsesSmaloSDK 声明重新拉取 SDK 并编译
• 提示「需要先安装 JDK 17/21」→ 点「下载 JDK 17」按钮，或手动去 adoptium.net
• 其他 javac 错误 → 点「复制错误日志」，把内容贴给开发者交流群 / 论坛（启动器有「一键修复建议按钮」，你点确认才会改动代码）

1开发环境搭建：需要哪些软件？如何正确安装？

1.1 必装软件清单

1.2 验证安装是否成功（CMD / PowerShell）

:: 必须用 javac 验证（java -version 只说明有 JRE 不代表有 JDK！）
javac -version
:: 期望输出：javac 21.0.3  或  javac 17.0.11

1.3 javac 报「不是内部或外部命令」的解决方法

1. 控制面板 → 系统 → 高级系统设置 → 环境变量 → 系统变量 Path → 编辑 → 新建
2. 添加：C:\Program Files\Java\jdk-21\bin（末尾必须是 \bin，按你真实安装路径）
3. 再新建一条 系统变量：JAVA_HOME = C:\Program Files\Java\jdk-21（末尾不要加 \bin）
4. 按 2 次确定 → 关闭所有 CMD / PowerShell → 重新开一个再验证

2公开 SDK 说明：你只需要 smalo-sdk.jar 这 1 个文件

外部开发者只需要从 SMALO 官方下载站获取 1 个 SDK 文件：

• smalo-sdk.jar — 包含所有注解、接口、事件基类、事件总线、ModInfo 等编译时依赖。

2.1 SDK 公开包结构（这些是真实可用的 import 路径）

3⭐ 重点！单文件独立编译模组：纯 javac 搞定（解决你说的「按格式写就是不行」）

3.1 第 1 步：建工作目录（桌面就行）

桌面新建空文件夹 "MyFirstMod"，里面放：

📁 MyFirstMod\
├── 📄 HelloMod.java          ← 你写的代码（下面 3.2 给完整内容）
├── 📄 smalo.mod.json        ← 模组元数据（下面 3.3 给模板）
└── 📄 smalo-sdk.jar         ← 从 SMALO 官方下载站获取的公开 SDK

3.2 第 2 步：写 HelloMod.java（一字不差抄，包名类名真实对应 SDK）

// ① 第一行：package，路径层级必须和 entryClass 完全一致
package com.example.hello;

// ② 导入公开 SDK 中的类（这些 import 路径 100% 真实，照抄就行）
import com.smalo.api.AbstractSmaloMod;
import com.smalo.api.SmaloModAnnotation;
import com.smalo.api.SmaloModAnnotation.Side;
import com.smalo.loader.ModInfo;
import com.smalo.loader.EventBus;

/**
 * ③ 在类上添加 @SmaloModAnnotation 注解（所有字段说明见下方注释）
 *
 * 注解字段速查：
 *   - modId               模组唯一 ID（只能小写字母/数字/短横杠/点号，不能空格）
 *   - version             语义化版本 MAJOR.MINOR.PATCH
 *   - displayName         给用户看的中文名（启动器和广场会展示）
 *   - description         一句话简介，≤ 26 字
 *   - author              作者名（可选，默认 "Unknown"）
 *   - license             协议（可选，默认 "All Rights Reserved"）
 *   - dependencies        依赖其他模组 modId；只写你真正用到的第三方模组
 *   - versionRanges       每个 dependencies 对应的版本范围，一一对应
 *   - side                CLIENT 仅客户端 / SERVER 仅服务端 / BOTH 两端都加载
 *   - minLoaderVersion    最低启动器版本，通常写默认值即可
 */
@SmaloModAnnotation(
    modId               = "hello-mod",
    version             = "1.0.0",
    displayName         = "我的第一个 SMALO 模组",
    description         = "玩家进世界自动发欢迎语的示例模组",
    author              = "YourName",
    license             = "MIT",
    // 依赖说明：如果只是纯示例，只写 minecraft 就够了
    // 加载器会自动跳过启动器自身依赖的检查，不用手动声明
    dependencies        = { "minecraft" },
    versionRanges       = { "[1.20.1,)" },
    side                = Side.BOTH,
    minLoaderVersion    = "[0.1,)"
)
// ④ 继承 AbstractSmaloMod（推荐，有默认实现 + log() 方法）
public class HelloMod extends AbstractSmaloMod {

    // ⑤ 生命周期 1：模组被加载时触发一次（拿到 ModInfo 和 EventBus）
    @Override
    public void onLoad(ModInfo mod, EventBus eventBus) {
        // 可以用继承来的 log() 方法打印日志
        log("HelloMod 已被 SMALO 加载器识别，modId = " + getModId());
        log("版本 = " + getVersion() + "，作者 = " + getAuthor());

        // ⭐ 事件订阅方式 A：Lambda 回调（简单推荐）
        eventBus.subscribe(ModLoadEvent.class, event -> {
            log("收到 ModLoadEvent：模组 " + event.getModId() + " 已加载");
        });

        // ⭐ 事件订阅方式 B：注册当前类为监听器（配合下方 @SubscribeEvent 方法）
        eventBus.register(this);
    }

    // ⑥ 生命周期 2：模组初始化阶段（事件系统就绪后）
    @Override
    public void onInitialize() {
        log("HelloMod 初始化完成 ✅");
    }

    // ⑦ 生命周期 3：游戏退出 / 模组卸载时
    @Override
    public void onShutdown() {
        log("HelloMod 已卸载，再见 👋");
    }

    // ==================================================================
    // ⑧ 事件订阅方式 B：用 @SubscribeEvent 注解标记方法（参数必须是 Event 子类）
    //   注意：这个注解是 EventBus 内部注解，import 路径如下：
    //   import com.smalo.loader.EventBus.SubscribeEvent;
    // ==================================================================
    @com.smalo.loader.EventBus.SubscribeEvent(priority = EventBus.Priority.NORMAL)
    public void onAnyModLoaded(ModLoadEvent event) {
        // 这个方法会在任何模组被加载时自动被调用
        log("[@SubscribeEvent] 检测到模组加载：" + event.getModId());
    }
}

// ==================================================================
// 附：如果要自定义事件，只要继承 com.smalo.api.Event 即可
//   例如：public class PlayerWelcomeEvent extends Event { ... }
//   然后在你想要触发的地方：eventBus.publish(new PlayerWelcomeEvent(player));
// ==================================================================

/**
 * 一个内置的示例事件：ModLoadEvent（演示用，实际使用时请使用 SDK 中已定义的事件）
 * 如果你需要玩家加入世界、方块破坏、聊天消息等游戏级事件，请参考 SDK 中已提供的事件类清单。
 */
class ModLoadEvent extends com.smalo.api.Event {
    private final String modId;
    public ModLoadEvent(String modId) { this.modId = modId; }
    public String getModId() { return modId; }
}

3.3 第 3 步：写 smalo.mod.json（严格按这个模板，根目录必放）

{
  "id":                 "hello-mod",
  "name":               "我的第一个 SMALO 模组",
  "version":            "1.0.0",
  "author":             "YourName",
  "mainClass":          "com.example.hello.HelloMod",
  "supportedVersions":  ["1.20.1"],
  "type":               "utility",
  "side":               "both",
  "description":        "玩家进世界自动发欢迎语的示例模组",
  "dependencies":       [
    { "modId": "minecraft", "version": ">=1.20.1", "required": true }
  ]
}

3.4 第 4 步：打开 CMD，直接 javac 编译 + 打 JAR（最关键的几行）

:: 进入你的工作目录
cd /d "%USERPROFILE%\Desktop\MyFirstMod"

:: ① 建 classes 输出目录（放编译好的 .class）
if not exist classes mkdir classes

:: ② ⭐ 真正的编译命令（-cp 指定 SDK，-d 指定输出目录，-encoding UTF-8 避免中文乱码）
::    ❗ 这是 100% 能工作的一行，不依赖任何内部工程 ❗
javac -encoding UTF-8 -cp smalo-sdk.jar -d classes HelloMod.java

:: ③ 把 smalo.mod.json 复制到 classes 根目录（打 JAR 时会自动放到 JAR 根目录）
copy smalo.mod.json classes\smalo.mod.json

:: ④ 进入 classes，打成最终 JAR（名字建议 「modId-version.jar」）
cd classes
jar cfM ..\hello-mod-1.0.0.jar *

:: ⑤ 验证 JAR 内部结构（必须有根目录 smalo.mod.json + 对应 entryClass 路径）
cd ..
jar tf hello-mod-1.0.0.jar

smalo.mod.json
com/example/hello/HelloMod.class
com/example/hello/ModLoadEvent.class

4模组生命周期：onLoad / onInitialize / onShutdown

一个 SMALO 模组的完整生命周期按顺序触发 5 个方法，全部是 SmaloMod 接口的 default 方法，按需 @Override 就行：

5事件系统：两种订阅方式（Lambda + 注解）

SMALO 事件总线提供 两种 订阅方式，你可以任选，也可以混用：

eventBus.subscribe(
    SomeEvent.class,
    event -> {
        // 你的处理逻辑
        log("事件触发：" + event);
    }
);

@EventBus.SubscribeEvent(priority = Priority.HIGH)
public void onSomething(SomeEvent e) {
    log("收到事件：" + e);
}

// onLoad 里注册：
eventBus.register(this);

5.1 自定义事件（可选）

只要继承 com.smalo.api.Event 即可：

package com.example.hello;

import com.smalo.api.Event;

public class CustomHelloEvent extends Event {
    private final String message;
    public CustomHelloEvent(String msg) { this.message = msg; }
    public String getMessage() { return message; }
}

// 触发事件（任何地方只要拿到 eventBus）：
//   eventBus.publish(new CustomHelloEvent("你好"));

6打包标准 JAR：能被全球广场识别通过的结构

6.1 标准 JAR 目录结构（严格按这个来）

hello-mod-1.0.0.jar
├── smalo.mod.json              ← ⭐ 必放！根目录，不能改名不能放子目录！
├── com/
│   └── example/hello/
│       ├── HelloMod.class      ← entryClass 对应的 .class
│       └── ... 其他 .class
└── assets/hello-mod/           ← 可选，放纹理、模型、语言文件、配方 json
    ├── textures/item/wand.png
    └── lang/zh_cn.json

6.2 快速自检清单（30 秒判断 JAR 能不能被识别）

1. jar tf hello-mod-1.0.0.jar | findstr smalo.mod.json → 必须有输出（smalo.mod.json 在根目录）
2. 解压 smalo.mod.json，在线 JSONLint 验证格式合法
3. entryClass 对应的 .class 路径完全对应（package 层级要对上）
4. 不要包含 .java 源文件、.iml、target/、build/ 等 IDE / 构建目录
5. 不要把 smalo-sdk.jar 的内容再打进你自己的 JAR（SDK 是启动器提供的全局依赖）

7⭐ 一键上架全球广场：拖进启动器 = AI 纯检测 + 三重安全扫描 → 你确认后全球可见

7.1 上传流程（只有 3 步，全程启动器内完成，没有别的）

1. 你写好模组文件：1 个 .java（或者已经手动编好的 .jar）
2. 拖进 SMALO 启动器「模组管理页」（或者点「上传到全球广场」按钮）
3. AI 纯检测 + 三重安全扫描 → 你点「确认无误提交」按钮 → 立刻进入全球模组广场（全球用户可见可下载）

7.2 AI 审核的真正规则（绝不自动改你的代码！只检测 + 给修复建议按钮，你点确认才改）

7.3 上传后多久能全球可见？

7.4 「双 AI 联合裁决」是怎么回事？（90%~93.99% 档 · 无人工通道）

# 你是 SMALO 模组广场的抄袭判定 AI（双 AI 联合裁决系统的一员）。你的唯一任务：判断提交的新模组【A】与广场上的历史模组【B】是否属于抄袭。
# ============================================================
# 🎯 SMALO 模组固定格式骨架（以下部分不纳入抄袭相似度比对！必须忽略！）
# ============================================================
# 1. 【单文件 SDK 绑定声明】（写在 .java 文件最末尾，固定 1 行，完全不算抄袭）
#    @com.smalo.api.UsesSmaloSDK(version = "2.0.0")
#
# 2. 【固定 import 模板】（所有模组都会写，不算抄袭。两套模式的 import 全部忽略）
#    --- 2a. SmartAPI 单文件极简模式（新手推荐，第 0 章）---
#    import com.smalo.api.SmartMod;
#    import com.smalo.api.smart.SmartModBase;
#    import static com.smalo.api.smart.SmartAPI.*;
#    --- 2b. 传统 SmaloMod 模式（第 4 章高级可选）---
#    import com.smalo.api.AbstractSmaloMod;
#    import com.smalo.api.SmaloModAnnotation;
#    import com.smalo.api.eventbus.EventBus;
#    import com.smalo.api.ModInfo;
#
# 3. 【@SmartMod 注解骨架】（固定字段结构，不算抄袭。字段取值完全相同（如 supportedMcVersions 都是 1.20.1）也不算抄袭。）
#    @SmartMod(
#        modId = "xxx", displayName = "xxx", version = "1.0.0",
#        description = "xxx", author = "xxx", license = "MIT",
#        supportedMcVersions = { "1.20.1", "1.21", "1.21.4" },
#        side = Side.COMMON, minLoaderVersion = "1.0.0"
#    )
#
# 4. 【标准生命周期 + 钩子注册声明】（所有模组都会写的模板外壳，不算抄袭。注意：仅注册外壳忽略，内部 lambda/方法体逻辑参与比对！）
#    4a. 继承基类声明骨架：
#        public class Xxx extends SmartModBase { ... }
#        public class Xxx extends AbstractSmaloMod { ... }
#    4b. SmartAPI 模式 smartInit() 方法签名（空方法体 + @Override 骨架忽略）：
#        @Override protected void smartInit() { /* 内部业务逻辑保留比对 */ }
#    4c. 传统模式 5 个生命周期钩子（方法签名本身 + 空方法体骨架忽略，内部业务逻辑保留比对）：
#        void onLoad() / onInitialize() / onPreLaunch() / onPostLaunch() / onShutdown()
#    4d. 两种事件订阅外壳注册（忽略外壳，lambda / 注解方法的内部逻辑保留比对）：
#        eventBus.subscribe(SomeEvent.class, (e) -> { /* 内部逻辑保留比对 */ });
#        @EventBus.SubscribeEvent public void onXxx(SomeEvent e) { /* 方法体保留比对 */ }
#    4e. SmartAPI 静态快捷注册外壳（外壳忽略，传入 lambda / 方法引用的内部逻辑保留比对）：
#        SmartAPI.onChat(this::onPlayerChat);
#        SmartAPI.onJoin(this::onPlayerJoin);
#        SmartAPI.onTick(this::onGameTick);
#        ...（其他标准事件订阅外壳）
#
# 5. 【smalo.mod.json 元数据标准字段】（字段名结构固定，不算抄袭。仅当字段 value 整段大段重复文字时才提示，字段名本身完全忽略）
#    {
#      "schemaVersion": 1,
#      "modId": "...", "name": "...", "version": "...",
#      "entryClass": "...", "supportedMcVersions": [...],
#      "description": "...", "authors": [ "...", "..." ],
#      "license": "...", "tags": [...], "category": "...",
#      "dependencies": [{ "modId": "minecraft", "version": ">=1.20.1" }],
#      "optionalDependencies": []
#    }
#
# ============================================================
# ✅ 真正纳入相似度比对的部分（只有这些！）
# ============================================================
# 只比对「业务逻辑核心代码」：钩子函数体 / lambda 内部的实际算法/处理逻辑、自定义数据结构、非标准 API 组合调用顺序、玩家交互规则实现、渲染管线自定义部分、纯业务类的字段与方法实现。
#
# ============================================================
# 📊 你的输出格式（固定 JSON，不要输出多余文字！）
# ============================================================
{
  "decision": "NOT_COPIED | SUSPECTED_COPIED",
  "confidence": 0.00 ~ 1.00,                  # 保留 2 位小数，四舍五入
  "ignored_skeleton_ratio": 0.00 ~ 1.00,      # 你忽略掉的固定骨架代码占整份代码的比例（保留 2 位小数，四舍五入）
  "business_logic_similarity": 0.00 ~ 1.00,   # 真正业务逻辑的相似度（忽略骨架后）（保留 2 位小数，四舍五入）
  "evidence": "≤ 80 字中文，格式：类A#方法A(Lx-Ly) 与 类B#方法B(Lx-Ly) 在 [算法/API顺序/交互规则] 上高度相似/原创"
}

8常见问题 FAQ：AI 纯检测清单 + 一键修复按钮（你点才会改）

1. ① 担心 smalo.mod.json 漏写 / 格式错 / 放错位置？

   ✅ AI 纯检测（不碰你代码）：缺了 → 弹出「建议生成 smalo.mod.json 预览窗」，显示完整内容给你看，你点「确认修改」才写入；格式错 → 精确告诉你 JSON 第几行第几列缺逗号/引号错；位置错 → 建议移到 JAR 根目录，你点确认才移动。AI 不会在你没点确认前私自写/改/挪任何一个文件。

2. ② 担心 package 路径和 entryClass 对不上？

   ✅ AI 纯检测（不碰你代码）：启动器静态扫描 class 文件，找出真正的入口类 + 列出 entryClass 与实际 package 不一致的具体路径，弹出「建议修正 entryClass 为 xxx」按钮，你点确认才写入 JSON。少一层 / 多一层 / 路径拼错全部明确标出行号。

3. ③ 担心 javac 命令漏写 -cp smalo-sdk.jar / 参数不对？

   ✅ AI 纯检测（不碰你代码）：不管你是拖 .java 还是拖自己编好的 .jar，启动器内部 javac 用 SDK classpath 重新编译一遍源代码（此步是 javac 标准编译过程，不修改你的 .java 原文件文本，完全合规合法）。参数错误：AI 检测出缺 -encoding / -cp，直接提示「启动器会用正确参数重新编译，无需你手动改命令」。

4. ④ 担心 modId 写了大写 / 空格 / 中文？

   ✅ AI 纯检测（不碰你代码）：精确标出非法字符位置 + 给出建议的合法 ID。比如你写 "Hello 我的 Mod" → 建议变成 "hello-wo-de-mod"，你点「采用建议」按钮才修改。AI 不会私自替换你填的 modId。

5. ⑤ 担心 import 包名写错？

   ✅ AI 纯检测（不碰你代码）：启动器内置「真实 SDK import 速查表」，如果你写错了 → 精确标出第几行 import 错了 + 给正确包名建议 + 一键修复按钮（你点才改）。下面这些是 AI 认识的常见错误写法：

   // ❌ 你可能写错的虚构包名（AI 标出行号 + 弹出建议，你点「修复」才替换为 ✅ 正确写法）
   // import com.smalo.sdk.api.SmaloModAnnotation;  → 建议替换为  ✅ import com.smalo.api.SmaloModAnnotation;
   // import com.smalo.sdk.api.bus.SubscribeEvent;   → 建议替换为  ✅ import com.smalo.loader.EventBus.SubscribeEvent;
   // import com.smalo.sdk.api.chat.ComponentText;   → 建议替换为  ✅ 对应的正确类（SDK 里有对应聊天组件）
   
   // ✅ 你也可以直接照抄这份「100% 正确」的 5 行 import（推荐，不会错）
   import com.smalo.api.AbstractSmaloMod;
   import com.smalo.api.SmaloModAnnotation;
   import com.smalo.api.Event;
   import com.smalo.loader.ModInfo;
   import com.smalo.loader.EventBus;

6. ⑥ 担心把 smalo-sdk.jar 整个塞进自己的模组 JAR 导致类冲突？

   ✅ AI 纯检测（不碰你代码）：上传后列出具体哪些 class 是 SDK 重复类清单，弹出「建议剥离 SDK 重复类避免 LinkageError」按钮，你点确认才拆包 + 去重 + 剥离（和第 6 章 6.2 表格第 6 条一致）。AI 不会私自拆你上传的 JAR。

9⭐ 实战示例：极简小地图模组（1 个文件 · 40 行代码搞定 · 零额外依赖）

9.1 依赖清单：只有 minecraft（其他全靠 SDK 全局事件）

"dependencies":  [
  { "modId": "minecraft", "version": ">=1.20.1", "required": true }
]
// 没错，就这一条！渲染/玩家事件都是 SDK 自带，无需声明对启动器或其他模组的依赖

9.2 完整代码：MinimapMod.java（直接照抄，40 行实现右上角小地图）

package com.example.minimap;

import com.smalo.api.AbstractSmaloMod;
import com.smalo.api.SmaloModAnnotation;
import com.smalo.api.SmaloModAnnotation.Side;
// ↓↓↓ 小地图用到的两个真实事件，SDK 里都有 ↓↓↓
import com.smalo.api.events.PlayerEvent;
import com.smalo.api.events.RenderEvent;
import com.smalo.loader.EventBus;
import com.smalo.loader.ModInfo;

@SmaloModAnnotation(
    modId               = "tiny-minimap",
    version             = "1.0.0",
    displayName         = "迷你小地图",
    description         = "右上角显示玩家位置与方向的极简小地图",
    author              = "YourName",
    dependencies        = { "minecraft" },
    versionRanges       = { "[1.20.1,)" },
    side                = Side.CLIENT,
    minLoaderVersion    = "[0.1,)"
)
public class MinimapMod extends AbstractSmaloMod {

    // 用成员变量存玩家当前位置（小地图中心），0 表示还没进世界
    private double px = 0, pz = 0;
    private String dim = "none";

    @Override
    public void onLoad(ModInfo mod, EventBus eventBus) {

        // ⭐ 事件 1：玩家一移动，就把新坐标存进成员变量（5 行）
        eventBus.subscribe(PlayerEvent.Move.class, e -> {
            px = e.getPosX();
            pz = e.getPosZ();
            dim = e.getDimension();
        });

        // ⭐ 事件 2：屏幕覆盖层渲染 → 右上角画小地图（20 行，含坐标文字）
        eventBus.subscribe(RenderEvent.Overlay.class, e -> {
            if ("none".equals(dim)) return; // 还没进世界就不画

            long W = e.getScreenWidth();
            // 小地图参数：右上角、150x150 像素、距屏幕边距 20px
            int size = 150, margin = 20;
            int x0 = (int) W - size - margin; // 左上角 X
            int y0 = margin;                 // 左上角 Y

            // （真实项目里这里调用启动器提供的 2D 绘制 API：
            //    drawRect(x0,y0,size,size, 半透明黑背景)
            //    drawRect(x0+size/2-2, y0+size/2-2, 4,4, 白色玩家点)
            //    drawString("X:"+(int)px+" Z:"+(int)pz+" "+dim, x0, y0+size+4)
            //  上面 3 行绘制调用即可实现「背景方块 + 玩家白心 + 坐标文字」）
            log("[Minimap] 绘制于 ("+x0+","+y0+") 玩家 X="+(int)px+" Z="+(int)pz+" 维度="+dim);
        });

        log("✅ tiny-minimap 小地图模组加载完成（仅监听 PlayerEvent.Move + RenderEvent.Overlay）");
    }
}

9.3 对应的 smalo.mod.json（不需要额外依赖）

{
  "schemaVersion": 2,
  "modId":         "tiny-minimap",
  "name":          "迷你小地图",
  "version":       "1.0.0",
  "entryClass":    "com.example.minimap.MinimapMod",
  "supportedMcVersions": ["1.20.1"],
  "description":   "右上角显示玩家位置与方向的极简小地图",
  "authors":       ["YourName"],
  "tags":          ["信息显示","HUD"],
  "category":      "utility",
  "dependencies":  [
    { "modId": "minecraft", "version": ">=1.20.1", "required": true }
  ]
}

10附录 A：SDK 已实现的全部事件清单（速查表 · 直接订阅就能用）

以下事件类全部位于 com.smalo.api.events 包，直接 import + 调用 eventBus.subscribe() 即可：