@moku-labs/game 0.12.0 → 0.13.1

package/llms.txt

@@ -10,7 +10,7 @@ Facts: Bun only. ESM only. `"sideEffects": false`. `pixi.js` `^8.0.0` is a peer
 - `@moku-labs/game/app`: `defineGameApp`, `startMoment` and the types of a game's `index.ts` and `config.ts`. No `node:` import, no system or native package. See "The game shell".
 - `@moku-labs/game/app/page` (the browser): `startPage`, the page the generated `.moku/main.ts` calls.
 - `@moku-labs/game/app/system` (the browser, the native shell): `systemShellOf`, `fromSystem`, `storeSave`, `createSystemApp`, the type `SystemModules`, over the optional peer `@moku-labs/system`. The one entry that names it, in types only: the page hands it the loaders.
-- `@moku-labs/game/cli` (node and bun only): `runCli`, the bin `moku-game`, and `preparePage`, the editor's dev page.
+- `@moku-labs/game/cli` (node and bun only): `runCli`, the bin `moku-game`, `preparePage`, the editor's dev page, and `watchKeys`, the watch that keeps `generated/` fresh next to it.
 - `@moku-labs/game/testing`: headless play, repro runs, isolated feature tests (`isolate`, `stub`), fake clock, in-memory save provider. No `node:` import.
 - `@moku-labs/game/visual` (node and bun only): the visual tests `defineVisualTest`, `runVisualTests`, `parseVisualArgv`. The bin runs them: `moku-game visual`.
 - `@moku-labs/game/assets` (node and bun only): the asset key scanner, the production packer and the string compiler. The package bin `moku-game-assets` runs it.
@@ -306,6 +306,7 @@ The page. `moku-game dev` and `build` write a `main.ts` that calls `startPage(ga
 // .moku/main.ts of the engine's mini game, written by moku-game dev
 // Written by moku-game dev. Do not edit.
 import "./dev.ts";
+import "./assets-stamp.ts";
 import { startPage } from "@moku-labs/game/app/page";
 import game from "../index.ts";
 import config from "../config.ts";
@@ -317,12 +318,13 @@ await startPage(game, config, {
 ```
 
 Commands of the bin `moku-game` (bun). Every command takes `--root <dir>` (default `.`), `--preload <path>` and `--serve-plugin <path>` (both repeat), before or after the command word. Exit 0 on success, else 1 with a `[game] …` line.
-- `moku-game dev [--port 3000] [--packed]`: writes `.moku/index.html`, `dev.ts`, `main.ts`, `bunfig.toml` (the hot plugin first, `__MOKU_GAME_DEV__` defined `true`), runs Bun again under that bunfig in the game folder and serves `/`. It prints `› <folder>: dev server, raw assets. Ctrl+C stops it.` and then the bound URL alone on its own line, `http://localhost:3000/`. `--port 0` takes a free port. `--packed` serves `dist/assets`. A new or removed file in `tests/scenarios/` rewrites `main.ts`. A taken port: `[game] dev: port 3000 is in use.` with `Pass --port 0 for a free port.`
+- `moku-game dev [--port 3000] [--packed]`: writes `.moku/index.html`, `dev.ts`, `main.ts`, `assets-stamp.ts`, `bunfig.toml` (the hot plugin first, `__MOKU_GAME_DEV__` defined `true`), runs Bun again under that bunfig in the game folder and serves `/`. It prints `› <folder>: dev server, raw assets. Ctrl+C stops it.` and then the bound URL alone on its own line, `http://localhost:3000/`. `--port 0` takes a free port. `--packed` serves `dist/assets`. A new or removed file in `tests/scenarios/` rewrites `main.ts`. On the raw files it keeps `generated/` fresh: it runs the scan of `keys` once before the page is written, and a save of an asset file (`.png`, `.webp`, `.fnt`, `.mp3`, `.m4a`) or of a `strings/<locale>.json` runs it again 100 ms after the last file event and prints `› keys: <path>` or `› keys: <path> and <n> more`; a changed or new string hot swaps through `generated/strings.<locale>.ts`, an asset file that is new, removed or saved with new bytes reloads the page through `.moku/assets-stamp.ts`, which `main.ts` imports, and files answer `Cache-Control: no-store`. A failed scan is one warning `[game] keys: <message>` and the server runs on. A changed layer in `config.ts` needs a restart; `--packed` watches nothing. A taken port: `[game] dev: port 3000 is in use.` with `Pass --port 0 for a free port.`
 - `moku-game build [--out dist/web]`: packs the assets, bundles the page minified with `__MOKU_GAME_DEV__` defined `false` (no scenario, no agent, no `.dev` module, no `/control`), every link `./`, and copies the pack beside it with `manifest.json` next to `index.html`. Runs from any http sub-path and from Tauri, not from `file://`.
 - `moku-game native build <target> [--simulator]`, `native dev <target>`, `native doctor [<target>]`, `native clean [<target>]`: one verb of `@moku-labs/native` (a dev dependency, `^0.3.2`) over `config.ts`. App name, identifier and icon from `native`, orientation and background colour from `page`; the web build is `moku-game build`, the dev server `moku-game dev --port 5173`; system rows for `back`, `haptics`, `store`; the Tauri project in `.moku/tauri`, the apps in `dist-native`. `[game] config.ts has no native section.` without `native`.
-- `moku-game keys [--check]`: `generated/assets.ts`, the compiled strings and `manifest.json`. `moku-game pack [--no-cache]`: `dist/assets`. Both pass the layers of `config.ts`.
+- `moku-game keys [--check]`: `generated/assets.ts`, the compiled strings and the dev manifest `generated/manifest.json`; `dev` runs the same scan at start and on save and serves the manifest on `/manifest.json`, `visual` stops without it. `moku-game pack [--no-cache]`: `dist/assets`. Both pass the layers of `config.ts`.
 - `moku-game visual [--update] [--only <name>] [--no-pixels | --pixels] [--webgl] [--dir <path>] [--tests <file>] [--url <url>]`: runs `runVisualTests` with the default export of `tests/visual/index.ts`, `{ app, tests }` (`app` is a `VisualSetup` `{ app, page? }`: `export default { app: { app: fixtureApp }, tests }`), against `tests/visual/baselines/`. The flags go through `parseVisualArgv`. The pixel leg runs on a Mac only unless `--pixels`/`--no-pixels`; without `--url` the command writes its own page into `.moku/visual/` (the page of `dev` and of the editor in `.moku/` stays), runs Bun again under `.moku/visual/bunfig.toml` as `dev` does (hot plugin, `--serve-plugin`, `--preload`), and the child serves the page on a free port, then stops it. No `manifest.json`: `[game] visual: no manifest.json in "<game>".` Exit 0 when the report is ok, else 1. `[game] visual: <file> must export default { app, tests }.` for a missing module or another shape, a bare app factory too.
-- `preparePage(root, { agents?, preload?, servePlugins? })` of `@moku-labs/game/cli` writes the dev page of `moku-game dev` and resolves `{ html, bunfig }`, both absolute, for a server the caller starts: `bun --config=<bunfig>`. With agents the page also imports the game's `**/*.dev.ts` and hands them to the agents. The editor calls it: `await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] })`.
+- `preparePage(root, { agents?, preload?, servePlugins? })` of `@moku-labs/game/cli` writes the dev page of `moku-game dev` and resolves `{ html, bunfig }`, both absolute, for a server the caller starts: `bun --config=<bunfig>`. With agents the page also imports the game's `**/*.dev.ts` and hands them to the agents. It also writes the first, empty `.moku/assets-stamp.ts` when the game has none. The editor calls it: `await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] })`.
+- `watchKeys(root, { onError? })` of `@moku-labs/game/cli` is the keys watch of `moku-game dev` for a server the caller runs: it runs the scan of `keys` once, resolves `{ close() }` after it, then scans again on a save of an asset or a strings file. A failed scan calls `onError(message)` (default: a console warning `[game] keys: <message>`) and the watch goes on. The editor calls it next to `preparePage`: `const keys = await watchKeys("games/timber", { onError: message => log.warn(message) })`, then `keys.close()`. It rejects with the `[game]` errors of `preparePage` for a folder that is not a game.
 
 ## More patterns
 
@@ -623,7 +625,7 @@ Dev only. A save of a view file swaps the module in the running page: same state
 plugins = ["@moku-labs/game/hot"]
 ```
 
-- View files swap: `.tsx`, `styles.ts`, `view.ts`, `animations.ts`, `effects.ts`, `generated/strings.<locale>.ts`. On the layered layout also any `.ts` directly in a kind folder: `styles/`, `motion/`, `effects/`, `views/`, `world/projections/`, `world/layout/`, in a feature or in `shared/`. Styles, components, function components, projections of a registered name, animations, text styles, emitters and strings. After a strings JSON edit run `bun run assets:keys`; its output is what swaps.
+- View files swap: `.tsx`, `styles.ts`, `view.ts`, `animations.ts`, `effects.ts`, `generated/strings.<locale>.ts`. On the layered layout also any `.ts` directly in a kind folder: `styles/`, `motion/`, `effects/`, `views/`, `world/projections/`, `world/layout/`, in a feature or in `shared/`. Styles, components, function components, projections of a registered name, animations, text styles, emitters and strings. Under `moku-game dev` or the editor's `watchKeys` a save of a strings JSON compiles by itself and its output swaps, a new key too; an asset file that is new, removed or saved with new bytes reloads the page. A game with a server of its own runs `bun run assets:keys` after a strings JSON edit; its output is what swaps.
 - Logic files reload the page: `rules/`, `nodes/`, `flows/`, `state.ts`, `tables.ts`, `kit.ts`, a feature `index.ts`, `world/components/`, `world/systems/`. A view file that exports a scene, system, ECS component, filter, flow, node, feature, plugin, a new projection or a new animation is refused: `ui` logs `ui:hot-refused` and throws, and Bun reloads the page.
 - A swap logs `ui:hot-swap` and emits the global event `ui:hot-swap` `{ file, module }`.
 - Another layout, on a server of the game's own: `export default hot({ include, exclude })` from the game's `hot.ts`, listed as `plugins = ["./hot.ts"]`.
@@ -711,7 +713,7 @@ core/             the kit (the defineGame call) and its types
 shared/           the shared layer
 features/<f>/     one feature: flow/, rules/, views/, styles/, motion/, world/, assets/, strings/
 plugins/          the game's own plugins
-generated/        what moku-game keys writes
+generated/        what moku-game keys writes: assets.ts, the strings, manifest.json
 tests/            the tests; tests/scenarios/<name>.ts are the saves of ?player=<name>
 .moku/            what moku-game writes, ignored by git
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": false,