Gameverse: npm, make games from the command line

Before you start

You need Node.js version 20 or newer, which comes with npm. To check, open a terminal (Command Prompt, PowerShell, Terminal) and run:

node --version

If it prints a number that starts with 20 or higher, you are ready. If the command is not found, or the number is lower, install the current LTS version from nodejs.org and open a new terminal.

Make your first game in four commands

You do not need to install anything. npx downloads the package the first time and runs it.

Start a game. This makes a folder with a working starter game:
npx gameverse new my-game
Go into it.
cd my-game
Play it while you edit. This opens the game in your browser, in the same sandbox as the website, and reloads it every time you save a file. Edit main.cs in any text editor and watch it change:
npx gameverse dev --open
Build the cartridge. This checks the game and writes my-game.cart, one file you can send to anyone:
npx gameverse pack

Then drop my-game.cart on the home page to play it, send it to a friend, or keep it in your Studio if you are on the Developer plan.

Install it once, then just type `cart`

If you will use it a lot, install it so you can type cart instead of npx gameverse:

npm install -g gameverse

After that, every command on this page works with cart in place of npx gameverse:

cart new my-game

To update to the newest version later, run npm update -g gameverse. To remove it, run npm uninstall -g gameverse.

The commands

Command	What it does
`cart new <name>`	Starts a game in a new folder from the CartScript starter: a manifest, a small working game and a README.
`cart dev`	Plays the game in your browser and reloads it when you save. Compile errors show above the game. Add `--port 8081` to pick a port, `--open` to open the browser for you and `--touch` to show the on-screen D-pad and buttons that phones and tablets get, so you can see how the game feels with them.
`cart check`	Looks for mistakes: the manifest, the entry file, compile errors, blocked features and missing files. It exits with an error if something is wrong, so it also works in scripts. It also gives warnings for things that run but are probably not what you meant (see below). Add `--strict` to make warnings fail too.
`cart run`	Plays the game with no browser, with scripted buttons, and prints what happened. Good for tests.
`cart pack`	Checks the game and builds the `.cart`. Add `--obfuscate` to make the source harder to read (it checks the game behaves identically afterwards).
`cart inspect <file.cart>`	Shows a cartridge's manifest and the files inside it.
`cart unpack <file.cart>`	Extracts a cartridge into a folder, so you can read or change someone's game.
`cart help [command]`	Explains a command.

What is in your game folder

main.cs: the game, written in CartScript.
manifest.json: the title, author, version and the id that names your save slot. Before you share a game, change the id from local.my-game to your own, the reverse of a domain you own, such as com.mystudio.my-game.
README.md: a short guide for the folder.

To use more colors, set colors in the game's config and raise "cartscript" in manifest.json to match: colors: 256 needs "cartscript": 3, colors: 65536 needs 4 and colors: 16777216 needs 5. A named palette such as palette: "gameboy" needs 6, and your own palette (palette: [...]) or set_palette() needs 7. cart check tells you if they do not agree. The spec explains each mode.

Warnings from `cart check`

A game can run perfectly and still have a slip in it. cart check prints a warning, never an error, for three of them, so a warning never stops you from packing or sharing:

Text that runs off the screen. text("A LONG TITLE", 40, 10) is 47 pixels wide, so on a 64-wide screen it ends at 87 and is cut off. The warning says where the text ends and how wide the screen is. It only looks at text and positions written out in full in the code, never at ones worked out while the game runs.
A sprite that is never drawn. A sprite hero [...] with no spr("hero", ...) anywhere is probably left over. (If your game picks sprites by a name it works out, cart check cannot know, so it says nothing.)
rnd() while drawing. Drawing takes random numbers from the same stream as the game's logic, so adding or removing a rnd() in on draw changes every later random number. Use something worked out from frame, such as sin(frame * 7), or numbers made once in on init.

To make warnings fail, which is useful in a script or before you pack, run:

npx gameverse check --strict

It prints the warnings and then exits with an error code if there were any. Without --strict, warnings are only printed.

Test without a browser

cart run plays the game for a number of frames while pressing the buttons you list, then prints variables or the screen. For example, hold right for 20 frames, press A at frame 5, and print score:

npx gameverse run --frames 60 --input "right@0-20,a@5" --state --vars score

Add --dump to print the final screen as text, and --seed 7 to get the same random numbers every time. Games are deterministic, so the same inputs always give the same result.

If something goes wrong

npm: command not found or npx: command not found: Node.js is not installed, or the terminal was open before you installed it. Install it from nodejs.org and open a new terminal.
On Windows PowerShell: “running scripts is disabled on this system”: PowerShell is blocking npm's launcher. Use Command Prompt instead, or allow scripts for your own account with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
EACCES or “permission denied” when installing with -g: Your system does not let npm write to its global folder. Do not use sudo. Use npx gameverse instead, which needs no install, or follow npm's guide to change where global packages go.
cart dev says the port is in use: Another program is using it. It tries the next ports by itself, or you can pick one with --port 8090.
The game says it needs a newer CartScript version: Raise "cartscript" in manifest.json to the number the message names.
No npm at all?: Use the tools download (a zip you run with node), the Playground, or the Pack a cart page, which need no install.

About the package

It has no dependencies: installing it downloads nothing else.
cart dev only listens on your own computer (127.0.0.1), so nobody else on your network can reach it.
The commands read and write only the game folder you point them at.
The package page is npmjs.com/package/gameverse. It is MIT licensed.

Building with an AI agent? Give it the CartScript spec, and see the copy-paste prompt on Make a game.