Docs ▸ Start

gameshipper.json

init writes every field with its default. The main ones:

{
  "name": "Spinning Cube",
  "version": "1.0.0",
  "game": { "dir": ".", "entry": "index.html", "buildCommand": null, "outputDir": null },
  "icon": "icon.png",
  "keyArt": "art/key-art.png",
  "logo": "art/logo.png",
  "targets": ["windows", "mac", "linux"],
  "window": { "width": 1280, "height": 720, "fullscreen": true, "resizable": true },
  "steam": { "appId": 480, "user": null, "sdk": null, "overlay": "auto" },
  "mobile": { "bundleId": null, "orientation": "landscape" },
  "itch": { "project": null },
  "github": { "repo": null },
  "plugins": []
}

Builds start fullscreen when window.fullscreen is true, and always on Steam Deck. npx gameshipper help --json includes the full schema.

Builds package the game folder (game.dir, or game.outputDir when there's a buildCommand) except .env files, .git, .DS_Store, Thumbs.db, steam_appid.txt and the Steamworks SDK anywhere in it, and every dot file and folder at its top; only when the game folder is the project folder itself are the project's own top-level files skipped too (out/, node_modules/, gameshipper.json, gameshipper.lock, CLAUDE.md, AGENTS.md and package-manager lockfiles), so a dist/ folder keeps its own node_modules/ or out/.

Files

Path
`gameshipper.json`	The config. Commit it.
`gameshipper.lock`	The URL and SHA-256 of every downloaded CDN file. Commit it. When a CDN file changes, `build` warns with `CDN_CHANGED` and updates the lock; `--frozen-lock` makes that an error.
`out/<target>/`	The builds.
`out/store/`	The store images; `out/store/screenshots/` holds the screenshots from F12 and `play --screenshot`.
`.sdk/`	Your Steamworks SDK zip. Don't commit it (`init` adds it to `.gitignore`).
`.gameshipper/logs/`	Run logs (the newest 50 of each command), plus the events logs and smoke summaries of `play` runs (the newest 20).
`.gameshipper/last/`	The last result of each command, which `status` reads.
`.gameshipper/check/`	The last `check`: `report.json` and the Deck-size `frame.png`.
`.gameshipper/steam/`	The last `publish` to Steam: the SteamPipe build scripts, and SteamCMD's build logs in `output/`.

Environment variables

Variable
`GAMESHIPPER_CACHE`	Gameshipper's download cache (CDN files, Steamworks SDK libraries, native Steam bridges). Default: the OS's user cache folder.
`GAMESHIPPER_STEAM_SDK`	Your Steamworks SDK zip or folder (see Steam).
`GAMESHIPPER_NPM_REGISTRY`	The npm registry that other OSes' native Steam bridges (`@koromix/koffi-*`) are downloaded from. Default: `npm_config_registry`, then https://registry.npmjs.org. Downloads are checked against pinned hashes.
`GAMESHIPPER_SOFTWARE_GL`	Set to `1` on machines without a GPU, such as hosted CI runners, so games may render WebGL in software. Only `play`, smoke runs and `check` use it: a player's launch of a shipped game ignores it. The `ci init` workflow sets it.
`GAMESHIPPER_MAC_IDENTITY`	The Developer ID Application identity Mac builds are signed with (see Mac signing and notarization). Unset: ad-hoc signing.
`GAMESHIPPER_NOTARY_PROFILE`, `GAMESHIPPER_NOTARY_KEYCHAIN`	The notarytool keychain profile (and, optionally, the keychain holding it) Mac builds are notarized with.
`GAMESHIPPER_NOTARY_KEY`, `GAMESHIPPER_NOTARY_KEY_ID`, `GAMESHIPPER_NOTARY_ISSUER`	For CI instead of a profile: an App Store Connect API key (`.p8` path), its ID and its issuer ID.
`GITHUB_TOKEN`, `GH_TOKEN`	`publish`: a token that can write to the GitHub repository (`GH_TOKEN` is read when `GITHUB_TOKEN` isn't set). The `gh` CLI's login is never used.
`BUTLER_API_KEY`	`publish`: an itch.io API key for butler, for CI, instead of butler's own login.
`GAMESHIPPER_GITHUB_API`	`publish`: the GitHub API to use, for GitHub Enterprise. Default: https://api.github.com.
`GAMESHIPPER_STEAMCMD`, `GAMESHIPPER_BUTLER`	`publish`: a SteamCMD or butler to run instead of the ones Gameshipper downloads.

help --json lists them all under environment. Apple credentials and tokens are only ever read from these variables and your keychain, never from gameshipper.json.

TypeScript

/// <reference types="gameshipper/types" />

This types window.steam and window.gameshipper (both undefined in a normal browser).