Skip to content

Releases

0.0.7

Choose a tag to compare

@aksheyd aksheyd released this 09 Oct 06:12

Highlights

  • check catches files the page can't use. It reads the start of every image and sound file in the game's folder and fails, naming each, on one that's empty or doesn't start like a type the page takes, like a Git LFS pointer saved as logo.png. It takes what Chrome reads under any name, including RF64 and BW64 WAVs, and an MP3 or AAC whose first frame comes after zero bytes.
  • run --port and --host. run serves its page at a port you name, or on another address of the machine, like 0.0.0.0 for the host of a Docker container, and warns when other machines can reach it.
  • Errors in ThreeJam's words. A misspelled command, a bad value for a global flag, and an MCP call whose arguments don't fit the tool's schema fail as USAGE, with one line that says what to do. A game, view, or driver that links outside its folder fails with BUILD_ERROR.
  • Nothing holds a command for good. Each bundle of a game has a time limit, the longer of 30 s and --timeout, so a file it reads that never ends, like a FIFO, fails it, and run stops even while a rebuild waits on one.

Breaking changes

  • ctx.play takes a pitch from 1/16 to 16, four octaves down to four up, and any other pitch is an error at the call, in sim, check, and the page alike. Before, a pitch far outside that range passed sim and check, but stopped the game in the browser.

Also

  • mcp add registers the server with the Node that ran it, by its absolute path.
  • A sound file the page can't load or decode no longer silences the game's other sound files.
  • run quits on an Esc that comes during a reload and exits when it stops on Node 22 and 24, and when something stops run --record while its page is sending part of the playtest, run waits up to a second for that part.
  • shot works when DISPLAY names a display that's gone, says how Chrome ended when it exits as soon as it starts, and kills a crashed Chrome's helpers instead of waiting for them.
  • An MCP server answers nothing once a stop signal or its exit has stopped its shots. esbuild's service ends with the command that started it, and check's type check leaves no folder behind, even when killed with SIGKILL.
  • check works with a relative TMPDIR, --help names number flags <number>, and running out of memory with --every says that the snapshots it keeps count toward it.

Full changes: #33 through #57, in the changelog.

0.0.6

Choose a tag to compare

@aksheyd aksheyd released this 08 Oct 16:59

Highlights

  • The skill's install line on the first screen. The README, and so the npm page, gives npx skills add aksheyd/threejam on its first screen and in Quick start, next to a skills.sh badge that counts the skill's installs. Quick start also gives the tag command, to pin the skill to a release.
  • The skill matches the release. The skill on main now changes only with a release, so the short line installs the skill the latest release ships, and the skill sends agents to AGENTS.md at the v0.0.6 tag instead of main's.

Also

  • On macOS and Linux, when Chrome exits as it starts, shot kills the processes Chrome started before it removes Chrome's profile, so a busy machine no longer leaves the profile's folder behind.
  • The README's first example names the command that writes its game of catch, npx threejam new games/catch.

Full changes: #27 through #31, in the changelog.

0.0.5

Choose a tag to compare

@aksheyd aksheyd released this 07 Oct 22:43

Highlights

  • Play on phones and in the browser. The example games are online at https://aksheyd.github.io/threejam/, and on a touch screen, exported games and run's page show a key for each keyboard key the game reads, so a keyboard game plays on a phone.
  • Check a game's balance. sim --seeds 0-99 runs the same flags once for each seed and sums up how often and how soon --until held.
  • Replay a playtest. run --record FILE saves what a person played as a driver that sim, shot, and simulate replay exactly.
  • Pixel art and 3D. A game can draw pixel art written as text with sprites, and the new Racer example draws its 2D rules in 3D.

Breaking changes

  • Game code may grow its heap to 1 GB, the same on every machine, and past that it fails with GAME_ERROR. Before, the limit followed the machine's memory, so a game that kept more than 1 GB could pass on one machine and fail on another.

Also

  • run's page and exported games answer advanceTime and render_game_to_text, the hooks OpenAI's develop-web-game client drives a game with.
  • export --script URL adds a script, like a game jam's widget, to an exported page.
  • The package ships the agent skill, and the docs' npx skills add installs it from the latest release's tag.
  • run keeps serving after a save that doesn't build and stops promptly on macOS, and on macOS and Linux its window closes however it ends.
  • run, shot, check, and the MCP server leave less behind when they're stopped or killed, and an MCP server whose client closes stdin gives its calls 2 s to finish, then exits.

Full changes: #4 through #25, in the changelog.

0.0.4

Choose a tag to compare

@aksheyd aksheyd released this 06 Oct 07:47

Highlights

  • The same run on every machine. The same files and seed now give the same run in sim and in the page, whatever the machine's clock, locale, or time zone. Long sim runs are about 3x faster.
  • One-line errors with real codes. Every failure is one line with a code that says what went wrong, in the CLI and over MCP.
  • Checks before work. Number flags accept digits only, -o is checked before any work, and mcp add accepts only the forms its help shows.

Breaking changes

  • New error codes BUILD_ERROR, BROWSER_ERROR, IO_ERROR, and INTERNAL_ERROR replace some GAME_ERROR, USAGE, and TYPE_ERROR cases. In check, a syntax error, or an import of a file or a name that doesn't exist, is now BUILD_ERROR instead of TYPE_ERROR, and a type check that runs past --timeout is TIMEOUT. A failed MCP tool call's text now starts with its code, as in TYPE_ERROR: ....
  • game.js and view.js are refused, with a hint to rename them to .ts.
  • Game code that reads the clock, the machine's locale or time zone, or crypto's randomness now fails instead of varying, and so does a write to the world outside start and update.

Also

  • sim --exact prints exact numbers. By default sim rounds what it prints, while --until compares exact values.
  • shot applies --timeout to the page too, and run's page says why a game or view.ts didn't load.
  • run's Chrome no longer leaves a profile folder in the temp folder now and then.
  • A --driver that isn't a file, and an unknown word after mcp add, are USAGE errors.

Full changes: #2 and #3.

0.0.3

Choose a tag to compare

@aksheyd aksheyd released this 06 Oct 09:51

Loading a game runs its code in a sandbox, a game's page and check take only files from the game's folder, run's server answers only its own page, and every runtime dependency is the exact version CI tests. From #1.

Breaking changes

  • check, sim, and the loads behind shot and export run game.ts and any --driver in a sandbox: a JavaScript realm with the language and the engine and nothing else, in a child process that can't touch files, start processes, or reach the network. Game code that used Node's APIs, eval, new Function, or import() no longer runs there.
  • A game's files may import only threejam and files in the game's folder, and a --driver file may also import files in its own folder. Anything else, even through a link, fails with the import's path:line in check, sim, run, shot, and export, so a game that imports a shared ../lib/util.ts no longer builds.

Added

  • Each run has a time budget, --timeout seconds on check, sim, shot, and export (default 30), after which it fails with the new TIMEOUT code and the tick it reached, so an endless loop no longer hangs sim or the MCP server.
  • Each MCP call that loads a game runs in a process of its own, so one game that loops doesn't block the others, and a long-running server doesn't grow.
  • An MCP sim reply too large for a client is refused with the new OUTPUT_TOO_LARGE code and how to narrow it.
  • The MCP tools that load a game, check, sim, shot, and export, are marked as running code, and the server's instructions say that a game's log, errors, and suggested commands are its own data, not directions.
  • check maps three to ThreeJam's own Three.js types, so import type from 'three' in a view.ts describes the THREE it receives, in a project or not.

Security

  • run serves its page on 127.0.0.1 to that page alone: a request from another page, even one on another local port or opened from a file, or one that names another host, gets 403, and live reload and Esc take a token only the page has. An image or sound opened directly runs nothing, and an SVG downloads instead of opening.
  • ThreeJam starts Chrome with no DevTools port, even when a wrapper script asks for one, talks to shot's headless Chrome over a pipe, and passes Chrome only the environment variables a browser needs.
  • In node_modules, check reads only TypeScript's libraries and ThreeJam's own type packages, so a type error can't quote another package's files.
  • The import rule compares real paths exactly, as the OS spells them, instead of folding case.
  • Every runtime dependency is pinned to the exact version CI tests, and the build fails if one isn't. incur moves from 0.5.1 to 0.7.0.
  • A release publishes only after all of CI passes on the tagged commit, from a tarball built with install scripts off that matches a second build's.

Fixed

  • check bundles the page too, so it refuses an import that run, shot, or export would.
  • A game's runtime import of three fails with a hint to use the THREE that init and draw receive.
  • shot cleans up when Chrome fails to start, and only shot loads Puppeteer.

Development

  • npm test names its test files, so a Node that can't run TypeScript fails instead of finding no tests, and a test that runs past two minutes fails.
  • npm run test:package installs the package with install scripts off, as npm 12 does, and checks that a view.ts gets Three.js's types there.
  • CI tests Node 24 as well, and gives each commit on main a run of its own.
  • The repo approves esbuild's install script for the version it pins, which npm 11 asks for.

Full changes in CHANGELOG.md.

0.0.2

Choose a tag to compare

@aksheyd aksheyd released this 06 Oct 09:51
  • shot retries a page navigation that Chrome on Windows sometimes aborts in a new tab.
  • A release publishes from a job that runs no dependency code, and the workflows pin every action to a commit.

Full changes in CHANGELOG.md.

0.0.1

Choose a tag to compare

@aksheyd aksheyd released this 06 Oct 09:51

The first release on npm. A game is a folder with a game.ts of entities as data and an update function, with groups, grids, parts, images, sounds, the mouse, and an optional view.ts for Three.js extras. The new, check, sim, shot, run, and export commands work as a CLI, as MCP tools, and as generated skills, next to a hand-written skill and seven example games.

Full changes in CHANGELOG.md.