面向游戏开发者
为 dingn 制作游戏
dingn 游戏就是网页:HTML、CSS 和 JavaScript,可以用任何能生成静态文件的引擎或框架制作。游戏运行在 dingn.com 的安全框架中,通过 dingn 游戏 SDK 获取玩家的语言和名字、保存进度以及登录。
三步开始
- 下载入门游戏并解压。
- 在你的电脑上启动这个文件夹的网页服务:
因为 dingn 在沙盒中运行游戏,你的服务器必须允许跨源访问(CORS)。使用 Vite 时,请把 server.cors 设为 true。npx serve --cors -l 5173 dingn-starter - 打开试玩场,输入 http://localhost:5173/ 并点击“加载”。修改文件后,点击“重新加载游戏”即可看到效果。
在游戏中加入 SDK
直接从 dingn 导入。它适用于任何现代浏览器,用不用打包工具都可以。
import { connect } from "https://dingn.com/sdk/v1/dingn-sdk.js";
const dingn = await connect();使用 TypeScript?下载类型定义: dingn-sdk.d.ts
在 dingn 之外单独打开时,connect() 依然可用:玩家未登录,语言跟随浏览器,存储的数据在页面关闭前有效。
SDK 参考
| 调用 | 作用 |
|---|---|
dingn.locale | 玩家的语言,"en" 或 "zh-CN"。请用这种语言显示游戏。 |
dingn.player | { signedIn, name, avatar }。不会包含邮箱或账号 ID。 |
dingn.onPlayer(fn) | 玩家登录或退出时调用。返回一个用于停止监听的函数。 |
dingn.storage.get(key)
dingn.storage.set(key, value) | 只在本设备上保存 JSON。键名最多 64 个字母、数字、点、短横线或下划线,值最大 16 KB。 |
dingn.progress.load()
dingn.progress.save(data) | 把 JSON 保存到已登录玩家的账号,换设备也能继续。最大 16 KB。没有玩家登录时,save() 会以代码 "signed_out" 失败。 |
dingn.rewards.unlock(id)
dingn.rewards.list() | 颁发 game.json 中列出的徽章,例如 "level-10"。每个徽章对每位玩家只发一次 dingn 金币,dingn 会弹出“获得徽章”提示。没有玩家登录时,unlock() 会以代码 "signed_out" 失败。list() 返回游戏的徽章以及玩家已获得哪些。 |
dingn.rewards.spend(id)
dingn.rewards.shop() | 出售 game.json "shop" 中列出的升级(例如 "power-1"),花费玩家的 dingn 金币。dingn 会先请玩家确认。spend() 可能以代码 "cancelled"、"not_enough_coins"、"requires" 或 "signed_out" 失败。shop() 返回游戏的升级以及玩家已拥有哪些。 |
dingn.rewards.earn(coins) | 为玩法本身向已登录玩家支付 1 到 10 个 dingn 金币,例如虽然失败但有所进展的关卡。每个游戏每天最多以这种方式向一位玩家支付 500 个金币,不计入徽章奖励;超出后 earn() 支付 0。dingn 会在游戏上方显示金币。无人登录时会以 "signed_out" 代码失败。 |
dingn.requestSignIn() | 引导玩家去登录,登录后会回到你的游戏。 |
dingn.navigate(path) | 离开游戏,前往 dingn 的某个页面,例如 "/" 是游戏列表。 |
dingn.ready() | 隐藏 dingn 的加载画面。游戏可以开玩时调用它。 |
沙盒规则
- 你的游戏运行在独立隔离的源中,无法读取 dingn 的页面、Cookie 或玩家账号。
- localStorage、sessionStorage、IndexedDB 和 Cookie 都被禁用。请改用 dingn.storage 和 dingn.progress。
- 用相对路径加载自己的文件,例如 img/hero.png。游戏的每个版本都放在各自的文件夹中提供。
- 支持全屏、声音、游戏手柄和指针锁定。链接会在新标签页中打开。
- 因为游戏的源是不透明的,请求其他服务器需要对方支持 CORS。
game.json
每个游戏在 index.html 旁边都有一个 game.json,用英文和中文为游戏命名:
{
"id": "mygame",
"version": "1.0.0",
"title": { "en": "My Game", "zh": "我的游戏" },
"description": { "en": "…", "zh": "…" },
"entry": "index.html",
"category": "casual",
"cover": "cover.png"
}id 为 2 到 31 个小写字母和数字,以字母开头。每次发布都需要新的版本号,因为已发布的版本永远不会改变。
category 可以是 casual(休闲)、memory(记忆)或 puzzle(益智):游戏通过审核后,会出现在该分类的页面和菜单里。cover 是游戏文件中的一张可选图片,用作游戏卡片,比例 16:10,约 800×500。没有的话,dingn 会用游戏标题画一张卡片。
在 dingn 上发布
- 压缩游戏文件夹,game.json 和 index.html 放在最外层。需要构建的游戏,请压缩构建后的文件。
- 在“我的游戏”上传压缩包。它会成为预览版,你可以马上试玩和分享。
- dingn 审核预览版后将其上线。每次更新时,请提高 game.json 中的版本号并重新上传。
从 GitHub 或脚本上传
在“我的游戏”中创建上传密钥,然后用它发送 zip。这样上传的版本与其他上传一样需要审核。在 GitHub Action 中,把密钥存为名为 DINGN_UPLOAD_KEY 的 secret:
curl --fail-with-body -X POST https://dingn.com/api/developer/games/upload \
-H "Authorization: Bearer $DINGN_UPLOAD_KEY" \
-H "Content-Type: application/zip" \
--data-binary @my-game-1.0.0.zip任何人都可以在“我的游戏”中接受开发者协议后注册。 阅读开发者协议