# Extend your game

Add mechanics, replace artwork, and evolve your project without losing the work you already have.

Find the right files, make a focused change, and check it in a playable build.

<a id="get-oriented"></a>

## Understand your project

A downloaded SpawnKit game is a standalone project. You can work on it with your editor and the packages it already includes; you do not need the SpawnKit repository.

- Read `AGENTS.md` for the project's instructions.
- Check `package.json` for the installed engine, dependencies, and scripts.
- Read `game.config.json` for the original kit configuration.
- Start at `src/main.ts`, then follow its imports into the game logic.

Before a larger change, save a Git commit or copy your game folder to a separate backup location. Keep existing artwork, saves, and local configuration. For generated tools, use [Add tools and modules](https://spawnkit.cloud/docs/updating); for verification, see [Testing and debugging](https://spawnkit.cloud/docs/testing).

<a id="change-the-game"></a>

## Build one playable change at a time

Choose a small outcome you can test: a new collectible, a different movement speed, an obstacle, or a score display. Use the rendering engine already installed in the project.

1. Run `pnpm dev` and establish that the current game works.
2. Make the smallest change that produces the behavior you want.
3. Try it in the browser with real input, including its failure or reset state.
4. Run the project's checks, then save that working version before the next change.

> **Adding assets**
>
> Put static assets in `public/` and reference them using their browser path. For example, `public/art/player.png` is served at `/art/player.png`. Check file sizes before shipping large textures or audio.

<a id="add-modules"></a>

## Add tools that fit your stack

Use the [kit builder](https://spawnkit.cloud/templates) to explore supported rendering, physics, UI, and testing combinations. The [versioned catalog](https://spawnkit.cloud/catalog/v1.json) exposes those same compatibility rules for agents and tools.

A new kit download is a separate project, not an update to your existing folder. Compare its configuration and source before moving changes across. Physics kits provide example scenes you can extend, rather than finished controllers for every genre.

> **Keep browser code public**
>
> Anything bundled into a game can be inspected by players. Keep credentials out of source files, static assets, and `VITE_` environment variables.

<a id="verify-changes"></a>

## Check the result

**Terminal · core checks**

```sh
pnpm lint
pnpm build
```

Run `pnpm test` and `pnpm e2e` if those scripts exist in `package.json`. Tests prepare Chromium automatically when they start. See [Test environment setup](https://spawnkit.cloud/docs/testing#browser-setup) for CI and setup troubleshooting.

- Exercise keyboard, pointer, and touch controls that your game claims to support.
- Check the game at a narrow phone size and a wide desktop size.
- Reload and check any saved progress.
- Test the built game with `pnpm preview`, using the address printed in the terminal.

<a id="cli-modules"></a>

## Add modules with @spawnkit/cli

Inspect the available commands for your installed version. Preview a change before applying it.

**Terminal · inspect and preview**

```sh
pnpm dlx @spawnkit/cli add --help
pnpm dlx @spawnkit/cli addons --json
pnpm dlx @spawnkit/cli add vitest --dry-run --json
```

Review the plan for dependencies, files, and conflicts. Apply a resolved plan only when it matches the change you want. The generator protects modified files; if it reports a conflict, compare the affected files and resolve it explicitly.

Keep `.spawn/state.json`. It records the generator's file baseline; deleting it or replacing edited files to force an update removes that protection. Existing `AGENTS.md` instructions are preserved during module additions.