# Add tools to an existing game

Add modules without losing custom code, handle conflicts, and validate changes before publishing an update.

Keep a recoverable baseline, inspect the proposed changes, and verify one addition at a time.

<a id="baseline"></a>

## 1. Save a working baseline

Commit your working game or make a separate backup before changing modules. Record what currently passes: lint, build, installed tests, and a short playthrough. Keep `game.config.json`, `.spawn/state.json`, and your lockfile; they describe the generated project and its dependency state.

**Inspect and verify the current project**

```sh
git status --short
pnpm lint
pnpm build
```

If the folder is not a Git repository, use your backup workflow instead of the Git command. Do not delete edited files to make an addition succeed.

<a id="preview"></a>

## 2. Preview a module addition

> **Review before applying**
>
> Use [CLI installation](https://spawnkit.cloud/docs/cli#installation) to run the commands below. A dry run shows files and conflicts before any changes are applied.

**Inspect available modules and proposed changes**

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

The ownership record lets SpawnKit compare the original generated file, the new generated file, and your current file. Compatible JSON fields can be merged; conflicting edits stop the operation. The CLI does not switch renderers through `pnpm dlx @spawnkit/cli add`.

<a id="apply"></a>

## 3. Apply and inspect

**Add tests, then install their dependencies**

```sh
pnpm dlx @spawnkit/cli add vitest
pnpm install
git diff --stat
git diff
```

Review and accept the CLI confirmation before installation. In automation, pass `--yes` only after reviewing a resolved dry run. Review source and configuration changes, not just the file count. Keep your game-specific logic, listing, and user-written `AGENTS.md` instructions. Commit the updated lockfile with the addition. `--yes` accepts a resolved plan; it cannot force an overwrite of conflicting edits.

<a id="conflicts"></a>

## Handle conflicts

| Problem | Safe next step |
| --- | --- |
| Edited file conflicts with the new module | Read the proposed changes, compare against a separate generated project, and merge intentionally. |
| Incompatible selected add-ons | Inspect `pnpm dlx @spawnkit/cli addons` and the dry run. Use `--replace <names>` only when you intend to replace those components. |
| Missing or unsupported ownership record | Run the command from your generated project root. Do not fabricate or edit `.spawn/state.json`. |
| Different renderer desired | Create a new project and port game logic and assets deliberately. |

**Create a comparison project in a new directory**

```sh
pnpm dlx @spawnkit/cli init comparison-game --add phaser,vitest --dry-run
pnpm dlx @spawnkit/cli init comparison-game --add phaser,vitest
```

Choose your actual renderer and modules; the example uses Phaser. The destination must not already exist. A comparison project is a reference, not a replacement for the original.

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

## 4. Verify and release

**After adding the Vitest module**

```sh
pnpm lint
pnpm test
pnpm build
pnpm preview
```

Play through existing behavior and the feature you changed. If the checks pass, review the diff and save the new baseline. Follow [Publishing an update](https://spawnkit.cloud/docs/publishing-examples#updates) to target the same hosted project.

If the addition fails verification, preserve any new work before restoring your known-good baseline. Reinstall from the restored lockfile and repeat the checks. Hosted rollback is a separate operation; it restores retained release artifacts and does not undo database migrations.