# Idle Clicker A themeable idle game inspired by *Universal Paperclips*. Make units by hand, sell them, automate production, buy upgrades. Runs in any browser (phone, tablet, desktop); progress is saved in cookies and can be exported/imported as a JSON or TXT file. There is **one game**: themes (paperclips, witch potions, alien minerals, leaf-piling insects, computers) are only skins, so switching theme keeps every amount. Zero runtime dependencies: a small Node server (`http` module only) plus a vanilla JS frontend (ES modules). ## Run it ```bash docker compose up -d --build # http://localhost:8080 (GAME_PORT=9000 to change the port) ``` The container is a single image running as the unprivileged `node` user, with a read-only filesystem, no capabilities and `no-new-privileges`. Without Docker: `npm start` (Node 22+). Tests: `npm test`. ## How the project is organised ``` server/ static file server + /api/themes and /api/locales (auto-discovery) public/ index.html page skeleton (texts come from i18n via data-i18n attributes) css/ base (tokens) · layout (responsive grid) · components data/ GAME CONTENT, theme-independent (ids + numbers): rules, generators, upgrades, investments, research, legacy perks, achievements, tabs locales/ core UI texts, one file per language (en, fr) themes// ONE FOLDER PER THEME theme.json order + (later) image paths theme.css colours/fonts, as CSS variables locales/.json the theme's vocabulary: names of resources, generators, upgrades js/ engine/ game rules, pure JS, no DOM (also used by the tests): engine (production, market, time) + one module per system (investments, gamble, research, legacy, contracts, achievements) services/ cookies · storage · save import/export · i18n · formatting · data loading ui/ DOM helpers · main view · one view per section · tabs/menu · settings · toasts · fx (the quick purchase animations) main.js wires everything together tests/ node:test suites (engine, systems, save import/export, server, content completeness) ``` The key idea: **mechanics are shared, themes are skins.** `public/data/` defines generators and upgrades by id (`gen1`, `click_1`, …) with their numbers; a theme only gives those ids a name, a colour palette and, later, images. Rebalancing the game is a change in `public/data/`, not in each theme. ## The game beyond the factory The production screen is the core loop. Further sections appear in the menu as you progress (a tab bar on tablets and desktops, a burger menu on phones; the three resources stay visible in a bar at the top): | Section | Unlocks at (lifetime production) | What it is | |---|---|---| | Contracts | 20 K | Sell a target amount in time for funds, research, chips or a production boost; opportunities (surge, rush, windfall) to seize within seconds; rare incidents. | | Investments | 100 K | 9 societies in 3 risk tiers (low ±5 %, medium ±15 %, high ±50 % every 60 s), dividends, a 0.5 % fee. Themed names. | | Research | 500 K | Labs (bought with funds) produce research points slowly; a tree of 15 permanent bonuses, including a late one that reveals the balanced price. | | Gamble (themed: Quantum Computer, Crystal Ball…) | 5 M | Chips are costly and each one costs more. Stake them on a cycle: win, jackpot or crash. Reliability upgrades tilt the odds; chips boost demand with diminishing returns. | | Legacy | 500 M | Restart the run for permanent points: a passive bonus per point plus repeatable perks. Research, achievements and statistics survive. | | Achievements | always | 23 milestones, each with a small permanent bonus. | Everything is data-driven: `tabs.json` (unlocks), `investments.json`, `research.json`, `legacy.json`, `achievements.json` and the `gamble`, `research`, `legacy`, `contracts` and `events` blocks of `rules.json`. All bonuses share one vocabulary of effects (`engine/effects.js`). Texts for research, perks and achievements are in the core locale files; only the theme vocabulary (the gamble's name, the chip/research/legacy currencies, the nine societies) is per theme. ## Add a theme 1. Copy `public/themes/paperclip/` to `public/themes//` (lowercase letters, digits, dashes). 2. Edit `theme.css` (palette, font, radius), `theme.json` (`order`), and the texts in `locales/*.json`. 3. Reload. The server discovers the folder; no code change and no rebuild list. (With Docker, rebuild the image or mount the folder.) `npm test` fails if a theme misses a name for any resource, generator or upgrade, or lacks a language the game supports. ## Add a language 1. Copy `public/locales/en.json` to `public/locales/.json` and translate it (set `meta.name` to the language's own name). 2. Add `public/themes//locales/.json` to every theme. Missing keys fall back to English, then to the raw key. Strings accept `{param}` and `{@other.key}` (embeds another entry, which is how core texts use the theme's vocabulary, e.g. `{@theme.res.material}`). ## Images Every icon is currently a grey square. See [Icons to produce](#icons-to-produce) at the end of this file for the exhaustive list, the format and how to plug images in. ## Saves - One shared game for all themes, stored in cookies (`ic_game_*`, chunked and base64-encoded because a cookie holds ~4 KB), plus one preferences cookie (theme + language). Saves from the first version (one per theme) are merged automatically: the most advanced one is kept. - **Save & settings** exports the save as `.json` or `.txt` (download or copy/paste) and imports either (file picker or pasted text). The file does not depend on the theme. Imports are validated and sanitised: unknown ids are dropped, numbers clamped. - Progress continues while the game is closed: up to 8 h, at 50 % efficiency (`public/data/rules.json`). - Cookies are sent with every request to the server. A late-game save is about 4 KB (base64), far below header limits, but it is the reason to keep saves compact. ## Tuning the game Everything numeric is in `public/data/`: `rules.json` (market, raw material, marketing, offline, autosave), `generators.json`, `upgrades.json`, `endless.json`. - **Endless upgrades:** the 36 one-time upgrades are milestones. When a family is complete (manual work, each automation tier, global output, demand, sale value, material efficiency, discounts, stack size), it continues as a repeatable line in `endless.json`: each level multiplies the effect once more (`effect.value`) and costs `baseCost × costGrowth ^ level`, up to `maxLevel` (10 000, which cannot be reached: costs overflow long before). Costs must climb much faster than effects. Income is the *product* of several lines, so if the ratios `ln(effect) / ln(costGrowth)` of the income-driving lines add up to more than 1, the economy explodes (an early tuning reached 1e207 units/s in two hours). A test guards this sum. Endless levels belong to the run: a legacy restart resets them. - **Material lots** can be bought in part: if the whole lot costs more than your funds, you get as much as the funds buy, at the same unit price, so a player can never be locked out of material. - **Selling:** demand is a smooth curve, `baseDemand × demandMultiplier × (referencePrice / price) ^ elasticity` units/s: lower the price and more people buy, with no ceiling. The best price is where demand just matches your output (selling for less gains no volume, selling for more leaves stock unsold). That point moves with every generator, upgrade and marketing level, and the game does not display it: the market hint only says whether you are selling too cheap, too dear, or about right. - **Raw material** (wire, herbs…): the price per unit starts high (`startUnitPrice`, about a third of the sale price) and falls towards `floorUnitPrice` as total production grows (economies of scale). A lot covers about 10 s of current output (in doublings), multiplied by the "stack" upgrades (`batch_size_mult`, a chain of five, ×180 in total). A lot costs in proportion to its size, so bigger stacks cost more per purchase while the price per unit still falls with scale. The market is erratic: the price is re-drawn every 10 s (`updateEverySeconds`) with wide random swings plus frequent shortages and gluts (`spikeChance`, `spikeSize`), and is shown to the cent, with ▲/▼ for its last move. The auto-buy upgrade is patient: it waits for a fair price unless stock is nearly gone. ## Icons to produce Every icon the game shows is a grey square until a theme provides an image. The exhaustive work list is in **[ICONS.txt](ICONS.txt)**: a checklist per theme, with the file name, the key and what to draw for each icon. It is generated from the game data, so it is always complete. All 23 achievements share a single `trophy` icon. - **Format:** one square image per icon, SVG preferred (or PNG at 128×128 px or more), transparent background, readable at 28 px (top bar) and 48 px (lists). Files go in `public/themes//img/`. - **Plugging them in:** list each file in the theme's `theme.json`; anything not listed keeps the grey square, so images can be added a few at a time: ```json { "order": 1, "assets": { "res.units": "img/res-units.svg", "gen.gen1": "img/gen-gen1.svg" } } ``` - `npm run icons -- --write` regenerates `ICONS.txt`, `npm run icons -- --manifest` prints a complete `assets` skeleton to start from. `npm test` fails if `ICONS.txt` is out of date or if the interface uses an icon key that is not listed.