Repository navigation
Releases
Releases · aksheyd/threejam
0.0.7
Highlights
checkcatches 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 aslogo.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 --portand--host.runserves its page at a port you name, or on another address of the machine, like0.0.0.0for 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 withBUILD_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, andrunstops even while a rebuild waits on one.
Breaking changes
ctx.playtakes apitchfrom 1/16 to 16, four octaves down to four up, and any other pitch is an error at the call, insim,check, and the page alike. Before, a pitch far outside that range passedsimandcheck, but stopped the game in the browser.
Also
mcp addregisters 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.
runquits on an Esc that comes during a reload and exits when it stops on Node 22 and 24, and when something stopsrun --recordwhile its page is sending part of the playtest,runwaits up to a second for that part.shotworks whenDISPLAYnames 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. checkworks with a relativeTMPDIR,--helpnames number flags<number>, and running out of memory with--everysays that the snapshots it keeps count toward it.
0.0.6
Highlights
- The skill's install line on the first screen. The README, and so the npm page, gives
npx skills add aksheyd/threejamon 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
mainnow changes only with a release, so the short line installs the skill the latest release ships, and the skill sends agents toAGENTS.mdat thev0.0.6tag instead of main's.
Also
- On macOS and Linux, when Chrome exits as it starts,
shotkills 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.
0.0.5
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-99runs the same flags once for each seed and sums up how often and how soon--untilheld. - Replay a playtest.
run --record FILEsaves what a person played as a driver thatsim,shot, andsimulatereplay 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 answeradvanceTimeandrender_game_to_text, the hooks OpenAI'sdevelop-web-gameclient drives a game with.export --script URLadds a script, like a game jam's widget, to an exported page.- The package ships the agent skill, and the docs'
npx skills addinstalls it from the latest release's tag. runkeeps 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.
0.0.4
Highlights
- The same run on every machine. The same files and seed now give the same run in
simand in the page, whatever the machine's clock, locale, or time zone. Longsimruns 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,
-ois checked before any work, andmcp addaccepts only the forms its help shows.
Breaking changes
- New error codes
BUILD_ERROR,BROWSER_ERROR,IO_ERROR, andINTERNAL_ERRORreplace someGAME_ERROR,USAGE, andTYPE_ERRORcases. Incheck, a syntax error, or an import of a file or a name that doesn't exist, is nowBUILD_ERRORinstead ofTYPE_ERROR, and a type check that runs past--timeoutisTIMEOUT. A failed MCP tool call's text now starts with its code, as inTYPE_ERROR: .... game.jsandview.jsare 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 outsidestartandupdate.
Also
sim --exactprints exact numbers. By defaultsimrounds what it prints, while--untilcompares exact values.shotapplies--timeoutto the page too, andrun's page says why a game orview.tsdidn't load.run's Chrome no longer leaves a profile folder in the temp folder now and then.- A
--driverthat isn't a file, and an unknown word aftermcp add, areUSAGEerrors.
0.0.3
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 behindshotandexportrungame.tsand any--driverin 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, orimport()no longer runs there.- A game's files may import only
threejamand files in the game's folder, and a--driverfile may also import files in its own folder. Anything else, even through a link, fails with the import'spath:lineincheck,sim,run,shot, andexport, so a game that imports a shared../lib/util.tsno longer builds.
Added
- Each run has a time budget,
--timeoutseconds oncheck,sim,shot, andexport(default 30), after which it fails with the newTIMEOUTcode and the tick it reached, so an endless loop no longer hangssimor 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
simreply too large for a client is refused with the newOUTPUT_TOO_LARGEcode and how to narrow it. - The MCP tools that load a game,
check,sim,shot, andexport, 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. checkmapsthreeto ThreeJam's own Three.js types, soimport typefrom'three'in aview.tsdescribes theTHREEit receives, in a project or not.
Security
runserves its page on127.0.0.1to 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,checkreads 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
checkbundles the page too, so it refuses an import thatrun,shot, orexportwould.- A game's runtime import of
threefails with a hint to use theTHREEthatinitanddrawreceive. shotcleans up when Chrome fails to start, and onlyshotloads Puppeteer.
Development
npm testnames 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:packageinstalls the package with install scripts off, as npm 12 does, and checks that aview.tsgets 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
shotretries 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
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.