jgengine
v0.55.0
Published
jgengine — game framework SDK CLI (npm package jgengine / @jgengine/*). Not automotive. Humans: tell a coding agent Make a game that ... with jgengine. Agents: create, skills, doctor, desktop. Skills ship in the package under skills/. https://jgengine.com
Maintainers
Readme
jgengine
Agent-side CLI for the JGengine TypeScript game SDK (@jgengine/* on npm). Not automotive.
Docs: jgengine.com · Source: Noisemaker111/jgengine
Human interface
People don't run this CLI — they tell a coding agent:
Make a game that … with jgengine
Agent quickstart
npx jgengine create "Game Name" # scaffold a playable base + install agent skills into the project
cd Game-Name
# follow the installed `jgengine` skill: intake → foundation + only the domains the game needs → buildThe game is its own project on the published npm packages. Never clone the jgengine GitHub repo to build a game, and never copy code, assets, or content from its games/* directory — those are private in-repo test games, not templates.
Skills ship inside this package under skills/ and are installed into the project by create (recovery: npx jgengine skills -p). They cover intake/routing, world, gameplay, combat, UI, multiplayer, editor authoring, assets, verification, and game/level design.
Commands
| Command | What it does |
| --- | --- |
| create "<Game Name>" | Scaffold playable base + install skills (--from-scene <folder>, --standalone/--in-repo, --no-install, --no-skills, --pm bun\|npm\|pnpm) |
| editor [dir] | Open the standalone 3D scene editor on a folder; Ctrl+S writes editor.scene.json back |
| shoot [...] | Screenshot the current game headless (WebGL-safe) to shots/shot.png (--device, --out, --url, --settle, --timeout, --help); needs Chrome/Chromium |
| drive [...] | Play/test the current game headless — --click/--click-at x,y (CSS viewport pixels)/--key/--wait/--shot steps, --rpc, --playtest --strict; --help for all flags |
Key holds restore focus to the game's keyboard surface after menu clicks and remain held until at least one rendered frame runs, with a bounded grace period for slow headless rendering. shoot and drive always run this CLI's own harness; a game carries no copy, so a newer CLI brings driver fixes.
| desktop [dir] | Ship a Windows NSIS installer for a project or --url; --steam lays out a SteamPipe depot and build scripts from package.json "jgengine": { "steam": { "appId" } }, --steamworks adds the Steam overlay; players pick Match display or Uncapped in Graphics, and <Game>.exe --uncapped forces uncapped |
| skills -p \| -g | Re-install agent skills (project / global) |
| doctor [dir] [--workspace [--json]] | Game diagnostics by default; opt-in aggregate workspace SDK installation checks |
| sync [dir...] [--check] | Bring a game, or a workspace root and its games, to this CLI's engine version and each game's jgengine.json; prints the release notes crossed |
| assets … | List, search, and pull CC0 asset packs (@jgengine/assets) |
| editor-mcp … | Scene-editor agent bridge (document RPC / localhost server) |
| versions | CLI + installed @jgengine/* versions |
doctor resolves default and named Bun workspace catalogs and recognize hoisted SDK installs. Missing catalog entries and corrupt installed metadata fail diagnostics. Reports distinguish installed versions from declared baselines; unavailable migration notes never establish that a project is up to date.
doctor also follows direct installed consumers (including file: links) and SDK dependency/peer edges by real package paths, up to 256 packages. A private SDK copy fails even when its version matches the root copy: identical versions can still own separate module state. The diagnostic names the importer, range, resolved path/version, and canonical project path/version; review the root SDK catalog and linked-consumer declarations, then reinstall from the root and check again. A root install may leave private linked-package installs intact. Doctor reads manifests without requiring a package root export and never changes files. It covers the declared package graph, not custom bundler aliases or indirect non-SDK dependency chains.
Default doctor checks the chosen project's direct consumers and installed SDK graph alongside game diagnostics. For one root installation check, run jgengine doctor --workspace --json after installing at the workspace root. It inspects the root and every declared workspace owner, including shared packages such as studios, and returns an aggregate SDK identity verdict and coverage. This mode does not run game source/render audits. Restart running games after installation so cached modules use the updated paths. Unused catalog packages without a project install are listed as uninspected; required dependencies or peers without an install fail.
Workspace mode supports relative literal directories and terminal directory/* patterns, including Games' * and engine packages/*. It streams at most 4096 directory entries, attempts at most 512 candidate manifests, inspects at most 256 workspace directories and 64 patterns, and retains the bounded SDK graph check per owner. Unsupported patterns, missing/malformed literal manifests, unmatched wildcards, escaped or broken symlinks, and exhausted budgets report incomplete coverage and exit nonzero. Directory aliases deduplicate by real directory; distinct directories sharing a manifest still get separate resolution checks. JSON includes every owner graph, coverage counters, exclusions and errors; the command never installs or changes files.
To move to a new engine release, run npx jgengine@latest sync in a game, or at a workspace root to move the root's Bun catalog pins and every workspace game together. Sync targets the engine version of the CLI that runs it, prints the release notes in between (Migrate steps first, oldest release first), and --check reports without writing. Catalog sync preserves range styles, unrelated text, per-game catalog: declarations, CLI/github versions and an existing root editor override, refuses a downgrade, and rejects a file changed while it planned. It changes declarations only: run bun install at the root, then jgengine doctor --workspace --json to verify installed SDK identities, then rebuild, migrate and verify each game.
Packages
The lockstep SDK set is @jgengine/{core,rapier,ui,ws,node,sql,convex,shell,editor,assets,navbake} — versions move together; see CHANGELOG.md (also importable as typed data from @jgengine/core/meta/changelog).
