SillyMaker

English | 简体中文

An LLM-friendly TypeScript + React game engine for visual novels, management sims, and RPG-flavored story games. Deterministic runtime contracts, a semantic stage, atomic saves — authorable by humans and AI agents alike, running on Deno.

Play the flagship example: the Cat Cafe (《雨巷猫舍》) is a complete, publishable game built to drive the engine — title screen, scheduling gameplay, petting hit-regions, a turn-based contest, an album, multiple endings with a postgame, dialogue playback QoL (typewriter / auto / skip / history / rollback), scene-driven audio, save slots with safepoints, bilingual text, and a host/cross-target desktop-packaging preview.

Then break the genre: SillyOS 98 is a retro desktop shell — overlapping draggable windows, a taskbar, a Start menu, deterministic Minesweeper (mines drawn from the transactional RNG, never leaked to the UI), a Notepad whose files persist through engine saves, and a period browser. Same engine, zero visual-novel assumptions.

• Deterministic on supported paths — one session owns authoritative state; admitted commands commit atomically or not at all; transactional RNG travels inside snapshots, so supported replay and rollback paths reproduce recorded outcomes.
• Semantic stage, not a canvas — Stories publish plain-data stage targets (content IDs, placements, appearances, hit regions); renderers are swappable React components; saves never contain renderer state.
• Static data as content tables — items, activities, events, and reactions live in validated content-database tables with typed queries; mutable state stays in modules; tuning is editing a table row.
• Built for both audiences — AI agents get structured diagnostics, headless simulation, and authoring canaries; humans get a DevDock with live inspectors, a writable tuning panel, trajectory traces, and save diffs.

Requires Deno >= 2.9.0 (runtime and package manager in one; npm dependencies resolve through Deno's Node compatibility).

deno install
deno task dev            # Vite dev server (pick an app with --mode <applicationId>)

Common commands:

• deno task check — the canonical local gate: format, lint, typecheck, and the product-level test suite;
• deno task test / deno task test:e2e — engine/game behavior tests and browser user flows;
• deno task story <verb> <app> — the application lifecycle CLI (inspect / check / simulate / dev --smoke / build / desktop, JSON reports);
• deno task site:build — compose the publishable static site (docs + the playable Cat Cafe and SillyOS 98 examples) into dist/site, then deploy via the GitHub Pages workflow or deno task site:deploy:cf (Cloudflare Workers); see build-and-release.

Start a new game by copying template/ and following its README. Each application is a self-contained project with its own sillymaker.config.ts; the root project.config.ts only lists application directories for repository-wide commands.

• Documentation map — the index of everything below
• Architecture · Features · Roadmap
• Development and testing · Story authoring · Authoring quickstart
• Agent game guide — point a coding agent at this repo and get a game back
• Build and release (web, static hosting, desktop packaging)
• Public site (VitePress, en/zh) lives in website/

engine/packages/base     Generic contracts, Story authoring, runtime, saves, diagnostics
engine/packages/tooling  Project config and story CLI commands
engine/packages/ui       Generic React game UI and presentation runtime
engine/packages/web      Browser host, IndexedDB/HTTP persistence, mounting, automation
e2e/                     The neutral engine-conformance Story (Engine Lab)
template/                The starter skeleton for new games
examples/                Example Stories (bookshop, cat-cafe, silly-os)
project.config.ts        Repository directory list for aggregate commands
scripts/                 Build identity, asset checks, desktop save server, site composer
docs/                    Internal engineering docs (plans, research, proposals, policies)
website/                 The public documentation site (VitePress, en + zh)

Workspace packages are private; “public export” means a supported in-repo package entry, not an npm release.

Copyright © 2026 Jun Jiang (jasl).

The whole repository — engine, examples, scripts, and documentation — is MIT. Project-owned media assets under examples/*/assets/** and art-source/** are dedicated to the public domain under CC0 1.0: commercial use, derivatives, and redistribution without restriction. Contribution guidelines: CONTRIBUTING.md.