dokiworlds-app-sdk 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # dokiworlds-app-sdk 使用指南
2
2
 
3
- 适用版本:`dokiworlds-app-sdk@0.4.2`。主要入口是 `createAppClient`、`client.whenReady`、`client.input`、`client.apps.launch`、`client.complete`、`client.requestExit` 和独立世界的 `createLlmRuntime`;宿主侧可用 `createAppHost` 和 `createAppsHostExtension`。协议仍为 v2。
3
+ 适用版本:`dokiworlds-app-sdk@0.5.0`。主要入口是 `createAppClient`、`client.whenReady`、`client.input`、`client.apps.launch`、`client.complete`、`client.requestExit`、独立世界的 `createLlmRuntime` 与 `getWorldLocale`;宿主侧可用 `createAppHost` 和 `createAppsHostExtension`。协议仍为 v2。
4
4
 
5
5
  每次接入、构建或发布前,请先打开 OSS 上的[最新使用指南](https://static-doki.aimeng.ai/releases/dokiworlds-app-sdk/GUIDE.md)、[独立世界规范](https://static-doki.aimeng.ai/releases/dokiworlds-app-sdk/WORLD_PACKAGE_GUIDE.md)与 [README / 版本摘要](https://static-doki.aimeng.ai/releases/dokiworlds-app-sdk/README.md),并执行 `npm view dokiworlds-app-sdk version` 确认 npm 当前版本。若当前安装版本落后于在线规范要求,升级依赖、更新 lockfile 后重新构建和回归测试。
6
6
 
@@ -15,11 +15,24 @@
15
15
  在 App 或独立世界的源码项目中,从 npm 安装已发布的 SDK。为保证构建可复现,首次接入及正式发布应固定版本:
16
16
 
17
17
  ```bash
18
- npm install dokiworlds-app-sdk@0.4.2
18
+ npm install dokiworlds-app-sdk@0.5.0
19
19
  ```
20
20
 
21
21
  SDK 是浏览器端 ESM。App 必须运行在支持 `postMessage` 的 iframe 中,由实现 `dokiworld.app` v2 的宿主加载;`apps.launch` 另外要求宿主允许拉起子 App。`npm install` 只提供 SDK,不会自行创建 App 目录、列表或弹窗。若 App 以静态文件放在 `public/apps`,请用自己的构建工具把 `dokiworlds-app-sdk` 打包进浏览器脚本;浏览器不能直接从静态页面解析 `import ... from 'dokiworlds-app-sdk'` 这个 npm 裸包名。
22
22
 
23
+ ## 独立世界语言运行时
24
+
25
+ 独立世界必须完整支持 `zh-CN` 与 `en`。不要在 `manifest.json` 另加语言开关;平台会在访客从右上角选择语言并启动世界时,把最终语言注入入口页面。世界源码从 SDK 读取它,再加载对应的 UI、文本、音频或其他本地化资源:
26
+
27
+ ```js
28
+ import { getWorldLocale } from 'dokiworlds-app-sdk/world_runtime';
29
+
30
+ const locale = getWorldLocale(); // 只会是 'zh-CN' 或 'en'
31
+ const copy = locale === 'en' ? englishCopy : chineseCopy;
32
+ ```
33
+
34
+ 本地直开调试可使用 `?_dw_locale=en` 或 `?_dw_locale=zh-CN`;它只用于预览。上线后以平台启动时注入的语言为准。不得只依赖浏览器语言,也不得把语言状态改写为 API key、用户身份或 LLM 参数。
35
+
23
36
  升级时执行 `npm install dokiworlds-app-sdk@<目标版本>`,保留更新后的 lockfile,重新构建并运行回归测试。面向 DokiWorlds 上传的 ZIP 只放构建产物,绝不上传 `node_modules/`、lockfile 或 `.env`。如需离线交付,也可在包目录执行 `npm pack` 生成 tgz;这不是从 npm 安装的替代要求。
24
37
 
25
38
  ## 检定演出插槽:给 App 作者
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  ## Install
4
4
 
5
5
  ```bash
6
- npm install dokiworlds-app-sdk@0.4.2
6
+ npm install dokiworlds-app-sdk@0.5.0
7
7
  ```
8
8
 
9
9
  Use the package from a source project and bundle it for the browser. A browser cannot resolve the npm bare import directly from a static HTML world. To upgrade, install the explicitly selected newer version, update the lockfile, rebuild, and retest the published world package.
@@ -20,7 +20,7 @@ Do not rely on an old copied guide or replace a single SDK file inside an alread
20
20
 
21
21
  完整 HTML 世界的 ZIP 结构、`packageType: "world"` 清单和平台 LLM 接入见 [WORLD_PACKAGE_GUIDE.md](./WORLD_PACKAGE_GUIDE.md)。
22
22
 
23
- Version 0.4.2 synchronizes the published guides with the platform's 24-hour, world-scoped HttpOnly session contract. Runtime code and the v2 App protocol remain unchanged from 0.4.1.
23
+ Version 0.5.0 adds `dokiworlds-app-sdk/world_runtime`. Standalone worlds use `getWorldLocale()` to follow the language selected in the DokiWorlds visitor interface. Version 0.4.2 synchronizes the published guides with the platform's 24-hour, world-scoped HttpOnly session contract.
24
24
 
25
25
  Version 0.4.1 keeps standalone-world LLM proxy requests on the DokiWorlds page origin when published resources use a CDN `<base>` URL. Version 0.4.0 adds `llm.listModels()` for standalone worlds. An embedded App can read its versioned input, return a completion, and request another App when the host grants that capability. The host controls catalog lookup, permissions, presentation, and lifecycle. See GUIDE.md for the check-reveal slot contract and local package installation.
26
26
 
@@ -41,6 +41,16 @@ const reply = await llm.invoke({ model, messages: [{ role: 'user', content: 'Hel
41
41
 
42
42
  Do not hard-code a provider model name. `listModels()` returns only text models currently enabled by the platform for the launched world; each item has `modelId`, and may include `tierId`, `recommended`, and `priceDiamonds`. The available list can change with platform configuration, player entitlement, or provider availability.
43
43
 
44
+ ## Standalone-world locale
45
+
46
+ ```js
47
+ import { getWorldLocale } from 'dokiworlds-app-sdk/world_runtime';
48
+
49
+ const locale = getWorldLocale(); // 'zh-CN' or 'en'
50
+ ```
51
+
52
+ The selected locale comes from the visitor interface at launch. A world must ship complete `zh-CN` and `en` gameplay UI and content, then select its own translations/assets from this value. It is not stored in `manifest.json` and is not an LLM option.
53
+
44
54
  ```js
45
55
  import { createAppClient } from "dokiworlds-app-sdk";
46
56
 
@@ -101,7 +101,7 @@ honglou-opening.zip
101
101
 
102
102
  ```bash
103
103
  # 首次接入:固定使用当前已验证版本
104
- npm install dokiworlds-app-sdk@0.4.2
104
+ npm install dokiworlds-app-sdk@0.5.0
105
105
  ```
106
106
 
107
107
  升级时由开发者明确选择目标版本,再重新构建和完整验证世界包:
@@ -114,6 +114,21 @@ npm run build
114
114
 
115
115
  `package.json` 与 lockfile 必须一并保留在世界源码仓库中,以便复现已发布 ZIP 的构建结果。每次 SDK 升级都必须重新生成 ZIP、提高世界 `version`,并从 DokiWorlds 访客入口实际验证 LLM;不要只替换 ZIP 内某个 SDK 文件。静态 HTML 不能直接解析 npm 裸模块名,因此构建过程必须把 SDK 编译进浏览器脚本或输出为包内相对模块。
116
116
 
117
+ ## 双语世界(必需)
118
+
119
+ 每个独立世界必须同时提供完整的简体中文(`zh-CN`)与英文(`en`)游玩体验,包括首屏、按钮、菜单、提示、剧情文本、角色对话和世界自身的 LLM UI。展示卡片用的 `manifest.locales` 仍保持现有结构;**不要**为运行语言新增 manifest 字段。
120
+
121
+ 运行语言由访客入口右上角的当前语言决定。源码项目安装 SDK 后,从 `dokiworlds-app-sdk/world_runtime` 读取它,再选择自己的本地化资源:
122
+
123
+ ```js
124
+ import { getWorldLocale } from 'dokiworlds-app-sdk/world_runtime';
125
+
126
+ const locale = getWorldLocale(); // 'zh-CN' | 'en'
127
+ const text = locale === 'en' ? englishText : chineseText;
128
+ ```
129
+
130
+ 构建后的 ZIP 需要包含该相对模块及两套实际使用的文本/资源;不能把 npm 裸模块名留在 HTML。平台启动时会把语言注入入口 HTML,SDK 会优先读取该值;本地预览可在入口 URL 追加 `?_dw_locale=en` 或 `?_dw_locale=zh-CN`。浏览器语言仅是直接打开包时的兜底,不能替代双语内容。
131
+
117
132
  ```js
118
133
  import { createLlmRuntime } from 'dokiworlds-app-sdk/llm_config';
119
134
 
@@ -179,6 +194,7 @@ my-world/
179
194
  5. 本地将目录放到 `frontend/public/apps/<id>/`,从访客入口启动一次,确认封面、首屏、音频/视频、进入流程和 LLM(若启用)都正常。
180
195
  6. 若升级过 SDK:确认 `package.json` 与 lockfile 已锁定目标 SDK 版本,且已重新执行构建;ZIP 中没有 `node_modules/` 或 `.env` 文件。
181
196
  7. 更新已提高 `version`;发布后用无缓存窗口验证入口、封面和首屏资源均来自新 release。
197
+ 8. 分别从访客入口切换为中文和 English 后启动世界,确认两种语言的首屏、流程、动态文本与 LLM UI 都使用对应语言。
182
198
 
183
199
  Game Admin 后续会把以上会导致运行失败的项目逐步升级为上传阻断校验;在此之前,作者必须自行完成该清单。
184
200
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dokiworlds-app-sdk",
3
- "version": "0.4.2",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -10,6 +10,10 @@
10
10
  "./llm_config": {
11
11
  "types": "./src/llm_config.d.ts",
12
12
  "default": "./src/llm_config.js"
13
+ },
14
+ "./world_runtime": {
15
+ "types": "./src/world_runtime.d.ts",
16
+ "default": "./src/world_runtime.js"
13
17
  }
14
18
  },
15
19
  "files": ["src", "README.md", "GUIDE.md", "WORLD_PACKAGE_GUIDE.md"],
@@ -0,0 +1,10 @@
1
+ export type WorldLocale = 'zh-CN' | 'en';
2
+
3
+ export declare const WORLD_LOCALES: readonly WorldLocale[];
4
+
5
+ export declare function getWorldLocale(options?: {
6
+ document?: Pick<Document, 'querySelector'>;
7
+ location?: Pick<Location, 'search'>;
8
+ navigator?: Pick<Navigator, 'language' | 'languages'>;
9
+ fallback?: WorldLocale;
10
+ }): WorldLocale;
@@ -0,0 +1,35 @@
1
+ export const WORLD_LOCALES = Object.freeze(["zh-CN", "en"]);
2
+
3
+ function validLocale(value) {
4
+ return WORLD_LOCALES.includes(value);
5
+ }
6
+
7
+ function metaLocale(document) {
8
+ const value = document?.querySelector?.('meta[name="dokiworlds-world-locale"]')?.getAttribute("content");
9
+ return validLocale(value) ? value : null;
10
+ }
11
+
12
+ function queryLocale(location) {
13
+ const value = new URLSearchParams(location?.search || "").get("_dw_locale");
14
+ return validLocale(value) ? value : null;
15
+ }
16
+
17
+ function browserLocale(navigator) {
18
+ const candidates = Array.isArray(navigator?.languages) && navigator.languages.length
19
+ ? navigator.languages : [navigator?.language];
20
+ for (const candidate of candidates) {
21
+ if (typeof candidate !== "string") continue;
22
+ if (candidate.toLowerCase().startsWith("en")) return "en";
23
+ if (candidate.toLowerCase().startsWith("zh")) return "zh-CN";
24
+ }
25
+ return null;
26
+ }
27
+
28
+ /**
29
+ * Returns the platform-selected locale for a standalone world.
30
+ * Platform-injected HTML takes precedence; the query string supports local previews.
31
+ */
32
+ export function getWorldLocale({ document = globalThis.document, location = globalThis.location, navigator = globalThis.navigator, fallback = "zh-CN" } = {}) {
33
+ if (!validLocale(fallback)) throw new TypeError("fallback must be zh-CN or en");
34
+ return metaLocale(document) || queryLocale(location) || browserLocale(navigator) || fallback;
35
+ }