Open Game Studio

Open Game Studio is a Codex-native command line studio for making games with AI agents without hiding the workflow in a black box.

Create a local game project, generate Codex-ready role prompts, hand focused work to a studio role, then validate the project artifacts before you trust them. The state lives in your repository under .codex/; generated games live under projects/<slug>/; normal execution goes through codex exec.

npm run init -- --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \
  --concept "A compact puzzle game about routing trains through haunted switchyards"

node dist/cli.js run producer --project projects/signal-cartographer \
  "Create the initial market overview."

npm run validate -- --project projects/signal-cartographer

Why developers use it

Open Game Studio gives game teams a repeatable way to work with Codex across design, production, engineering, art, QA, and release tasks.

• Local-first project state. No hosted planner, hidden queue, or opaque database.
• Codex-native instructions in generated AGENTS.md and .codex/prompts/<role>.md files.
• Role-specific context packets instead of dumping every template into every task.
• Hard-failing validation for generated prompts, workflows, package assets, and project contracts.
• Inspection paths with --dry-run and --print-prompt before Codex touches the workspace.
• Engine scaffolding for Godot, Unity, and Unreal projects.

This is not a game engine and it is not a replacement for human creative direction. It is a workflow layer: a small, inspectable CLI that turns studio roles and production documents into bounded Codex work.

The studio loop

flowchart LR
  A[init project] --> B[projects/slug]
  B --> C[.codex studio state]
  C --> D[generated role prompts]
  D --> E[run role with Codex]
  E --> F[review, fix, verify]
  F --> G[validate project]
  G --> D

A generated project contains the working contract Codex needs: project summary, engine context, role prompts, workflow prompts, starter production docs, and validation metadata. Role runs prepare a bounded prompt packet under .codex/runs/ and invoke codex exec from the project root.

Requirements

• Node.js 20 or newer.
• npm.
• Codex CLI available on PATH for normal run <role> execution and full validation.

Install from source

git clone git@github.com:merlinhu1/open-gamestudio.git
cd open-gamestudio
npm install
npm run build
node dist/cli.js --help

For package use after installing or linking the package:

npm exec opengamestudio -- --help
npm exec opengamestudio -- templates list

For local development from this checkout, prefer the npm scripts. They build first and exercise the built CLI through node dist/cli.js:

npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive
npm run manage -- --project projects/my-game
npm run templates -- list
npm run validate -- --project projects/my-game

Quick start

1. Create a project

npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive \
  --concept "A compact puzzle game about routing trains"

Open Game Studio creates projects/my-game/ with engine markers, starter docs, .codex/studio.json, generated role prompts, generated workflow prompts, and a project-level AGENTS.md.

2. Inspect the project

npm run manage -- --project projects/my-game
node dist/cli.js resume --project projects/my-game

status and resume are read-only. freeze is the explicit command that changes project status.

3. Choose a template or workflow

npm run templates -- list
npm run templates -- show gdd
node dist/cli.js market --project projects/my-game
node dist/cli.js ship-check --project projects/my-game

Workflow shortcuts render prompts only. They do not launch Codex.

4. Run a studio role through Codex

npm run build --silent
node dist/cli.js run producer --project projects/my-game \
  "Create the initial market overview."

Want to see exactly what Codex will receive first?

node dist/cli.js run producer --project projects/my-game \
  "Create the initial market overview." --dry-run

node dist/cli.js run producer --project projects/my-game \
  "Create the initial market overview." --print-prompt

run <role> inlines the generated project role prompt from .codex/prompts/<role>.md and only the package templates selected for that role and task. --allow-broad-context adds bounded discovery for existing project artifacts such as the GDD, production timeline, market overview, AGENTS.md, and .codex/studio.json; it does not recursively load the whole project.

5. Validate before relying on output

npm run validate
npm run validate -- --project projects/my-game

Validation exits nonzero on failure. It checks package contracts, template availability, forbidden future surfaces, build output, project state, generated-surface freshness metadata, rendered-body hashes, and stale or tampered generated prompt/workflow files.

Commands

Command	What it does
init / new	Create a project under projects/<slug>/.
status	Print project phase, status, engine, and the next validation command.
resume	Print a read-only continuation summary.
freeze	Mark a project as frozen.
validate	Run hard-failing repository or project validation.
templates list	List packaged template IDs.
templates show <template-id>	Print a packaged template.
run <role>	Prepare one bounded Codex prompt packet and invoke codex exec by default.
task create / task run	Manage file-backed .codex/tasks.json tasks.
market, analytics, design-spec, feel-review, art-direction, ui-review, milestone, handoff	Render focused workflow prompts.
review, ship-check	Render baseline review and release-check prompts.

Studio roles

Open Game Studio ships a Codex-native role roster with hyphenated IDs:

Area	Roles
Direction and production	studio-orchestrator, producer, release-manager
Market and analytics	market-analyst, data-scientist
Design and writing	creative-director, senior-game-designer, game-designer, narrative-designer, game-feel-designer
Engineering	gameplay-programmer, engine-programmer, tools-programmer
Art and interface	senior-game-artist, technical-artist, ui-ux-designer
Quality	qa-playtester

Legacy underscore role IDs are intentionally rejected. narrative-designer is a first-class story and content owner.

What gets generated

Repository assets:

• src/: TypeScript CLI implementation.
• src/roles.ts: Codex role packages compiled into the CLI.
• templates/: reusable design, production, art, QA, release, analytics, and engine templates.
• engine_configs/: engine overlays for Godot, Unity, and Unreal.
• docs/: migration, validation, truth, and compatibility notes.
• tests/: Vitest coverage for project workflow, templates, agents, runner prompts, validation, and engine behavior.

Project artifacts:

• projects/<slug>/: generated project root.
• AGENTS.md: primary generated Codex project instructions, owned by src/agents.ts.
• .codex/studio.json: project metadata, role roster, workflow IDs, and workflow state.
• .codex/prompts/: generated role prompts.
• .codex/workflows/: generated workflow prompts.
• .codex/runs/: prepared prompt packets and run metadata from non-dry role runs.
• .codex/tasks.json: file-backed task state when you use task create or task run.
• documentation/: starter game-design and production documents.
• source/project-<slug>/: engine project location contract.

Generated role prompts and workflow files carry deterministic freshness metadata and rendered-body hashes. New project validation compares those files against the current renderer and flags stale, malformed, or manually tampered surfaces.

Current boundaries

Open Game Studio is intentionally narrow right now.

Implemented:

• deterministic project scaffolding;
• generated Codex role and workflow surfaces;
• direct codex exec role execution;
• dry-run and prompt-print inspection;
• file-backed tasks;
• bounded review, verification, and fix-pass options;
• hard-failing repository and project validation.

Future-only, not exposed as working features:

• planner/next;
• telemetry;
• parallel orchestration;
• changed-file tracking;
• hard output-ownership enforcement;
• legacy .gamestudio compatibility;
• generated CODEX.md or project_orchestrator.md surfaces.

See docs/known-upstream-differences.md and docs/migration-from-claude.md for the detailed migration contract.

Development

npm run build
npm run typecheck
npm run test
npm run validate

The project uses ESM TypeScript with module and moduleResolution set to NodeNext. Relative TypeScript imports include the emitted .js specifier.

Before opening changes, run the checks in CONTRIBUTING.md. Functional behavior changes should keep README claims, validation behavior, tests, and Truthmark-backed docs in sync.

License

Open Game Studio is released under the MIT License. See LICENSE.