pelican-engine 0.3.3 → 0.3.5

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.
Files changed (19) hide show
  1. package/AGENTS.md +21 -8
  2. package/CONTRIBUTING.md +35 -0
  3. package/README.md +72 -117
  4. package/distribution.json +18 -16
  5. package/docs/DECISIONS.md +1 -0
  6. package/docs/GETTING-STARTED.md +80 -0
  7. package/docs/PELICAN-MIGRATION.md +5 -5
  8. package/docs/RENDER-BACKENDS.md +6 -4
  9. package/docs/STATUS.md +1 -1
  10. package/docs/api/REFERENCE.md +2 -2
  11. package/docs/api/index.json +2 -2
  12. package/docs/assets/pelican-mark.svg +9 -0
  13. package/docs/npm/DISTRIBUTION.md +72 -117
  14. package/docs/npm/GAME-AUTHOR.md +21 -8
  15. package/engine.manifest.json +1 -1
  16. package/lib/sdk/index.d.ts +1 -1
  17. package/lib/sdk/index.js +1 -1
  18. package/package.json +2 -1
  19. package/docs/M3-USAGE.md +0 -192
package/AGENTS.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Pelican Engine Game Author
2
2
 
3
+ For an installed game, start in an empty directory with `npm --prefix . install
4
+ --save-dev --save-exact pelican-engine`, then run `npx pelican dev`. The CLI
5
+ generates the minimal starter when the directory is eligible and preserves existing
6
+ game files. See `docs/GETTING-STARTED.md` in the package for npm and source
7
+ workflows. Commands use common Node/npm syntax; the currently supported development
8
+ environment is Windows, while player support depends on actual browser capabilities.
9
+
3
10
  Your workspace is the game project. Use the public `pelican-engine` API and local
4
11
  game modules. Do not modify engine internals or `node_modules`, import Three.js,
5
12
  TSL, GPU devices, physics-library objects, compiler internals or Node APIs into
@@ -15,8 +22,8 @@ lists the JSON CLI protocol. `docs/CAPABILITIES.md` records implemented scope an
15
22
  limitations. The longer `docs/AI-WORKFLOW.md` is shared design context, not an
16
23
  instruction to run source-only engine acceptance tasks.
17
24
 
18
- The shared `docs/M3-USAGE.md` describes the current rendering and compute
19
- contracts. Its `examples/`, engine `packages/`, and `npm run probe:*` references
25
+ The source checkout's `docs/STATUS.md` summarizes current engine capabilities
26
+ and gaps. Its `examples/`, engine `packages/`, and `npm run probe:*` references
20
27
  are maintainer references available only in a source checkout; the npm package
21
28
  intentionally contains no example projects, game assets, or engine source. Use
22
29
  the same public declarations in your own game project and validate them with the
@@ -107,20 +114,26 @@ Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
107
114
  `KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],
108
115
  restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the
109
116
  actual keyboard event; Space is `" "`. Actions are read inside systems through
110
- `ctx.input.held`, `pressed`, `released`, or `axis`. Always exercise real keyboard
111
- input in the browser; a mocked system test does not establish browser bindings.
117
+ `ctx.input.held`, `pressed`, `released`, or `axis`. A mocked system test does not
118
+ establish browser bindings; real input requires separate verification when permitted.
112
119
 
113
120
  ## Work Loop
114
121
 
115
122
  1. Inspect `pelican.project.json`, `game.ts`, asset declarations and the public API.
116
123
  2. Make small game-only edits. Keep the exact engine version lock.
117
- 3. Run `pelican check`, then `pelican dev` and exercise actual gameplay.
124
+ 3. Follow the active project policy for running the game or checking gameplay.
118
125
  4. Use `inspect`, `input`, `step`, `pause`, `resume`, `snapshot`, `restore`,
119
- `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port.
120
- 5. Run `capture --live` against the dev port or a standalone `capture`, inspect
121
- the actual screenshot, and preserve explicit failures rather than claiming success.
126
+ `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port
127
+ when verification is permitted.
128
+ 5. When verification is permitted, use capture and inspect results; preserve
129
+ explicit failures rather than claiming success.
122
130
  6. Run `build` and serve `dist/` over HTTP(S). Keep notices and license files.
123
131
 
132
+ The current engine project decision permits compilation and builds only, not
133
+ tests, browser/GPU runs, smoke or other validation. Historical instructions and
134
+ reports do not authorize those activities or establish that they passed for the
135
+ current source.
136
+
124
137
  Installed package commands use `npx --no-install pelican <command>` from the game
125
138
  directory. Repository commands use `node --import tsx <engine>/tools/cli.ts
126
139
  <command> --project <game-directory>` with the same operations and protocol.
package/CONTRIBUTING.md ADDED
@@ -0,0 +1,35 @@
1
+ # 参与开发
2
+
3
+ 感谢关注 Pelican Engine！本项目使用 MIT 许可证。游戏作者可以只安装 npm 包；本指南面向需要阅读、修改或维护引擎源码的贡献者。
4
+
5
+ ## 开发前
6
+
7
+ 请先阅读 [当前研发状态](docs/STATUS.md)、[架构](docs/ARCHITECTURE.md) 和与你的改动有关的文档。确认改动范围、现有工作区状态和已知限制，不覆盖他人的未提交文件。公开 API 由 SDK 源码定义；改动接口时应同时维护相关类型、文档和示例。
8
+
9
+ 当前支持的引擎开发环境为 Windows，使用 Node.js 24.x 和 npm。以下是通用 Node/npm 命令的写法，不代表其他开发系统已经受支持。玩家端按实际浏览器与图形能力判断，不设置平台白名单。
10
+
11
+ ## 从源码运行
12
+
13
+ ```sh
14
+ git clone https://github.com/danchar12138/pelican-engine.git
15
+ cd pelican-engine
16
+ npm ci
17
+ npm run dev
18
+ ```
19
+
20
+ `npm run dev` 使用仓库当前默认示例；`npm run build` 将示例静态构建输出到根目录 `dist/`。源码 ZIP 和已有目录也可以使用这些命令，不依赖 Git 元数据。若只是创建游戏，请优先阅读 [快速入门](docs/GETTING-STARTED.md)。
21
+
22
+ ## 单线、单主题提交
23
+
24
+ - 在 `main` 主工作树按依赖串行工作，不建立额外工作树或开发分支。
25
+ - 一次提交围绕一个功能、修复或版本；不要把无关工作和历史证据混在一起。提交消息使用中文 Conventional Commits，例如 `fix(renderer): 修复资源释放`。
26
+ - 需要发布时在仓库中显式维护统一的标准版本号。推送 `main` 会触发 npm OIDC 发布；版本已存在时不会覆盖。GitHub Release 用于标记里程碑。详见 [发布说明](docs/RELEASING.md)。
27
+ - 用户要求当前只允许编译和构建；不要运行测试、浏览器、GPU、性能、smoke 或其他验证，也不要声称未执行的步骤通过。以前的测试文件和证据保留其历史属性。
28
+ - 不要为整理目录而删除未经确认的用户数据、历史报告或未合并候选；不能递归跟随目录链接或 junction。
29
+
30
+ ## 提交问题或改动
31
+
32
+ 描述目标、涉及的公开接口、实际运行的编译或构建命令、结果与已知缺口。运行或硬件行为未经验证时明确说明。涉及第三方代码或资产时记录来源与许可证；不要提交凭据、开发缓存或构建输出。
33
+
34
+ - [问题反馈](https://github.com/danchar12138/pelican-engine/issues)
35
+ - [公开 API](docs/api/REFERENCE.md) · [能力说明](docs/CAPABILITIES.md) · [开发状态](docs/STATUS.md)
package/README.md CHANGED
@@ -1,130 +1,85 @@
1
- # Pelican Engine npm development distribution
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/danchar12138/pelican-engine/main/docs/assets/pelican-mark.svg" alt="Pelican Engine" width="110" height="110">
3
+ <h1>Pelican Engine</h1>
4
+ <p><strong>Build games for the web with TypeScript.</strong></p>
5
+ <p>Code-first · WebGPU-first · Designed for human and external AI workflows</p>
6
+ <p>
7
+ <a href="https://www.npmjs.com/package/pelican-engine"><img src="https://img.shields.io/npm/v/pelican-engine?label=npm&amp;color=168b80" alt="npm version"></a>
8
+ <img src="https://img.shields.io/badge/license-MIT-24536b" alt="MIT license">
9
+ <img src="https://img.shields.io/badge/TypeScript-SDK-3178c6" alt="TypeScript SDK">
10
+ </p>
11
+ </div>
12
+
13
+ Pelican Engine provides a TypeScript SDK, compiler, runtime, renderer and CLI in one package. Define game content and behavior in code, run a local development server and build a static web distribution. AI tools may assist development, but the game runtime does not include an LLM or AI agent.
14
+
15
+ > **Development status:** this is an evolving engine, not a complete first release. Current source behavior, hardware compatibility, performance and the full feature set have not been fully validated. A normal version number is not an acceptance claim. See the [development status](https://github.com/danchar12138/pelican-engine/blob/main/docs/STATUS.md) for known gaps.
16
+
17
+ ## Quick start
18
+
19
+ Install Node.js **24.x** and npm, then create a new empty game directory:
20
+
21
+ ```sh
22
+ mkdir my-pelican-game
23
+ cd my-pelican-game
24
+ npm --prefix . install --save-dev --save-exact pelican-engine
25
+ npx pelican dev
26
+ ```
27
+
28
+ The first `dev` creates `game.ts`, `pelican.project.json` and `AGENTS.md` in an eligible empty project. Existing game files and author instructions are not overwritten. The explicit `--prefix .` prevents npm from choosing a parent project; `--save-exact` pins the installed version. Stop the development server before building:
29
+
30
+ ```sh
31
+ npx --no-install pelican build
32
+ ```
2
33
 
3
- The installed package is `pelican-engine`. Its root export is the same compiled
4
- public SDK used by repository games, not a wrapper or a separate SDK. The package
5
- also provides the `pelican` executable. This is an M3 development distribution,
6
- not accepted M3 hardware evidence or a complete engine release.
34
+ Deploy the resulting `dist/` directory, including its generated assets and notices, to an HTTP(S) static host. For a nested deployment, use `npx --no-install pelican build --base /game/`.
7
35
 
8
- ## Windows project workflow
36
+ Commands use common Node/npm syntax rather than a particular shell. **Engine and game development currently support Windows only**; Linux and macOS development workflows have not been promised or validated. Player platforms are not restricted by brand or OS: actual rendering availability depends on browser and graphics capabilities.
9
37
 
10
- Use Node 24 and npm in an empty project directory. The explicit prefix keeps npm
11
- in this directory even when a parent directory is also an npm project:
38
+ ## Your game
12
39
 
13
- ```powershell
14
- npm --prefix . i -D pelican-engine
15
- npx pelican dev
40
+ The generated starter defines a scene and a rotating box. Game code imports only the public package, for example:
41
+
42
+ ```ts
43
+ import { defineGame, defineMaterial, defineScene } from "pelican-engine";
44
+
45
+ const material = defineMaterial({ id: "paint", color: "#38b8a4", roughness: 0.45 });
46
+ const scene = defineScene({
47
+ id: "main",
48
+ camera: { position: [4, 3, 6], target: [0, 0, 0], fov: 50 },
49
+ entities: [
50
+ { id: "box", mesh: { geometry: { kind: "box" }, material } },
51
+ { id: "light", light: { kind: "directional", intensity: 4 },
52
+ transform: { position: [3, 6, 4] } },
53
+ ],
54
+ });
55
+ export default defineGame({ id: "my-game", scene });
16
56
  ```
17
57
 
18
- The first installed `dev` creates the minimal `game.ts`, `pelican.project.json`
19
- version lock, and game-author `AGENTS.md` when the directory contains only npm
20
- installation metadata. An existing game or manifest is used as supplied; other
21
- project files or author instructions prevent automatic scaffolding. Files are
22
- never overwritten. Stop dev with Ctrl+C, then use the same local CLI:
58
+ Save it as `game.ts` in a project created by the CLI. The exact engine version is recorded in `pelican.project.json`: migrate the game and update its lock explicitly when changing engine versions. Do not edit `node_modules` or import engine internals.
59
+
60
+ Useful commands:
23
61
 
24
- ```powershell
62
+ ```sh
63
+ npx --no-install pelican help
25
64
  npx --no-install pelican api
26
- npx --no-install pelican setup --install-browser
27
- npx --no-install pelican check
65
+ npx --no-install pelican api --symbol defineGame
28
66
  npx --no-install pelican dev --port 4173
29
- npx --no-install pelican capture --port 4174 --output capture.png
30
67
  npx --no-install pelican build
31
68
  ```
32
69
 
33
- For an exact-version install use `npm --prefix . i -D --save-exact pelican-engine@0.3.3`,
34
- or substitute the local `pelican-engine-0.3.3.tgz` tarball before registry
35
- publication. `pelican create --template minimal` remains available explicitly.
36
-
37
- Without `--prefix .`, npm may select an ancestor `package.json` or `node_modules`
38
- as the install root and modify that parent. The shorter `npm i -D pelican-engine`
39
- works when npm selects the intended directory; verify `npm prefix` before using
40
- it. The smoke harness uses an explicit prefix and does not require `npm init`.
41
-
42
- `create --template minimal` uses the same primitive starter in npm and repository
43
- workflows. npm defaults to `minimal` and reports the selected template; repository
44
- default `m2` is preserved with its historical sample assets. Samples are not engine
45
- capabilities. Identical authored game/asset inputs use the same API/compiler/runtime
46
- in either channel. npm does not bundle the `m2` sample or any sample/game assets.
47
-
48
- `create` writes `game.ts`, `AGENTS.md` and an exact `pelican.project.json` lock in the current
49
- directory. Existing project files are never overwritten. Author TypeScript with
50
- named imports from `pelican-engine` and project-local imports only. The compiler
51
- reports `TC_PUBLIC_API` for renderer, Three.js, TSL, physics, Node and internal
52
- package imports, including type-only and unused imports. Package subpaths are not
53
- public exports. Project lock mismatches report `TC_ENGINE_VERSION_MISMATCH`;
54
- mixed package/API versions report `TC_ENGINE_SDK_VERSION`. Reinstall a matching
55
- exact version, or migrate through the public API before explicitly changing a lock.
56
-
57
- After npm dependencies and Playwright Chromium have been installed, authoring,
58
- API inspection, checks, builds, dev/control commands and capture need no network
59
- service. `setup --offline` never installs dependencies or downloads a browser in
60
- an installed package. Keep the game package-lock for repeatable future installs;
61
- an offline _reinstall_ additionally requires the npm cache or a dependency mirror.
62
- `TC_DISTRIBUTION_DEPENDENCY_MISSING` and
63
- `TC_DISTRIBUTION_DEPENDENCY_VERSION` identify broken tool dependencies.
64
-
65
- Serve the generated `dist/` directory over HTTP(S), including its `generated/`
66
- files, license files, notices and compression manifests. No Node process, engine
67
- repository, SDK installation, external AI service or development control server
68
- is needed by players. Use `build --base /game/` for a nested deployment URL.
69
- Capture requires installed Chromium and actual supported graphics capability.
70
- No software renderer result establishes hardware acceptance.
71
-
72
- ## AI entry points
73
-
74
- Read the game-author `AGENTS.md`, `docs/npm/GAME-AUTHOR.md`, `docs/CAPABILITIES.md` and
75
- `docs/api/REFERENCE.md` inside `node_modules/pelican-engine`. The machine-readable
76
- API is `docs/api/index.json`, also discoverable through `pelican api`.
77
- `lib/sdk/index.d.ts` is the authoritative installed declaration surface.
78
- `docs/PELICAN-MIGRATION.md` explains current names and historical provenance.
79
- Repository paths and release instructions in copied documents are historical
80
- context; the installed workflow above replaces source-checkout commands.
81
- The JSON CLI protocol and dev control operations are shared with the repository.
82
-
83
- ## Maintainer validation and publishing
84
-
85
- ```powershell
86
- npm run distribution:test
87
- npm run distribution:pack
88
- npm run distribution:smoke
89
- npm run distribution:smoke -- --gpu
90
- ```
70
+ The renderer prioritizes WebGPU and can use Three.js's built-in WebGL2 raster fallback. Compute-dependent hybrid/path tracing and compute features are not available on WebGL2; unsupported requests return diagnostics rather than silently claiming equivalent rendering. See the [backend guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/RENDER-BACKENDS.md).
71
+
72
+ ## Documentation
73
+
74
+ - [Getting started: npm and source checkout](https://github.com/danchar12138/pelican-engine/blob/main/docs/GETTING-STARTED.md)
75
+ - [Game author guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/npm/GAME-AUTHOR.md)
76
+ - [API reference](https://github.com/danchar12138/pelican-engine/blob/main/docs/api/REFERENCE.md) and [capabilities](https://github.com/danchar12138/pelican-engine/blob/main/docs/CAPABILITIES.md)
77
+ - [Source repository and contribution guide](https://github.com/danchar12138/pelican-engine)
78
+
79
+ The installed package also includes `docs/npm/GAME-AUTHOR.md`, `docs/api/REFERENCE.md`, `docs/api/index.json` and `lib/sdk/index.d.ts`. The installed declarations and `pelican api` describe the API of the actual installed version. Repository examples and assets are not shipped in the npm package.
80
+
81
+ Playwright Chromium is optional for capture and browser automation. If needed, prepare it while online with `npx --no-install pelican setup --install-browser`. With required dependencies and assets already available, everyday operations need no engine account or hosted development service. An offline reinstall additionally requires cached packages.
82
+
83
+ ## License
91
84
 
92
- Build output is regenerated from current sources into ignored
93
- `.pelican/npm/package/`; tarballs and smoke reports go in `.pelican/npm/artifacts/`.
94
- Neither staging nor tarballs are inside the deployable game `dist/`.
95
- Pack that staging directory, not the private repository root. Compiled relative
96
- imports use `lib/` modules and `.js`, never the TypeScript source layout. The
97
- tarball allowlist excludes source maps, evidence, examples and game assets;
98
- SDK declarations, engine runtime code, MIT, copied AI docs, and dependency
99
- license texts are included. `distribution.json` records version and file hashes.
100
- Dependencies are normal pinned npm dependencies, not vendored engine sources.
101
-
102
- The npm workflow runs only for a published GitHub milestone release. Its gate
103
- requires tag/version/SDK/manifest identity and the existing milestone acceptance
104
- and source-fingerprint checks. An ordinary push or CPU-green build cannot publish.
105
- M3 is deliberately blocked until its release profile and real acceptance exist.
106
- The default smoke install uses npm cache only; `--online-install` allows network
107
- for initial dependency installation, then runs every operation offline with a
108
- disabled registry. CI uses this flag because `npm ci` alone need not populate
109
- registry metadata for a fresh external install. `--gpu` additionally measures
110
- the installed WebGPU backend, renders path/hybrid/raster, checks a nonblank canvas,
111
- captures through both CLI routes, verifies WebGL2 fallback rejection, and loads
112
- the nested-base static build without a development hook. It is not M3 acceptance.
113
-
114
- The single unscoped package is `pelican-engine`, its only public import is
115
- `pelican-engine`, and its executable is `pelican`. The GitHub target is
116
- `danchar12138/pelican-engine`; main completed the public repository rename and
117
- verified the updated origin. No new organization is required. The authorized
118
- npm Automation Token was authenticated as `danchar12138`, and main confirmed
119
- the repository Actions secret `NPM_TOKEN` is configured. `npm view pelican-engine`
120
- returned `E404` before publication. The package remains unpublished pending
121
- genuine M3 acceptance; this is not an authentication or organization blocker.
122
- `setup-node` configures the registry;
123
- only the final publication step receives `NODE_AUTH_TOKEN`. A missing secret
124
- fails with `TC_NPM_AUTH_MISSING`, without printing the value. The token must have
125
- permission to publish the fixed unscoped package. No OIDC/trusted-publisher setup
126
- or provenance flag is required by this workflow. Prereleases use `next`; stable
127
- versions use `latest`. These credentials do not bypass milestone acceptance.
128
- No token value is stored in source, documentation, or probe output. No publication
129
- is performed by this packaging task. See
130
- `tools/npm/publish-gate.ts` in the source distribution.
85
+ Pelican Engine's own code is MIT licensed. Dependency licenses and third-party notices are included in the package under `licenses/` and in the [repository notices](https://github.com/danchar12138/pelican-engine/blob/main/docs/THIRD-PARTY-NOTICES.md).
package/distribution.json CHANGED
@@ -1,23 +1,25 @@
1
1
  {
2
2
  "format": "pelican.npm-distribution",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
4
4
  "files": {
5
- "AGENTS.md": "af63b23d2afdef415c865685aea31dacd365edde17505bde823a757bd46caa5a",
5
+ "AGENTS.md": "ce7b26c4f857971fc030155fa494f544953b8c127838d1267321647f08e0cb86",
6
+ "CONTRIBUTING.md": "0ffad5d841d90f319fc50a75b81d3c0ad6dab8d5d9bec2846c65c7f8358d5a50",
6
7
  "docs/AI-WORKFLOW.md": "aa992686df93f791795f6f3fce01713d812eea6a1b9556f07411ac5847278efa",
7
- "docs/api/index.json": "fdb344c9956edf316548487ee0b183847e23cdecffe95eeda7f1f54c0c26b770",
8
- "docs/api/REFERENCE.md": "dff3868360926651e7986a25d2676283c1e1336d585e070e62313bf89fd2e1be",
8
+ "docs/api/index.json": "e33dc44ea0404e596392a2f252d1bb6510368816bdb5adaee5861335ec6fb2f2",
9
+ "docs/api/REFERENCE.md": "caf7a5d299fbfabc9f265b5ff64f6b2d2fdfdaceb9854788f8f1a4362399e272",
9
10
  "docs/ARCHITECTURE.md": "3184b73592d466390e7793b1cf39bbb80d6052b523fba7e7cb377b5207074627",
11
+ "docs/assets/pelican-mark.svg": "23d8f869fcf995d4d661b98b46e97f4cc17c3d8e5df38a3796a73b5ddcd8eb61",
10
12
  "docs/CAPABILITIES.md": "92950817497d8c63db07830db96dc93c877befa8d038320feed1ae1f1a053cb1",
11
- "docs/DECISIONS.md": "f7d287654c1ca4014474c54defbd1a9fb2a7e0d00794a3453f7518dae4490311",
12
- "docs/M3-USAGE.md": "39b2b4675840f3700da9ccf81c690cff4c69ee1ed5785a0b430c7c055935c31a",
13
- "docs/npm/DISTRIBUTION.md": "9312e4e7c4c0ac097793c7d5aeaa9146ec52e64d10caa7b804813ce61ceeaf87",
14
- "docs/npm/GAME-AUTHOR.md": "af63b23d2afdef415c865685aea31dacd365edde17505bde823a757bd46caa5a",
15
- "docs/PELICAN-MIGRATION.md": "633f4a4fe30bc899ebb01fb63ec9573a931e43f28c199224509db95890806e5f",
16
- "docs/RENDER-BACKENDS.md": "de104cca78d734f9a853a2757c6e3d7b832a31224da5df462851ef2cf9768ade",
13
+ "docs/DECISIONS.md": "47d3a1de8ecc8c5b06ddd867536831b9d3573fb0fefa9de6d4d9e87615daead8",
14
+ "docs/GETTING-STARTED.md": "5519ebe4e513e8ae4517c04948ee9dc70bcb1e3d04a65d468a6537c838502663",
15
+ "docs/npm/DISTRIBUTION.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
16
+ "docs/npm/GAME-AUTHOR.md": "ce7b26c4f857971fc030155fa494f544953b8c127838d1267321647f08e0cb86",
17
+ "docs/PELICAN-MIGRATION.md": "c5d6ab8e5186f4d36720a0a01d1a7e4157a5d386c5400e2db99571a7d10a1e49",
18
+ "docs/RENDER-BACKENDS.md": "d981ea94742a835d028db37d536fb7fba05102e37bc6274a37baf74f5034b954",
17
19
  "docs/ROADMAP.md": "29ac1c54f36064e23c17cfe7f549d6860889257a57d1227e322958aa9c281568",
18
- "docs/STATUS.md": "1e8b85ced94f7b4484773e73363e1cfbd488d8441e6c98e45358486402927c8d",
20
+ "docs/STATUS.md": "8cf14dbdcd97d659e155c0ac9035bd31ac38d1492cac138567a8d688ff5e2adc",
19
21
  "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
20
- "engine.manifest.json": "155537b36e7bb1f7a1550817571c08404739d4be3c0caa07a75b5089f8db1be1",
22
+ "engine.manifest.json": "449f96f7205a8ebd8700cf5cbffdb9e5305ff3219664ab0e7a78615ccc2bda5a",
21
23
  "lib/assets/audio.js": "6facdce4e053afd172af5b9407569b035169844ea17b49f93f8b67f72b78895f",
22
24
  "lib/assets/errors.js": "70572678655c6e53179d31920d71f29882d373a0e12d560220bb0fc2cd74f2cc",
23
25
  "lib/assets/glb.js": "b808479a36299c154db97f50c16863a3b5a2c61f725e66bf01d01a5f62a288a5",
@@ -119,8 +121,8 @@
119
121
  "lib/runtime/world.js": "c43621fbaca8bd2b0d6477a96e60e895312f0f7b1eb97614b6e4f9b716129ea1",
120
122
  "lib/schema/index.js": "594429eecb4494c4af2f3d04537be3211f2c9297a1fc555bbba5d028d8627965",
121
123
  "lib/sdk/graph-values.js": "a58c00f127cb82aba5fd2824981942844e06d9a59a88a05e35d1d3df2fc7ed2f",
122
- "lib/sdk/index.d.ts": "948449f30fe58d60c6dfd1cf8c9155b46df15f2b273ab830d55b751fd0cad041",
123
- "lib/sdk/index.js": "113dd48a7f1ebea382dcbe8a7f1e685c71fbfdeb105d00a4b6069ea59485a8f0",
124
+ "lib/sdk/index.d.ts": "7c6f8e175ef45fd0d888bf35428b578bce822d1ef39da02bce33e3a4f4b95895",
125
+ "lib/sdk/index.js": "fecaeed2934e54247e2654a48516d1556676c448f99169b71b8fae4f5bc8cba7",
124
126
  "lib/tools/api-index.js": "6aedc153a0ce8eaf18239b0368a76a8ae8e4397bd8e6cdf571889bc39265be5d",
125
127
  "lib/tools/browser-session.js": "1fa7f78d4752d8a59a55dc2283b4d42cd1df230f0d5a5dc80c6d78ade45b4cdb",
126
128
  "lib/tools/cli.js": "ad5e915f046cc2e6bf612edd1a88cc33758b1d2b0ce2f057be50e0a2c4770062",
@@ -191,8 +193,8 @@
191
193
  "licenses/undici-types/LICENSE": "a6db8096b2707bc0102d256917d4d33f298ba36d8c3f25de067a2b5bb379db27",
192
194
  "licenses/uniq/LICENSE": "e67aed7df22dc8031e4fcf5338fe91cb33e3817e5c58a99a2a2802eea9069791",
193
195
  "licenses/vite/LICENSE.md": "a22152baa1aef74402443008e767e7c689a524c0909d19b0431d97f5ab066a13",
194
- "package.json": "68d95a497d2ccb17c1cb47be1414f4a26e093cb2262ae34449d3c411bedd7c77",
195
- "README.md": "9312e4e7c4c0ac097793c7d5aeaa9146ec52e64d10caa7b804813ce61ceeaf87",
196
+ "package.json": "235fb53c5e790fe0b020e7775d92155387b55cdade53f1283e5728f142a22248",
197
+ "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
196
198
  "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
197
199
  }
198
200
  }
package/docs/DECISIONS.md CHANGED
@@ -69,6 +69,7 @@
69
69
  | D53 | 用户要求每次推送主线自动以无预发布后缀的正式版本发布到 npm `latest`，使用 OIDC，不再人工审批 | 覆盖 D48、D52 的 token/staged/next 方案。GitHub Actions 使用 npm 可信发布，不传长期发布令牌；每次运行生成唯一正式版本，更新 `latest`。发布失败、队列延迟和不可覆盖版本须如实记录。正式版本命名不表示行为、硬件或完整里程碑已验证，D50 仍有效。 |
70
70
  | D54 | 用户要求推送主线即尝试发布 npm，GitHub Release 仅标记里程碑；仓库和 npm 使用相同的简洁版本，移除 `next` | 覆盖 D53 的运行 ID 自动版本方案。版本由仓库显式维护，CI 不自动改号；每次推送使用该版本以 OIDC 发布到 `latest`，版本重复则失败并等待后续版本，不覆盖既有包。移除 `next` 别名但保留历史版本；已有长版本不可重用或抹除。D50 仍有效。 |
71
71
  | D55 | 用户要求单线开发时不再堆积变更，提交和推送不等待里程碑 | 工作区只保留下一功能或版本的改动；每次提交围绕一个可说明的功能、修复或版本，完成后及时提交推送。推送前按 D54 明确递增版本，npm 发布失败如实记录。保留历史证据和未确认成果，不将无关内容混入提交；D50 和 D51 继续有效。 |
72
+ | D56 | 用户要求仓库首页、npm 与源码使用指南按常见开源引擎结构组织，美观且实用，命令不绑定特定 shell | 提供清晰的功能概览、状态、快速入门、文档导航与源码贡献入口；仓库和 npm 指引保持一致。通用命令写法不改变 D15 的 Windows 开发支持范围，也不暗示其他系统已受支持或验证；D50 的验证禁令继续有效。 |
72
73
 
73
74
  ## 本次变更实施顺序
74
75
 
package/docs/GETTING-STARTED.md ADDED
@@ -0,0 +1,80 @@
1
+ # 快速入门
2
+
3
+ 本指南介绍两种使用方式：**用 npm 制作游戏**，或**从源码仓库运行引擎和游戏**。两者使用同一个 `pelican-engine` 公开 SDK；一般游戏项目不需要引擎源码。已有功能及未完成项请先阅读 [当前研发状态](STATUS.md)。
4
+
5
+ ## 环境
6
+
7
+ - Node.js 24.x 和 npm；仓库及 npm 包当前声明的 Node 版本范围为 `>=24 <25`。
8
+ - 当前支持的引擎与游戏开发环境为 Windows。本指南中的命令使用通用 Node/npm 形式，不要求特定 shell；**不代表 Linux 或 macOS 开发流程已经受支持或完成验证**。
9
+ - 玩家端无操作系统或浏览器品牌白名单，实际可用的 WebGPU、WebGL2 和图形能力取决于设备、浏览器和运行环境。
10
+ - 首次安装依赖需要网络。浏览器截图等自动化功能还需要按需安装 Playwright Chromium；普通启动与构建不要求先安装它。
11
+
12
+ ## 方式一：使用 npm 开始游戏
13
+
14
+ 在空目录中安装引擎并启动开发服务：
15
+
16
+ ```sh
17
+ mkdir my-pelican-game
18
+ cd my-pelican-game
19
+ npm --prefix . install --save-dev --save-exact pelican-engine
20
+ npx pelican dev
21
+ ```
22
+
23
+ `--prefix .` 将安装目标明确指定为当前目录，避免 npm 选中父级项目；`--save-exact` 将安装版本锁定在游戏项目中。首次 `dev` 在允许的空目录里生成：
24
+
25
+ ```text
26
+ my-pelican-game/
27
+ ├── game.ts # 游戏入口
28
+ ├── pelican.project.json # 入口及引擎版本锁
29
+ ├── AGENTS.md # 外部 AI 的游戏开发入口
30
+ ├── package.json
31
+ └── package-lock.json
32
+ ```
33
+
34
+ 默认示例创建一个方块、相机、灯光和旋转系统。编辑 `game.ts` 以修改它；游戏侧从 `pelican-engine` 导入公开接口。CLI 不覆盖已有项目：如果目录已有其他文件而无法自动生成，请使用空目录，或显式创建项目。
35
+
36
+ 停止开发服务后构建：
37
+
38
+ ```sh
39
+ npx --no-install pelican build
40
+ ```
41
+
42
+ 产物位于游戏目录的 `dist/`。将整个目录部署到支持静态文件的 HTTP(S) 服务器，并保留其中的资源和许可文件。部署到子路径时，可使用 `npx --no-install pelican build --base /game/`。
43
+
44
+ 查看命令与 API：
45
+
46
+ ```sh
47
+ npx --no-install pelican help
48
+ npx --no-install pelican api
49
+ npx --no-install pelican api --symbol defineGame
50
+ ```
51
+
52
+ 项目锁与安装版本不一致时，应先迁移项目，再明确更新 `pelican.project.json` 中的版本；不要通过修改 `node_modules` 绕过诊断。更多使用细节见 [npm 分发指南](npm/DISTRIBUTION.md) 和 [Game Author 指南](npm/GAME-AUTHOR.md)。
53
+
54
+ ## 方式二：从仓库使用引擎
55
+
56
+ 需要研究引擎源码、尝试仓库示例或参与维护时，可以检出仓库：
57
+
58
+ ```sh
59
+ git clone https://github.com/danchar12138/pelican-engine.git
60
+ cd pelican-engine
61
+ npm ci
62
+ npm run dev
63
+ ```
64
+
65
+ 这会启动当前仓库配置的示例。源码 ZIP 或已有目录也可以使用，不要求 `.git` 存在。使用源码为另一个目录创建最小游戏：
66
+
67
+ ```sh
68
+ node --import tsx tools/cli.ts create --project ../my-source-game --template minimal
69
+ node --import tsx tools/cli.ts dev --project ../my-source-game
70
+ ```
71
+
72
+ 这些命令从**引擎目录**执行；新游戏在相邻的 `my-source-game` 目录中。CLI 会写入相对引擎路径和版本锁，游戏仍使用公开的 `pelican-engine` API。已有目标文件不会被覆盖。更多引擎开发说明见 [参与开发](../CONTRIBUTING.md)。
73
+
74
+ ## 选择渲染模式
75
+
76
+ 引擎优先尝试 WebGPU，必要时通过 Three.js 内置回退尝试 WebGL2 光栅。WebGL2 不提供依赖 compute 的混合光追、路径追踪或受控计算；能力不足时应读取诊断，不应把光栅结果当成光追。能力查询和错误码见 [渲染后端](RENDER-BACKENDS.md)。
77
+
78
+ ## 已知边界
79
+
80
+ 当前版本仍在研发；构建成功不证明画质、性能、硬件兼容或所有功能已经验收。当前用户约束禁止项目验证活动，因此仓库中的历史测试命令不是本次执行或通过的声明。实际局限、已知物理缺陷和历史证据入口见 [当前研发状态](STATUS.md)。
package/docs/PELICAN-MIGRATION.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Pelican Engine 命名与迁移
2
2
 
3
- 本次名称由用户确定：**Pelican Engine（鹈鹕游戏引擎）**。引擎仍处于 M3 开发，不因更名重启里程碑，也不把已有开发探针提升为正式验收。
3
+ 产品名称为 **Pelican Engine（鹈鹕游戏引擎）**。本文件保留更名与迁移背景；当前版本、能力缺口及发布状态见 [研发状态](STATUS.md)，历史开发探针不是当前源码的正式验收。
4
4
 
5
5
  | 对象 | 唯一正式名称 |
6
6
  | --- | --- |
@@ -9,7 +9,7 @@
9
9
  | npm 单包 | `pelican-engine` |
10
10
  | 命令 / bin | `pelican` |
11
11
  | 游戏侧公开导入 | `pelican-engine` |
12
- | 源码目录启动脚本 | `pelican.ps1` |
12
+ | 源码命令入口 | `npm run dev` 或 `node --import tsx tools/cli.ts` |
13
13
  | 项目清单 | `pelican.project.json` |
14
14
  | 本地缓存 / 开发控制路由 | `.pelican/` / `/__pelican/` |
15
15
  | 部署版本清单 | `pelican-build.json` |
@@ -18,8 +18,8 @@ SDK、runtime、renderer、编译器和 CLI 位于同一个 npm 包中。内部
18
18
 
19
19
  目标最短使用流程为：
20
20
 
21
- ```powershell
22
- npm i -D pelican-engine
21
+ ```sh
22
+ npm --prefix . install --save-dev --save-exact pelican-engine
23
23
  npx pelican dev
24
24
  ```
25
25
 
@@ -35,4 +35,4 @@ M0–M2 的原名称、标签、提交、Release 附件与 `evidence/` 是历史
35
35
 
36
36
  ## 远端实际状态
37
37
 
38
- 用户后续明确 GitHub 只改仓库名，不改组织。远端现已改名为 `danchar12138/pelican-engine`，本地 origin 同步更新，公开仓库、历史标签与 Release 保留。npm 身份已通过授权 Automation Token 验证，令牌仅配置为该仓库 Actions 的 `NPM_TOKEN` secret，未写源码或证据。npm `pelican-engine` 查询仍返回 404；本轮只完成更名和开发分发验证，不在里程碑验收前提前推送、创建标签或发布包。
38
+ GitHub 仓库为 `danchar12138/pelican-engine`，所有者保持不变。npm 使用 Trusted Publisher OIDC；当前稳定版本见 `package.json` 与 [npm package](https://www.npmjs.com/package/pelican-engine)。历史标签和历史发布记录保留原样，不更名、不重写。
package/docs/RENDER-BACKENDS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # 渲染后端与能力诊断
2
2
 
3
- 适用：M3 开发工作树及由同一版本生成的 npm 包。历史 M0–M2 标签保留当时 WebGPU-only 行为；本文件不改写旧验收。
3
+ 适用：当前源码及由相同版本生成的 npm 包。历史标签保留当时的行为与证据；本文件不改写旧验收。当前源码的后端兼容性尚未完成完整验收。
4
4
 
5
5
  ## 同一公开接口
6
6
 
@@ -35,11 +35,13 @@ const capabilities = ctx.render.capabilities();
35
35
 
36
36
  配置和检查点恢复先校验能力再提交；被拒绝的配置不改变当前模式或设置。运行态开发控制命令返回结构化 `failed` 与稳定错误码，不因正常的不支持请求把游戏置为崩溃状态。
37
37
 
38
- ## 实测入口
38
+ ## 历史实测入口
39
+
40
+ 以下是历史开发命令；当前 D50 禁止测试、浏览器、GPU 和其他验证，恢复授权前不要运行。
39
41
 
40
42
  在 Windows、已安装依赖与 Playwright Chromium、真实硬件加速环境中：
41
43
 
42
- ```powershell
44
+ ```sh
43
45
  npm run probe:backends
44
46
  # 仅运行独立 WebGL2 回退矩阵：
45
47
  npm run probe:backends -- --webgl-only
@@ -47,4 +49,4 @@ npm run probe:backends -- --webgl-only
47
49
 
48
50
  输出 `.pelican/backend-probes/<run>/report.json` 与截图，包括源码指纹、实际 ANGLE/GPU 身份、画面像素检查、三类初始化失败、不可用模式/降噪/计算错误码、两次上下文恢复、重复内容重载，以及两后端都不可用的诊断。默认还复测真实 WebGPU 三模式设备重建。
49
51
 
50
- 这是开发专项，不是完整 M3 acceptance。主里程碑只接受真实 WebGPU 硬件证据；WebGL2 单列记录，不用它或软件渲染器代替主门禁。性能保留诚实观测，不以固定帧率阈值阻断 1.0，也不放松功能正确性和资源生命周期验证。
52
+ 这些是历史开发专项记录，不构成当前版本的完整图形或硬件验收。WebGPU 与 WebGL2 应分别记录，不用一种后端或软件渲染器代替另一种后端的证据。当前授权只允许编译和构建，历史测量不自动适用于当前源码。
package/docs/STATUS.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## 版本与发布
4
4
 
5
- - 当前版本以 `package.json`、`engine.manifest.json` 和 SDK 中的相同标准版本号为准。每次需要发布时，在主线显式更新版本；相同版本不能重复发布。
5
+ - 当前版本为 `0.3.5`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
6
6
  - 推送主线会通过 GitHub Actions 和 npm 可信发布更新 `latest`；GitHub Release 用于记录里程碑。历史版本和旧标签保持原样，不代表当前源码通过。
7
7
  - 当前按用户要求仅允许编译和构建，不运行测试、浏览器、GPU、性能或其他验证。普通版本号不意味着运行行为、硬件或完整引擎已验收。
8
8
 
package/docs/api/REFERENCE.md CHANGED
@@ -1,4 +1,4 @@
1
- # pelican 0.3.3 API 索引
1
+ # pelican 0.3.5 API 索引
2
2
 
3
3
  Installed declarations: `lib/sdk/index.d.ts` (relative to the package root).
4
4
  The signatures below come from the same public SDK source as repository games.
@@ -11,7 +11,7 @@ Source-file paths and line numbers are build-time provenance only; TypeScript so
11
11
  来源：`packages/sdk/src/index.ts:2`
12
12
 
13
13
  ```ts
14
- SDK_VERSION = "0.3.3"
14
+ SDK_VERSION = "0.3.5"
15
15
  ```
16
16
 
17
17
  ## Vec2
package/docs/api/index.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "format": "pelican.api-index",
3
3
  "version": 1,
4
- "engineVersion": "0.3.3",
4
+ "engineVersion": "0.3.5",
5
5
  "entry": "pelican-engine",
6
6
  "source": "packages/sdk/src/index.ts",
7
7
  "symbols": [
8
8
  {
9
9
  "name": "SDK_VERSION",
10
10
  "kind": "constant",
11
- "signature": "SDK_VERSION = \"0.3.3\"",
11
+ "signature": "SDK_VERSION = \"0.3.5\"",
12
12
  "line": 2
13
13
  },
14
14
  {
package/docs/assets/pelican-mark.svg ADDED
@@ -0,0 +1,9 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="160" height="160" viewBox="0 0 160 160" role="img" aria-labelledby="title">
2
+ <title id="title">Pelican Engine mark</title>
3
+ <rect x="4" y="4" width="152" height="152" rx="40" fill="#12334a"/>
4
+ <path d="M32 104c13 21 51 30 76 10 9-7 15-18 17-31-12 11-27 13-42 9-19-4-32-19-38-33-12 13-17 29-13 45z" fill="#edf8f6"/>
5
+ <path d="M45 59c7-21 24-33 44-30 15 2 24 12 28 25-9 1-18 4-26 11-12 10-19 21-20 31C57 88 48 75 45 59z" fill="#58cfb8"/>
6
+ <path d="M98 60c11-8 27-11 43-6l-30 17-26 13c1-9 5-18 13-24z" fill="#ffbd69"/>
7
+ <circle cx="94" cy="48" r="3.5" fill="#12334a"/>
8
+ <path d="M31 119c21 11 47 15 74 5" fill="none" stroke="#58cfb8" stroke-width="4" stroke-linecap="round"/>
9
+ </svg>
package/docs/npm/DISTRIBUTION.md CHANGED
@@ -1,130 +1,85 @@
1
- # Pelican Engine npm development distribution
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/danchar12138/pelican-engine/main/docs/assets/pelican-mark.svg" alt="Pelican Engine" width="110" height="110">
3
+ <h1>Pelican Engine</h1>
4
+ <p><strong>Build games for the web with TypeScript.</strong></p>
5
+ <p>Code-first · WebGPU-first · Designed for human and external AI workflows</p>
6
+ <p>
7
+ <a href="https://www.npmjs.com/package/pelican-engine"><img src="https://img.shields.io/npm/v/pelican-engine?label=npm&amp;color=168b80" alt="npm version"></a>
8
+ <img src="https://img.shields.io/badge/license-MIT-24536b" alt="MIT license">
9
+ <img src="https://img.shields.io/badge/TypeScript-SDK-3178c6" alt="TypeScript SDK">
10
+ </p>
11
+ </div>
12
+
13
+ Pelican Engine provides a TypeScript SDK, compiler, runtime, renderer and CLI in one package. Define game content and behavior in code, run a local development server and build a static web distribution. AI tools may assist development, but the game runtime does not include an LLM or AI agent.
14
+
15
+ > **Development status:** this is an evolving engine, not a complete first release. Current source behavior, hardware compatibility, performance and the full feature set have not been fully validated. A normal version number is not an acceptance claim. See the [development status](https://github.com/danchar12138/pelican-engine/blob/main/docs/STATUS.md) for known gaps.
16
+
17
+ ## Quick start
18
+
19
+ Install Node.js **24.x** and npm, then create a new empty game directory:
20
+
21
+ ```sh
22
+ mkdir my-pelican-game
23
+ cd my-pelican-game
24
+ npm --prefix . install --save-dev --save-exact pelican-engine
25
+ npx pelican dev
26
+ ```
27
+
28
+ The first `dev` creates `game.ts`, `pelican.project.json` and `AGENTS.md` in an eligible empty project. Existing game files and author instructions are not overwritten. The explicit `--prefix .` prevents npm from choosing a parent project; `--save-exact` pins the installed version. Stop the development server before building:
29
+
30
+ ```sh
31
+ npx --no-install pelican build
32
+ ```
2
33
 
3
- The installed package is `pelican-engine`. Its root export is the same compiled
4
- public SDK used by repository games, not a wrapper or a separate SDK. The package
5
- also provides the `pelican` executable. This is an M3 development distribution,
6
- not accepted M3 hardware evidence or a complete engine release.
34
+ Deploy the resulting `dist/` directory, including its generated assets and notices, to an HTTP(S) static host. For a nested deployment, use `npx --no-install pelican build --base /game/`.
7
35
 
8
- ## Windows project workflow
36
+ Commands use common Node/npm syntax rather than a particular shell. **Engine and game development currently support Windows only**; Linux and macOS development workflows have not been promised or validated. Player platforms are not restricted by brand or OS: actual rendering availability depends on browser and graphics capabilities.
9
37
 
10
- Use Node 24 and npm in an empty project directory. The explicit prefix keeps npm
11
- in this directory even when a parent directory is also an npm project:
38
+ ## Your game
12
39
 
13
- ```powershell
14
- npm --prefix . i -D pelican-engine
15
- npx pelican dev
40
+ The generated starter defines a scene and a rotating box. Game code imports only the public package, for example:
41
+
42
+ ```ts
43
+ import { defineGame, defineMaterial, defineScene } from "pelican-engine";
44
+
45
+ const material = defineMaterial({ id: "paint", color: "#38b8a4", roughness: 0.45 });
46
+ const scene = defineScene({
47
+ id: "main",
48
+ camera: { position: [4, 3, 6], target: [0, 0, 0], fov: 50 },
49
+ entities: [
50
+ { id: "box", mesh: { geometry: { kind: "box" }, material } },
51
+ { id: "light", light: { kind: "directional", intensity: 4 },
52
+ transform: { position: [3, 6, 4] } },
53
+ ],
54
+ });
55
+ export default defineGame({ id: "my-game", scene });
16
56
  ```
17
57
 
18
- The first installed `dev` creates the minimal `game.ts`, `pelican.project.json`
19
- version lock, and game-author `AGENTS.md` when the directory contains only npm
20
- installation metadata. An existing game or manifest is used as supplied; other
21
- project files or author instructions prevent automatic scaffolding. Files are
22
- never overwritten. Stop dev with Ctrl+C, then use the same local CLI:
58
+ Save it as `game.ts` in a project created by the CLI. The exact engine version is recorded in `pelican.project.json`: migrate the game and update its lock explicitly when changing engine versions. Do not edit `node_modules` or import engine internals.
59
+
60
+ Useful commands:
23
61
 
24
- ```powershell
62
+ ```sh
63
+ npx --no-install pelican help
25
64
  npx --no-install pelican api
26
- npx --no-install pelican setup --install-browser
27
- npx --no-install pelican check
65
+ npx --no-install pelican api --symbol defineGame
28
66
  npx --no-install pelican dev --port 4173
29
- npx --no-install pelican capture --port 4174 --output capture.png
30
67
  npx --no-install pelican build
31
68
  ```
32
69
 
33
- For an exact-version install use `npm --prefix . i -D --save-exact pelican-engine@0.3.3`,
34
- or substitute the local `pelican-engine-0.3.3.tgz` tarball before registry
35
- publication. `pelican create --template minimal` remains available explicitly.
36
-
37
- Without `--prefix .`, npm may select an ancestor `package.json` or `node_modules`
38
- as the install root and modify that parent. The shorter `npm i -D pelican-engine`
39
- works when npm selects the intended directory; verify `npm prefix` before using
40
- it. The smoke harness uses an explicit prefix and does not require `npm init`.
41
-
42
- `create --template minimal` uses the same primitive starter in npm and repository
43
- workflows. npm defaults to `minimal` and reports the selected template; repository
44
- default `m2` is preserved with its historical sample assets. Samples are not engine
45
- capabilities. Identical authored game/asset inputs use the same API/compiler/runtime
46
- in either channel. npm does not bundle the `m2` sample or any sample/game assets.
47
-
48
- `create` writes `game.ts`, `AGENTS.md` and an exact `pelican.project.json` lock in the current
49
- directory. Existing project files are never overwritten. Author TypeScript with
50
- named imports from `pelican-engine` and project-local imports only. The compiler
51
- reports `TC_PUBLIC_API` for renderer, Three.js, TSL, physics, Node and internal
52
- package imports, including type-only and unused imports. Package subpaths are not
53
- public exports. Project lock mismatches report `TC_ENGINE_VERSION_MISMATCH`;
54
- mixed package/API versions report `TC_ENGINE_SDK_VERSION`. Reinstall a matching
55
- exact version, or migrate through the public API before explicitly changing a lock.
56
-
57
- After npm dependencies and Playwright Chromium have been installed, authoring,
58
- API inspection, checks, builds, dev/control commands and capture need no network
59
- service. `setup --offline` never installs dependencies or downloads a browser in
60
- an installed package. Keep the game package-lock for repeatable future installs;
61
- an offline _reinstall_ additionally requires the npm cache or a dependency mirror.
62
- `TC_DISTRIBUTION_DEPENDENCY_MISSING` and
63
- `TC_DISTRIBUTION_DEPENDENCY_VERSION` identify broken tool dependencies.
64
-
65
- Serve the generated `dist/` directory over HTTP(S), including its `generated/`
66
- files, license files, notices and compression manifests. No Node process, engine
67
- repository, SDK installation, external AI service or development control server
68
- is needed by players. Use `build --base /game/` for a nested deployment URL.
69
- Capture requires installed Chromium and actual supported graphics capability.
70
- No software renderer result establishes hardware acceptance.
71
-
72
- ## AI entry points
73
-
74
- Read the game-author `AGENTS.md`, `docs/npm/GAME-AUTHOR.md`, `docs/CAPABILITIES.md` and
75
- `docs/api/REFERENCE.md` inside `node_modules/pelican-engine`. The machine-readable
76
- API is `docs/api/index.json`, also discoverable through `pelican api`.
77
- `lib/sdk/index.d.ts` is the authoritative installed declaration surface.
78
- `docs/PELICAN-MIGRATION.md` explains current names and historical provenance.
79
- Repository paths and release instructions in copied documents are historical
80
- context; the installed workflow above replaces source-checkout commands.
81
- The JSON CLI protocol and dev control operations are shared with the repository.
82
-
83
- ## Maintainer validation and publishing
84
-
85
- ```powershell
86
- npm run distribution:test
87
- npm run distribution:pack
88
- npm run distribution:smoke
89
- npm run distribution:smoke -- --gpu
90
- ```
70
+ The renderer prioritizes WebGPU and can use Three.js's built-in WebGL2 raster fallback. Compute-dependent hybrid/path tracing and compute features are not available on WebGL2; unsupported requests return diagnostics rather than silently claiming equivalent rendering. See the [backend guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/RENDER-BACKENDS.md).
71
+
72
+ ## Documentation
73
+
74
+ - [Getting started: npm and source checkout](https://github.com/danchar12138/pelican-engine/blob/main/docs/GETTING-STARTED.md)
75
+ - [Game author guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/npm/GAME-AUTHOR.md)
76
+ - [API reference](https://github.com/danchar12138/pelican-engine/blob/main/docs/api/REFERENCE.md) and [capabilities](https://github.com/danchar12138/pelican-engine/blob/main/docs/CAPABILITIES.md)
77
+ - [Source repository and contribution guide](https://github.com/danchar12138/pelican-engine)
78
+
79
+ The installed package also includes `docs/npm/GAME-AUTHOR.md`, `docs/api/REFERENCE.md`, `docs/api/index.json` and `lib/sdk/index.d.ts`. The installed declarations and `pelican api` describe the API of the actual installed version. Repository examples and assets are not shipped in the npm package.
80
+
81
+ Playwright Chromium is optional for capture and browser automation. If needed, prepare it while online with `npx --no-install pelican setup --install-browser`. With required dependencies and assets already available, everyday operations need no engine account or hosted development service. An offline reinstall additionally requires cached packages.
82
+
83
+ ## License
91
84
 
92
- Build output is regenerated from current sources into ignored
93
- `.pelican/npm/package/`; tarballs and smoke reports go in `.pelican/npm/artifacts/`.
94
- Neither staging nor tarballs are inside the deployable game `dist/`.
95
- Pack that staging directory, not the private repository root. Compiled relative
96
- imports use `lib/` modules and `.js`, never the TypeScript source layout. The
97
- tarball allowlist excludes source maps, evidence, examples and game assets;
98
- SDK declarations, engine runtime code, MIT, copied AI docs, and dependency
99
- license texts are included. `distribution.json` records version and file hashes.
100
- Dependencies are normal pinned npm dependencies, not vendored engine sources.
101
-
102
- The npm workflow runs only for a published GitHub milestone release. Its gate
103
- requires tag/version/SDK/manifest identity and the existing milestone acceptance
104
- and source-fingerprint checks. An ordinary push or CPU-green build cannot publish.
105
- M3 is deliberately blocked until its release profile and real acceptance exist.
106
- The default smoke install uses npm cache only; `--online-install` allows network
107
- for initial dependency installation, then runs every operation offline with a
108
- disabled registry. CI uses this flag because `npm ci` alone need not populate
109
- registry metadata for a fresh external install. `--gpu` additionally measures
110
- the installed WebGPU backend, renders path/hybrid/raster, checks a nonblank canvas,
111
- captures through both CLI routes, verifies WebGL2 fallback rejection, and loads
112
- the nested-base static build without a development hook. It is not M3 acceptance.
113
-
114
- The single unscoped package is `pelican-engine`, its only public import is
115
- `pelican-engine`, and its executable is `pelican`. The GitHub target is
116
- `danchar12138/pelican-engine`; main completed the public repository rename and
117
- verified the updated origin. No new organization is required. The authorized
118
- npm Automation Token was authenticated as `danchar12138`, and main confirmed
119
- the repository Actions secret `NPM_TOKEN` is configured. `npm view pelican-engine`
120
- returned `E404` before publication. The package remains unpublished pending
121
- genuine M3 acceptance; this is not an authentication or organization blocker.
122
- `setup-node` configures the registry;
123
- only the final publication step receives `NODE_AUTH_TOKEN`. A missing secret
124
- fails with `TC_NPM_AUTH_MISSING`, without printing the value. The token must have
125
- permission to publish the fixed unscoped package. No OIDC/trusted-publisher setup
126
- or provenance flag is required by this workflow. Prereleases use `next`; stable
127
- versions use `latest`. These credentials do not bypass milestone acceptance.
128
- No token value is stored in source, documentation, or probe output. No publication
129
- is performed by this packaging task. See
130
- `tools/npm/publish-gate.ts` in the source distribution.
85
+ Pelican Engine's own code is MIT licensed. Dependency licenses and third-party notices are included in the package under `licenses/` and in the [repository notices](https://github.com/danchar12138/pelican-engine/blob/main/docs/THIRD-PARTY-NOTICES.md).
package/docs/npm/GAME-AUTHOR.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Pelican Engine Game Author
2
2
 
3
+ For an installed game, start in an empty directory with `npm --prefix . install
4
+ --save-dev --save-exact pelican-engine`, then run `npx pelican dev`. The CLI
5
+ generates the minimal starter when the directory is eligible and preserves existing
6
+ game files. See `docs/GETTING-STARTED.md` in the package for npm and source
7
+ workflows. Commands use common Node/npm syntax; the currently supported development
8
+ environment is Windows, while player support depends on actual browser capabilities.
9
+
3
10
  Your workspace is the game project. Use the public `pelican-engine` API and local
4
11
  game modules. Do not modify engine internals or `node_modules`, import Three.js,
5
12
  TSL, GPU devices, physics-library objects, compiler internals or Node APIs into
@@ -15,8 +22,8 @@ lists the JSON CLI protocol. `docs/CAPABILITIES.md` records implemented scope an
15
22
  limitations. The longer `docs/AI-WORKFLOW.md` is shared design context, not an
16
23
  instruction to run source-only engine acceptance tasks.
17
24
 
18
- The shared `docs/M3-USAGE.md` describes the current rendering and compute
19
- contracts. Its `examples/`, engine `packages/`, and `npm run probe:*` references
25
+ The source checkout's `docs/STATUS.md` summarizes current engine capabilities
26
+ and gaps. Its `examples/`, engine `packages/`, and `npm run probe:*` references
20
27
  are maintainer references available only in a source checkout; the npm package
21
28
  intentionally contains no example projects, game assets, or engine source. Use
22
29
  the same public declarations in your own game project and validate them with the
@@ -107,20 +114,26 @@ Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
107
114
  `KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],
108
115
  restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the
109
116
  actual keyboard event; Space is `" "`. Actions are read inside systems through
110
- `ctx.input.held`, `pressed`, `released`, or `axis`. Always exercise real keyboard
111
- input in the browser; a mocked system test does not establish browser bindings.
117
+ `ctx.input.held`, `pressed`, `released`, or `axis`. A mocked system test does not
118
+ establish browser bindings; real input requires separate verification when permitted.
112
119
 
113
120
  ## Work Loop
114
121
 
115
122
  1. Inspect `pelican.project.json`, `game.ts`, asset declarations and the public API.
116
123
  2. Make small game-only edits. Keep the exact engine version lock.
117
- 3. Run `pelican check`, then `pelican dev` and exercise actual gameplay.
124
+ 3. Follow the active project policy for running the game or checking gameplay.
118
125
  4. Use `inspect`, `input`, `step`, `pause`, `resume`, `snapshot`, `restore`,
119
- `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port.
120
- 5. Run `capture --live` against the dev port or a standalone `capture`, inspect
121
- the actual screenshot, and preserve explicit failures rather than claiming success.
126
+ `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port
127
+ when verification is permitted.
128
+ 5. When verification is permitted, use capture and inspect results; preserve
129
+ explicit failures rather than claiming success.
122
130
  6. Run `build` and serve `dist/` over HTTP(S). Keep notices and license files.
123
131
 
132
+ The current engine project decision permits compilation and builds only, not
133
+ tests, browser/GPU runs, smoke or other validation. Historical instructions and
134
+ reports do not authorize those activities or establish that they passed for the
135
+ current source.
136
+
124
137
  Installed package commands use `npx --no-install pelican <command>` from the game
125
138
  directory. Repository commands use `node --import tsx <engine>/tools/cli.ts
126
139
  <command> --project <game-directory>` with the same operations and protocol.
package/engine.manifest.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pelican-engine",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
4
4
  "milestone": "M3",
5
5
  "stage": "advanced-rendering-development",
6
6
  "license": "MIT",
package/lib/sdk/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
2
- export declare const SDK_VERSION = "0.3.3";
2
+ export declare const SDK_VERSION = "0.3.5";
3
3
  export type Vec2 = readonly [number, number];
4
4
  export type Vec3 = readonly [number, number, number];
5
5
  export type Vec4 = readonly [number, number, number, number];
package/lib/sdk/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
2
- export const SDK_VERSION = "0.3.3";
2
+ export const SDK_VERSION = "0.3.5";
3
3
  export const SYSTEM_PHASES = [
4
4
  "input",
5
5
  "prePhysics",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pelican-engine",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
4
4
  "description": "Pelican Engine public SDK and offline development CLI",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -27,6 +27,7 @@
27
27
  "docs",
28
28
  "licenses",
29
29
  "AGENTS.md",
30
+ "CONTRIBUTING.md",
30
31
  "README.md",
31
32
  "LICENSE",
32
33
  "engine.manifest.json",
package/docs/M3-USAGE.md DELETED
@@ -1,192 +0,0 @@
1
- # M3 开发候选使用指引
2
-
3
- 当前 `0.3.0-m3.0` **尚未正式验收或发布**。稳定 M2 为 `v0.2.0-m2.0`，不能用当前源码更新历史 M2 验收指纹。本文说明已有开发候选的实际操作，不宣称完整高级渲染完成。
4
-
5
- ## 模型材质槽
6
-
7
- 模型可用 `materialSlots: { Paint: replacement }` 按加载后的材质名称精确替换该名称的全部材质槽，其余槽保留原材质；与整体 `material` 覆盖互斥。同名槽会一起替换，不能区分同名或无名槽。未知名称返回 `TC_MODEL_MATERIAL_SLOT_MISSING`，诊断包含部分可用的已加载材质名；名称或数量过多时会截断。未知目标材质也会明确报错，替换材质的生命周期仍由引擎管理。仓库示例 `examples/material-slots` 展示此接口；它不代表所有 glTF 扩展均受支持。
8
-
9
- 模型实际包含 `KHR_animation_pointer` 动画通道时当前明确拒绝并报告 `TC_MODEL_EXTENSION_UNSUPPORTED`；不要将其材质动画当作已经播放。只声明可选扩展而没有使用该通道的模型不因此被拒绝。普通 glTF 平移、旋转、缩放与 morph 动画仍按现有接口使用。
10
-
11
- ## 不透射介质折射率
12
-
13
- `defineMaterial({ id, ior, transmission: 0, ... })` 可为不透射的物理材质指定有限正数折射率，默认值为 1.5。介质法线入射反射率由 `((ior - 1) / (ior + 1))²` 决定；光栅、hybrid 和 path 共享该输入，路径采样与 PDF 也使用对应反射率。金属部分仍使用 baseColor 的 F0。`attenuationColor` 和 `attenuationDistance` 仍要求正的 transmission，不能用不透射 IOR 伪装体积吸收。
14
-
15
- 仓库中的 `examples/opaque-ior` 以三个黑色平面展示差异；`npm run probe:opaque-ior` 是需要独占 GPU 的小型三模式开发验证。该例不代表完整物理材质扩展或正式 M3 验收；npm 渠道使用同一公开接口，当前源码增量的新包安装验收仍待稳定候选。
16
-
17
- 不透射物理材质还可设置 `specularIntensity`（0 到 1，默认 1）和 `specularColor`（sRGB `#rgb`、`#rrggbb` 或颜色名称，默认白色）。这两个因子参与介质高光、掠射和 path/hybrid 采样；金属部分仍由 baseColor 决定。非默认高光与正 `transmission` 的组合目前返回 `TC_MATERIAL_SPECULAR_TRANSMISSION`，不会悄悄使用默认值。
18
-
19
- 自包含 GLB 可使用 `KHR_materials_specular`／`KHR_materials_ior` 的常数材质因子；不透射材质还支持 specular 强度纹理 alpha 与 sRGB 颜色纹理 RGB，资产仅接受 TEXCOORD_0，`optimize` 保留并复核因子、图像和采样配置。高光颜色 PNG 支持 1/2/4-bit 灰度和调色板 Adam7、无色彩元数据的 16-bit，以及 gAMA 45455/100000、标准 sRGB cHRM、sRGB intent 0、cICP [1,13,0,1]；其他 16-bit 色彩块值和 ICC 仍明确拒绝。正透射结合高光纹理及其他未实现扩展仍不支持。示例 `examples/specular-material`、`examples/specular-textures` 和 `examples/specular-textures-16` 对照导入材质；探针需串行独占 GPU。完整 M3 和全新系统或公开注册表验收尚未完成。
20
-
21
- ## 计算到渲染的缓冲绑定
22
-
23
- `defineGame({ computeBuffers: [...] })` 可在首帧前建立受管理缓冲。材质以 `buffers: [{ name, type, buffer?, count? }]` 声明槽，顶点图和片元 `graph`/`graphs` 的 `readBuffer` 引用槽名；初始 `buffer` 必须引用已声明的逻辑 ID。游戏通过 `ctx.render.buffers.bind(materialId, slot, handle)` 改绑，`unbind` 解除引用，`state(materialId)` 查询已绑定的逻辑名称/类型/数量，不能取得底层对象。活跃未绑定槽、类型/数量不符和失效句柄明确报错。
24
-
25
- 计算任务先产生候选 GPU 输出，完成着色器/越界/非有限值及 CPU 结果校验后才发布新 revision。渲染器对已提交原生缓冲做 GPU→GPU 复制到自己持有的稳定 Three storage 属性，不把 CPU 镜像重新上传当作 GPU 绑定。首次值、显式 CPU 写和恢复检查点可以上传；`inspect` 中 `computeGpu` 区分上传、候选、提交和版本，`bufferBindings` 区分 GPU 复制与渲染属性资源。当前不是零复制，也不是完全无读回：CPU 镜像仍用于任务校验、快照、动态 bounds/BVH 和查询。
26
-
27
- 被渲染槽引用的缓冲不能 release，先解除所有引用。检查点只保存逻辑绑定；跨插件预检确保 compute 快照包含匹配的 ID/类型/count，失败不改变旧世界。恢复后原缓冲句柄失效，游戏应按名称 resolve；物理 GPU 资源重新建立。WebGL2 上活跃 storage 槽返回 `TC_RENDER_BUFFER_CAPABILITY`，不会上传 CPU 镜像伪装 WebGPU 功能。
28
-
29
- 后处理以 `definePostProcess({ id, buffers: [...], graph })` 声明相同的类型化槽，通过 `ctx.render.effects.buffers.bind(passId, slot, handle)`、`unbind`、`state` 管理。材质 ID 与 pass ID 是独立命名空间，可以同名。两类槽联合保护逻辑源缓冲，取消其中一个引用不会移除另一类引用的 pin。快照同时预检两类绑定与 compute peer，失败不部分恢复。
30
-
31
- 片元和后处理允许从 `uv` 等逐像素输入计算动态索引，使用 `floor` 得到整数。负数、非整数、非有限或超过元素数的渲染读取明确返回该类型的零值，不取相邻元素；bool 为 false。compute 越界仍使任务失败，顶点域仍由 CPU 几何镜像执行索引检查，不能把渲染 gather 的零边界语义套到计算任务。
32
-
33
- path/hybrid 将常驻 GPU 数据复制进原生材料表的附加 vec4 区域；CPU 表只写材质、参数和零占位。`rendering.surface.materialGraphs.bufferSlots` 记录原生槽的复制、字节、版本和零 CPU 结果上传；资源版本变化使积分/时域失效，未变化帧跳过复制。渲染复制不等于零复制，计算仍逐任务读回验证镜像。
34
-
35
- 顶点反馈例子为 `examples/compute-render`。片元/后处理例子为 `examples/fragment-buffers`，两者都只使用公开 SDK；源码渠道可运行 `npm run dev -- --project examples/fragment-buffers`。npm 渠道使用同样的声明和 `render.effects.buffers` 接口，无需引擎源码。独占 GPU 的小型复测入口为 `npm run probe:fragment-buffers`。计算纹理及直接渲染槽见下文；完整高级矩阵仍待完成，不宣称全部 CAP-17 已验收。
36
-
37
- ## 受控顶点图
38
-
39
- `defineMaterial({ vertex: { position?, normal? } })` 接受 vec3 输出图。输入可用 `positionLocal`、`normalLocal`、`vertexIndex`、`instanceIndex`、uv/uv1、固定时间、参数及声明纹理的 base-LOD 采样；材质域、计算域和后处理域不能冒用这些输入。至少定义一个通道。
40
-
41
- 这里的 local 明确指内置 morph、骨骼和实例变换之后、对象世界矩阵之前。position 返回绝对位置，不是位移增量；normal 输入已归一化，输出零向量时保留它。GPU 光栅节点和 f32 CPU 镜像读取同一原始输入快照。未提供法线图时不会自动推导变形微分，也不会自动修正切线或所有法线贴图组合。
42
-
43
- 使用 `model: { asset, material }` 可显式整模替换导入材质，把顶点图用于带骨骼/morph 的模型；不传 material 保留原资产材质。覆盖材质由游戏内容所有者持有，模型实例与模板不会销毁借用材质。当前是整模替换，不是按源材质槽合并。
44
-
45
- 引擎从同一变形几何维护对象包围体和渲染射线查询，剔除保持开启，路径/混合 BVH 会更新或 refit。Transform 和显式物理 collider 不被 shader 改写；本功能不等于自动 Rapier 形变或 M4 耦合。
46
-
47
- 最小例子：`npm run dev -- --project examples/vertex`。数据纹理和小型带骨骼/morph GLB 是可离线重建的 MIT 夹具；`node --import tsx tools/prepare-vertex-assets.ts` 可重新生成。高收益实测入口为 `npm run probe:vertex`，内部 MRT 遮挡回归为 `npm run probe:postprocess:occlusion`；两者都应独占 GPU，不是完整 M3 验收。
48
-
49
- ## 受控 HDR 后处理
50
-
51
- 通过 `definePostProcess({ id, graph, enabled? })` 声明 vec4 输出图，并在 `defineGame({ postProcesses: [...] })` 中显式排序。系统使用 `ctx.render.effects.configure/state/setParameter/resetHistory`，无需也不能导入 Three.js、GPU 对象或着色器源码。
52
-
53
- 图支持 `uv`、`screenSize`、`texelSize`、固定时间和已有类型化参数/算术。`sampleFrame` 的 channel 可为 `scene.color`（未曝光/未色调映射的线性 HDR）、`scene.normal`（世界空间着色法线 RGB，命中 alpha=1）或 `scene.depth`（R 为相机到首表面的世界单位距离，未命中 0），也可为更早 pass 的 ID。`sampleHistory` 读取已声明 pass 的上一个成功提交呈现帧；不允许当前帧的前向依赖。
54
-
55
- pass 输出为全尺寸 rgba16float，捕获保持场景原 MSAA，最终曝光/色调映射和颜色转换只执行一次。无启用效果时仍走原直出链路。后端缺少所需 HDR/MSAA/MRT 能力则明确报 `TC_POSTPROCESS_CAPABILITY`，不会自动降尺寸、采样或精度。颜色、法线和距离不是透明多层 G-buffer；半精度范围、复杂透明与逐像素算术溢出的完整诊断矩阵尚未验收。
56
-
57
- 效果开关及参数参与 CPU 检查点；反馈纹理不序列化，恢复/内容/模式/设备变化明确重置历史。开关变化会防御性重置所有历史；关闭的 pass 不再推进历史，当前帧输出为上游直通。参数改变默认保留历史，需要时显式 `resetHistory(id?)`。反馈按呈现帧推进，不是游戏物理时间或存档状态。
58
-
59
- 最小三段例子在 `examples/postprocess`：`npm run dev -- --project examples/postprocess`。小规模独占 GPU 验证为 `npm run probe:postprocess`，覆盖三模式像素、通道、反馈/恢复、4× MSAA、方向标记及一条 WebGL2 路径；它不是完整 M3、画质或性能验收。
60
-
61
- ## 受管理计算
62
-
63
- 声明 `defineCompute({ id, count, outputType, buffers, graph })`，其中 `buffers` 为具名只读绑定及其 GraphType。计算图用 `input/index`、`readBuffer`、参数和既有算术节点表达计算，不接收原始 shader 或 GPU 对象。系统通过 `ctx.compute` 创建/查询/读写/释放缓冲，派发任务并查询或取消任务；类型、维度、绑定、越界和非有限输出均有明确诊断。
64
-
65
- 引擎在每个固定 tick 后等待 GPU 任务结算；`readBuffer` 返回上次完整成功结果的 CPU 镜像，失败或取消不覆盖输出。输出可同时作为输入，读取的是派发前快照。枚举 `tasks()` 并释放终态任务，避免无限保留历史；恢复后按缓冲名称 `resolve()`，不复用旧句柄。快照/回放/设备重建已接入，WebGL2 不执行计算。
66
-
67
- 仓库最小反馈游戏：`npm run dev -- --project examples/compute`。受影响功能复测使用 `npm run probe:compute:numeric`，完成后再串行执行 `npm run probe:compute`；前者为小规模真实 GPU 数值与释放检查，后者为游戏反馈、输入、快照/回放、恢复和一条 WebGL2 能力分支。不要并行争用同一 GPU，也不需要为每次局部修改运行整个 M3 矩阵。
68
-
69
- 显式依赖使用 `bindings: { name: { task: predecessor } }`：读取该任务的确切成功输出，即使同一源缓冲已经被后续任务覆盖。`after: [predecessor]` 只约束执行顺序，普通缓冲句柄绑定仍读取派发时快照；参数与 time 也在派发时固定。只能引用同一运行时已有的未释放任务，不支持前向/跨 owner 引用。
70
-
71
- 失败或取消的前置任务使消费者以 `TC_COMPUTE_DEPENDENCY_*` 失败，不运行其 GPU 计算、不发布输出；独立任务继续执行。仍被未完成消费者引用的任务不能释放（`TC_COMPUTE_TASK_IN_USE`）。未释放成功任务会保留其 CPU/GPU 结果版本，及时 `releaseTask` 才能回收历史。已排队的任务结果绑定保护源缓冲；已释放的源资源不能通过旧任务复活。
72
-
73
- 任务不序列化进快照。游戏不要把临时任务句柄作为持久状态：恢复或设备重建后重新派发链路；源缓冲按名称 resolve。公开示例 `examples/compute-dependencies` 演示分支、覆盖、纯顺序依赖及失败隔离；小型串行硬件验证为 `npm run probe:compute-dependencies`。
74
-
75
- 当前任务仍顺序执行且每节点读回 CPU 镜像，不是一次批量 GPU-only DAG。GPU 常驻顶点/片元/后处理的缓冲和纹理绑定、顶点图、HDR 后处理及计算纹理核心已接入；完整高级矩阵仍待完成。现有链路不等于 CAP-17 或完整 M3 已验收。
76
-
77
- ## 计算纹理
78
-
79
- 使用 `defineGame({ computeTextures: [{ id, width, height, data? }] })` 或 `ctx.compute.createTexture(...)` 创建受管理二维纹理。格式固定为线性 `rgba32float`，data 为行优先 Vec4 数组；宽高必须是正整数，总 texel 数最多 2^24，实际 GPU 限制另行校验。纹理与缓冲共用唯一 ID 空间，但句柄不同，不能混用两类 API。
80
-
81
- `resolveTexture(id)` 按名称获取句柄，`describeTexture` 返回尺寸/格式/revision，`readTexture` 返回上次完整成功结果的分离 CPU 镜像。`writeTexture(handle, texels)` 写整图，第三参数 `{x,y,width,height}` 可写矩形；全部数据和范围先通过检查，再一次更新 revision。`releaseTexture` 拒绝仍有未结束消费者的源。
82
-
83
- 计算内声明 `textures: [{ name, filter?, wrapU?, wrapV? }]`，图中 `sampleTexture` 引用该槽名。filter 为 nearest/linear（默认 linear），寻址为 clamp/repeat/mirror（默认 clamp）。dispatch 通过 `textures: { name: textureHandle }` 捕获派发时输入，或 `{ name: { task: predecessor } }` 读取该任务的确切纹理版本；`after` 仍只提供顺序。纹理不能传给普通缓冲 bindings。
84
-
85
- dispatch.output 可为纹理句柄，此时 outputType 必须为 vec4，count 必须等于 width×height。计算输入 `pixelCoord` 是输出整数坐标，`outputSize` 是输出宽高，`uv` 是 texel 中心归一化坐标；缓冲输出视为 count×1，index 保持线性索引。非有限采样 UV 使整个任务以 `TC_COMPUTE_TEXTURE_COORD` 失败，有限域外 UV 按声明寻址。
86
-
87
- 同一 GPU compute shader 写真实 storage texture 和验证用 packed buffer，校验后成对提交；失败/取消不发布其中一半。后续采样重用确切 GPU 版本，不上传 CPU 计算结果。初始化、显式 CPU 写、恢复后的检查点可以上传；`computeGpu.textureUploads/liveTextures/textureResidentHits/storageTextureDispatches` 可观察实际纹理资源与使用。任务仍读回 buffer 验证，不能宣称 GPU-only。
88
-
89
- 纹理句柄不跨恢复保存，恢复后按名称 resolveTexture，重新派发临时任务链。示例 `examples/compute-textures` 只导入公开 SDK；源码渠道运行 `npm run dev -- --project examples/compute-textures`，小型硬件复测 `npm run probe:compute-textures`。npm 渠道使用同样的类型/接口与随包本文档。
90
-
91
- ## 动态纹理渲染与资产
92
-
93
- 材质和后处理各自声明 `textures: [{ name, texture?, width?, height?, filter?, wrapU?, wrapV? }]`；`texture` 是初始的受管理纹理 ID，不是资产对象。图中 `sampleTexture` 的 texture 使用该槽名。槽名不能与静态纹理资产 ID 相同；静态资产采样仍走原来的接口。运行时通过 `ctx.render.textures.bind(materialId, slot, handle)` 或 `ctx.render.effects.textures.bind(passId, slot, handle)` 改绑，两个服务都提供 `unbind` 和 `state`。尺寸约束可省略；已经绑定的尺寸变化须重新 bind。
94
-
95
- 槽可用于材质片元、顶点位置／法线和后处理。顶点 CPU 镜像使用相同过滤与寻址维护变形 bounds/BVH 和射线查询，不改变物理 collider。渲染采样非有限 UV 明确返回透明零值；计算采样非有限 UV 仍导致 `TC_COMPUTE_TEXTURE_COORD`。材质／后处理与缓冲／纹理四组引用联合 pin；纹理被引用时 `releaseTexture` 保持现有 `TC_COMPUTE_BUFFER_IN_USE` 错误码。
96
-
97
- `computeTextures: [{ id, asset }]` 或 `ctx.compute.createTexture({ id, asset })` 可以从声明并加载的普通纹理资产建立独立计算纹理。支持可读的 RGBA8 或 float32 像素；按资产声明的 sRGB／linear 色空间转换为线性数据并保持上传行顺序。计算纹理之后独立更新，快照保存像素而非依赖重新读取资产。资产不可读、未声明或格式不支持时返回 `TC_COMPUTE_TEXTURE_ASSET`。
98
-
99
- Three 路径将常驻纹理以 GPU→GPU 复制到自身资源；path/hybrid 将同版本的 GPU packed mirror 复制到已有材料表。两条路径不会把 CPU 计算结果上传作为渲染更新，但也不是零复制。`rendering.textureBindings` 和 `rendering.surface.materialGraphs.textureSlots` 可查看复制计数；活跃槽在 WebGL2 返回 `TC_RENDER_TEXTURE_CAPABILITY`。示例 `examples/render-textures` 和 `npm run probe:render-textures` 覆盖资产导入与小型三模式链路；npm 使用相同 SDK 和文档，实际新版本安装验收留至里程碑冻结。
100
-
101
- ## 场景与公开设置
102
-
103
- ```powershell
104
- npm run dev
105
- ```
106
-
107
- 默认加载 `examples/m3` 的真实 Fox/WaterBottle 画廊。`1/2/3` 切换 raster/hybrid/path；Space 切换刚体运动，N 切换空间降噪，D/I 切换直接/间接光照。游戏只导入 `pelican-engine`。
108
-
109
- ```ts
110
- export default defineGame({
111
- id: "render-example",
112
- scene,
113
- render: {
114
- mode: "path",
115
- samplesPerFrame: 1,
116
- maxBounces: 6,
117
- denoise: true,
118
- denoiseIterations: 3,
119
- exposure: 1,
120
- directLighting: true,
121
- indirectLighting: true,
122
- debug: "beauty",
123
- },
124
- systems,
125
- });
126
- // 在同步玩法系统中：
127
- ctx.render.configure({ mode: "hybrid", denoise: true });
128
- const settings = ctx.render.state();
129
- ```
130
-
131
- 设置是可序列化状态，参加 Host 快照和恢复；未知字段、非法数值或模式明确失败，不公开 GPU 对象。调试视图支持 beauty/albedo/normal/depth/samples。材质新增 emissive/emissiveIntensity/opacity/alphaTest/side，使用相同编译诊断与引擎封装。opacity 的随机覆盖不是折射。
132
-
133
- ## 物理透射开发链路
134
-
135
- ```ts
136
- const glass = defineMaterial({
137
- id: "glass",
138
- color: "#ffffff",
139
- roughness: 0.15,
140
- metalness: 0,
141
- transmission: 1,
142
- ior: 1.5,
143
- attenuationColor: "#80c0e0",
144
- attenuationDistance: 2,
145
- });
146
- ```
147
-
148
- `transmission` 是介电透射与不透明 BSDF 的混合比例；它不修改 opacity。IOR 必须为正，透射要求 metalness 为 0；正衰减距离按世界单位计算 Beer 吸收，颜色先转为线性值，距离为 0 关闭吸收。SDK 不暴露底层材质对象。
149
-
150
- path/hybrid 将正透射对象的闭合几何边界编入介质目录，支持平滑/粗糙折射、反射、嵌套介质和相机内部初始状态。每个对象或实例必须是单个闭合、连续、非自交壳体；相交/接触体积、开口和部分不透明边界有明确诊断。目录不是通用自交证明；复杂重叠介质、空腔、多壳体、光谱色散尚未实现。完整规则见 `packages/renderer/MEDIUM.md`。
151
-
152
- ```powershell
153
- npm run dev -- --project examples/refraction
154
- ```
155
-
156
- 该项目仅使用公开 SDK，包含吸收平板、内外相机、嵌套边界、折射/粗糙度、尺度/平移和介质内点光源对照。线性图像、边界错误计数与解析 Beer 断言由独立开发探针检查；不能把可见玻璃球当成完整 M3 画质验收。光栅使用物理材质实现，但其屏幕空间透射/厚度与路径体积的一致性仍需补验。
157
-
158
- ## 已有链路
159
-
160
- - 光栅模式使用 WebGPURenderer，WebGPU 初始化不可用时走 Three.js 内置 WebGL2 回退，不主动降画质。`game.render.capabilities()` / `ctx.render.capabilities()` 返回当前后端及可用模式；WebGL2 下切 path/hybrid 返回 `TC_RENDER_MODE_UNAVAILABLE`，降噪/计算返回 `TC_RENDER_COMPUTE_UNAVAILABLE`，原设置保持不变。两后端都不可用返回 `TC_RENDER_BACKEND_UNAVAILABLE`。状态栏同步显示 WebGPU/WebGL2。
161
- - path 使用当前表面/BVH 的实际光线命中，UV、法线、PBR 纹理和多材质组进入 WGSL。
162
- - hybrid 光栅化首命中，再使用同一材质/灯光进行真实阴影与二次光线求值，不透明叠加独立图片。
163
- - 支持点/方向光、环境辐射、发光几何及 MIS；studio PMREM 捕获实际 HDR，不用均值或假背景替代。
164
- - 内容变更、相机、灯光、材质和设置变化使路径累积失效。开启 denoise 后独立主命中通道输出上一帧 UV/预期深度，先做时域历史验证/邻域裁剪，再做空间滤波；静态连续累积不重复计入历史。完整时域画质矩阵仍未验收。
165
- - 设备丢失会暂停并尝试重建设备/管线/环境，保留 CPU 游戏状态；失败保持故障诊断。自动化就绪不依赖点击、焦点或按回车。
166
-
167
- 当前 capture/cache、CPU SAH/refit 与 GPU 线程化遍历是不同阶段。它们不等于 GPU refit、BLAS/TLAS 或专用硬件 RT。原生 1080p 的当前高反弹负载仍慢，性能优化和完整质量矩阵未完成。
168
-
169
- `examples/temporal` 是只用公开 SDK 的运动/遮挡/动画/资源恢复测试场景。
170
- `denoiseIterations` 仅控制空间迭代次数；`denoise=false` 关闭时域与空间链路。
171
- 内部开发读回不是游戏接口。时域历史的权重不是严格独立的光线样本数，
172
- 不能据此把低 spp 动态帧宣称为高 spp 物理参考。详见 `packages/renderer/TEMPORAL.md`。
173
-
174
- ## 开发复验
175
-
176
- ### 刚体角运动（M4 并行增量）
177
-
178
- `ctx.physics.angularVelocity(entity)` 查询世界坐标弧度／秒；`setAngularVelocity(entity, vec3)` 设置动态刚体角速度，`torqueImpulse(entity, vec3)` 施加世界空间力矩冲量，`impulseAtPoint(entity, impulse, worldPoint)` 在指定世界坐标施加冲量，同时影响平动和转动。后三者只支持动态刚体；固定、运动学或角色体返回 `TC_PHYSICS_BODY_TYPE`。写操作参与物理历史、快照和回放，旧快照仍兼容。
179
-
180
- 示例 `examples/angular-physics` 只使用公开 SDK；源码渠道运行 `npm run dev -- --project examples/angular-physics`，独占 GPU 的小型验证为 `npm run probe:angular-physics`。当前 M4 非正式完成，首次正常物理步前移除刚体存在已复现的底层生命周期缺陷，见 `docs/tasks/M4-ANGULAR-PHYSICS.md`；完整模拟交互仍需后续验收。npm 渠道使用相同 SDK，更新包安装验收留待稳定节点。
181
-
182
- ```powershell
183
- npm run typecheck
184
- npm run probe:m3
185
- npm run build
186
- ```
187
-
188
- `probe:m3` 必须在真实硬件 WebGPU 环境运行，生成带源码指纹的开发记录和图像。失败不覆盖成成功；`formalMilestoneAccepted` 明确为 false。全量测试的硬件 opt-in 见 `docs/tasks/M3.md`；未启用时的跳过不算通过 GPU 验证。
189
-
190
- 构建仍为 `dist/`，可在普通静态服务器子路径部署；默认生产不暴露开发控制 hook。`tools/m3-static-probe.ts` 使用真实按键测试模式切换和冷启动。直接浏览器自动化是外部测试职责，游戏源码不得调用内部开发 hook。
191
-
192
- 当前公开图语言仍是有限子集。后处理、多通道、变形和计算接口的完整表达矩阵、完整物理材质图像矩阵、时域重建、原生性能及独立 AI 使用门禁未完成前，不发布 M3。已确认的 M1–M8 总范围保持不变。