Screeps TypeScript Starter

A modern Screeps AI starter written in TypeScript, configured for Node 24, Forgejo Actions, and private-server deployment through Pterodactyl.

Requirements

• Node.js 24 LTS for local development and CI
• npm 10.8.2 or newer
• A Screeps auth token for the official server, or screepsmod-auth on your private server for username/password uploads

Install

npm ci

Build And Test

npm run lint
npm test
npm run build

npm run build compiles the TypeScript bot to dist/main.js without uploading it.

Deploy To A Private Server

Private-server deploys are driven by screeps.json, which is intentionally ignored because it contains credentials.

For Forgejo Actions, add these repository secrets:

• SCREEPS_PSERVER_HOST
• SCREEPS_PSERVER_PORT (optional, defaults to the Pterodactyl game port 25568)
• SCREEPS_PSERVER_PROTOCOL (optional, defaults to http)
• SCREEPS_PSERVER_PATH (optional, defaults to /)
• SCREEPS_PSERVER_TOKEN, or both SCREEPS_PSERVER_USERNAME and SCREEPS_PSERVER_PASSWORD

Optional repository variable:

• SCREEPS_PSERVER_BRANCH (defaults to main)
• SCREEPS_SKIP_AUTHMOD_CHECK (set to true only if you intentionally want to skip the /api/authmod preflight)

The Deploy Master To Screeps workflow uploads the compiled code whenever master is pushed. You can also run it manually from Forgejo and choose a Screeps branch.

For local deploys, set the same environment variables and run:

npm run deploy:pserver

Pterodactyl Egg

Import pterodactyl/egg-screeps-node24.json into Pterodactyl to create a standalone Screeps private server using Node 24 and built-in LokiJS storage (db.json). The egg installs screeps@4.3.0 and screepsmod-auth@2.9.0 by default. The egg startup is bash ./start-screeps.sh; the installer writes that script and it rebuilds isolated-vm when the Node/V8 patch version changes, which prevents V8 snapshot mismatch crashes after the runtime image updates.

After the server starts, confirm http://YOUR_HOST:YOUR_GAME_PORT/api/authmod returns JSON. If it returns 404, the running server has not loaded screepsmod-auth yet. The Pterodactyl startup command must be bash ./start-screeps.sh, and mods.json must use the Screeps 4 format with the default bot entry preserved: {"mods":["node_modules/screepsmod-auth"],"bots":{"simplebot":"node_modules/@screeps/simplebot/src"}}.

For password uploads, open the Screeps CLI and set the upload password for your bot account:

auth.setPassword("Username", "YourPassword");

Use that username and password in the Forgejo secrets above. If you do not want to store a password in Forgejo, create a token instead:

auth.createAuthToken("Username", "forgejo");

Use the returned token as SCREEPS_PSERVER_TOKEN.

Notes

• screeps.json, .env, dist, and node_modules are ignored.
• Git remotes are not managed by this repo. Point origin at your Forgejo repository when you are ready.