# 开发手册

欢迎你报名本届 TeaCon ！

本手册将简述关于 TeaCon 参展流程中代码相关的细节，尤其是那些可能会影响展出的细节。因此，本手册的预期读者是各参展团队的开发者，换言之就是写代码的那些人。

如果你是建筑师，你可能想浏览[建筑手册](/doc/9c12b5f9-ae2c-44cb-87c7-c190d86b8459)，而不是这个。


:::info
# 写在前面

虽然我们会全力保证尽可能多的内容得以展示，但是因为 TeaCon 展示服的公开性质，我们用于维持基本参观秩序的大量基础设施模组仍然有可能会制约你能展示的内容。鉴于此，请完整阅读本手册，我们在下文中详细解释了 TeaCon 展示服与一个通常的 Minecraft: Java 版 服务器有何不同。

以下提及的所有内容，如果你的模组确有需要涉及，请遵循对应的指引操作。必要时，请在配置文件中留下开关，并联系茶馆员工商讨具体细节。

如果您对这些内容有疑问，或有本手册未讨论的特殊问题，请联系茶馆员工。

:::


# 有多少个服务器？

从技术角度来说，TeaCon 服务器总数不定，但可以分成三类：

| 服务器 | 数量  | 可以用来…… | 不可以用来…… |
|-----|-----|--------|---------|
| 测试服 | 1   | * 拦截自动化测试不容易发现的 Bug； <br> * 大范围、破坏力大，压力大的测试； <br> * 测试你的模组和其他模组之间的兼容性； <br> * ~~反复崩服。~~ | * 搭建展馆（存档会在每次重启后重置）； <br> * 参观（也没有可以参观的内容）。 |
| 建筑服 | 1   | * 搭建展馆。 | * 测试新内容。 |
| 展示服 | >= 1 | * 让游客参观。 | * 测试新内容； <br> * 搭建展馆。 |

# 服务器上有哪些模组？

出于展馆搭建需要，并为维持基本参展秩序，方便游客参观，展示服会预装一系列模组。我们统称为「基建模组」。

这些模组无需在前置中报名：你可以假定这些模组在我们的服务器上一定存在。

*本列表可能会随时间更新。请定期查阅。*

*列表即将到来*

# 如何提升我的作品到测试服/建筑服/展示服？

默认情况下，你的作品不会被自动加入任何一个服务器。

如果你确信你的作品已基本完成且稳定，你可提升作品到测试服。此时，请前往「碧螺春」，打开「参与构建」。如果你未能在截止时间前产出第一个可正常运行的版本，你的作品将被强制退赛。

TeaCon 参展作品持续交付系统「龙井」会全天候跟踪你的作品的最新提交，并在发现新提交时打包最新版本（延迟至多半天）。此后，如果构建正常，你的作品会出现在测试服上，但不会自动进入建筑服或展示服。**如果构建失败，你会收到相关邮件。**

**请在测试服上充分测试你的作品。**

在展示服开启后，如果你确认当前版本没有导致服务器崩溃的问题后，可以点击「提升测试版本」，将当前测试服的版本提升到建筑服。请注意：如因模组漏洞导致建筑服或展示服崩溃，您可能会被扣除乌龙分（参阅：[乌龙分手册](/doc/0e3dfdc6-8630-4e1b-91de-5eaad9375830)）。如果你未能在截止时间前产出第一个可正常运行的版本，你的作品将被强制退赛。

在茶馆员工认为当前建筑服的模组和地图状态稳定时，建筑服的模组和地图数据会提升至展示服。


# 展示服

为了让尽可能多的玩家同时参观，TeaCon 展示服由多个 Minecraft 服务端组成，我们称之为「分服」。

## Kubernetes（K8s）

展示服使用容器技术。所有分服皆受其统一调度。

根据我们的经验，你几乎不可能遇到由他导致的问题。

## 冒险模式

为了服务器（在各种意义上的）安全，所有进服参观的游客都是「冒险模式」。

你应该确保你的模组和展馆设计不会（有意或无意地）使游客能切换到其他模式。

如果你希望使用某些生存模式才能达到的功能，请优先考虑使用 AreaControl 和原版标签。

## 预制地形

展示服中，主世界场地使用预制地形，而非基于原版世界生成器的程序化生成地形。主世界没有模组添加的新地物（Feature）、结构或其他生成产物。

若你需要展示世界生成，我们建议直接把生成出的方块或结构当展品摆出来。

## 存档同步与重置

「分服」的存档本质上是建筑服的备份存档。所有分服启动时，都会使用来自建筑服的全新备份存档，重启前地图上的任何修改都会消失。有鉴于此，您的展馆必须设计为「即使重置了也不影响展出」的样子。

唯一的例外是玩家数据：所有「分服」共享一套玩家数据，故玩家数据不受上述机制影响。这保证了玩家在第一个分服下线，再在第二个分服上线后，其背包里的物品保持原状。**如果你确实需要在多个分服间共享和玩家相关的数据，请按照 NeoForge** [**DataAttachment 文档**](https://docs.neoforged.net/docs/datastorage/attachments) **创建附着到玩家的实例，并在玩家退出游戏时保存它们。TeaCon 的服务器基础设施会自动在玩家切换到其他服务器时同步他们。**

出于内部需要，我们有办法长期保存某些非玩家信息（例如 VoteMe 的投票信息），但需要走完复杂的适配流程，且你可能不会在其他地方再次用到这些特殊适配。如果你确实需要保证某些存档数据在展示服重启后仍然存在，请尽早、及时与我们联系。


# 基础设施模组

你的模组可能和以下关键基础设置模组发生奇妙的化学反应——即模组冲突——请注意避让。

## AreaControl (AC)

这是我们自研的领地保护模组，用于保证展馆及展品免遭意外破坏。或者免遭蓄意破坏。

其保护机制可能会与你要展出的玩法和内容有冲突，但你可以根据需求选择性关闭其保护机制。查阅 AreaControl 的使用指南以了解详细信息。

## Not Enough Bandwidth ++ (NEB)

这是 TeaCon 自研的带宽优化模组，用于压缩服务器与客户端之间的通信开销。

NEB 设计原则上对其他模组透明，但仍然有小概率与某些模组不兼容。我们目前未收集到足够多的案例，但如果你确实遇到了相关问题，请尽早、及时与我们联系。

## ProjectMe (玩家投影)

因为展示服有不止一个，玩家登入展示服的时候会随机选一个进入。如果没有特殊处理，身处两个不同分服的玩家互相看不到对方——毕竟他们不在一个服务器上。

ProjectMe 便是试图缓解此问题的一个小 Mod。他能把其他服务器上的玩家「投影」到你当前所在的服务器上，让你们看起来像是在一个服务器里。

然而这只是玩家的「投影」。这些影子一旦遇到交互就会露馅儿：你给影子丢一个物品，影子是捡不起来的；在影子玩家所对应的真服务器上也看不到你丢出的物品；攻击影子也显然不可能，你会一拳打在空气上。

一般来说，你不需要专门去适配这个。我们有一套能让组团参观的玩家尽可能身处同一服务器的机制，如此便可保证他们不受「影子」机制的影响。

## Sodium、Iris 与 Replay

我们在录制宣传片、截图、直播活动时可能会使用这些模组。

请确保您的模组与其至少有最基本的兼容性，不会在录制宣传片、应用光影包时崩溃或出现明显的渲染错误。

---

**Documents**

- [遇到问题？](https://wiki.teacon.cn/s/2026/doc/6ygh5yiw6zeu6aky77yf-NgdPosCpsy)
- [选手公告栏](https://wiki.teacon.cn/s/2026/doc/6ycj5oml5yws5zgk5qcp-vFzxUq952K)
- [参展参赛指南](https://wiki.teacon.cn/s/2026/doc/5yc5bgv5yc6lwb5oyh5y2x-3D3GdnKXep)
- [基础建设模组使用指南](https://wiki.teacon.cn/s/2026/doc/5z656ga5bu66k65qih57ue5l255so5oyh5y2x-S3YP8OWfo5)
- [展馆内测前自查单](https://wiki.teacon.cn/s/2026/doc/5bgv6aag5yaf5rwl5ymn6ieq5pl5y2v-vt4GaCsKlT)