Addon API

附属接口文档

首页 ｜ 使用手册 ｜ 下一页：三分钟做一个 App

给附属模组开发者：做一个手机 App、画在手机屏幕里、往应用商店里塞东西、给操作定个价。

App 系统通过 SPI 开放，你的模组不需要被 MCphone 感知也能往手机里装 App。内建 App 走的是同一套机制，没有走后门。

项	值
对外包	com.november.mcphone.api
API 代号	MCphoneApi.VERSION = 1
兼容承诺	五条
构建	NeoForge + ModDevGradle

只有 com.november.mcphone.api 这一个包对外。 其余（core、feature、compat、util）都是内部实现， 随时会改名会消失，别引用。这条规矩写在 MCphoneApi 的第五条里。 唯一的例外是浏览器后端，那一页专门交代它为什么还在 feature 下。

本文档分几页

页面	内容
三分钟做一个 App	依赖、四个方法、SPI 文件、语言与贴图
IPhoneApp	一个 App 的全部方法：签名、默认值、调用时机
IPhonePage / PhoneCanvas / PhoneStyle	把界面画在手机屏幕里
IAppSource / AppInfo	自定义应用商店来源
ICost 家族	定价、扣费、接一个 EMC 来源
版本与两端安全	五条兼容承诺、VERSION 怎么判、哪些能在服务端碰
浏览器后端	IBrowser / IBrowserBackend，唯一一个不在 api 包里的扩展点
⚠ 非踩不可的坑	上面几页里所有警告的集中版，写完代码对一遍

---

一张总表

"起于"指在现在这个包名下从哪一版开始有——包名也是 API，挪过包的类按挪完那一版算。

类型	干什么	怎么注册	哪一端	起于	详见
client.app.IPhoneApp	一个 App	SPI	仅客户端	1.0.46	→
client.app.RequiredMod	前置 / 联动模组的声明	记录，直接 new	仅客户端	1.0.46	→
client.ui.IPhonePage	画在手机屏幕里的一页	IPhoneApp.openPage() 返回	仅客户端	1.2.13	→
client.ui.PhoneCanvas	一帧的绘制上下文	MCphone 传给你	仅客户端	1.2.13	→
client.ui.PhoneStyle	手机当前的配色	canvas.style()	仅客户端	1.2.13	→
client.store.IAppSource	商店里的 App 从哪来	SPI	仅客户端	1.0.46	→
client.store.AppInfo	商店列表里的一条	AppInfo.builder() / of()	仅客户端	1.2.12	→
cost.ICost	「要花点什么」	直接构造	两端	1.0.40	→
cost.ItemCost / cost.EmcCost	ICost 的两个实现	直接构造	两端	1.0.40	→
cost.IAppPriceProvider	给 App 报价	SPI	两端	1.0.40	→
cost.IEmcWallet / cost.EmcWallets	接一个 EMC 来源进来	EmcWallets.set()	两端	1.0.40	→
MCphoneApi.VERSION	API 代号	读常量	两端	1.2.12	→

SPI 注册

三个接口走 SPI。服务文件放 src/main/resources/META-INF/services/，文件名就是接口全名，内容是你的实现类全名，一行一个：

com.november.mcphone.api.client.app.IPhoneApp
com.november.mcphone.api.client.store.IAppSource
com.november.mcphone.api.cost.IAppPriceProvider

⚠ 一个附属构造失败不会中断整个扫描（见 util/SpiLoader），但那个 App 就是没了，而且只在日志里留一行。 别指望它兜底 —— 见坑 · SPI 构造失败是静默的。

有没有现成的例子

有：november521/mcphone-deepseek，MCphone 的第一个附属，一个 DeepSeek 对话 App。

它用到了 IPhoneApp + IPhonePage + PhoneCanvas + PhoneStyle，纯客户端，独立仓库，可以整个抄结构。

这份文档不会烂掉

本文档所有示例代码都躺在 docs/AddonApiExamples.java 里， 照抄一份。它只要求编得过，跑不跑无所谓：

CP="build/classes/java/main:build/moddev/artifacts/neoforge-<版本>-merged.jar:$(tr '\n' ':' < build/moddev/serverLegacyClasspath.txt)"
javac -cp "$CP" -d /tmp/doccheck docs/AddonApiExamples.java

谁改了 API 的签名，这个文件当场编不过——那就是"该回来改文档了"的信号。文档里的方法名、参数顺序、返回类型全靠它守着，不靠人记得。

---

首页 ｜ 下一页：三分钟做一个 App