Hopkit / Reference

Create a game

Create a portable Hopkit game from the local initializer, then use npm, pnpm or Bun.

The initializer gives you a playable Pocket Harvest project, editable game rules, local runtime dependencies, and a ZIP exporter.

Hopkit’s packages are unpublished. These commands use a local Hopkit checkout; they do not depend on a public npm release. The repository requires Node.js 24+ and its pinned pnpm 12. Generated games can use npm, pnpm or Bun as a package manager.

If you want the tutorial game instead, download a runnable checkpoint. It already contains the same portable runtime dependencies.

Create the folder

From the Hopkit checkout, install its pinned dependencies once:

pnpm install --frozen-lockfile

Choose the package manager for the new game. The initializer creates a new folder and installs its dependencies. It refuses to overwrite an existing destination.

npm

npm commands

pnpm create:game ../my-game --package-manager npm
cd ../my-game
npm run dev

pnpm

pnpm commands

pnpm create:game ../my-game --package-manager pnpm
cd ../my-game
pnpm run dev

Bun

Bun commands

pnpm create:game ../my-game --package-manager bun
cd ../my-game
bun run dev

Open the local URL printed by Vite. Collect gems and avoid the bees. Start, pause, retry, sound, and hold controls live inside the canvas. Use Tab to select a canvas button, then Enter or Space to activate it. The source works outside the Hopkit checkout. The generated scripts run build and export under Node.js; Bun package-manager support is separate from Bun runtime support.

Find the parts you own

File	What to change
`src/game.ts`	The main game loop and model
`src/rules.ts`	Speed, collection, damage, and the win condition
`src/presentation.ts`	Declared art and sound, sprite bindings, and catch feedback
`src/controls.ts`	Canvas HUD, start, pause, retry, and hold controls
`src/records.ts`	Validated local best-score storage
`src/game/systems/`	Optional installed recipe source
`public/`	Artwork, sound, and their notices

Change one rule, play again, and keep the result you like. The first-game guide uses a different small game to explain movement, jumping and saves.

Check and export

npm

npm commands

npm run check
npm run export

pnpm

pnpm commands

pnpm run check
pnpm run export

Bun

Bun commands

bun run check
bun run export

check runs lint, formatting, types, tests and a production build. export builds, checks the output, and writes a ZIP under exports/. It uploads nothing. Build and export covers production testing and hosting paths.

Keep the game portable

Commit the game’s source, the lockfile made by your chosen manager, and all of .hopkit/. That directory includes the runtime packages under .hopkit/vendor/ and the local recipe snapshot. Keep the vendor packages’ dist folders even if you ignore your game’s root dist/ output.

Use a fresh install and build to check a new checkout. A runtime snapshot does not update itself. Recipe updates show diffs and stop on customized files.

Initializer options

Option	Behavior
`--package-manager npm\|pnpm\|bun`	Select the generated project’s installer
`--no-install`	Write the project without downloading dependencies
`--dry-run`	Print the plan without writing files or installing
`--no-agent-skill`	Omit optional project-local agent guidance
`--registry 'https://trusted-host/r/{name}.json'`	Configure a trusted alternate registry

A failed install keeps the generated source so you can fix the problem and retry. The optional agent skill belongs to the project; the initializer installs nothing globally. Keep the starter and third-party license notices.