新建插件与插件规范

Apollo 插件是一组网络服 Mod 的集合，实现独立完整的功能。这一篇讲怎么用工作台新建插件，以及官方插件开发规范——即便是自用插件，也强烈建议遵守，能避免冲突、便于协作和二次开发。

用工作台新建插件

1. MC Studio「创作」分页 → 新建基岩版服务器
2. 点空白插件的新建按钮，弹出新建插件窗口（基岩版服务器 - 插件分页也有此入口）
3. 填团队名称、插件名称等并勾选，点创建
4. 创建完成的插件直接显示在工作台中

命名规范

团队名与插件名

名称	规则	示例
团队名	全局唯一，小写英文+数字、不以数字开头，≤10 字符	netease
插件名	与功能相关，小写英文+数字、不以数字开头，≤20 字符	announce

目录命名（驼峰、团队名开头）

插件强制按服务器类型分目录，每种服务器一个目录，用驼峰法、以团队名开头：

服务器类型	目录命名	示例（团队 lovecraft / 插件 guild）
大厅服/游戏服	团队名(小写) + 插件名(首字母大写)	lovecraftGuild
控制服	上述 + Master	lovecraftGuildMaster
功能服	上述 + Service	lovecraftGuildService

插件目录结构

以大厅服/游戏服插件 lovecraftGuild 为例：

lovecraftGuild
├── mod.sql              # SQL 语句（utf-8），非必须
├── readme.txt           # Mod 介绍（utf-8），必须
├── server.properties    # mc server 配置，非必须
├── behavior_packs       # 行为包
├── developer_mods       # 服务端 mod
├── resource_packs       # 资源包
├── worlds               # 地图
└── studio_res           # 美术资源工程导出文件（不影响运行）

四个包目录的根目录命名规则（均以团队名+插件名开头）：

目录	包根目录后缀	代码根目录后缀
behavior_packs	Behavior	Script
developer_mods	Dev	Script
resource_packs	Res	—

如 behavior_packs/lovecraftGuildBehavior/lovecraftGuildScript（代码从 Script 目录起 import）。控制服/功能服只含 developer_mods，规则同上。

配置文件规范

mod.sql

• 涉及多服时，mod.sql 只放一种服下，优先级：功能服 > 大厅服/游戏服 > 控制服
• 用 MySQL、InnoDB、编码 utf8mb4、文件 utf-8
• 表名以团队名+插件名开头（如 lovecraftGuildXx）
• 所有版本的 SQL 都放 mod.sql，用注释分隔不同版本

-- ###########################version1.0.0####################
create table lovecraftGuild(
    id int unsigned not null COMMENT '唯一id'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

mod.json

记录插件全部可改配置，能改的属性都放这里（用 _comment 加注释）：

属性	含义
netgame_mod_name	插件名字
netgame_mod_version	版本，从 1.0.0 起
min_app_version / max_app_version	最低/最高引擎版本（后者不配=不限）
support_server_type	支持的服类型：game/lobby/master/service
author	团队名
group	插件所属功能（多插件同功能时设为一样）
module_names（service 需要）	service 模块名，与插件名一致，用于 RPC 调用

readme.txt

必须，构成固定：插件介绍 → 插件构成 → 使用步骤 → 插件 API → 插件 event → 运营指令 → 更新记录。type 统一用 bool/int/float/str/dict/list(str) 等；缩进用空格、utf-8。

server.properties

放在插件里的 server.properties 会在部署时自动拼接到服务器的 server.properties，所以只写需要的属性即可。文件末尾需有空行。

client-side-chunk-generation-enabled

2.5 版本后新增字段，控制是否开启客户端本地地图生成。若地图大部分不是自然生成的（除生存服外基本都是），配 false。

界面开发注意

显示/隐藏整个界面

强制用 uiNode.SetScreenVisible(True/False) 显示/隐藏整个 json 界面，别用逐个 SetVisible 控件的方式。

界面分层

所有弹出界面（会阻挡摇杆/攻击的界面）都要按用途分到不同层，初始化后用 uiNode.SetLayer("", int) 设置层次。层次宏在 minecraftEnum.py：

层	值	用途	是否需 SetLayer
Desk	0	主界面常驻（如主菜单按钮）	否
DeskFloat	15000	主界面浮动提示	否
PopUpLv1	25000	一级弹出界面	是
PopUpLv2	45000	二级弹出界面	是
PopUpModal	60000	模态弹出（提示确认）	是
PopUpFloat	75000	模态之上的浮动提示（大喇叭）	否

import client.extraClientApi as clientApi
clientApi.RegisterUI("neteaseAppear", "shop", "neteaseAppearScript.appearShopUi.ShopScreen", "netease_appear_shopUI.main")
clientApi.CreateUI("neteaseAppear", "shop", {"isHud": 1})
shopUI = clientApi.GetUI("neteaseAppear", "shop")
shopUI.SetLayer("", clientApi.GetMinecraftEnum().UiBaseLayer.PopUpLv1)
shopUI.SetScreenVisible(False)

界面分层是插件不冲突的关键

多个插件的界面共存时，分层错乱会导致界面互相遮挡。老实按用途 SetLayer——这是插件规范里最容易被忽视、又最容易出问题的一条。

美术资源命名

手机系统区分大小写，所以美术资源目录/文件名强制用小写英文 + 下划线（不用驼峰）：

• UI JSON：必须用 Studio 界面编辑器生成，文件名以 团队名_插件名_ 开头（如 lovecraft_guild_create.json）
• 界面贴图：放在 textures/ui/团队名_插件名/ 下
• 模型/特效：经编辑器导出，文件名以 团队名_插件名_ 开头
• 自定义物品/实体：identifier 用 团队名+插件名（如 lovecraftGuild:xx），json 文件名用 团队名_插件名_xx.json

---

规范打底后，下一篇调整地图插件——把官方插件套到你的地图上。回到基岩版网络游戏首页。