模拟与调试

PXA 创作与开发指南

浏览器在线试玩

无需安装,直接体验 PXA 应用;了解当前能力和开发接入。

中文指南 · 11 分钟阅读 · PXA 0.10.0
适用环境与阅读准备

适用环境现代桌面与手机浏览器;实验版 PXA Browser Host

开始前无需开发板或开发环境;联网打开试玩页面

术语速查 →

不用安装工具,也不用连接开发板。到 作品商城,登录后点击作品卡片上的 在线玩,即可在当前浏览器运行。也可以打开 平台示例,体验接球挑战、计数器和中文便签。

只有当前版本满足浏览器能力要求的作品会显示在线入口。没有入口的作品仍可下载到设备;详情页会说明设备专用构建或尚未接入的硬件服务。

0.10.1 更新与兼容性

网页运行时现为 Browser Host 0.10.1,基于 PXA 0.10.0、Core 2.1 构建;官网示例与商城在线玩使用同一版运行时。它是独立发布的实验宿主,设备固件和 DevKit 不会随网页更新而自动升级。

0.10.1 修正商城在线玩的兼容表,使它与实际注册的 Core 服务、Window 0.5、Net 0.8、FS 0.6 和 GameRender 1.6 一致,并声明原生 WebSocket 及其权限。页面和 Worker 的连接策略允许 WebSocket;HTTPS、混合内容和目标服务的来源检查仍然生效。

本版支持 Window 0.5 的方向请求与四分之一圈旋转,画面尺寸和指针坐标随实际方向更新,方屏保留旋转角度。Sensor 可报告线性加速度;实际可用传感器以设备与浏览器权限为准,不能用模拟输入证明真实硬件能力。

系统字体字形读取继续使用 UI 0.10:C 使用 pxa_font.h,C++ 使用 pxa/font.hpp,异步获得行高、基线、字形度量和 A8 覆盖位图。字体大小为 8–48 像素,单字形最多 3072 字节。需要在包中声明 UI 0.10 与字体字形功能位;旧版普通 UI 应用继续兼容。浏览器读取本机系统字体,不能保证与设备或应用自带像素字体外观一致。

更新后刷新页面再启动作品即可使用新版运行时,正常升级不会主动清除存档。已打开的旧页面继续使用自己的版本资源;保存进度后再刷新。

怎么操作

  • 接球挑战:左右方向键或 A / D 移动挡板,也可以拖动画面。Z / 空格暂停游戏,X 重新开局。
  • 交互计数器:点击画面内的 +1,或按 Z / 空格。
  • 触屏与手柄:画面下方提供触摸按键;标准映射的 USB / 蓝牙手柄使用方向键、A / B / X / Y、Start / Select 和肩键。键盘和手柄控制前先点击游戏画面。
  • 全屏:点击全屏按钮扩大画面,保持长宽比;手机也可以用页面方向键和动作键组合操作。
  • 暂停与重启:页面的暂停按钮停止应用计时;切换到其他标签页会自动暂停。点击继续恢复,点击重新开始重启应用,已保存的便签不会清空。

页面的画面更新率统计实际完成绘制的帧数,静止界面没有必要持续刷屏。这个数字反映当前电脑或手机的浏览器性能,不能代替开发板的帧率测试。

选择设备与画面缩放

展开播放器上方的设备名称,可以按设备外观插画选择 GameKit-1、PAI Touch、SenseCAP Watcher、Korvo-1、ESP Mosaico 或 GameKit。应用会以对应的显示分辨率启动,画面始终保持比例。插画根据实物重绘;普通 GameKit 暂用通用示意图。

切换设备会停止当前作品并刷新已经写入的浏览器存档,然后点击开始重新运行。请先在游戏内保存进度;停止不等于替游戏自动创建即时存档。游戏存档按应用隔离,切换设备不会另外创建一份存档。

像素清晰使用最近邻缩放,适合像素游戏;平滑显示适合一般界面与连续色彩图像。切换立即生效,不重启游戏、不增加逐帧绘图。这只改变浏览器放大画面的采样方式,不改变游戏内部绘图或 3D 抗锯齿;非整数倍放大时,像素宽度可能略有差异。

GameKit-1 提供可操作的设备外壳,其他设备目前提供外观插画选择与分辨率预览。圆屏、圆角屏完整显示矩形帧,不裁切游戏内容;安全区域、屏幕遮罩、旋钮和传感器等硬件行为仍需桌面模拟器及真机验证。高分辨率需要处理更多像素,在同一台电脑上也可能降低帧率。手机优先展示大画面和尺寸足够的控制按钮。

当前支持范围

浏览器 Host 0.8.0 支持商城中符合条件的 Wasm 作品,以及接球挑战、交互计数器和中文便签示例。代码、包内数据和配套资源包均经过签名及摘要校验。多组件应用可以启动主界面;额外的脚本执行器和系统输入法提供者不会自动启动。

使用 Core 2.1 主循环的游戏需要浏览器支持 WebAssembly JSPI;页面会检测能力并在不支持时提示。建议使用新版 Chrome 或 Edge。普通事件回调应用不依赖 JSPI。

应用使用标准 PXA C / C++ SDK 的 WebAssembly 产物,浏览器执行应用代码,PXA Core 与 LVGL 负责界面和绘图。应用运行在独立 Worker 中,可由页面停止。

当前已接入 UI、Canvas、Window、Clock、私有 KV/文件存储、应用媒体目录、Assets 图片与数据资源、PCM 音频与音效、封装音乐、网络、Surface、GameRender、租约,以及日志和设备运行环境查询。接入使用现有 Core 服务和光栅器。C 与 C++ 应用均使用标准 SDK 的 Wasm 构建;芯片 AOT 文件不能直接用于浏览器。

大应用的加载

商城按块验证并解码资源,复用已验证的服务器磁盘缓存;浏览器按已声明的长度接收资源,让各文件共用下载缓冲,再一次性移交运行 Worker。这样可减少大资源包的重复内存分配。首次加载仍需要下载、校验及编译 Wasm,速度受网络、资源大小和设备影响;运行期间不会反复解压整个安装包。

服务器缓存可以淘汰并重建,不属于用户存档。浏览器只将导入文件和应用主动保存的数据持久化,不因保存进度而复制整套商城资源。

中文输入与存档

点击便签的输入框即可使用浏览器的原生输入区域,支持中文输入法、粘贴和手机系统键盘。点击「完成」或「保存并播放提示音」保存。字体来自浏览器系统字体,按字形度量处理中文基线。

存档按应用隔离,保存在当前浏览器。正常暂停或停止会等待写入;浏览器崩溃、强制关闭或清理站点数据可能丢失存档。页面会提示保存结果;不支持安全持久化的浏览器会明确提示临时存储。同一个应用不能在两个页面同时修改存档。

声音与按键

点击开始允许播放声音;如果浏览器拦截自动播放,再点击「开启声音」。页面静音仅影响当前应用,音量通过电脑或手机的系统音量调整。商城自动进入游戏时可能需要手动点击「开启声音」。系统音量键保持原有行为;浏览器没有读取或设置系统主音量的接口。Escape 对应应用返回,离开页面会松开所有已按下的游戏按键。

导入 ROM、书籍与其他文件

点击播放器的「导入文件」,或使用应用内的导入入口,选择本机文件。每次最多 64个文件、每个文件最多 64 MiB,全部包资源和导入数据合计最多 256 MiB。文件出现在当前应用的媒体目录中;同名文件会跳过。导入完成后,可在应用内刷新列表。

导入文件与存档按应用保存在当前浏览器,其他应用不能访问。商城附带的示例资源保持独立,保存进度不会重新写入整个资源包。停止应用会取消尚未完成的导入;文件完整写入后才出现在列表中。

麦克风与联网

应用请求录音时,页面显示「启用麦克风」。只有点击后才会弹出浏览器的系统授权;停止或暂停会释放麦克风。录音依赖 AudioWorklet 与 WebCodecs 的 Opus 编码支持,不支持时会返回明确错误。声音的解码、网络账号和第三方服务可用性也受浏览器及服务方限制。

联网权限来自已验证的应用声明。商城和独立示例均由本机浏览器直接访问目标服务,不经过商城服务器转发,也不在直连失败时回退到转发。请求不携带浏览器 Cookie,受目标服务的 CORS、浏览器 HTTPS 与混合内容策略限制。web 权限允许在 HTTPS 页面上将 HTTP 地址改用 HTTPS;具体 HTTP 域名权限不会自动扩大为其他来源。浏览器禁止设置的 User-Agent、Referer、Cookie 等请求头由浏览器管理。流式上传、可见响应头和跳转也遵守浏览器限制。

浏览器没有原始 TCP/TLS Socket API,此类操作返回「不支持」;依赖设备端 Socket 协议的应用需要针对浏览器原生协议适配。旧版本的服务器 HTTP 与 Socket 转发入口已经停用。商城登录仍用于获取并验证应用包,不参与运行中的第三方网络请求。

Net 0.8 提供浏览器原生 WebSocket,可用于联机、聊天与设备控制。C++ 先查询 context.network().capabilities():native_websockets() 为真时使用 context.websockets().open_native();具备 TCP 客户端的固件和桌面端可使用 context.websockets().open() 连接同一应用服务器。申请 net.socket 的实际权限, 并在整个会话中保留权限及连接对象。HTTPS 页面需要可信 WSS;设备的明文 WebSocket 可能需要 TLS 代理,并受浏览器本地网络授权限制。

TCP 监听、UDP 和 DNS-SD 发现是独立能力。ESP 与 Linux/macOS 原生后端可提供 IPv4 实现;当前 Windows 桌面端和浏览器不提供这些监听、数据报与发现后端。 请逐项查询实际能力,而不是根据发行号推断。房间、玩家和同步规则由应用实现; 直接输入对端 IP 不能自动穿透 NAT,跨公网需要可达服务器、路由、VPN 或应用中继。 验收时运行两个实际端点,核对消息与确认、断开、有限重连及退出清理。

平台边界

图形计算只同步需要的内存区域。持久 Surface 使用固定的 Host 影子缓冲,每次提交复制对应一帧,不复制整个应用堆,也不宣称零拷贝或硬件直刷。应用与 Host 的 Wasm 内存各自上限 512 MiB,实际可用空间还取决于浏览器。

体感作品按应用订阅自动启用加速度、陀螺仪和浏览器原生磁力计,不再显示独立启用按钮。部分浏览器必须通过用户操作授权:点击现有的「开始/继续」或首次操作游戏画面即可触发原生授权;允许后,新增传感器、切换订阅和暂停恢复不再重复要求启用。退出和取消订阅会停止采集,授权结果在本页保留。

运动数据按 PXA 的设备原生坐标转换:X 指向设备顶部,Y 指向左侧,Z 朝屏幕外。三类传感器使用相同的 (x,y,z) → (y,-x,z) 旋转,不覆盖应用内的测量方向设置。硬件不存在、读数无效或超时均不生成假读数;支持时会在原生采集短暂失败后改用新的 DeviceMotion 读数,授权被拒绝时不会绕过权限。

磁力计通过 sensor.read / magnetic-field.0 提供三轴磁场,将浏览器的 µT 转为 PXA 的 nT,采样最多 10 Hz。网页需使用 HTTPS,并允许 magnetometer 权限策略。它读取的是运行浏览器的手机或电脑自身的传感器,不会自动读取 USB 外接开发板。原始磁场接口在部分 Chrome 版本不可用,即使手机确实有磁力计;不需要查找或开启实验标志。

浏览器还支持独立的 sensor.read / orientation.heading:系统提供磁北参考的绝对方位,单位为微度,单值范围 [0, 360000000),最多 20 Hz。新版北辰指南针优先使用原始磁场;没有可用的磁场/重力组合时自动使用“系统方位”。此模式由操作系统处理校准,不显示原始磁场强度,也不进行六面校准。原有磁力计校准会保留。

方位来自标准绝对朝向事件,或 AbsoluteOrientationSensor,必须允许 accelerometer、gyroscope 和 magnetometer 三项权限策略。需要用户授权的浏览器会在点击开始或画面时请求绝对方位权限。普通相对旋转不能用来指北;无效、过期、相对数据以及没有明确水平指向的极端姿态不会发送。平放以手机物理上沿为前进方向;抬起 45°–70°时平滑过渡到机背朝向,竖握时屏幕面向自己、机背指向前方。横竖屏切换不重定义物理参考。使用时远离磁铁;若仍无数据,检查站点的运动传感器权限。接口存在不保证硬件可用,网站无法绕过系统或浏览器权限。系统方位不会伪装成三轴磁场或第二颗磁力计。参见 Device Orientation 标准。

仍未提供任意 .pxa 包安装、后台任务、系统输入法提供者注册和设备商店安装服务。触摸画面目前为单点;手柄和页面虚拟按键可组合使用。需要这些设备能力的应用,会提示限制或保留设备运行入口。

完整支持范围见运行时的 能力清单,以及源码中的 simulator/browser/README.md。不能把「已注册服务」理解为所有可选操作均可用。

开发自己的作品

保留浏览器可执行的 Wasm

网页只能执行包中主组件的 WebAssembly,不能执行 ESP32-S3、S31、P4 的芯片 AOT 文件。为同时支持网页与真机,发布时保留原始 Wasm,并附上需要的芯片 AOT 产物;仅含 AOT 的设备专用包不会获得在线玩入口。即使应用使用相同 SDK 发行号,商城仍按声明的服务版本、功能位及权限判断可用性。

2D 像素游戏与性能

字体、精灵和地图保持整数坐标,并优先使用整数倍缩放;播放器选择「像素清晰」。Surface 的 Host 影子缓冲仍需在提交时复制,因此应复用缓冲、缓存静态地形,按变化重绘,避免每帧创建大对象或重复解码资源。先分别测量应用绘制和页面呈现,再决定优化方向。

网页统计的是浏览器完成绘制的更新帧,不是 LCD 扫描刷新率,也不与不同分辨率的开发板直接等同。静止画面较低的更新率通常表示按需重绘;真机应分别测试静止、持续行走和复杂场景。

创作流程

继续使用 一句话 AI 创作教程。浏览器试玩不要求安装环境;开发、编译与完整调试仍使用 Agent Kit、桌面模拟器和真机。

可以把这句话补充到创作需求中:

请使用标准 PXA C 或 C++ SDK 编写,保持 SDK 与设备代码不变。如果需要浏览器预览,先核对浏览器宿主支持的服务,保留 Wasm 构建产物;不要把未接入的资源包或设备能力报告为通过。最终仍在模拟器验证,连接设备后再实测性能。

浏览器宿主源码、构建步骤及约束位于 pxa-system/simulator/browser/。它扩展 Host 平台,不修改应用 SDK 或 Core ABI。

重复启动与本地缓存

浏览器按版本保存运行时,发布新版本后使用新的版本地址。应用每次启动先请求最新清单并检查登录及上架状态,再复用哈希匹配的本地 Wasm 和资源;更新或缓存缺失时下载对应文件,损坏缓存会自动删除并重新下载。

应用资源缓存每个站点最多 256 MiB、16 个文件,并根据浏览器存储配额下调到配额的 10%。达到上限时先清理较早缓存。浏览器清理站点数据也会删除缓存;禁用缓存或空间不足时仍可正常联网运行。应用缓存与存档分开,自动清理资源缓存不会删除存档。每次启动仍需要联网检查最新清单,这不是离线安装模式。

商城在应用成功启动后统计在线运行次数,跨版本累计;同一账号连续 30 分钟没有启动该作品,下一次启动才增加次数。短时间刷新、重新开始和重复请求合并统计;加载失败不计数。该统计从功能上线时开始,历史次数无法根据“最近玩过”准确还原。

参考实现与资料simulator/browser ↗

输入关键词,搜索全部教程。