The game shell

A game is a folder

index.ts is the game as one data object. config.ts is the page, the native app, the system plugins and the save, as plain data. The engine bin moku-game serves, builds and packs the folder. A game writes no page, no server, no bridge and no bunfig.toml, and makes no createApp call.

index.ts: the game

defineGameApp(definition) takes the whole game and returns { headless(seams?), screen(seams?) }. It creates no app. Every type comes from the object: no generic at the call site.

import { defineGameApp } from "@moku-labs/game/app";
import { mainFlow } from "./flow";

export default defineGameApp({
  flow: mainFlow,
  safeNode: "home",
  player: { coins: 0, lastRoll: 0 },
  session: { rolls: 0 },
  seed: 7,
  headless: { features: [] },
  pluginConfigs: { flow: { holdMs: 120 }, ui: { tapTargetPt: 48 } }
});

The shell writes some plugin configs from the seams. Those keys are not in the type, so writing one is a compile error, never a value a shallow merge would drop.

defineGameApp checks what TypeScript cannot stop: [game] defineGameApp needs flow., and [game] defineGameApp: features[2] is not a feature. for an entry defineFeature did not make.

config.ts: the page, native, system, save

import type { GameConfig } from "@moku-labs/game/app";

export default {
  page: {
    title: "Dice",
    lang: "en",
    background: "#10161d",
    orientation: "portrait",
    icons: { favicon: "assets/icon.png" },
    boot: { image: "assets/boot.png" }
  },
  system: ["lifecycle", "back"],
  save: "local",
  assets: { layers: { shared: "ui" } }
} satisfies GameConfig;

A value TypeScript would refuse, in a file that skips satisfies, stops moku-game and the page: [game] config.save is "disk"., [game] config.system names "tray", which the game shell does not wire., [game] config.page.title is empty.

The page

moku-game dev and moku-game build write the page. Its main.ts calls startPage(game, config, options) of @moku-labs/game/app/page:

// 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";
import scenario0 from "../tests/scenarios/rich.ts";

await startPage(game, config, {
  scenarios: { "rich": scenario0 }
});

On pagehide the page flushes the save, and stops the app when the page is really left. A page kept in the back/forward cache keeps its app running. Every problem goes to the app's log.

Commands

bunx moku-game help

Every command takes --root <dir> (default .), --preload <path> and --serve-plugin <path>, before or after the command word. The exit code is 0 on success, else 1 and a [game] … line.

dev

moku-game dev writes the dev page into .moku/: index.html, dev.ts, main.ts, bunfig.toml and assets-stamp.ts, each only when its text changed. It runs Bun again under that bunfig in the game folder and serves the page.

• --port 0 takes a free port. A taken port: [game] dev: port 3000 is in use.
• /manifest.json is the dev manifest. A path segment that starts with a dot, and node_modules, answer 404. Every file answers with Cache-Control: no-store.
• main.ts lists tests/scenarios/*.ts by file stem. A new or removed scenario rewrites it, and the page reloads.
• A save of an asset or a strings file scans the keys again, 100 ms after the last file event. A failed scan is one warning, and the server runs on.
• It watches the installed engine and restarts its server when the engine changes.

build

moku-game build packs the assets with the layers of config.ts, then bundles the page minified into --out, with __MOKU_GAME_DEV__ defined false and no hot plugin. The page carries no scenario, no agent, no .dev module and no /control. Every link starts with ./, so it runs from any http sub-path and from Tauri, not from file://. A release page that carries the editor's agent is refused, and its output folder removed.

The editor's seam

The editor takes the same page from the engine. @moku-labs/game/cli exports what it needs:

With agents, the page also imports the game's **/*.dev.ts and hands them to the agents. See Doors.

Related

• Quick start: the smallest index.ts and config.ts.
• Native: native, system, the store save and the native build.
• Hot swap: what dev swaps and what it reloads.
• API reference: @moku-labs/game/app, /app/page, /cli.