晓织游戏开发者指南
象晓羊 · 发布于 2026-11-08 13:20:13 · 更新于 2026-11-22 13:11:45 · 54
一、这份指南讲什么
本指南面向两类读者:人(第一次给晓织游戏平台做游戏的开发者)和 AI 助手(被要求按平台规范生成游戏包的程序)。读完可以独立完成:搭好一个符合规范的前端包、写对 config.json、接入玩家资料与权限、打包并通过校验上架。
平台上的游戏都是纯静态网页(HTML / CSS / JavaScript / 图片 / 音频 / 字体 / wasm),在玩家浏览器里运行。平台不代为运行后端进程;需要服务器存档、排行榜、联机的游戏走「自备服务器」方式(见第九节)。
当前平台运行库版本:v2026.3.8。
二、接入总流程(七步)
- 注册并登录本站,在 申请成为开发者 提交名称与简介,等待审核通过。
- 按第四节目录结构准备游戏,入口为根目录或第一层子目录下的
index.html。 - 按第五节写好包内
config.json;需要玩家资料、摄像头、麦克风、第三方联网时,按第六节填privacy隐私清单。 - 本地双击
index.html或起静态服务自测通过。 - 在 创建游戏 上传前端 zip;平台自动解包读取
config.json并做校验。 - 校验通过后出现在游戏列表;上架前平台做形式审查。
- 后续改动在游戏管理页重新上传包并填写更新日志。
三、开发者账号
- 审核通过后,开发者编号直接使用你的网站用户编号(与账号
user_id一致),不另发编号。 - 只有成为开发者后才能创建游戏、上传代码包、查看下载与试玩数据。
- 隐私清单违规累计达到 3 次会被永久封禁开发者账号;权限用途必须如实填写。
四、游戏包目录结构
前端包是一个 zip。index.html 可以在压缩包根目录,也可以在一层子目录里(规范允许二级子目录)。包内资源一律用相对路径引用,不能用绝对路径,也不能用 ../ 跳出目录。
下面是一个结构清晰的典型工程,目录名自取:
my-game/
├── index.html 入口页面,浏览器直接打开的那个文件
├── config.json 平台配置:标题、图标、运行库版本、键鼠形态、隐私清单
├── css/
│ └── style.css 样式
├── js/
│ ├── config.js 数值、文案、关卡参数
│ ├── bridge.js 平台桥接封装(取昵称/头像/XGID)
│ └── game.js 游戏逻辑与主循环
└── assets/
├── img/
│ ├── logo.png 1:1 图标,512×512 左右
│ └── avatar.svg 取不到头像时的默认占位头像(可选)
└── audio/ 音效/背景音乐(mp3/ogg/wav/m4a/webm,可选)
打包时把这个目录整体压成 zip;解压后应能直接看到 index.html 与 config.json。
五、配置文件 config.json
config.json 必须是合法 JSON 对象,放在包内可被定位到的层级。平台上传时自动读取,表单只做兜底;不上传代码包时才需要在表单里粘贴配置。
5.1 字段一览
| 字段 | 类型 | 必填 | 取值 / 默认 | 说明 |
|---|---|---|---|---|
title 或 name | 字符串 | 否 | 取压缩包目录名 | 游戏标题,最长 100 字 |
logo | 字符串 | 是 | 相对路径 | 1:1 的 png / svg / ico 图标,如 assets/img/logo.png |
runtime | 字符串 | 是 | vYYYY.N[.R] | 运行库版本号,只填版本号,不要写「晓织游戏运行库」这类完整名称 |
engine | 字符串 | 否 | 默认 h5 | 运行形态:h5 普通网页前端;java 网页版 Java(浏览器内 JVM 读取 jar 运行),见第十一节 |
vinput | 字符串 | 否 | 默认 allow | 虚拟键鼠形态:off 强制关闭 / allow 允许开启(默认关)/ on 默认展开 |
server_mode | 字符串 | 否 | 默认 none | none 平台托管纯前端 / external 自备服务器 |
server_url | 字符串 | 条件必填 | 空 | 选 external 时填试玩页加载地址,必须以 http:// 或 https:// 开头 |
privacy | 对象或数组 | 否 | 无 | 隐私与权限清单,写法见第六节 |
5.2 运行库版本格式
正则规则:v + 四位年份 + . + 第几次发布(1~3 位)+ 可选 . + 修订次数(1~3 位)。
合法示例:v2026.3.8、v2026.3、v2026.3.12。
不合法:晓织游戏运行库 v2026.3.8、2026.3.8、V2026.3.8(首字母必须小写 v)。
5.3 最小配置示例
{
"title": "我的小游戏",
"logo": "assets/img/logo.png",
"runtime": "v2026.3.8",
"vinput": "allow",
"server_mode": "none",
"privacy": [
{ "name": "profile", "purpose": "在游戏内显示玩家昵称与头像" }
]
}
5.4 不能写进配置的内容
开源协议(license / licence / 协议 / open_source_license / 授权协议)只能在提交表单里选择,写进 config.json 会被校验直接拒绝。开源可选协议:MIT、Apache-2.0、GPL-3.0、MulanPSL-2.0、BSD-3-Clause、CC-BY-4.0、自定义。
六、隐私与权限清单 privacy
游戏要读取玩家资料、调用摄像头/麦克风、连接第三方服务器时,必须先在 privacy 里声明权限和用途。未声明的权限运行时无法调用;用途不填或多次虚报会被拒绝上架,严重者永久封禁开发者账号。
6.1 两种写法(效果相同)
对象写法:
{
"privacy": {
"permissions": ["profile"],
"declarations": { "profile": "用于在游戏内显示你的昵称" }
}
}
数组写法:
{
"privacy": [
{ "name": "profile", "purpose": "用于在游戏内显示你的昵称" }
]
}
6.2 可选权限标识
| 标识 | 含义 |
|---|---|
profile | 昵称、头像等公开资料 |
email | 邮箱地址(需本人同意) |
camera.front | 前置摄像头 |
camera.back | 后置摄像头 |
camera | 摄像头(不区分前后) |
microphone | 麦克风 / 录音 |
network.third_party | 向第三方服务器发送数据 |
6.3 第三方联网域名白名单
声明 network.third_party 时,还要用 net_hosts 列出要连接的外部域名或 IP:
{
"privacy": {
"permissions": ["network.third_party"],
"declarations": { "network.third_party": "上传本关成绩到排行榜服务器" },
"net_hosts": ["api.example.com", "1.2.3.4"]
}
}
平台自身同源地址(本站域名、localhost、127.0.0.1、::1)以及后台维护的固定白名单地址不需要声明、也不弹授权;其余外部地址都按第三方网络处理。
6.4 授权流程
运行时由平台弹窗,玩家可选择:仅此一次(本次游玩有效)、永久允许(此浏览器不再询问)、全部允许(永久放行该游戏的所有第三方网络)、拒绝。被拒绝或未登录时,回调拿到空值,请用默认昵称、占位头像继续,不要卡住游戏流程。
七、平台桥接接口(XG)
需要昵称、头像、XGID 等资料时,不要自己写登录,直接引用平台桥接脚本:
<script src="/@!game-bridge.js"></script>
<script>
XG.onUser(function (user, game) {
if (!user) { /* 未登录或被拒绝:走兜底显示 */ return; }
console.log(user.username, user.avatar, user.xgid);
});
</script>
7.1 回调拿到的用户对象字段
| 字段 | 说明 |
|---|---|
uid | 网站用户编号 |
xgid | 平台内 XGID |
username / nickname | 昵称(二者等价) |
avatar | 头像图片地址,可直接写进 <img src>;为空时用占位头像兜底 |
email | 邮箱,仅在申请了 email 权限且玩家同意后才有值 |
registered_at | 注册日期(YYYY-MM-DD) |
7.2 回调拿到的游戏对象字段
| 字段 | 说明 |
|---|---|
uuid | 游戏在平台内的唯一标识 |
title | 游戏标题 |
version | 当前版本号 |
source_type | open 开源 / closed 闭源 |
runtime | 运行库版本 |
developer | 开发者显示名 |
privacy | 本游戏已声明的权限清单 |
whitelist | 当前放行的外部网络地址列表 |
7.3 XG 提供的方法
| 方法 | 作用 |
|---|---|
XG.onUser(fn) | 订阅玩家资料;已就绪则立即回调,否则排队等待。返回 XG 便于链式调用 |
XG.getUser() | 同步取当前用户,未就绪为 null |
XG.getGame() | 取当前游戏对象 |
XG.isReady() | 桥接是否已就绪 |
XG.requestUser() | 主动触发 profile 授权并拉取用户 |
XG.requestPermission(perm, cb) | 请求指定权限,回调返回 {state, mode, reason};未声明的权限直接 denied |
XG.hasPermission(perm) | 当前是否已有该权限 |
XG.getPermissions() | 已获准的权限标识列表 |
XG.getPrivacy() | 已声明的隐私清单 |
XG.request(url, opts) | 带网络授权封装的 fetch;白名单或已授权时直接请求,否则先弹 network.third_party 授权 |
XG.send(type, data) | 向平台父页面发消息 |
XG.storageKey(name) | 按游戏隔离生成 localStorage 键名,避免不同游戏串档 |
XG.onClear(fn) | 注册「清除本游戏本地数据」时的回调 |
XG.clearLocal() | 清除本游戏在本机的本地存储与会话权限 |
7.4 自备服务器取资料
后端游戏可用玩家 token 调平台接口拉取公开资料:
GET https://www.xiagoyn.cn/games/api/me
Header: Authorization: Bearer <玩家 token>
返回: {"ok":true,"user":{"uid":"200","xgid":"u0200","username":"晓织云梯","avatar":"https://…"}}
平台只给公开资料,不会把密码、邮箱、会话 token 交给游戏;取不到资料时按未登录处理,不要伪造玩家身份。
八、虚拟键盘与虚拟鼠标
试玩页内置一套虚拟键盘(标准美式 QWERTY,含 F1—F12、方向键、Shift / Ctrl / Alt)和虚拟鼠标(触控板加屏幕光标,支持左键、右键、滚动),供手机、平板和无实体键鼠的电脑使用。
每个游戏三选一,在创建游戏或详情页设置,也可写进 config.json 的 vinput:
| 取值 | 含义 |
|---|---|
off 强制不允许 | 游戏与虚拟键鼠不兼容(自绘输入框、坐标强绑定等)。不显示开关,玩家无法打开 |
allow 允许开启(默认关) | 显示「虚拟键盘」「虚拟鼠标」按钮,玩家自己点开。大多数游戏用这个 |
on 默认展开 | 允许开启且进页面就展开,玩家仍可关掉。适合明确需要键盘操作的游戏 |
可在详情页填一段 JSON 自定义配色:
{"kbBg":"rgba(20,24,34,.94)","kbFg":"#e8eefc","kbAccent":"#f59e0b","mouseBg":"rgba(24,28,40,.92)"}
支持的键:kbBg 键盘底色、kbFg 字色、kbAccent 按下高亮色、mouseBg 触控板底色。玩家开关状态按浏览器记忆,游戏不能强制覆盖玩家选择,也不会读取玩家的实体键盘输入。
九、闭源游戏与自备服务器
闭源游戏仍要上传两个包:前端代码(玩家可下载到本地缓存)与后端代码(上传存档供平台审核),两个都必填。后端代码由你自己的服务器运行,平台不代为运行、也不对外提供下载;需要常驻服务的游戏请自备服务器与域名。
选「自备服务器」时填试玩页要加载的地址,必须以 http(s):// 开头;试玩页把该地址放进 iframe 加载,跨域由你的服务器自行处理。自备服务器的游戏同样可以引用 /@!game-bridge.js、调用 /games/api/me,把玩家资料接到自己的后端。
十、打包与校验规则
上传时平台会自动解包并逐项校验,任一不满足即拒绝并返回错误码。
10.1 体积与数量
- 单包不超过 3000 个文件。
- 解压后总大小不超过 512 MB。
10.2 允许的文件扩展名
.html .htm .js .mjs .css .json .txt .md .png .jpg .jpeg .gif .webp .svg .ico .bmp .mp3 .ogg .wav .m4a .webm .mp4 .ttf .otf .woff .woff2 .wasm .xml .csv
10.3 禁止的文件扩展名
.exe .dll .so .sh .php .py .bat .cmd .msi .jar .apk .scr .vbs .ps1 .jsp .asp .aspx .cgi .pl
包内出现上述可执行/服务端脚本后缀会被直接拒绝。唯一例外:config.json 里 "engine": "java" 的网页版 Java 游戏,允许附带 .jar 程序包(jar 由浏览器端 JVM 分块读取,不在服务器上执行);其余可执行后缀依旧禁止。
10.4 路径与结构
- 压缩包内不得使用绝对路径,不得出现
../、/../或根路径跳转,平台做路径穿越检查。 - 必须包含
config.json,且能被解析为 JSON 对象。 - 必须包含可直接试玩的
index.html。 logo图标必须存在且为 1:1。- 后端源码不要打进前端包,前端包只放玩家可见的资源。
10.5 常见错误码
| 错误码 | 含义 | 处理方向 |
|---|---|---|
BAD_ZIP | 压缩包无法解析 | 重新打包,确保是标准 zip |
NO_CONFIG | 缺少 config.json | 把配置文件放进包内可定位层级 |
BAD_CONFIG / INVALID_CONFIG | 配置不是合法 JSON 或校验未过 | 检查 JSON 语法与字段取值,按报错提示修改 |
BAD_RUNTIME | 运行库版本格式错误 | 改成 vYYYY.N[.R] 纯版本号 |
MISSING_FIELDS | 标题或配置为空 | 补标题或配置 |
TOO_LONG | 标题超过 100 字 | 缩短标题 |
BAD_SOURCE | 开源/闭源未选或取值非法 | 选 open 或 closed |
LICENSE_REQUIRED | 开源游戏未选协议 | 在表单选择开源协议 |
十一、最小可运行示例工程
index.html:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>我的小游戏</title>
<link rel="stylesheet" href="css/style.css">
</head>
<body>
<div id="app"></div>
<script src="/@!game-bridge.js"></script>
<script src="js/game.js"></script>
</body>
</html>
config.json:
{
"title": "我的小游戏",
"logo": "assets/img/logo.png",
"runtime": "v2026.3.8",
"vinput": "allow",
"server_mode": "none",
"privacy": [
{ "name": "profile", "purpose": "在游戏内显示玩家昵称与头像" }
]
}
js/game.js(取资料并兜底):
XG.onUser(function (user, game) {
var name = user ? user.username : '游客';
var avatar = user && user.avatar ? user.avatar : 'assets/img/avatar.svg';
document.getElementById('app').textContent = '你好,' + name;
});
十二、网页版 Java 游戏(engine: java)
12.1 原理
平台通过浏览器内的 WebAssembly JVM(CheerpJ)直接读取并运行打包进来的 .jar。玩家本机不需要安装 Java,服务器也不执行 Java 代码;程序全程在玩家浏览器沙箱内运行。
12.2 包结构
my-java-game/
├── index.html 加载页:引入 CheerpJ 运行时并启动 jar
├── config.json
├── assets/img/logo.png
└── lib/
└── game.jar Java 程序包
12.3 config.json
{
"title": "我的 Java 小游戏",
"logo": "assets/img/logo.png",
"runtime": "v2026.3.9",
"engine": "java",
"server_mode": "none",
"privacy": []
}
engine 不填时默认 h5;填 java 后,校验才会放行包内的 .jar,其余可执行后缀仍然禁止。
12.4 加载页 index.html
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>我的 Java 小游戏</title>
<script src="https://cjrtnc.leaningtech.com/5.0/loader.js"></script>
</head>
<body>
<script type="module">
await cheerpjInit({ version: 8 });
cheerpjCreateDisplay(800, 600);
await cheerpjRunJar("/app/lib/game.jar");
</script>
</body>
</html>
cheerpjInit启动浏览器内 JVM,version选 Java 版本(8 / 11 / 17 / 21)。cheerpjCreateDisplay在页面上划出承载 Java 窗口的区域。cheerpjRunJar相当于java -jar;若程序不是可执行 jar、需要指定主类,改用cheerpjRunMain。
12.5 运行目录与路径
/app/是 Java 视角下本游戏包的 web 根目录;jar 与包内资源在 Java 代码里按/app/...引用,最常见的错误是漏写/app/前缀。- 浏览器沙箱内的虚拟文件系统就是运行目录,不读写玩家本机磁盘;需要落盘的存档走浏览器存储或自备服务器。
- 静态服务需支持 HTTP Range 分块读取(平台静态资源服务已支持)。
12.6 支持范围与限制
- 支持 Java 8 / 11 / 17 / 21(25 为预览),界面为 Swing / AWT。
- 不支持 JavaFX、SWT,以及预编译的原生
.dll/.so/.dylib。 - 首次进入需在线拉取运行时与 jar,体积较大、请耐心等待;建议使用 Chrome / Edge / Firefox / Safari 较新版本。
- CheerpJ 对个人、教育、爱好与技术评估免费;一人公司与非商业开源项目可免费使用并需保留 “Built with CheerpJ” 署名;商业用途需向其获取授权。上架前请自行确认许可口径。
12.7 平台侧同意流程
玩家进入 Java 游戏时,平台游玩页会先弹出「本游戏为网页版 Java 版本」说明与同意按钮;玩家同意后才加载运行环境与 jar,拒绝则不加载。开发者无需再自己写一层同意弹窗。
12.8 桥接与存档
- Java 程序不能直接调用网页版
XG桥接;如需昵称、头像等资料,由加载页 JS 经/@!game-bridge.js取到后,再通过 CheerpJ 与 Java 侧通信(进阶用法)。 - 本地存档约定同第十三节。
十三、本地存档约定
- 游戏本地进度建议存在 localStorage;键名优先用
XG.storageKey('best')生成,按游戏隔离,避免不同游戏串档。 - 玩家在平台「删除游戏数据」时,平台会调用本游戏注册的
XG.onClear回调并清除以本游戏命名空间开头的本地存储;如有内存态状态,在回调里一并重置。 - 平台不负责保存纯前端游戏的进度;需要跨设备存档或排行榜,请走第九节自备服务器方案。
十四、发布后更新
在游戏管理页重新上传代码包并填写更新日志即可出新版本。更新会重新走第十节的校验规则。游戏上架前会做形式审查;发现违规、举报核实或安全风险时,平台有权先行下架。
十五、上架前自查清单
供人工逐项核对,也可供 AI 程序化检查:
- 包内有
index.html,双击或静态服务可直接进入游戏。 config.json是合法 JSON,含logo与runtime。runtime为vYYYY.N[.R]纯版本号。logo路径相对、文件存在且 1:1。- 未把
license等协议字段写进配置文件。 - 用到的资料/摄像头/麦克风/第三方联网都在
privacy声明并写了用途。 - 外部联网域名已列入
net_hosts。 - 包内无第十节禁止的可执行/服务端脚本后缀;
engine: java包除外,仅允许附带.jar。 - Java 包的
index.html已引入 CheerpJ 加载器,jar 路径使用/app/...前缀。 - 无绝对路径与
../穿越;资源引用全部相对路径。 - 文件数 ≤3000,解压后 ≤512 MB。
- 未登录、被拒绝授权时游戏有兜底显示,不卡死流程。
- 手机竖屏与电脑横屏画面都不变形、不贴边。
十六、常见问题
试玩页打不开? 检查包内是否有 index.html,资源引用是否为相对路径。
上传被拒绝? 多为包含可执行文件、超过体积/文件数上限、路径越界或配置 JSON 不合法,按返回的错误码与提示重新打包再传。
开源与闭源怎么选? 开源:全部代码可下载、可修改、可再分发,须选开源协议。闭源:前端可下载,后端上传存档但运行在你自己的服务器上。
虚拟键鼠把画面挡住了? 键盘半透明覆盖在底部,玩家可随时关掉;游戏底部有固定按钮时建议选「允许开启(默认关)」。
玩家没登录取不到资料? XG.onUser 回调拿到 null,用默认昵称和占位头像继续,别卡住流程。
Java 游戏进不去 / 找不到 jar? 确认 config.json 写了 "engine": "java",加载页用 /app/... 引用 jar;jar 路径漏写 /app/ 前缀是最常见原因。JavaFX、SWT 与原生动态库不被支持。