MCPhone Apps Extension

English | 中文说明

English

Create MCPhone apps directly in game, organize them into home screen folders, and control access with per-player unlocks and item purchases.

Minecraft 1.21.1 / NeoForge 21.1.248+ / Java 21. Requires MCPhone 1.10.1 or later. This is an independent, unofficial add-on. Mod ID: mcphone_apps_extension.

Creating apps in game

1. As an administrator (permission level 2; cheats must be enabled in singleplayer), open Apps Extension → Visual app editor → New on your phone. You can also open the manager with the client command /mcphoneappseditor.
2. Enter an ID, name, description, and optional icon texture. Example ID: mcphone_apps_extension:home. Names and descriptions accept plain text or JSON text components, with live previews and separate example buttons.
3. Click Actions to add, edit, or move actions up. Each app can contain up to 12 actions, executed in order.
4. Return to the app editor and click Save. Once the success message appears, the definition is synced to online players.
5. Open MCPhone's App Store to download the app. Custom apps are not preinstalled automatically.

Apps Extension and /mcphoneappseditor are available only to administrators. Other players do not see the manager on the home screen or in the store, but they can download unlocked apps and manage their own folders through the phone's original Settings app. Granting or revoking administrator permission updates the manager's availability within 20 server ticks (about one second under normal conditions), without reconnecting. The server validates permissions and data again when it receives an edit. If another administrator has changed the configuration, an outdated edit is rejected. Return to the list and reopen the editor before editing again.

Actions

Commands support the {player} and {uuid} placeholders. Each action can have a 0–200 tick delay before execution. Keybind actions can hold the key for 1–200 ticks. There are 20 ticks in one second. Each player can run one action sequence at a time; starting another replaces the previous sequence. At most one launch is accepted every 5 ticks. The player must be alive and carrying a MCPhone. The server rechecks access and phone possession before each action. Disconnecting, dying, or losing access stops the remaining actions.

Commands do not automatically receive OP or console permissions. To make a feature available to regular players, configure a command they are allowed to use, such as a quest mod's player command or /trigger. Keybind support uses standard KeyMapping click counts and held state. For mods that listen only for raw GLFW input events, use their command interface instead.

Icons

Leave the icon texture blank to use the selected background color and the first character of the app's name. You can also enter a PNG resource location from a resource pack:

my_pack:textures/app/home.png

This corresponds to assets/my_pack/textures/app/home.png in the resource pack. A square PNG is recommended. Every client needs the resource pack that provides the texture. The add-on does not download remote images or read arbitrary local file paths.

Text components and localization

The editor, action pages, stage and price rules, folder management, and editing feedback include English and Simplified Chinese translations and follow Minecraft's language setting. Language resources are located at assets/mcphone_apps_extension/lang/en_us.json and zh_cn.json. Resource packs can override these entries or add other languages.

App names accept plain text (up to 48 characters) or Minecraft JSON text components (up to 2048 characters). New apps start with this colored, translatable example. Click Name example to restore it:

{"translate":"mcphone_apps_extension.example.name","color":"#55FFFF","bold":true,"extra":[{"text":" ✦","color":"#FFAA00"}]}

In English, this displays Example app in bold cyan with a gold star. In Chinese, the name becomes 新应用. Supported Minecraft component fields include text, translate, fallback, with, extra, colors, and styles. Click events in a displayed name are not executed as app actions. For your own translation keys, provide the matching language entries in a client resource pack or use fallback for a default name.

Descriptions also accept JSON text components (up to 2048 characters), plain text (up to 256 characters), or an empty value. New apps start with the following colored, multiline example. The Description example button restores it independently. Both the editor preview and MCPhone's original store detail page preserve colors, line breaks, and styles:

{"translate":"mcphone_apps_extension.example.description","color":"#55FFAA","extra":[{"text":"\n"},{"translate":"mcphone_apps_extension.example.description_hint","color":"#AAAAAA","italic":true}]}

In English, the first line reads “An app with a colorful description.” in green. The second reads “Tap the app to run its actions.” in gray italics. Switching to Chinese automatically uses the corresponding translations.

Paste JSON directly into the in-game fields without adding another pair of quotes around the whole value. When editing apps.json by hand, name and description are still strings, so quotes and backslashes inside them must be escaped according to JSON syntax. See examples/apps.json. Existing plain-text names and descriptions continue to display as written.

Home screen folders

Open the phone's original Settings → Desktop folders page. Create a folder, open its management page, and choose installed apps to include. All players can use this feature. Each app can belong to one folder at a time. Selecting it in another folder moves it there; selecting an existing member removes it from the folder.

Folders appear directly on the MCPhone home screen, with icon previews of their first four members. Opening a folder shows its app grid inside the phone, with paging, mouse-wheel scrolling, and navigation-bar back support. Grouped apps are removed from the home screen's individual app icons while remaining installed and retaining their original MCPhone shortcuts. Apps and folders can still be dragged to rearrange the home screen. Deleting a folder returns its members to the home screen without uninstalling them. Folders support installed apps from MCPhone and other add-ons. Layouts are stored locally for each world ID and player UUID. They are not shared with other players or carried into a different world.

Player stages and download access

First enable the stage requirement. For a custom app, switch the editor to Stage: requires unlock. Alternatively, open Apps Extension → App stages and prices, select a configurable app, set its stage and purchase rules, and save. Settings and the App Store cannot be stage-locked. The extension manager cannot be stage-locked either, but remains visible only to administrators.

For example, after creating mcphone_apps_extension:home and enabling its stage requirement:

/mcphoneappsextension appadd Steve mcphone_apps_extension:home

Steve can now see the app in the store and proceed with downloading it, subject to any purchase requirement. This grants download and usage eligibility; it does not install the app for the player.

# Revoke access and remove the app from this player's current installations.
# If access is granted again, the player needs to download it again.
/mcphoneappsextension appremove Steve mcphone_apps_extension:home

# Require stage access for MCPhone's Camera app
/mcphoneappsextension gate mcphone:camera true
/mcphoneappsextension appadd Steve mcphone:camera

# Remove the stage requirement and make the app publicly available
/mcphoneappsextension gate mcphone:camera false

# Check a player's unlock records
/mcphoneappsextension check Steve

# List custom app IDs and stage IDs known to the server
/mcphoneappsextension list

# Reload after manually editing the configuration.
# Invalid configuration does not replace the active valid configuration.
/mcphoneappsextension reload

These server commands require permission level 2 and can be run by operators, the server console, command blocks, or quest rewards. Omit the leading / in the server console. The player argument accepts online players, player selectors such as @a, and offline usernames whose profiles the server can resolve. Non-player entities are not accepted. Unlocks are stored by UUID and persist through death, dimension changes, reconnects, and server restarts. Apps without a stage requirement remain publicly available. Running appadd alone does not enable the stage requirement; the command will notify you when this applies.

Stage restrictions filter the store and home screen, block installation and launching, and guard MCPhone's purchase entry point, AppAccess.canUse, and all actions provided by this add-on on the server. Other add-ons with their own networking that do not call MCPhone's access checks must enforce access to those features themselves. Client-only screens cannot protect server resources.

Item purchases

Open Apps Extension → App stages and prices, select an app, enable Item purchase, enter the item and components plus a count, and click Save. Prices can be set for custom apps, MCPhone's apps, and other add-on apps. System management entries cannot be priced.

Payment can combine matching items from multiple inventory stacks. Item syntax matches the item argument of /give in Minecraft 1.21.1. Enter the count separately (1–2304):

minecraft:emerald
minecraft:paper[minecraft:custom_data={mcphone_ticket:1b}]
minecraft:diamond_sword[minecraft:damage=0]
minecraft:paper[!minecraft:custom_name]

An item ID on its own places no restrictions on components. When components are specified, each listed component must equal the corresponding component on the payment item; unlisted components may vary. !component_id requires that component to be absent. custom_data compares the entire component, including NBT numeric types; it is not a partial NBT match.

For prices with component requirements, hover over the required item text near the bottom of the original store detail page to see the item tooltip and the required component IDs and SNBT values. This also shows components such as custom_data that are normally hidden from item tooltips. !component_id is labeled “must be absent.” The tooltip uses the normal GUI font size, and its hover area follows the phone's scale. For long content, keep the pointer over the required item and use the mouse wheel to scroll.

Click Use main-hand item and components to import the held item's format, or Insert component example for a sample. An administrator can create the example ticket with:

/give @s minecraft:paper[minecraft:custom_data={mcphone_ticket:1b}] 3

Purchases use MCPhone's original Buy → Download flow. The server stores prices, checks requirements, and deducts items. Insufficient or nonmatching items are not consumed, and repeated purchases do not charge again. Inventory checks follow MCPhone's behavior and include the main inventory, hotbar, armor slots, and offhand. Creative mode follows MCPhone's rule of consuming no items, but still requires completing the purchase step.

Purchase records are stored in MCPhone's original player attachment. Uninstalling, downloading again, or regaining stage access does not charge the player again. Revoking stage access blocks use while preserving ownership. Removing an item price set by this add-on restores MCPhone's original price without clearing purchase records.

File locations

New servers start with an empty app catalog; no demonstration apps are added. examples/apps.json provides configuration examples you can copy. Keep your existing configuration before replacing it with an example. Configuration is saved through a temporary file and an atomic replacement. Malformed files are preserved and logged, rather than silently overwritten. If the catalog cannot be read at server startup, fix it and run reload.

中文说明

在游戏里直接创建 MCPhone App，将应用整理进主屏文件夹，并通过玩家阶段授权和物品购买控制使用资格。

Minecraft 1.21.1 / NeoForge 21.1.248+ / Java 21，需要 MCPhone 1.10.1 及以上。 这是独立的非官方附属，模组 ID 为 mcphone_apps_extension。

在游戏里添加 App

1. 管理员（权限等级 2；单人需允许命令）打开手机里的 「应用扩展」→「可视化 App 编辑器」→「新建」。 也可以执行客户端命令 /mcphoneappseditor 打开管理界面。
2. 填写 ID、名称、简介与可选的图标纹理。示例 ID：mcphone_apps_extension:home。名称和简介均支持纯文本或 JSON 文本组件，下方即时预览，并提供独立的示例按钮。
3. 点击 「动作」，添加、编辑或上移动作；每个 App 最多 12 个动作，依次执行。
4. 返回 App 页面，点击 「保存」。出现成功提示后，定义会同步到在线玩家。
5. 回到 MCPhone 「应用商店」 下载此 App。自定义 App 不会自动预装。

「应用扩展」和 /mcphoneappseditor 仅对管理员开放；普通玩家的主屏和应用商店不显示此入口，但可以下载已解锁 App，并在手机原有设置中管理自己的文件夹。在线授予或撤销管理员权限后，入口在最多 20 个服务端 tick（正常运行约 1 秒）内更新，无需重连。 服务器收到编辑请求时会重新验证权限和数据。多人同时编辑时，过期的修改会被拒绝，需要返回列表重新打开，避免覆盖另一位管理员的改动。

动作

命令支持 {player}、{uuid} 占位符。每个动作可以设置 0–200 tick 执行前延迟；键位动作可以设置 1–200 tick 按住时间，20 tick = 1 秒。 每个玩家同时执行一条动作序列，再次启动会替换旧序列；每 5 tick 最多接受一次启动。 玩家需存活并携带 MCPhone。服务器在执行每个动作前重新检查解锁状态和手机；退出、死亡或撤销授权会停止后续动作。

命令不会自动获得 OP 或控制台权限。要让普通玩家使用一个功能，应配置该命令本身允许的权限，例如任务模组提供的玩家命令或 /trigger。 键位兼容通过标准 KeyMapping 的点击计数与按住状态工作；只监听原始 GLFW 输入事件的特殊模组需要使用其命令接口。

图标

图标纹理留空时，主屏显示所选底色与名称首字。也可填写资源包中的 PNG 资源地址：

my_pack:textures/app/home.png

对应资源包文件 assets/my_pack/textures/app/home.png，推荐正方形 PNG。所有客户端需要安装提供该纹理的资源包；本附属不会下载远程图片或读取任意本地路径。

名称、简介文本组件与国际化

编辑器、动作页面、阶段和价格规则、文件夹管理及编辑反馈提供简体中文和英语翻译，跟随 Minecraft 的语言设置。资源位置为 assets/mcphone_apps_extension/lang/zh_cn.json 和 en_us.json，可用资源包覆盖，或添加其他语言文件。

名称可以继续填普通文字（最多 48 字符），也可以直接填 Minecraft JSON 文本组件（最多 2048 字符）。新建 App 默认填入以下彩色翻译示例，也可点击「名称示例」恢复：

{"translate":"mcphone_apps_extension.example.name","color":"#55FFFF","bold":true,"extra":[{"text":" ✦","color":"#FFAA00"}]}

中文显示青色粗体「新应用」和金色星号，英文显示「Example app」。支持 text、translate、fallback、with、extra、颜色和样式等 Minecraft 文本组件字段；界面名称不会把点击事件当作 App 动作执行。自定义翻译键需要在客户端资源包中提供对应语言条目，或用 fallback 提供缺省名称。

简介同样支持 JSON 文本组件（最多 2048 字符），也保留纯文本（最多 256 字符）和留空的写法。新建 App 默认填入下面的彩色、多行翻译示例；「简介示例」按钮可单独恢复它。编辑器预览和原应用商店详情页均保留颜色、换行和样式：

{"translate":"mcphone_apps_extension.example.description","color":"#55FFAA","extra":[{"text":"\n"},{"translate":"mcphone_apps_extension.example.description_hint","color":"#AAAAAA","italic":true}]}

中文第一行显示绿色「这是一个彩色的应用简介。」，第二行显示灰色斜体「点击应用执行配置的动作。」；英语环境自动切换对应翻译。

输入框里的内容直接是 JSON，不需要再给整段内容加引号。手动编辑 apps.json 时，name 和 description 仍是字符串，需按 JSON 规则转义其中的引号和反斜杠；参见 examples/apps.json。旧版纯文本名称和简介会按原样显示。

手机文件夹

进入手机原有的 「设置」→「桌面文件夹」：新建文件夹，点击文件夹进入管理页，再选择已安装的 App。这个功能对所有玩家开放。 每个 App 最多属于一个文件夹；选择另一个文件夹会移动成员，点击已选成员会将其移出。

文件夹直接显示在 MCPhone 主屏，图标预览前四个成员，点击在手机内部打开成员网格；支持分页、滚轮和导航栏返回。 已分组的 App 从主屏单独图标列表中收起，保持已安装状态和 MCPhone 原有的快捷键。主屏仍可拖动 App 与文件夹排序。 删除文件夹后成员回到主屏，不会卸载。支持 MCPhone 本体及其他附属提供的已安装 App。 布局按世界唯一 ID 和玩家 UUID 保存在个人客户端中，不会共享给其他玩家，也不会把另一存档的文件夹带进来。

玩家阶段 / 下载解锁

先启用阶段限制：自定义 App 在编辑器中切换 「阶段：需要解锁」；也可以在 「应用扩展」→「App 阶段与价格」 页面选择任意可配置 App，再设置阶段与购买规则并保存。 设置、应用商店不受阶段限制；扩展管理器也不受阶段限制，但仅管理员可见。

例如建立 ID 为 mcphone_apps_extension:home 的 App 并开启阶段后：

/mcphoneappsextension appadd Steve mcphone_apps_extension:home

现在 Steve 才能在应用商店看到并下载这个 App。这里授予的是下载和使用资格，不会代替玩家下载安装。

# 撤销资格，并从该玩家当前安装列表中移除；重新授予后需重新下载
/mcphoneappsextension appremove Steve mcphone_apps_extension:home

# 将本体相机设为需要阶段
/mcphoneappsextension gate mcphone:camera true
/mcphoneappsextension appadd Steve mcphone:camera

# 取消阶段限制，改为公开下载
/mcphoneappsextension gate mcphone:camera false

# 查看某个玩家的解锁记录
/mcphoneappsextension check Steve

# 列出服务器已知的自定义 App ID 和阶段 ID
/mcphoneappsextension list

# 手动编辑配置后重载；坏配置不会替换已运行的有效配置
/mcphoneappsextension reload

这些服务器命令需要权限等级 2，可由 OP、服务端控制台、命令方块或任务奖励执行。控制台中去掉开头的 /。 玩家参数支持在线玩家、@a 等玩家选择器以及服务器能解析到档案的离线用户名；不接受非玩家实体。解锁数据以 UUID 为准，跨死亡、维度切换、重连与服务器重启保留。 没有开启阶段限制的 App 始终公开；单独运行 appadd 不会自动把它改成阶段 App，指令会对此给出提示。

阶段限制会过滤商店和主屏、阻止安装与打开，并在服务端拦截本体的购买入口和 AppAccess.canUse，以及本附属的所有动作。 其他附属若有独立网络功能且不调用 MCPhone 的权限入口，其独立功能还需由该附属本身授权；客户端专属界面也不能用来保护服务端资源。

物品购买

进入 「应用扩展」→「App 阶段与价格」，选择 App，启用「物品购买」，填写物品及组件和数量，再点击「保存」。这项规则支持自定义 App、本体 App 和其他附属 App；系统管理入口不能定价。

物品栏支持合并多个物品堆，格式与 1.21.1 的 /give 物品参数一致，数量在独立输入框中填写（1–2304）：

minecraft:emerald
minecraft:paper[minecraft:custom_data={mcphone_ticket:1b}]
minecraft:diamond_sword[minecraft:damage=0]
minecraft:paper[!minecraft:custom_name]

只填物品 ID 时，不限制组件。填写组件后，列出的每个组件必须与物品对应组件相等；未列出的组件不限。!组件ID 表示该组件必须不存在。custom_data 比较整个该组件，NBT 数值类型也需要一致；它不是部分 NBT 条件匹配。

当价格包含组件条件时，将鼠标移到原应用商店详情页底部的需求物品文字上，会显示物品提示及所要求的组件 ID、SNBT 值。custom_data 等默认物品提示中不可见的组件也会列出，!组件ID 则标明「必须不存在」。提示以正常界面字号显示，并跟随手机缩放正确判断悬停；内容过长时保持鼠标在需求物品上，用滚轮查看。

可以点击「使用主手物品及组件」自动填入手持物品格式，或点击「填入组件示例」。示例票据可由管理员生成：

/give @s minecraft:paper[minecraft:custom_data={mcphone_ticket:1b}] 3

购买直接使用 MCPhone 原有应用商店的「购买 → 下载」流程。价格由服务器保存、验证和扣除；物品不足或组件不匹配不扣费，重复购买不重复收费。检查范围与本体一致，包括主物品栏、快捷栏、盔甲和副手；创造模式也按本体规则免扣物品，但仍需完成购买流程。

购买记录保存在 MCPhone 原有玩家附件中。卸载、重新下载或重新授予阶段不会再次收费；撤销阶段会禁止使用，但保留已购记录。取消附属的物品价格会恢复 MCPhone 本来的价格，不会清除购买记录。

文件位置

新服务器默认生成空目录，不添加演示 App。examples/apps.json 提供可复制的配置示例；复制前保留自己的已有配置。 配置写入使用临时文件加原子替换；格式损坏会记录错误并保留原文件，不静默覆盖。服务器启动时若目录无法读取，则需要修复后运行 reload。