|
|
|
@@ -1,41 +1,75 @@
|
|
|
|
|
# Open GameStudio
|
|
|
|
|
# Open Game Studio
|
|
|
|
|
|
|
|
|
|
Codex Game Studio is a Node/TypeScript CLI package for creating and managing local, Codex-assisted game projects. It provides project scaffolding, engine-aware Codex context, role prompts, reusable templates, file-backed tasks, and validation gates that keep generated project artifacts predictable.
|
|
|
|
|
[](LICENSE)
|
|
|
|
|
[](package.json)
|
|
|
|
|
[](tsconfig.json)
|
|
|
|
|
|
|
|
|
|
The package is a Codex-native workflow layer for game making. It keeps project state local and inspectable under `.codex/`, invokes `codex exec` by default for role-specific work, and uses `--dry-run` or `--print-prompt` for non-executing inspection.
|
|
|
|
|
Open Game Studio is a Codex-native command line studio for making games with AI agents without hiding the workflow in a black box.
|
|
|
|
|
|
|
|
|
|
## Why This Exists
|
|
|
|
|
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`.
|
|
|
|
|
|
|
|
|
|
Open GameStudio started as a port motivated by a simple need: make the game-studio workflow open, portable, local-first, scriptable, and usable outside a single assistant environment.
|
|
|
|
|
```sh
|
|
|
|
|
npm run init -- --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \
|
|
|
|
|
--concept "A compact puzzle game about routing trains through haunted switchyards"
|
|
|
|
|
|
|
|
|
|
Claude Game Studio deserves real kudos for proving that role-based game-development workflows can be practical and useful. Open GameStudio is inspired by that idea, but it is an independent implementation with different priorities:
|
|
|
|
|
node dist/cli.js run producer --project projects/signal-cartographer \
|
|
|
|
|
"Create the initial market overview."
|
|
|
|
|
|
|
|
|
|
- CLI and package first, with deterministic npm scripts for local development.
|
|
|
|
|
- Codex-native by default, with direct `codex exec` integration for role-specific work.
|
|
|
|
|
- Generated game projects live under `projects/<slug>/`.
|
|
|
|
|
- Engine configs, templates, and base agents are package assets.
|
|
|
|
|
- Validation is explicit and hard-failing instead of advisory.
|
|
|
|
|
- Prompt packets are optimized for Codex and execute by default through `run <role>`.
|
|
|
|
|
- Telemetry, planner/`next`, ownership enforcement, changed-file tracking, and parallel orchestration are future-only.
|
|
|
|
|
npm run validate -- --project projects/signal-cartographer
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The goal is not to clone another tool. The goal is to make the workflow contract inspectable, portable, and easy to run in normal developer tooling.
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
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 for normal execution and repository validation.
|
|
|
|
|
- Codex CLI available on `PATH` for normal `run <role>` execution and full validation.
|
|
|
|
|
|
|
|
|
|
## Install
|
|
|
|
|
## Install from source
|
|
|
|
|
|
|
|
|
|
For package use after installation or linking:
|
|
|
|
|
```sh
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm exec open-gamestudio -- --help
|
|
|
|
|
npm exec open-gamestudio -- templates list
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For local development from this repository, use the npm scripts. They build first and then exercise the built CLI through `node dist/cli.js`:
|
|
|
|
|
For local development from this checkout, prefer the npm scripts. They build first and exercise the built CLI through `node dist/cli.js`:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive
|
|
|
|
@@ -44,106 +78,150 @@ npm run templates -- list
|
|
|
|
|
npm run validate -- --project projects/my-game
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
## Quick start
|
|
|
|
|
|
|
|
|
|
Create a project:
|
|
|
|
|
### 1. Create a project
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive --concept "A compact puzzle game about routing trains"
|
|
|
|
|
npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive \
|
|
|
|
|
--concept "A compact puzzle game about routing trains"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Inspect project status:
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run manage -- --project projects/my-game
|
|
|
|
|
node dist/cli.js resume --project projects/my-game
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
List templates:
|
|
|
|
|
`status` and `resume` are read-only. `freeze` is the explicit command that changes project status.
|
|
|
|
|
|
|
|
|
|
### 3. Choose a template or workflow
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Show a template:
|
|
|
|
|
Workflow shortcuts render prompts only. They do not launch Codex.
|
|
|
|
|
|
|
|
|
|
### 4. Run a studio role through Codex
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run templates -- show gdd
|
|
|
|
|
npm run build --silent
|
|
|
|
|
node dist/cli.js run producer --project projects/my-game \
|
|
|
|
|
"Create the initial market overview."
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Validate the repository or a generated project:
|
|
|
|
|
Want to see exactly what Codex will receive first?
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run validate
|
|
|
|
|
npm run validate -- --project projects/my-game
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Run a project agent through Codex:
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run build --silent
|
|
|
|
|
node dist/cli.js run producer --project projects/my-game "Create the initial market overview."
|
|
|
|
|
```
|
|
|
|
|
## Commands
|
|
|
|
|
|
|
|
|
|
Inspect the generated prompt packet without executing Codex:
|
|
|
|
|
| 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. |
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
node dist/cli.js run producer --project projects/my-game "Create the initial market overview." --dry-run
|
|
|
|
|
```
|
|
|
|
|
## Studio roles
|
|
|
|
|
|
|
|
|
|
The `run` command writes a bounded prompt packet and immediately invokes `codex exec` in the project root. The packet inlines the generated project role prompt from `.codex/prompts/<role>.md` and only the package templates selected for that role and task. `--fix` uses the same generated role prompt and selected templates as the primary implementation prompt. Use `--dry-run` or `--print-prompt` when you want to inspect the exact Codex context first.
|
|
|
|
|
Open Game Studio ships a Codex-native role roster with hyphenated IDs:
|
|
|
|
|
|
|
|
|
|
`--allow-broad-context` adds bounded project artifact discovery for existing files such as the GDD, production timeline, market overview, `AGENTS.md`, and `.codex/studio.json`; it does not recursively load every prompt, workflow, or template.
|
|
|
|
|
| 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` |
|
|
|
|
|
|
|
|
|
|
## CLI Commands
|
|
|
|
|
Legacy underscore role IDs are intentionally rejected. `narrative-designer` is a first-class story and content owner.
|
|
|
|
|
|
|
|
|
|
- `init` / `new`: create a project under `projects/<slug>/`.
|
|
|
|
|
- `status`: print project phase, status, engine, and next validation command.
|
|
|
|
|
- `resume`: print a read-only continuation summary.
|
|
|
|
|
- `freeze`: mark a project as frozen.
|
|
|
|
|
- `validate`: run repository or project validation and exit nonzero on failure.
|
|
|
|
|
- `templates list`: list packaged template IDs.
|
|
|
|
|
- `templates show <template-id>`: print a packaged template.
|
|
|
|
|
- `run <role>`: prepare one bounded Codex prompt packet for a studio role and invoke `codex exec` by default.
|
|
|
|
|
- `task create` / `task run`: manage file-backed `.codex/tasks.json` tasks.
|
|
|
|
|
- `review`, `ship-check`: render existing baseline Codex workflow prompts.
|
|
|
|
|
- `market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, `handoff`: render workflow prompts only; these shortcuts do not launch Codex.
|
|
|
|
|
|
|
|
|
|
## Studio Roles
|
|
|
|
|
|
|
|
|
|
The Codex-native role roster is `studio-orchestrator`, `producer`, `market-analyst`, `data-scientist`, `creative-director`, `senior-game-designer`, `game-designer`, `narrative-designer`, `game-feel-designer`, `gameplay-programmer`, `engine-programmer`, `tools-programmer`, `senior-game-artist`, `technical-artist`, `ui-ux-designer`, `qa-playtester`, and `release-manager`.
|
|
|
|
|
|
|
|
|
|
This preserves Claude Game Studio functional coverage without legacy underscore role IDs. `narrative-designer` remains a first-class Codex-native story/content owner.
|
|
|
|
|
|
|
|
|
|
Supported aliases remain intentional: `new` is an alias for `init`, and registered workflow shortcuts render their prompts. Unsupported upstream or legacy underscore role IDs are rejected.
|
|
|
|
|
|
|
|
|
|
## Project Layout
|
|
|
|
|
## What gets generated
|
|
|
|
|
|
|
|
|
|
Repository assets:
|
|
|
|
|
|
|
|
|
|
- `src/`: TypeScript CLI implementation.
|
|
|
|
|
- `src/roles.ts`: Codex role packages compiled into the CLI.
|
|
|
|
|
- `templates/`: reusable document and setup templates.
|
|
|
|
|
- `templates/`: reusable design, production, art, QA, release, analytics, and engine templates.
|
|
|
|
|
- `engine_configs/`: engine overlays for Godot, Unity, and Unreal.
|
|
|
|
|
- `docs/`: setup, migration, validation, and example notes.
|
|
|
|
|
- `docs/`: migration, validation, truth, and compatibility notes.
|
|
|
|
|
- `tests/`: Vitest coverage for project workflow, templates, agents, runner prompts, validation, and engine behavior.
|
|
|
|
|
|
|
|
|
|
Generated project artifacts:
|
|
|
|
|
Project artifacts:
|
|
|
|
|
|
|
|
|
|
- `projects/<slug>/`: the project root created by `init`.
|
|
|
|
|
- `projects/<slug>/`: generated project root.
|
|
|
|
|
- `AGENTS.md`: primary generated Codex project instructions, owned by `src/agents.ts`.
|
|
|
|
|
- `.codex/studio.json`: authoritative project metadata and workflow state.
|
|
|
|
|
- `.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.
|
|
|
|
|
- `documentation/`: generated game-design and workflow documents.
|
|
|
|
|
- `.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 include deterministic freshness metadata and rendered-body hashes. Project validation checks new generated surfaces for stale registry inputs or manual body tampering, and reports legacy generated files without metadata as regeneration-needed skip diagnostics rather than silently treating them as fresh.
|
|
|
|
|
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`](docs/known-upstream-differences.md) and [`docs/migration-from-claude.md`](docs/migration-from-claude.md) for the detailed migration contract.
|
|
|
|
|
|
|
|
|
|
## Development
|
|
|
|
|
|
|
|
|
|
Use the repository scripts:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run build
|
|
|
|
|
npm run typecheck
|
|
|
|
@@ -151,8 +229,10 @@ npm run test
|
|
|
|
|
npm run validate
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This project uses ESM TypeScript with `module` and `moduleResolution` set to `NodeNext`. Relative TypeScript imports include the emitted `.js` specifier.
|
|
|
|
|
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`](CONTRIBUTING.md). Functional behavior changes should keep README claims, validation behavior, tests, and Truthmark-backed docs in sync.
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
Open GameStudio is released under the MIT License. See `LICENSE`.
|
|
|
|
|
Open Game Studio is released under the MIT License. See [`LICENSE`](LICENSE).
|
|
|
|
|
MerlinH