面向游戏开发者

为 dingn 制作游戏

dingn 游戏就是网页:HTML、CSS 和 JavaScript,可以用任何能生成静态文件的引擎或框架制作。游戏运行在 dingn.com 的安全框架中,通过 dingn 游戏 SDK 获取玩家的语言和名字、保存进度以及登录。

下载入门游戏打开试玩场

三步开始

  1. 下载入门游戏并解压。
  2. 在你的电脑上启动这个文件夹的网页服务:
    npx serve --cors -l 5173 dingn-starter
    因为 dingn 在沙盒中运行游戏,你的服务器必须允许跨源访问(CORS)。使用 Vite 时,请把 server.cors 设为 true。
  3. 打开试玩场,输入 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 的加载画面。游戏可以开玩时调用它。

沙盒规则

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 上发布

  1. 压缩游戏文件夹,game.json 和 index.html 放在最外层。需要构建的游戏,请压缩构建后的文件。
  2. 在“我的游戏”上传压缩包。它会成为预览版,你可以马上试玩和分享。
  3. 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

任何人都可以在“我的游戏”中接受开发者协议后注册。 阅读开发者协议

我的游戏