MCphone 自身没有任何前置。缺了谁都照常开机，只是少那一个 App。

未安装对应模组时，依赖它的 App 不出现在主屏和应用商店的普通列表中——商店里放一个点了必然报错的东西，比它不存在更糟。缺了什么则由商店的「联动App」页回答。

工作台合成，一次一部：

玻璃 玻璃 玻璃
红染料 黄染料 蓝染料
铁锭 红石 铁锭

开机与关机

Esc 不分层级：开到哪一页按下去都是直接关机；要退一层走 ◁。

按键一览

模组注册的五个键，均可在原版「选项 → 按键设置 → MCphone」中改：

五个默认键在 Minecraft 1.21.1 原版中均未被占用。此外每个 App 还能各绑一个自己的快捷键，见每个 App 一个快捷键。

拖动排序

按住图标直接拖动即可换位，其余图标实时让位，松手落定。

分页

只有一页时画一个孤零零的点，会让人以为还能往旁边划。翻页三种方式：

翻页动画 160 毫秒。

把 App 挪到别的页

拖着图标停在屏幕左右边缘：边条（宽 10 像素）由浅到深亮起，停满 0.4 秒 自动翻页，手不必松开。

不是「碰到就翻」：拖向最右一列的路上必然扫过右边条，一碰就翻的话最后一格永远放不进去。

G 顶掉自动那条规矩，而不是与之并列：手机在副手上时按 G 也能收起，否则会出现「按了没反应」。副手上的手机被拿走或换掉后，自动那条重新生效。

按 Alt 唤出鼠标，再按一次收起 ——是切换，不是按住。唤出后可以翻页、点 App、在输入框里打字。

挂着的和 Alt 里的是同一部手机，不是两块屏：在 Alt 里翻到第三页，收起之后 HUD 上还是第三页。唤出鼠标期间是原版界面状态，人不会走动。

「设置 → 副手 HUD」里可开关、调大小与位置；也可以就地摆——拖边框或状态栏挪位置，滚轮缩放。

位置按锚点 + 偏移记录，换分辨率、改 GUI 缩放之后仍停在原处。

HUD 的大小与「设置 → 界面大小」是两个独立的数：一个管挂在画面上那部，一个管全屏打开那部。

均可在原版「选项 → 按键设置 → MCphone」中改键。

config/mcphone-client.toml：

取景框 + 分帧截图。照片存进游戏目录的 screenshots/，与原版 F2 截的图放在一起。

均可在原版「选项 → 按键设置 → MCphone」中改键。

快门闪光：白闪或模糊

在「设置 → App 管理器 → 相机」中，「快门闪光」一行点击即在两者间切换。

闪光持续 220 毫秒。两种都不会进照片 ——闪光在抓图完成之后才开始。

模糊借用原版菜单背景那条后处理链，不额外附带着色器文件；半径随时间收敛，因此是化开又收回，而非硬切一块糊画面。

白闪是照相机的惯例，但在夜间或暗处拍照时会把屏幕顶到全白，眼睛需要缓几秒。模糊同样交代了「拍下来了」，而不改变亮度。

设置项为客户端级，存于 config/mcphone-client.toml。

右上角「打开文件夹」用系统文件管理器直接打开截图目录。

相册也是美西螈发图时的图片来源；聊天里收到的图可以存进相册，存的是原始文件。

外放没有暂停：原版音效系统中不存在「从中间接着放」。两条路可同时发声。

装了 NetMusic 后，唱片仓同时接收它刻录的 CD：用其电脑方块搜歌、刻成 CD，放入手机后按播放，走到哪儿放到哪儿。

网络音乐能外放而本地文件不能，原因在于服务端只需广播一个地址，每个客户端各自去拉取。搜歌、登录、会员、刻盘均属 NetMusic；本模组只接手「播放」这一件。

放入 config/mcphone/music/ 即可，进入音乐 App 会自动重扫，无须重启游戏。

MP3 只支持 MPEG-1

这是所打包解码库的限制，对应其 issue #8。

不可播放的文件不会静默失败：曲库中该行置灰，悬停提示「MPEG-2 放不了，只认 MPEG-1」，日志中记录完整规格：

[MCphone] 打开 MP3 我的歌.mp3 —— MPEG-1 Layer III, 44100Hz, 立体声, 320kbps
[MCphone] 放不了 local:老歌.mp3：MPEG-2 Layer III, 22050Hz, 单声道, 64kbps。
 这个播放器只认 MPEG-1（44100 / 48000 / 32000 Hz），请转成 44.1kHz 再放进来

用任意转码工具转成 44.1kHz 的 MP3 即可，或转成 OGG。

循环模式与音量存于 config/mcphone-client.toml：

音量为该 App 自身的音量，最终输出还要乘以游戏主音量与唱片音量。

显示游戏内时间与现实时间。

原版时钟只有一个转盘，看得出大概是白天还是晚上，看不出「几点」，也看不出「还有多久天黑」——而后者才是玩家真正在问的问题。

换算基准

换算逻辑集中在 feature/clock/WorldClock，该类不接触 Minecraft，可单独跑断言。时间算错既不会崩溃也不会报错，只会让所有人的时钟差 6 小时。这类错误必须在进游戏之前就拦住。

显示当前天气，以及这种天适合做什么。

「现在下不下雨」抬头就看得见；有意义的是后半句：下雨适合钓鱼（雨天上钩快），打雷是抓高压苦力怕的时候，下雪可以拿铲子收雪堆雪傀儡。这些都是原版真实存在的机制。

六种天

六张图标均为 32×32，位于 assets/mcphone/textures/weather/，见换肤。

判定逻辑集中在 feature/weather/Weather，同样不接触 Minecraft，可单独跑断言。沙漠、雪山、下界这几种情况在自己的存档里根本试不出来，而判错了不会崩溃——手机只会在沙漠里说「正在下雨」。

加好友需对方同意。在右上角的「+」中从当前在线玩家里点选，对方在同一界面同意或拒绝；两人同时点「添加」直接成为好友。

输入栏左侧的「+」中有两项：图片与表情。

图片

即相册内容：相机 App 拍的、按 F2 截的都在其中，选中点击即发送。

表情

存放于 config/mcphone/stickers/，跟随客户端，换服务器、换存档均保留。导入方式两种：

• 把图片拖入游戏窗口（表情页开着时为「收进来」而非「发出去」，可一次拖入整包）
• 点该页右上角「打开文件夹」，用系统文件管理器放入

压缩

发送前客户端先行压缩：

雨天、树叶一类满屏噪点的截图 PNG 压不动，是走到第 2 步的主要情形。

不存原图：手机放大看图时也只有 448×680 个真实像素，存原图只是占用服主硬盘与所有人的带宽。

动图

GIF 表情发出后在对方手机上是动的：拆成帧、拼成一张雪碧图传输，播放在客户端完成。

表情页格子中显示的是第一帧——该页不做动画。

接收与保存

收到的图片直接显示，不套气泡。

动图存进相册的是第一帧 ——相册是给截图用的，动图放进去别处都读不了。

图片过期

保留该行而不删除：整条删去会使聊天记录凭空缺失若干句，且缺失的内容无从追溯。文字消息不受此限制，仍为每对会话 100 条。

服主可整个关闭图片功能，见服务端配置。

在线好友那一行的右下角有一个 7×7 的图标，点击即传送，手机同时自动关闭。

鼠标悬停时图标点亮，该行第二行的消息预览临时替换为「传送到他身边」。

对方恰在点击瞬间下线时提示「对方已经不在线了」——在线状态 3 秒刷新一次，这几秒的空档撞得上。图标放在右下角，是为了不与未读数、时间挤占位置，名字也不必让出宽度。

价格由内建的报价来源 feature/store/BuiltinAppPrices 声明，机制见IAppPriceProvider。

随手记录文字。

随身打开自己的末影箱。就是原版那一个，与方块末影箱、跨维度完全互通。

打开传送石碑的选点界面，前往任意一个已激活的传送点。

该价格仅在注册表中确实存在该物品时才登记——Waystones 缺失时这个 App 本身就不会出现。

它是唯一一个跳出机身的 App：手机屏幕为 120×200 像素，网页在其中一行正文放不下十个字，因此点开后是一块占屏幕九成的居中面板，退出即回到手机。

面板上方一条高 22 像素的工具条：后退、前进、刷新、地址栏，右侧圆点为加载指示。工具条位于面板之外，浮在面板上方的留白里，不占用网页高度。

输入内容按以下顺序判定：

MCEF 自带的快捷键可用（macOS 上以 ⌘ 代替 Ctrl）：

成因在 MCEF：它没有注册 CefLifeSpanHandler，而离屏渲染下也没有窗口可开，于是点击不产生任何效果。变通办法：把地址复制进地址栏手动打开。

浏览器后端本身是一个可替换的扩展点，开发者侧见浏览器后端。

底部两个页签：

收藏靠每行右端的 ☆：点一下进书架，再点一下移出。不用长按、也不另开菜单——长按在这种小屏上没有任何提示，等于把功能藏起来。

按存档分的结果会是「同一个包、换个服务器书架就空了」：书来自客户端装的模组，同一个整合包连到哪个服务器都是那几本。

两个页签顶部都是搜索框，进入该页时它已持有焦点，直接打字即可。可搜三个字段：书名、模组名、模组 id。中文客户端里书名是中文、出处是英文很常见；只搜一个字段就会出现「我明明记得这个模组叫什么，却搜不到它的书」。

排序规则

结果按分数从高到低排列：

多个词

用空格分开，是与的关系，各词可以命中不同字段（例：ars 笔记）。任一词未命中，整本即不算命中；整本的分数取最弱那一项的分。右上角的数字在搜索时变为「命中 / 总数」。

按键

这一页吃掉所有按键（含背包键），与记事本、设备命名几页相同：打拼音必然按到 e，不吃掉就成了开背包。ESC 照旧直接关机。尚未实现拼音搜索（xsmy → 新生魔艺），那需要一张拼音表。

点开一本书后，接管屏幕的是它自己的界面，进度、已读标记、条目锁定全部对得上，与在背包里右键该书一致。

本模组只提供目录：Patchouli 的书界面是 272×180，手机屏幕只有 120×200，放不下；而自行重画就要把它几十种页面类型重新实现一遍，它一改版即断。

GuideME：一次全收

AE2 的作者把自家手册系统拆成了独立模组 GuideME，AE2 与现代化工艺都硬依赖它。GuideME 自身即具备「列出全部手册」的能力，因此这一支是自动发现——不写死任何一本书的 id，将来第三、第四个模组接上它，书城里自动就有。

点开走的是它手册物品右键那条路，因此在手机里点开与在背包里右键进入的是同一个界面、同一段历史。图标是它为每本手册创建的那个物品。

白名单：非 Patchouli 的手册

有的模组自写了一整套手册系统，与 Patchouli 无关，扫描扫不出来——沉浸工程的《工程师手册》是第一个。这类书走一份写死的白名单，每条记录它出自哪个模组、用哪个物品作图标与书名、以及如何打开。打开走的是它自己物品右键那条路（ManualHelper.getManual().getGui()），连「停在上次看的那一页」都一致。书名取自该物品的名称，与背包、JEI 中显示的是同一行字。

新增一个模组：写一个 ExternalBook 实现，向 ExternalBookSource 的白名单加一行。对方未安装时自动跳过。

无对应物品的书

有些模组的书是 no_book 的，游戏内没有对应物品，只能用命令打开。它们在这里同样列出并可打开，图标使用默认的书。

有些模组把自己的手册整个换掉了，Patchouli 中只剩一本无人维护的旧书。这类由「书籍特例」层处理，它能做三件事：把某本书从架上移除、改写其显示、接管「点开之后打开什么」。

新增一条：写一个 BookQuirk 实现，加入 BookQuirks 的名单。对方未安装时自动跳过。

这类代码一律走反射、不加编译依赖：为一个方法引入几十 MB 的前置不值，且断了要能退回默认行为（打开那本遗留的 Patchouli 书），不能变成一个点了没反应的死按钮。

任务书是一局里翻得最勤的东西——每做完一件事就要回去看下一步。而它是个物品：要么长期占着快捷栏一格，要么每次都得回箱子里翻出来。这一格把它变成「开机 → 点一下」，书仍在原处，只是不必随身携带。

FTB Quests 缺失时，本 App 不出现在主屏与商店的普通列表中，但商店的「联动App」页照常列出它并写明缺哪个模组。

点开后接管屏幕的是它自己的界面，章节、进度、领奖、编辑权限全部对得上，与在背包里右键那本书一致——所调用的正是那本书右键时执行的那一句。

加了的话玩家点下去只会得到静默无反应；交给它，玩家看到的和右键实体书时是同一句话。

任务档案本身即同步在客户端，开界面也在客户端，服务端不会多收一个包。

接触面只有一个零参方法，走反射、不加编译依赖，理由与阅读的几支书源相同，写在 feature/quests/client/FtbQuestsBook.java 的类注释里。

任务书在绝大多数整合包里是开局白送、丢了还能再做的，卖它没有对应物；而这个 App 存在的意义就是少走几步，埋进商店等玩家自己发现，等于第一步就多走了。

收进书城的话每次都要走「开机 → 阅读 → 从几十本里找到它 → 点开」，比拿实体书还慢——多那一层列表，这个 App 就没有存在的必要了。

装了哪几家，App 详情页的简介末尾会写出来。

手机内置一个终端卡槽。点开「终端」时：

它解决的是「身上带着好几台，到底开哪一台」：答案从「背包顺序里第一台」变成玩家自己选的那一台。

卡槽里的终端死亡不掉落，与壁纸、笔记、唱片仓中的唱片一样跟随玩家。

这一条是刻意的：终端一旦收进手机就不在背包里，各家自己的快捷键（AE2WTLib 的补货／磁铁／收纳、RS 的打开无线网格）便找不到它。想用那些快捷键的人不装卡槽即可，代价只是多按一下。

因此它放不进卡槽；背包里带着它点「终端」会跳过它并说明原因——比点了没反应要好。要隔空打开，用高级那把。

加了自己的检查，两套规则迟早对不上，而对不上的表现是「手机上说不行、手里拿着又能开」。

末影箱那一格卖一个末影箱、传送石那一格卖一个传送石，因为 App 本身就是那件实物的替代品。这一格替代不了任何东西——它开的是你自己那台终端，没有终端它一格内容都没有。真正的门槛是那台终端，再收一次等于收两遍。

App 也可以由附属模组自带的来源提供，见IAppSource。

商店最后一格是「联动App」，排在所有可下载 App 之后。点进去一行一个列出：图标、名字、缺哪个模组、已装还是未装。未满足的整行压暗，看得见、点不动。

它回答的是「我怎么没有这个 App」——依赖缺失的 App 不出现在主屏与商店普通列表中，否则玩家会点到一个必然报错的图标；但完全不出现，玩家也就无从知道自己缺了什么。

手机内「设置 → 关于」的联动模组列表则一律列出这些模组，并标明装没装。开发者侧的声明方式见 companionMods()。

列出已安装的每一个 App。点一行进入它自己的一页：图标、名字、作者、版本、介绍，以及它由哪个模组提供、所声明的前置与联动模组装没装。

卸载在这一页，且需点击两次（第一次上膛、第二次才真卸），与相册删照片同一条规矩。系统 App 的卸载键置灰并写明原因。卸载后仍可从应用商店装回。

这一页往后是每个 App 的开关都该待的地方——操作区是一行一个的形状，加一个开关就是加一行。第一个这样的开关是快捷键，第二个是相机的快门闪光。

在「设置 → App 管理器 → 某个 App」中点击「快捷键」一行，然后按一个键。此后在世界中按下该键即直接开机并进入该 App。默认未指定。每个 App 各绑各的，已绑定的键显示在管理器的列表行上。

可绑定的键

左键是玩家在手机里点东西的那只手，等键时点一下即为取消；真绑上去的话，在世界中每挖一次方块都会开一次手机。绑在鼠标键上的 App 打开时不会顺带挥手或使用一次物品 ——那一下会被整个吃掉。

组合键

按住 Ctrl / Shift / Alt 再按主键即为组合，可叠加（Ctrl+Shift+K），鼠标键同样可以（Ctrl+侧键 4）。修饰键本身按下不算数，须按下主键那一刻才成立。macOS 上的 Command 即此处的 Ctrl。

触发要求完全一致：绑了 Ctrl+K，只按 K 不会触发，按 Ctrl+Shift+K 也不会。否则两个 App 分别绑这两个组合时，后者会连着前者一起响。

冲突处理

组合已被别的 App、或被原版／别的模组的键位占用时，该行变为「再按一次强制」并写明占用者；再按同一组合即强制绑定，此后该行常驻一个感叹号警示。

手机已经打开时按这些键不会切换 App——那时玩家多半正在手机里打字。

把任意尺寸的 PNG 放进 config/mcphone/wallpapers/，在这一页中选择。右上角「打开文件夹」用系统文件管理器直接打开该目录；点过之后这一页会盯着目录，拖进去的图切回游戏即可看见，无须退出重进。

把整个手机放大或缩小：拖动滑条，或点 − ＋ 每档 25%。

调整时手机（连同这一页本身）实时跟着变，无须另外预览。

贴合清晰倍数（默认开启）

配置键 uiScaleSnap。字体是位图、按最近邻绘制，因此每个像素是否方正只取决于一个乘积：GUI 缩放 × 界面大小。是整数则横平竖直；不是整数则有的列占两像素、有的占三像素，细线时粗时细。开启时档位自动对齐到 1 / GUI缩放：

− ＋ 一次正好走一档。关闭后可拖到任意值，代价是上述不匀。

六个预设，配置键 fontColor：

用了浅色壁纸就换黑色，否则浅底浅字看不清。选中即生效，无须重启。

给自己这部手机起名。起过名的手机在物品栏显示该名。

手机屏幕只有 120 像素宽，24 字已远超能显示的量。

手机拿在副手里时自动挂到画面上。开关、大小与位置在这一页，也可以就地摆——拖边框或状态栏挪位置，滚轮缩放。完整说明见 副手 HUD。

以上标注「客户端」的设置全部存于 config/mcphone-client.toml，跟随这台电脑，换服务器、换存档均保留。也可从模组列表的「配置」按钮进入修改。

服务端那一份（serverconfig/mcphone-server.toml）见服主须知 → 服务端配置。

手机里的输入框使用的就是原版按 T 那个聊天框的同一个控件，能否输入中文与原版完全一致。

store/button_disabled.png 是独立的一张，而非把可点的那张自动调暗：「不可点」该长什么样，由绘制贴图的人决定。

browser/panel.png 绝大部分会被网页盖住，真正看得见的只有加载中的空白期，纯色就够。browser/bar.png 那一条在面板外面，浮在面板上方的留白里，不占网页高度。

这四个位刻意使用通用名称：此后其他滑条（如音量）复用同一组贴图，只需绘制一次。

App 图标单独放在 app/ 下，文件名就是 App 的短名，都是 20×20：

app/settings.png app/app_store.png app/chat.png app/camera.png
app/gallery.png app/music.png app/ender_chest.png app/notes.png
app/waystone.png app/browser.png app/clock.png app/weather.png
app/reader.png app/quests.png

附属模组的 App 图标路径由它自己决定，见附属接口文档。

天气页那张大图标在 weather/ 下，六张 32×32：clear.png、rain.png、snow.png、thunder.png、dry.png、none.png，按当前是什么天各显其一。

尺寸不必精确匹配，贴图会被拉伸到目标区域。要不变形，按建议尺寸或其等比放大绘制即可。

模组自带图的倍数：

放大倍数取整数 ——非整数倍在低 GUI 缩放下会掉线条。

默认整张拉伸。不带元数据的贴图会被拉到实际大小，带圆角的图在宽气泡上抻长、在窄气泡上压扁，因此纯色或纵向渐变最稳妥。

要让圆角不变形，在 PNG 旁放一份同名的 .png.mcmeta：

{"mcphone_skin": {"border": 3}}

该图即改走九宫格：四角按源图上那 3 个像素原样绘制，只有四条边和中间被拉伸，气泡无论多宽多高，四个角都一样大。

自带图中使用九宫格的有五张：

因此模组在有贴图时改用别的表达：

绘制贴图时不必自行表达这些状态。半透明有效：alpha 介于 0 与 255 之间的像素会正常混合，抗锯齿边缘、整块半透明的底（「壁纸上压一层暗色」这类效果）都可以画。1.7.40 之前这类像素会被当作不透明绘制，边缘发硬、半透明的底变成实心。那是模组的缺陷，不是贴图的问题。

生成完整清单（含每个位现有的图长什么样、缺图时退回哪个颜色）：

python3 docs/make_texture_manifest.py

输出一张 HTML。不在文档里存一份静态清单，是因为那种清单必然过期——PhoneTheme 头部那一份就是这么失效的。

文件位置：

每对会话最多保留 20 张不同的图，所以每对好友封顶是该值的 20 倍。默认 512 KB 即每对 10 MB；200 对常聊的好友是 2 GB 上限。

图片按内容存储（文件名为「会话键 + 图片字节」的哈希），因此同一张表情在同一对好友之间发一百次，硬盘上仍然只有一份，也只占那 20 个名额中的一个。

上限 768 KB 是硬的：再往上就顶到原版「服务端发给客户端」那 1 MB 的包上限。服务器启动时会扫描一遍图片仓，删除没有任何消息认领的文件（写完文件、消息尚未落盘就崩溃会留下这种孤儿）。

做备份时要知道：

MCphone 会在方块注册的末尾，把 Integrated Dynamics 全部方块的掉落表提前解析一次。

成因：NeoForge 的注册阶段只要收到任何一个模组抛出的异常，就会把整个注册表回滚成原版状态；而回滚过程本身会在 Integrated Dynamics 的墙上火把处踩到一个空指针，于是真正的错误被顶掉，崩溃报告上只剩一句

Trying to access unbound value: integrateddynamics:menril_torch_stone

看起来像是 Integrated Dynamics 的问题，实际上它只是最后一个倒下的。提前解析一次即可绕开那个空指针，使回滚正常完成并抛出真正的原因。

细节写在 compat/IntegratedDynamicsCompat.java 的类注释里。未安装该模组时，这段代码一行都不会执行。

开一个 Issue 说明下列各项即可，或直接改本页提 PR：

长期无法构建、或仓库已删除的条目会从本页移除。

从三分钟做一个 App 开始，四步：加依赖、实现 IPhoneApp、登记 SPI、放语言文件与贴图。

所有接口都在 dev.november.mcphone.api 及其子包，命名以 I 开头。

下文按包逐一说明。每节都给最小代码；照抄即可跑，不必先读完整份文档。

MCphone 通过 Java 的 ServiceLoader 发现附属：你的 jar 里要有一个 META-INF/services/dev.november.mcphone.api.store.IAppSource 文件，里面一行是实现类的全名。

com.example.mymod.ExampleAppSource

MCphone 启动时会加载所有这样的实现，调用 apps()，把返回的 AppEntry 合并进主屏与商店。不需要事件、不需要注解处理器，一个文本文件搞定。

有。november521/mcphone-deepseek 是一个真实发布的附属，代码不长，结构就是「一个 IAppSource、一个 AppInfo、一个 IPhoneApp、一张列表页 + 一个详情页」。读它比从头猜快。

更短的起步模板见五分钟做一个 App。

做出来之后，想让它被更多人知道，见附属一览的收录规则。

发版时逐个目标构建，全部 jar 挂载于同一个 Release，文件名形如 mcphone-<版本>-<目标>.jar。取与自身目标一致的一个 —— 当前仅 mcphone-<版本>-1.21.1-neoforge.jar 一项可用。

下文以 NeoForge 为例，构建插件为 ModDevGradle，而非 ForgeGradle：不存在 fg.deobf 一类写法。

dependencies {
    compileOnly files("libs/mcphone-1.10.1-1.21.1-neoforge.jar")
    // 想在开发环境里真跑起来，再加一行
    localRuntime files("libs/mcphone-1.10.1-1.21.1-neoforge.jar")
}

在 neoforge.mods.toml 中声明依赖，使加载顺序正确：

[[dependencies.yourmod]]
modId = "mcphone"
type = "required"          # 可选依赖写 "optional"
versionRange = "[1.2.13,)" # 用到 IPhonePage 即为这一版起；只做图标可写 [1.0.46,)
ordering = "AFTER"         # 必须 AFTER：要用的注册表得先就位
side = "BOTH"

public final class CalculatorApp implements IPhoneApp {

    @Override
    public ResourceLocation getId() {
        return ResourceLocation.fromNamespaceAndPath("mymod", "calculator");
    }

    @Override
    public Component getDisplayName() {
        return Component.translatable("mymod.app.calculator");
    }

    @Override
    public ResourceLocation getIconTexture() {
        return ResourceLocation.fromNamespaceAndPath("mymod", "textures/app/calculator.png");
    }

    @Override
    public void onPress() {
        Minecraft.getInstance().setScreen(new CalculatorScreen());
    }
}

这四个方法是必须实现的，其余全为 default，见 方法一览。

界面要画在手机屏幕内部 而不是跳出去时，改为覆盖 openPage()。

文件：src/main/resources/META-INF/services/com.november.mcphone.api.client.app.IPhoneApp
内容：com.yourmod.client.CalculatorApp

文件名就是接口全名，内容是实现类全名，一行一个。

{
    "mymod.app.calculator": "计算器"
}

英文另开 en_us.json，两边的键要对齐。

20×20、PNG-32。路径要与 getIconTexture() 返回的一致

dev.november.mcphone.api.app.IPhoneApp 是一个 App 的运行态——玩家在主屏上点了你那个图标之后，手机实例化的那个对象。它不是 App 的描述（描述是 AppInfo），描述不变，运行态每次开机都是新的。

关 App 与换世界、登出的顺序是：先 onClosed()，再丢引用、再卸载世界。网络连接会随世界卸载自动断开，不要在 onClosed() 里再关一次——那种「先关连接、再清缓存」的顺序会让卸载流程等连接，或在空引用上再关一次。

进 App 后，你有多少数据，就开多少页：

不要「空数据时开一个假的空状态页」：那个假页没有返回栈、没有可点的东西，玩家只能走导航栏 ◁，而且连进 App 时看到的第一屏和正常用完全不一样。空状态应该画在正常会用到的那一页上——列表为空、详情加载中——那一页照样能翻、能点新建、能返回，只是内容区是一段提示。

手机屏幕内部是 120 × 200 的坐标空间（外框另算）。所有 render() 的坐标都在这个空间里：

正文区域之外是手机自带的状态栏与导航栏，别往里画——你的内容会被它们盖住，或者反过来盖住它们。

手机里那些按钮、滑条、滚动条不是每个 App 各自画的，而是一套共享控件，放在 dev.november.mcphone.api.ui.PhoneTextures 与相关的 …ui 类里：

用同一套控件，而不是自己画一份。否则换肤只能换一部分——资源包作者改了按钮贴图，你的 App 还是老样子，界面一半新一半旧。

换肤的完整路径表见 用户文档；从 API 这边调用它们的方式，看 mcphone 源码里相机 / 相册那两个内置 App 怎么画的，照着调即可。

玩家换了壁纸、改了字色，你的 App 不必自己跟着改：

• 壁纸由手机画在最底层，你的 render() 画在它上面
• 画在壁纸上的字，用手机提供的文本绘制方法，它会自动取玩家选的字色
• 导航栏、通知、聊天气泡这些自带构件不走玩家字色，别试图用自己的绘制去替换它们

你的 App 依赖某个别的模组（例如 Waystones、MCEF、NetMusic），实现一个 companionMods() 方法，返回那些 modid：

它回答的是「我怎么没有这个 App」。两个方法的区别：

两者都收进联动页，当前可用的 App 不列——那是噪声。

你的 App 想跳到另一个 App 的某个界面（例如从设置跳到壁纸选择、从聊天跳到相册），用 PhoneApi.get().openPage(...)：

dev.november.mcphone.api.app.IPhonePage 是 App 内部的一个界面。App 本身是「当前在第几页」，IPhonePage 是那一页长什么样、收什么输入。

屏幕底部的 ◁ 是手机自带的，玩家按它或点它，手机会问「当前页能不能退」：

你只管维护自己那一页的栈（一个 Deque<IPhonePage> 或两个字段足矣），不要自己在屏幕上画返回键——和底部那条自带导航会重复。

ESC 是手机级快捷键：它不分层级，按下去整个手机直接关机，不会先走 ◁。因此你的页面里不需要为「按 ESC」写处理。

在 App 内部换页，就是把 currentPage() 返回的对象换掉：

private IPhonePage current = ListPage.INSTANCE;

public IPhonePage currentPage() {
    return current;
}

// 玩家点了列表里某一项
public void openDetail(Item item) {
    this.current = new DetailPage(item, this::backToList);
}

private void backToList() {
    this.current = ListPage.INSTANCE;
}

DetailPage 持有一个「返回时该做什么」的回调，比让它直接持有 App 引用干净——对方将来改名 / 拆包时，你的详情页不会跟着断。

一页里有很多条，滚不完怎么办：用 ScrollSpec 描述怎么滚，把滚动位置存在你自己的字段里：

滚多远只在当前实例里：换页时新的页从零开始滚。不要把滚动位置存进存档——那是会话级的状态，不是持久数据。

你的 App 想在屏幕右上角弹一条通知（新消息、任务完成），用 dev.november.mcphone.api.notify.INotifyHandler：

聊天 App 的未读条数与「你被传送了」那种系统提示共用同一个槽位，别刷屏——同一事件连发十条，玩家只会觉得手机坏了。

「一个 App 是什么」和「一个 App 现在跑成什么样」是两件事：

商店列表、主屏图标、「设置 → App 管理器」的详情，全都来自 AppInfo；点进去之后才轮到 IPhoneApp。

光有描述还不够——手机还得知道「点下去 new 哪个类」。AppEntry 就是把 AppInfo 和一个创建运行态的工厂绑在一起：

public class ExampleAppEntry implements AppEntry {
    @Override
    public AppInfo info() { return ExampleAppInfo.INFO; }

    @Override
    public IPhoneApp create() {
        return new ExampleApp();          // 每次开机新实例
    }
}

一个附属可能有多个 App（例如「小工具」下挂着记事本、末影箱、传送石三个）。IAppSource 就是「我这一个附属有哪些 App」的清单：

public class ExampleAppSource implements IAppSource {
    @Override
    public List<AppEntry> apps() {
        return List.of(
            new ExampleAppEntry(),
            new AnotherAppEntry()
        );
    }
}

这个类同时是 SPI 文件里那一行的指向：

com.example.yourmod.ExampleAppSource

有的 App 替代了一件原版实物：末影箱那格卖一个末影箱，传送石那格卖一个传送石。手机本身没花钱就能用，但这种 App 一装上，那台实物你以后永远用不上了——收一份对应的物品，等于把原来的成本还给玩家。

反过来，终端那格免费：它开的是玩家自己那台终端，没有终端它一格内容都没有。真正的门槛是那台终端，再收一次等于收两遍。

买不起时商店按钮置灰并写明缺什么。购买走原版消耗：扣物品、放进去、写进存档，全程服务端判定，玩家不能伪造客户端绕过。

你想要「用经验等级付」「用服务器积分付」这种 MCphone 没想过的价格，实现 ICost，再通过 ICostRegistry 注册：

public class ExampleLevelCost implements ICost {
    private final int levels;

    public ExampleLevelCost(int levels) { this.levels = levels; }

    @Override
    public boolean canPay(Player player) {
        return player.experienceLevel >= levels;
    }

    @Override
    public void pay(Player player) {
        player.giveExperienceLevels(-levels);
    }
}

商店要把它画出来时，会问 displayText()——返回「12 级经验」这一行字即可。判定与扣除都在服务端，客户端只负责显示与提示。

有的整合包有自己的经济系统，不想让玩家用物品付。IAppPriceProvider 就是把「价格从哪来」整个换掉：

内建的 feature/store/BuiltinAppPrices 就是默认来源，声明了末影箱、传送石那几个价格。整合包想全部免费，写一个 Provider 把所有 App 都报成 Cost.Free 即可，不必改 MCphone、也不必改每个附属。

API 的版本号由 ApiVersion 给出，按下面的规矩演化：

mcphone 与附属的版本对不上时，游戏启动时会在日志里给出明确提示（哪个附属要求哪个 API 版本、当前 mcphone 是哪个），而不是进游戏点开某个 App 才崩。

规则很简单：凡是影响游戏世界的，都得在服务端判定；凡是只画给眼睛看的，都在客户端。中间要传的信息用 NeoForge 的网络包，别图省事在客户端直接改玩家血量——那只改了你自己屏幕上的数，一帧就被服务端盖回去。

因此你的 App 代码不能在类加载时就碰渲染相关的东西（GL 状态、字体渲染器、屏幕宽高）。要画的东西放在 render() 里，那个方法只在客户端被调到；类定义、静态字段、AppInfo 的构造里都不要 new 字体、不要拿 Minecraft.getInstance().font。

否则纯服务端一开服就 NoClassDefFoundError。

MCphone 内置的浏览器用 MCEF 加载网页。它在 MC 生态里是最成熟的选择，但有两个已知限制，写在 用户文档 里：

• 首次使用要下载约 200 MB 原生库
• target="_blank" 的链接点了没反应

这两条都来自 MCEF 本身，MCphone 改不了。

将来你想用别的浏览器内核（比如另一个 CEF 封装、或者一个离线文档服务器），实现浏览器后端的扩展点：

手机只认「一块纹理 + 一组输入事件」，不关心底下是 CEF 还是什么。后端选哪个由运行环境决定，不要在自己的附属里硬编码依赖 MCEF——玩家可能换了后端。

后端不必知道手机的坐标系；它只要把一张固定尺寸的纹理画好，手机负责把它贴到面板上、跟着界面大小缩放。

icon() 返回的 ResourceLocation 是 assets/<命名空间>/textures/… 之下的相对路径。最常见的错是写成 "icon/example.png" 而文件放在 assets/yourmodid/textures/gui/icon/example.png——命名空间对，路径少了一层。用原版的 getResourceLocation 检查一下，或直接看 mcphone 内置 App 的图标是怎么放的。

正文区只有 y = 12 … 186。按钮放在 y = 190 就压在导航栏上了；放在 y = 5 就顶到状态栏。滚列表时用 ScrollSpec 留的上下边距，别自己硬算。

凡是影响游戏世界的，都得发网络包到服务端判定。客户端改的只是本地副本，服务端不承认。完整边界见版本与两端安全。

你的 AppInfo 是静态常量，它的构造在类加载时就跑。别在那里 new 字体、拿 Minecraft.getInstance().font、读屏幕宽高。要画的东西放在 render()。见纯服务端也能装。

不要写 "mcphone:camera" 这种 id 去找内置 App——要用就走 openPage() 的查找，找不到就静默退一格。坐标、颜色常量同理：用 PhoneTextures，不要自己画一份按钮底。

git clone https://github.com/november521/mcphone.git
cd mcphone
./gradlew build

产物在 build/libs/，文件名形如 mcphone-<版本>-<目标>.jar。

仓库不按 Minecraft 版本或加载器分支，全部目标位于 main。计划支持哪些目标、各自什么状态，写在 versions/targets.json；当前发布的构建只有 Minecraft 1.21.1 · NeoForge 一项。

用官方映射（MojMap）。跑客户端用 ./gradlew runClient，跑服务端用 ./gradlew runServer。

本模组以 MIT 许可发布——随便改、随便发，保留版权声明即可。第三方下载与发布渠道见首页。