开始做应用

手动开发

1. 准备三样东西

• Python 3.10 以上：运行打包工具。
• Zig 0.13（或能编 wasm32 的 Clang）：把 C 编成应用。
• TinyRT SDK：下载本站 S31 SDK和Windows 编译器或Apple 芯片 Mac 编译器（macOS 26.5+），解压到任意目录。

python -m pip install -r requirements.txt

2. 新建一个应用

在 SDK 目录里运行。应用编号可以自由命名；发布时由网站自动检查编号归属和应用内容。

python tools/tinyrt.py new my-game --app-id my-game --title "My game" --template game

会得到一个 my-game 文件夹：main.c 是代码，app.json 是应用的名字、版本和权限。

3. 编译、打包

python tools/tinyrt.py build my-game --cc path/to/zig.exe
python tools/tinyrt.py pack my-game --target esp32s31 --wamrc path/to/wamrc.exe

成功后在 my-game/build/ 里有一个 .trpkg 文件，这就是应用包。

4. 在网页里玩

打开模拟器，点「导入应用包」，选刚才的 .trpkg。纯 Wasm 可在模拟器预览；徽章需要包内同时带有预编译版本。上传完整发布包后自动检查，通过即公开。

5. 接下来

读懂第一个应用

一个应用就是三个函数：开始时做什么、有事发生时做什么、画面怎么画。下面这个应用点一下加一，关掉再打开数字还在。

#include "tinyrt.h"

static int32_t count;                       /* 点了几下 */

int32_t tinyrt_init(int32_t width, int32_t height) {
    (void)width; (void)height;
    count = kv_get(0, 0);                   /* 读回上次存的数，没有就是 0 */
    return 0;
}

int32_t tinyrt_event(int32_t kind, int32_t x, int32_t y, int32_t arg) {
    (void)x; (void)y; (void)arg;
    if (kind == TINYRT_TOUCH_RELEASE) {     /* 手指抬起算一次点击 */
        count++;
        kv_set(0, count);                   /* 存起来，下次打开还在 */
    }
    return 0;
}

int32_t tinyrt_render(void) {
    char text[12];
    uint32_t n = 0;
    int32_t v = count;
    char rev[12];
    do { rev[n++] = (char)('0' + v % 10); v /= 10; } while (v > 0 && n < 11);
    for (uint32_t i = 0; i < n; i++) text[i] = rev[n - 1 - i];

    draw_clear(0x101418);                                   /* 每一帧先清屏 */
    draw_round_rect(113, 173, 240, 120, 32, 0xFFC93C);      /* 黄色圆角块 */
    draw_text_box(113, 173, 240, 120, text, n, 0x151515, 48, 1);
    draw_text_box(83, 320, 300, 40, "TAP", 3, 0xC9C7C0, 24, 1);
    return 0;
}

三个函数

三个函数成功都返回 0。还有一个可选的 tinyrt_stop，应用正常退出前调用一次，用来存档。

屏幕

屏幕是 466×466 的圆。四个角看不见，重要的东西放在中间约 330×330 的区域里（坐标 68 到 397）。颜色写成 0xRRGGBB。

app.json

{
  "app_id": "demo.hello",
  "title": "Hello",
  "version": 1,
  "abi_version": 1,
  "permissions": 7,
  "memory_pages": 2,
  "budget": 100000,
  "sources": ["main.c"]
}

permissions 是用到的能力相加：画面 1、触摸和按键 2、存档 4、定时器 8、声音 16、震动 32。上面的例子用了画面、触摸和存档，所以是 7。每次发新版本，version 加一。

装到徽章

两条路：数据线和蓝牙。已有 community.3 系统的徽章推荐先用 OTA 升级，保留应用。

更新系统

community.3 用户到系统升级页，选择数据线或蓝牙，通过 OTA 更新到 0.1.1，会保留应用。徽章需停在「等待发送固件」页，更新完成后按屏幕提示重启。

系统无法启动时，可展开「恢复出厂系统（整片刷写备用）」。这会清空应用、配对和存档，确认需要恢复后再操作。

用数据线装应用

到装到徽章页选好应用包，或者在社区的作品页点「装到实机」，选数据线。只写应用存储区，其他都不动。

用蓝牙装应用

徽章进「应用大厅」点右上角的 +，屏幕出现 6 位连接码；在作品页点「装到实机」，选蓝牙，浏览器弹出配对框时输入这 6 位。

用命令行

python tools/ble_install.py --scan
python tools/ble_install.py --address AA:BB:CC:DD:EE:FF --pair install my-game/build/my-game.trpkg

数据线和蓝牙需要电脑上的 Chrome 或 Edge。

发布包规范

发到社区的作品是一个结构固定的 ZIP。一条命令打出来，网站照着清单逐项检查，通过就能发布。

一条命令

python tools/tinyrt.py release my-game --cc path/to/zig.exe --runner path/to/tinyrt-run.exe --variant wasm-aot

下载 本站 S31 SDK、Windows S31 编译器 / Mac S31 编译器（Apple 芯片、macOS 26.5+）及受信目标契约。从 SDK 根目录执行，将工具路径换成本机实际路径。本站 S31 SDK 发行包提供此命令（见下方下载）；设备交付使用固定摘要的 ESP32-S31 AOT 编译器，桌面预览使用真实 WAMR runner。缺少工具时可先用「AI一键部署」提示词让 Agent 准备环境。

命令会编译、执行项目提供的测试、生成运行截图、打包并自检，输出 my-game/release/my-game-v1-wasm.zip。把这个 ZIP 拖进发布页完成在线检查与发布。

你需要准备的

应用目录里放好这几个文件，其余由命令生成：

ZIP 里有什么

my-game-v1-wasm.zip
  release.json          清单：所有文件的大小和摘要、应用信息、构建信息
  package.trpkg         应用包，设备只装这个文件
  cover.png             210×210 封面，和包内封面是同一张
  README.md             介绍
  CHANGELOG.md          更新日志
  LICENSES.md           来源和许可
  screenshots/01.png    466×466 截图，1 到 6 张，编号连续
  build/report.json     构建和测试记录（可选）

根目录直接放这些文件，不套文件夹，不能有别的文件。压缩包最大 12 MiB，解压后最大 10 MiB，和 SDK 一致。应用包本身多大能装，由徽章系统决定：安装前网页会先问徽章，再决定能不能装。

release.json

可下载当前站点的 release-v2.schema.json做机器校验，并参照 SDK 的发布规范。新版官方固件检查文件结构和完整性；应用来源和发布权限由网站自动检查。旧的 v1 发布包仍然接受。

网站怎么检查

1. ZIP 结构、文件白名单和大小上限。
2. 清单格式，以及每个文件的大小和摘要。
3. 图片尺寸：封面 210×210，截图 466×466，不能是动图。
4. 应用包的文件结构、内容摘要、权限和接口；加速代码需要重新编译核对。
5. 清单和应用包逐项对照：名字、版本、权限、接口列表、封面。
6. 应用 ID 是否属于你，这个版本是否已经发过。

不通过时会给出错误码、说明和出错的位置。

更新徽章系统

网页提供官方 0.1.1 主线的源码构建文件，适用于 ESP32-S31 徽章。

community.3 推荐 OTA 升级

现在是 community.3 的徽章，推荐通过 OTA 升级到本站 0.1.1，会保留已安装的应用。

在徽章进入固件升级页，确认屏幕显示「Send firmware / 等待发送固件」。网页选择数据线或蓝牙，按提示更新系统；保持供电和连接，完成后按徽章提示重启，再检查系统版本和原有应用。

打开系统更新 下载 OTA 固件

整片刷写作为备用

系统无法启动，或确需切换不兼容的固件签发来源时，使用系统升级页中的「恢复出厂系统」。整片刷写会清掉徽章上已经装的应用和存档，刷完后到社区重新安装。

升级后使用应用

在徽章应用大厅点“+”，停在等待接收页面，再从社区安装应用。每装完一个应用，下次安装前重新进入“+”页。

数据线用于安装应用和更新系统，蓝牙用于应用管理。网页读取徽章实际支持的能力，再检查安装条件。

系统文件从哪里来

文件根据官方公开源码构建，由本站固件钥签署，与 community.3 使用同一签发钥，可通过 OTA 升级。它与官方 Releases 签发的文件属于不同签发来源；切换到不兼容的签发来源时需整片刷写。

官方源码 · 构建记录和文件校验值 · 开发与校验合同

接口速查

函数

事件

不订阅时只会收到 1 和 2。3 到 6 需要在 init 里调用 input_events；8 要在掩码里加 256。模拟器里打开「手柄外设」开关，外框上的按键和键盘都能当手柄；键位可以在「手柄设置」里改，H 回大厅。

哪里能调用

代码层级

应用跑在沙箱里，碰不到硬件。从上到下四层，每层只和相邻的一层说话。

仓库

应用包

一个 .trpkg 里是：256 字节的头（名字、版本、权限等信息），然后是几段内容：Wasm 程序、AOT 机器码、资源、封面；网站新发布必须包含前两项。官方固件检查格式和完整性；网站自动核实发布账户及程序规则，新发布必须同时带 Wasm 和 S31 预编译版本。字节级的格式见核心仓库的 specs/package.md。

设备上的存储

应用包共用独立分区，S31 可用数据区约 3960 KiB，最多 16 个应用；没有独立的单包 2 MiB 限制，上限和剩余连续空间由徽章系统报告。更新应用时新旧两个版本要同时放得下。存档在另一个分区，按应用分开，更新保留，卸载清除。格式见 specs/store.md。

限制

没有的东西

• 没有文件系统、网络和麦克风接口。IMU 通过订阅事件提供三轴加速度，应用不能直接访问硬件。
• 没有 C 标准库和浮点数，自己写需要的小函数。
• 不能自己忙等；用定时器事件推进时间。

模拟器和真机的差别

• 模拟器不计指令数，真机上会计。
• 字体和速度略有不同。
• 带加速代码（AOT）的包，真机跑加速版，模拟器跑包里的 Wasm，玩法一样，速度不同。