Electrify

A mobile-friendly tycoon game about electricity markets. Play it at
electrifygame.com.

Getting started

Setup

Requires Node.js 24. Check your version with node --version.

Using a version manager such as nvm makes it easier to switch
between Node versions.

Development commands work in standard Windows, macOS, and Linux shells. The deployment script
requires a POSIX-compatible shell such as Git Bash.

With Node.js installed, run the following from the root of the repository:

npm ci

To use the online high score capabilities, you will need to contact an admin to get a Firebase api key.

Serve and watch

npm start

This runs the app at http://localhost:3000.

Run tests

npm test

This starts Jest in watch mode. Test files use the .test.ts or .test.tsx suffix. Use
npm run test:once -- <name> to run matching suites once and exit.

Check everything

npm run check

Types, lint, formatting and tests, which is what CI runs on every pull request. Individually:

npm run test:ci reports coverage and skips the *.sim.test.tsx suites, which CI runs without
coverage through npm run test:sim. src/helpers and src/reducers have floors set in
package.json just under where they stand today, so a change that guts them fails rather than
landing quietly; raise the floors as coverage grows.

Simulate the game headlessly

npm run sim -- --all

Plays every scenario through the real game reducer without a browser -- a 20 year run takes about
half a second -- and checks that the economy obeyed its invariants (no NaNs, cash only moves by
recorded revenue and expenses, storage can't invent electricity, and so on). Use it to sanity
check a change to the simulation in seconds rather than by playing through the UI.

npm run sim -- --scenario 103 reports one scenario month by month, and npm run sim -- --help
lists the flags. See the simulation guide for what it checks and how it
works.

Add a city to play in

Every location is a single file in public/data/weather: hourly readings from 1980 through 2025
for the twelve days a year the game actually simulates, packed into about 66KB, or 80KB with
offshore wind. Whichever cities have been downloaded are exactly the ones the custom game screen
offers - public/data/weather/index.json is written by the same script and is what the picker reads.

npm run fetch-weather -- --list

lists the 285 cities in scripts/cities.json and marks the ones already downloaded; naming some
of them fetches them, and naming none fetches everything still missing:

npm run fetch-weather -- Tokyo Nairobi Reykjavik

The data is ERA5 reanalysis from the Open-Meteo archive
API, which is free and needs no key but
rate limits by location-day. A 1980-2025 city costs 552 location-days, or 1,104 when its offshore
point is fetched too, which works out to roughly nine onshore cities or four offshore cities an
hour. The script paces itself against that, writes each city out as it finishes and skips whatever
is already on disk - so filling in the rest of the catalogue is a matter of running it again
tomorrow rather than leaving it running.

To extend every existing file after another calendar year has completed, run:

npm run update-weather

This preserves the existing packed readings and fetches only the missing years through the last
fully completed year. Use npm run update-weather -- --through 2030 to choose an explicit cutoff;
city ids and --limit work here too, and completed files are skipped when a rate-limited run is
resumed.

To add somewhere that isn't listed, add it to scripts/cities.json and fetch it. The id must match
the generated weather filename and the location references in the game data.

To enable offshore wind for a location, add a representative sea coordinate in its offshore
field. Fetching a location that has no weather file downloads both points. If its onshore weather
already exists, the fetcher downloads only the offshore history and adds it to the existing binary,
preserving every established onshore reading.

Offline icon cache

public/icons.json lists every image under public/images/. It is generated by
npm run icons:generate (run automatically before start, build and test) and is git-ignored like
src/data/RunCompatibility.json. After launch, the service worker downloads the listed icons in
the background for every user -- not just installed apps -- so all screens' artwork is available
offline before a game starts. Add an image to public/images/ and the next build picks it up
automatically; no service-worker change is needed. Images the app never displays, such as the
1024 px link-preview icon, are listed in EXCLUDED in scripts/generate-icon-manifest.js so
players don't download them.

Manual figures

Every player downloads the manual's figures, so they ship as WebP. The originals live in
design/manual/, which is not deployed. To add or change a figure, put the original there,
run node scripts/compress-manual-images.js (requires cwebp: brew install webp), and
reference the .webp from src/components/base/ManualEntries.tsx with its real width and
height. JPEG charts are re-encoded at WebP quality 88 (about 60-70% smaller, SSIM ≥ 0.993 and
indistinguishable at 3x zoom); PNGs are re-encoded losslessly. Always encode from the originals
so losses never compound. src/ManualFigures.test.ts checks the two stay in step. A diagram
drawn for the game keeps its SVG source beside it; render that to a PNG at its own size (for
example with a headless browser) and compress the PNG like any other original.

Release checklist

To release, install and authenticate the AWS CLI.

Merging to master deploys prod through GitHub Actions (.github/workflows/deploy-prod.yml).
To preview a change first, run npm run deploy beta and check that:

• basic functionality works (app loads, game starts, music plays)

Troubleshooting

The app supports the Redux DevTools browser
extension
for inspecting application state.

Display-name storage

Player names live in users/{uid}.displayName. Display names are not unique;
Firebase Auth UIDs identify accounts. Scores retain a display-name copy for efficient
leaderboard reads, with best-effort backfilling when a player renames themselves.

Legacy usernames documents and displayNameLower profile fields are unused and may be
deleted with admin tooling; deploying rules does not delete stored data.