OhMyGame

https://github.com/whitetowerai/ohmygame
Admin
OhMyGame is an open-source, local-first game creation studio that uses an AI agent to design assets,...
Tokens:39,319
Snippets:322
Trust Score:6.1
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Setup and run development: bun install and dev commands

Source: https://github.com/whitetowerai/ohmygame/blob/main/CONTRIBUTING.md

Install dependencies and start the development environment after ensuring Bun 1.4.2+ and Node.js 22.19+. Use 'bun run dev' for the web renderer with a local daemon, or 'bun run dev:desktop' for the Electron app.

```bash
bun install --frozen-lockfile
bun run dev            # web renderer + local daemon
bun run dev:desktop    # Electron app

```

--------------------------------

### graph.json example

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/runtime.md

A complete example of a graph.json file showing the runtime structure: version, title, viewport, entryNodeId, initialState, assets, nodes with signals, and edges. The example includes two nodes (main-menu and archive) and four edges with modes 'replace' and 'push'.

```json
{
  "version": 1,
  "title": "Ash Club",
  "viewport": { "width": 1920, "height": 1080 },
  "entryNodeId": "main-menu",
  "initialState": { "roundsCompleted": 0, "foundClues": [] },
  "assets": {
    "club-background": {
      "type": "image",
      "source": { "kind": "library", "assetId": "lib_8f2c…" }
    },
    "archive-desk": {
      "type": "image",
      "source": { "kind": "workspace", "path": "assets/archive-desk.webp" }
    }
  },
  "nodes": [
    {
      "id": "main-menu",
      "title": "Main menu",
      "source": {
        "html": "nodes/main-menu/index.html",
        "css": "nodes/main-menu/style.css",
        "javascript": "nodes/main-menu/node.js"
      },
      "assets": ["club-background"],
      "signals": [
        { "id": "enter-club", "label": "进入俱乐部" },
        { "id": "open-archive", "label": "查看旧案" }
      ]
    },
    {
      "id": "archive",
      "title": "Archive",
      "source": {
        "html": "nodes/archive/index.html",
        "css": "nodes/archive/style.css",
        "javascript": "nodes/archive/node.js"
      },
      "assets": ["archive-desk"],
      "signals": [
        { "id": "home", "label": "首页", "role": "navigation" },
        { "id": "rules", "label": "规则" }
      ]
    }
  ],
  "edges": [
    {
      "id": "e1",
      "source": { "nodeId": "main-menu", "signal": "enter-club" },
      "targetNodeId": "game-lobby",
      "mode": "replace"
    },
    {
      "id": "e2",
      "source": { "nodeId": "main-menu", "signal": "open-archive" },
      "targetNodeId": "archive",
      "mode": "push"
    },
    {
      "id": "e3",
      "source": { "nodeId": "archive", "signal": "home" },
      "targetNodeId": "main-menu",
      "mode": "replace"
    },
    {
      "id": "e4",
      "source": { "nodeId": "archive", "signal": "rules" },
      "targetNodeId": "game-rules",
      "mode": "push"
    }
  ]
}
```

--------------------------------

### mount function example

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/runtime.md

Shows the required export of a node: a mount function that receives a context. It uses context.root.querySelector, context.navigation.emit, context.state.get, and context.lifecycle.signal to handle a click event.

```javascript
export function mount(context) {
  const open = context.root.querySelector("[data-open]");
  const onClick = async () => {
    await context.navigation.emit(
      context.state.get("hasKey") ? "door-opened" : "door-locked",
    );
  };
  open.addEventListener("click", onClick, { signal: context.lifecycle.signal });
}
```

--------------------------------

### playable_add_node JSON example

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/agent.md

Example JSON payload for the playable_add_node tool, which creates a node from a preset. The preset 'choice' is used with id 'conductor' and title 'The conductor'.

```json
{ "preset": "choice", "id": "conductor", "title": "The conductor" }
```

--------------------------------

### Run test ablation with npm commands

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/experiments/test-ablation-2026-10-07.md

Commands to run the test ablation script. The first command performs a dry run, the second runs the full ablation, the third runs a single repetition for specific mutants, and the fourth resumes from a checkpoint. Requires dependencies installed and the cloud repository prepared or OHMYGAME_CLOUD_ROOT set.

```bash
npm run test:ablation -- --dry-run
npm run test:ablation
npm run test:ablation -- --runs=1 --mutant=D1,R3
# Resume a checkpoint with the same inputs, mutation selection and repetition count:
npm run test:ablation -- --resume=.data/test-ablation/<run>/results.json
```

--------------------------------

### game_use

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/agent.md

The existing game_use tool plays Playable Nodes projects. open builds the current sources into a draft of the Published Player, served on loopback under an unguessable path, and opens it in the Playtest window. Snapshots read text and interactive elements inside the Player's frames and node ShadowRoots, so the snapshot's text is what the screen shows. Its gameState is the Playtest debug record: current node, back stack, recent Signals and whether an edge followed them, State, State changes, errors, and save status. The bridge reset action starts a new game without the save. Only drafts expose the bridge; a published game does not. act drives real input; capture returns a screenshot.

```APIDOC
## game_use

### Description
The existing `game_use` tool plays Playable Nodes projects. `open` builds the current sources into a draft of the Published Player, served on loopback under an unguessable path, and opens it in the Playtest window. Snapshots read text and interactive elements inside the Player's frames and node ShadowRoots, so the snapshot's text is what the screen shows. Its `gameState` is the Playtest debug record: current node, back stack, recent Signals and whether an edge followed them, State, State changes, errors, and save status. The bridge `reset` action starts a new game without the save. Only drafts expose the bridge; a published game does not. `act` drives real input; `capture` returns a screenshot.

### Actions
- **open** - Builds the current sources into a draft of the Published Player and opens it in the Playtest window.
- **reset** - Starts a new game without the save (bridge action, only available in drafts).
- **act** - Drives real input.
- **capture** - Returns a screenshot.

### Response
Snapshots contain text and interactive elements inside the Player's frames and node ShadowRoots. `gameState` includes current node, back stack, recent Signals and whether an edge followed them, State, State changes, errors, and save status.
```

--------------------------------

### mount(context)

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/runtime.md

The mount function is the entry point for every node. It receives a context object and is called when the node is mounted. It may be async and can return a cleanup function.

```APIDOC
## mount(context)

### Description
The `mount` function is the entry point for every node. It is called with a `RuntimeContext` (or `NodeContext`) and is responsible for setting up the node's behavior. It may be async and can return a cleanup function (sync or async) that is called when the node is unmounted.

### Method
Function

### Signature
```js
export function mount(context) { ... }
```

### Parameters
- **context** (RuntimeContext | NodeContext) - Required - The runtime context providing access to the DOM root, assets, state, session, story, lifecycle, and navigation.

### Returns
- **cleanup** (function | Promise<function> | void) - Optional - A cleanup function to be called when the node is unmounted.

### Example
```js
export function mount(context) {
  const open = context.root.querySelector("[data-open]");
  const onClick = async () => {
    await context.navigation.emit(
      context.state.get("hasKey") ? "door-opened" : "door-locked",
    );
  };
  open.addEventListener("click", onClick, { signal: context.lifecycle.signal });
}
```

### Context Interface
```ts
interface RuntimeContext {
  root: ShadowRoot;
  assets: { url(id: string): string };
  state: {
    get(): Readonly<JsonObject>;
    get(key: string): JsonValue;
    set(key: string, value: JsonValue): Promise<void>;
    patch(values: JsonObject): Promise<void>;
    subscribe(listener: (state: Readonly<JsonObject>) => void): () => void;
  };
  session: {
    hasSave(): boolean;
    save(): Promise<void>;
    continue(): Promise<void>;
    reset(): Promise<void>;
    restart(): Promise<void>;
  };
  story: { map(): StoryMap };
  lifecycle: { signal: AbortSignal };
}

interface NodeContext extends RuntimeContext {
  navigation: {
    emit(signal: string): Promise<void>;
    back(): Promise<void>;
    connected(signal: string): boolean;
  };
}
```

### Notes
- Every request is validated. An undeclared asset, unknown state key, or undeclared Signal produces a visible runtime error.
- A node emits only its own declared Signals or goes back, so story flow stays visible in the graph.
```

--------------------------------

### Run pre-PR checks: test, typecheck, build, node-runtime, prettier

Source: https://github.com/whitetowerai/ohmygame/blob/main/CONTRIBUTING.md

Run the full check suite before opening a PR. Replace <changed files> with the actual files you modified; the prettier command is a no-install check.

```bash
bun run test
bun run typecheck
bun run build
bun run test:node-runtime
bunx --bun --no-install prettier --check <changed files>

```

--------------------------------

### playable_check JSON example

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/agent.md

Example JSON payload for the playable_check tool, which validates the graph and compiles nodes. The mode 'draft' is used.

```json
{ "mode": "draft" }
```

--------------------------------

### reset()

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/runtime.md

Restores the initial state and clears the back stack without leaving the current node. A menu starts a new game with reset() then its start Signal.

```APIDOC
## reset()

### Description
Restores the initial state and clears the back stack without leaving the current node. A menu starts a new game with reset() then its start Signal.

### Method
reset

### Parameters
None

### Returns
None

```

--------------------------------

### restart()

Source: https://github.com/whitetowerai/ohmygame/blob/main/docs/playable-nodes/runtime.md

Resets the game and enters the entryNodeId.

```APIDOC
## restart()

### Description
Resets the game and enters the entryNodeId.

### Method
restart

### Parameters
None

### Returns
None

```
Tokens:
Raw