Pokemon Auto Chess: local setup, services, and deployment constraints

What Pokemon Auto Chess changes about the auto-battler formula

Pokemon Auto Chess combines the positioning and match-based progression of an auto-battler with Pokémon characters, types and synergy data. The project describes itself as an open-source, non-profit game made by fans for fans. That framing is important for evaluation. It is a complete community game rather than a general-purpose auto-chess engine intended to be embedded into an unrelated product.

The repository is primarily TypeScript and contains application code, client and server build configuration, asset tooling, database command data, deployment documentation and production container files. According to `package.json`, the client is built with a custom `esbuild.js` pipeline, while the server is compiled with TypeScript. The application also uses precomputed game data, meaning some rules are prepared outside the normal server request path.

This design serves players who want access to the specific Pokémon auto-chess implementation and contributors who want to modify its characters, synergies or game content. It does not solve the broader problem of building a generic chess-like simulation library. The repository includes Pokémon-related intellectual property concerns, and the project description explicitly reserves rights to The Pokemon Company. Its fan-made status therefore limits how it should be considered for redistribution or commercial use.

Pokemon Auto Chess client, server, and precomputed data flow

The documented setup separates the game into client assets, a server application, persistent MongoDB data and Firebase Authentication. The README says assets are packed from `public/src/assets` into `public/dist/client/assets` by `npm run assetpack`. A content change under the source asset directory therefore requires an asset-packing step rather than being picked up automatically by the development server.

The `npm run dev` command runs `dev-client` and `dev-server` in parallel. The client script invokes `node esbuild.js --dev`, while the server script watches `./app/index.ts` through `tsx`. The resulting development environment is documented at `http://localhost:9000/`. This is useful for inspecting the game and modifying code, but the README explicitly says the development server is not optimized for production.

MongoDB stores persistent game data. Authentication is separate: Firebase lets players create accounts and log in, while Firebase server credentials allow the application to connect as an administrator. Bot play also has a database dependency. The instructions require a `dev` database with an empty `botv2` collection, followed by an import of `./db-commmands/botv2.json` through MongoDB Compass. The spelling of `db-commmands` is repository-specific and should be preserved when locating that file.

Pokemon and synergy changes have another constraint. The README says the game uses precomputed data in `app/models/precomputed` and requires `npm run precompute` after relevant data changes. That makes the content pipeline explicit: change source data, recompute derived values, then build or run the application as appropriate.

Installing Pokemon Auto Chess for the first local launch

The README recommends Node LTS and `nvm`, but `package.json` gives a stricter runtime contract: Node.js `>=24.19.0` and npm `>=10.8.1`. The repository's `Dockerfile` uses `node:24.19.0-alpine`, which is a concrete reference for matching the build environment. A generic older LTS installation may not satisfy the declared engine requirement.

After cloning the repository and selecting the required Node.js version, install the dependencies with the documented command. This resolves the packages recorded in `package-lock.json` and runs the project's configured lifecycle behavior.

npm install

Next, fetch the separate music repository and pack the game assets. These are distinct from the normal dependency installation.

npm run download-music
npm run assetpack

The first command downloads music through `degit` into `app/public/src/assets/musics`. The second command generates the packed client assets. After both steps complete, create the `.env` file at the repository root and add the MongoDB URI. For a local MongoDB setup, the README gives this exact example.

MONGO_URI=mongodb://localhost:27017/dev

The database itself must contain a database named `dev` and an initially empty collection named `botv2`. Import `./db-commmands/botv2.json` into that collection if bot matches are required. Omitting this import may leave the account and game interface available while leaving bot-based play without its documented data.

Create a Firebase project and web application next. Add the web SDK values to `.env` exactly as separate environment entries. The README limits the enabled sign-in methods to mail/password and anonymous authentication.

FIREBASE_API_KEY=<firebase_api_key>
FIREBASE_AUTH_DOMAIN=<firebase_auth_domain>
FIREBASE_PROJECT_ID=<firebase_project_id>
FIREBASE_STORAGE_BUCKET=<firebase_storage_bucket>
FIREBASE_MESSAGING_SENDER_ID=<firebase_messaging_sender_id>
FIREBASE_APP_ID=<firebase_app_id>

The server also needs the service-account identity fields. These are not equivalent to the public Firebase web configuration. The private key is sensitive and should not be committed to the repository.

FIREBASE_CLIENT_EMAIL=<client_email>
FIREBASE_PRIVATE_KEY=<private_key>

Start both development processes with the documented script. The expected local URL is port 9000.

npm run dev

Open `http://localhost:9000/` and verify that account registration or login reaches Firebase and that the server can read MongoDB. If either service is configured incorrectly, the first useful checks are the browser authentication flow, the Firebase service-account values and the MongoDB connection URI.

Docker deployment for Pokemon Auto Chess and its bundled MongoDB

The repository includes a `docker-compose.yaml`, so container deployment is a genuine alternative to installing each dependency separately on the host. The compose file defines two services: `app` and `mongo`. The application container is built from the repository's `Dockerfile`, and MongoDB uses `mongo:8.2.6-noble`.

The compose configuration exposes the application on host port 9000 and MongoDB on host port 27017. It passes Firebase variables into the application container and constructs its MongoDB URI from `MONGO_INITDB_ROOT_USERNAME` and `MONGO_INITDB_ROOT_PASSWORD`. The service hostname is `mongo`, not `localhost`, because the containers share the Compose network.

The container build performs a fuller setup than a typical application-only image. Its first stage installs Git, copies the repository, installs dependencies, downloads music and runs `npm run assetpack`. A builder stage then executes `npm run build`. The final image installs production dependencies with `--only=production --ignore-scripts` and copies the built distribution into `app/public/dist`.

This path reduces some host setup work, but it does not remove Firebase configuration, secret management or database initialization. The repository files do not show an automated import of `./db-commmands/botv2.json` into the Compose MongoDB service. An operator therefore cannot assume that starting the supplied services will produce a fully populated bot environment. This is a real deployment boundary: the image builds the application, while required data and credentials remain external responsibilities.

Pokemon and synergy changes require separate regeneration steps

Pokemon Auto Chess has content-specific maintenance commands that ordinary TypeScript projects do not necessarily need. Asset changes and game-data changes follow separate paths. Assets start under `public/src/assets` and are packed into `public/dist/client/assets`; Pokemon or synergy changes require `npm run precompute` because the application consumes files under `app/models/precomputed`.

This separation can prevent stale content from reaching the game, but it also creates an easy contributor error. Editing source assets without running `npm run assetpack` leaves the generated client output unchanged. Editing Pokémon or synergy definitions without running `npm run precompute` leaves the derived data unchanged. Neither omission produces a conventional source compilation error, so correctness depends on following the documented workflow.

The build scripts reinforce a split client-server architecture. `npm run build` first invokes `build-client`, which runs `node esbuild.js --build`, and then invokes `build-server`, which runs `tsc`. A separate `build-prod` script uses `tsc -p tsconfig.prod.json --noCheck` for its server compilation. The production Docker image executes `node app/public/dist/server/app/index.js` after copying the generated distribution.

For code quality, the README recommends VS Code and the Biome extension. The package scripts expose linting and formatting over `app/`, while `typecheck` runs TypeScript with `--noEmit`. These commands provide static checks, but they do not replace recomputing or repacking content. The right build sequence depends on whether a change affects code, assets, Pokémon data or synergy data.

Licensing, maintenance, and the cost of running a fan game

Maintenance activity is visible from repository metadata. The repository is not archived, and the last push was on 2026-10-16. Version 6.11 is listed as the current package version, and recent named releases include 6.11 Stadium, 6.10 Carnival and 6.9 Expeditions. These records show recent project changes, but they do not guarantee compatibility with every Firebase or MongoDB configuration outside the documented setup.

There is a licensing inconsistency that adopters must resolve before redistribution. The repository metadata states `GPL-3.0`, the README displays a GPL v3 badge, and the repository license description names GPL-3.0. However, `package.json` declares `BSD-3-Clause`. This discrepancy is material because package consumers may read the manifest while repository reviewers read the `LICENSE` file. It should be corrected or explained by the project before code is incorporated into another codebase.

The rights statement presents a separate constraint. The description says all Pokémon rights belong to The Pokemon Company and that the game can stop whenever that company requests it. The GPL grant cannot by itself settle rights to third-party game characters or branding. This review does not offer legal advice, but it would be a mistake to treat the source-code license as a complete answer to Pokémon intellectual property questions.

Operational cost also comes from maintaining two external services. MongoDB needs durable data, backups and access control. Firebase needs a configured project, permitted sign-in providers, a service account and protected private-key material. Self-hosting MongoDB avoids one hosted bill but adds database administration. The Docker path packages MongoDB with the app, yet production still needs persistent storage, secret handling, initialization and monitoring appropriate to the deployment.

Where Pokemon Auto Chess is the wrong tool

Pokemon Auto Chess is the wrong choice for a lightweight prototype that only needs turn resolution or chess-like AI. Its architecture is tied to a complete Pokémon game: a client asset pipeline, a MongoDB data store, Firebase Authentication, bot data, precomputed Pokémon and synergy files, and a full server distribution. Adopting the repository means accepting that context rather than extracting a small simulation component.

It also does not fit an offline-only game without architectural changes. The documented authentication path depends on Firebase, and the persistent data path depends on MongoDB. An operator who wants a single executable, no cloud account and no external database would have to replace or bypass documented services. The repository does not describe such a mode.

A commercial project is another poor fit unless rights and licensing are settled first. The repository is explicitly a non-profit fan project, reserves Pokémon rights to The Pokemon Company, and contains conflicting source licensing declarations. A conventional auto-battler framework or an original game without Pokémon assets would avoid both the service overhead and this rights ambiguity.

For a contributor, the boundary is narrower but clear. The project is most practical when the intended outcome is running, studying or modifying this particular community game under its existing content rules. Its MongoDB, Firebase and regeneration commands are concrete project details, not incidental setup advice.

Editorial conclusion

Pokemon Auto Chess fits fans or contributors who already accept its MongoDB and Firebase dependencies and intend to work with its game-specific asset pipeline. It is a poor fit for a small standalone prototype, an offline-only game or a commercial deployment without resolving Pokémon rights and repository licensing concerns. Before adoption, verify the `LICENSE` file against `package.json`, confirm that Node.js `>=24.19.0` and npm `>=10.8.1` match the deployment image, and test Firebase account creation, login and the required `dev.botv2` database setup on the intended environment.

Frequently asked questions

Official sources

1. keldaanCommunity/pokemonAutoChess on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases