idle_clicker/README.md

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

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/<id>/           ONE FOLDER PER THEME
    theme.json             order + (later) image paths
    theme.css              colours/fonts, as CSS variables
    locales/<lang>.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
    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/<your-id>/ (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/<code>.json and translate it (set meta.name to the language's own name).
2. Add public/themes/<id>/locales/<code>.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 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. Each theme needs the same set of icons, drawn in its own style: the list below is generated from the game data, so it is always complete.

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). Put the files in public/themes/<theme>/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:

{ "order": 1, "assets": { "res.units": "img/res-units.svg", "gen.gen1": "img/gen-gen1.svg" } }

npm run icons -- --manifest prints a complete assets skeleton (every key mapped to img/<key>.svg) to start from. npm run icons prints the list below, and npm run icons -- --write refreshes it in this file; npm test fails if it is out of date or if the interface uses an icon key that is not listed.

The tables give what each icon represents in each theme (the name used in the game, in English).

115 icons per theme, 575 in total (5 themes: paperclip, witch, alien, insects, computers).

Group	Icons per theme	Shown in
Resources	6	top bar (units, funds, material), Gamble, Research and Legacy screens
Automation tiers	6	Production screen, Automation list
Upgrades	36	Production screen, Upgrades list
Investment societies	9	Investments screen
Endless upgrades	14	Production screen, Endless upgrades panel
Research	15	Research screen
Legacy perks	6	Legacy screen
Achievements	23	Achievements screen
Total	115

Resources (6)

Key	paperclip	witch	alien	insects	computers
res.units	Paperclips	Potions	Xenocrystals	Leaves	CPU Power
res.funds	Funds	Gold	Credits	Honeydew	GalliumCoin
res.material	Wire	Herbs	Raw ore	Silk	Energy (W)
res.chips	Quantum Chips	Fate Tokens	Chance Crystals	Pollen Grains	Qubits
res.research	R&D Points	Arcane Insight	Xeno-Data	Instinct	Algorithms
res.legacy	Patents	Grimoire Pages	Blueprints	Colony Memories	Legacy Code

Automation tiers (6)

Key	paperclip	witch	alien	insects	computers
gen.gen1	Autoclipper	Apprentice	Mining Drone	Worker Ant	Old Laptop
gen.gen2	MegaClipper	Bubbling Cauldron	Plasma Drill	Leafcutter Squad	Gaming PC
gen.gen3	Clip Factory	Alchemy Lab	Orbital Extractor	Beetle Hauler	GPU Mining Rig
gen.gen4	Hypno Drones	Broomstick Fleet	Asteroid Harvester	Termite Mound	Server Rack
gen.gen5	Probe Swarm	Moonlit Coven	Hive Swarm	Locust Swarm	Data Center
gen.gen6	Matter Converter	Philosopher's Engine	Planet Cracker	Hive Queen	Quantum Mainframe

Upgrades (36)

Key	paperclip	witch	alien	insects	computers
upg.click_1	Ergonomic Bender	Steady Stirring	Gravity Gloves	Sharper Mandibles	Mechanical Keyboard
upg.click_2	Pneumatic Grip	Enchanted Ladle	Exo-Suit	Pheromone Trail	Keyboard Macros
upg.click_3	Robotic Arm	Familiar's Help	Neural Link	Double-Grip Legs	Neural Interface
upg.g1_a	Sharper Autoclippers	Apprentice Lessons	Drone Firmware	Ant Drill Sergeant	Thermal Paste
upg.g1_b	Overclocked Autoclippers	Apprentice Mastery	Drone Swarm Logic	Marching Songs	Fresh OS Install
upg.g2_a	MegaClipper Servos	Copper Cauldrons	Diamond Bits	Wider Leaf Slices	Liquid Cooling
upg.g2_b	MegaClipper Turbines	Eternal Flame	Plasma Focusing	Leafcutter Guild	Overclocking
upg.g3_a	Assembly Line	Crystal Alembics	Tether Cables	Reinforced Shells	Custom BIOS
upg.g3_b	Just-in-Time Logistics	Rune-Etched Tables	Zero-G Smelting	Dung Beetle Logistics	Memory Timing Tuning
upg.g4_a	Hypno Harmonics	Waxed Brooms	Mass Drivers	Air-Conditioned Chambers	Hot-Swap Drives
upg.g4_b	Persuasion Algorithms	Hex-Powered Flight	Autonomous Prospecting	Deep Tunnel Network	Load Balancer
upg.g5_a	Probe Self-Replication	Full Moon Rites	Hive Mind Sync	Riding the Wind	Redundant Power Lines
upg.g5_b	Von Neumann Protocols	Blood Moon Pact	Queen Directive	Migration Instinct	Free Cooling (Arctic Site)
upg.g6_a	Atomic Reassembly	Transmutation Circles	Tectonic Resonance	Royal Jelly	Cryogenic Coolant
upg.g6_b	Universal Reformatting	The Fifth Element	Core Shattering	Queen's Decree	Entangled Qubits
upg.global_1	Quality Control	Spellbook Index	Quantum Diagnostics	Dewdrop Hydration	Firmware Update
upg.global_2	Lean Manufacturing	Grandmother's Grimoire	Alien Alloys	Seasonal Rhythm	Parallel Computing
upg.global_3	Industrial AI	Ley Line Tap	Dyson Tap	Hive Mind	Learning Scheduler
upg.global_4	Quantum Scheduling	Time Dilation Charm	Spacetime Folding	Perfect Spring	Distributed Grid
upg.demand_1	Newspaper Ad	Village Notice Board	Trade Beacon	Scent Markers	Forum Hype
upg.demand_2	Radio Campaign	Market Stall	Interstellar Broker	Cricket Courier	Tech Influencers
upg.demand_3	Viral Video	Royal Commission	Galactic Exchange	Forest Market	Exchange Listing
upg.demand_4	Global Brand	Legend of the Witch	Cosmic Monopoly	Famous Pile	Global Hype Cycle
upg.value_1	Gold-Plated Paperclips	Glittering Labels	Purity Certificate	Dewy Gloss	Shiny Whitepaper
upg.value_2	Premium Packaging	Apothecary Seal	Rare Spectrum Cut	Autumn Colours	Celebrity Endorsement
upg.value_3	Luxury Branding	Royal Warrant	Imperial Grade	Golden Leaf Grade	To The Moon
upg.mat_eff_1	Thinner Wire	Careful Pruning	Ore Analyzer	Tighter Weaving	Efficient PSU
upg.mat_eff_2	Wire Recycling	Distilled Essence	Molecular Sieve	Silk Recycling	Low-Power Chips
upg.mat_disc_1	Bulk Wire Contract	Forager's Pact	Asteroid Contract	Spider Contract	Off-Peak Contract
upg.mat_disc_2	Direct From the Mill	Enchanted Garden	Own the Mine	Silkworm Farm	Own Solar Farm
upg.stack_1	Bigger Spools	Larger Baskets	Bigger Cargo Pods	Bigger Silk Bundles	Bigger Batteries
upg.stack_2	Pallet Orders	Herb Sacks	Container Drones	Cocoon Sacks	Capacitor Banks
upg.stack_3	Container Loads	Cartloads	Freighter Holds	Web Warehouses	Grid Substation
upg.stack_4	Freight Trains	Greenhouse Harvest	Convoy Fleets	Spider Caravans	Dedicated Power Line
upg.stack_5	Wire Mills	Whole-Forest Rights	Orbital Stockpile	Great Silk Hoard	Private Power Plant
upg.auto_buy	WireBuyer	Self-Gathering Basket	Autonomous Freighter	Spider Delivery Service	Smart Power Meter

Investment societies (9)

Key	paperclip	witch	alien	insects	computers
inv.inv_low_1	Steady Staples Inc.	Old Hollow Apothecary	Zeta Mining Cooperative	Anthill Savings Bank	Stable Silicon Bank
inv.inv_low_2	Office Supply Trust	Greywood Herb Co-op	Orion Ore Trust	Honeycomb Trust	ByteSafe Trust
inv.inv_low_3	Copper Wire Bond	Village Cauldron Guild	Lunar Refinery Bond	Leafy Greens Co-op	Mainframe Heritage Fund
inv.inv_mid_1	Binder Dynamics	Moonpetal Brewers	XenoCorp Industries	Dung Beetle Logistics Ltd	NeoChip Holdings
inv.inv_mid_2	Clip Logistics	Nightshade & Sons	Nebula Extraction Ltd	Termite Tower Builders	CloudNine Hosting
inv.inv_mid_3	Stationery Futures	Crooked Broom Trading	Void Cargo Syndicate	Cricket Courier Corp	Packet Dynamics
inv.inv_high_1	NanoWire Labs	Dragonscale Elixirs	Hyperion Rift Labs	Locust Swarm Capital	MoonShot Mining DAO
inv.inv_high_2	Paperless Dreams Ltd	Wyrmwood Potions Ltd	Singularity Salvage	Wasp Venture Fund	HypeCoin Labs
inv.inv_high_3	Hyper-Clip Ventures	Forbidden Brew Cartel	Black Hole Ventures	Mantis Ambush Futures	Quantum Leap Capital

Endless upgrades (14)

Key	paperclip	witch	alien	insects	computers
endless.e_click	Manual mastery	Manual mastery	Manual mastery	Manual mastery	Manual mastery
endless.e_gen1	Autoclipper overhaul	Apprentice overhaul	Mining Drone overhaul	Worker Ant overhaul	Old Laptop overhaul
endless.e_gen2	MegaClipper overhaul	Bubbling Cauldron overhaul	Plasma Drill overhaul	Leafcutter Squad overhaul	Gaming PC overhaul
endless.e_gen3	Clip Factory overhaul	Alchemy Lab overhaul	Orbital Extractor overhaul	Beetle Hauler overhaul	GPU Mining Rig overhaul
endless.e_gen4	Hypno Drones overhaul	Broomstick Fleet overhaul	Asteroid Harvester overhaul	Termite Mound overhaul	Server Rack overhaul
endless.e_gen5	Probe Swarm overhaul	Moonlit Coven overhaul	Hive Swarm overhaul	Locust Swarm overhaul	Data Center overhaul
endless.e_gen6	Matter Converter overhaul	Philosopher's Engine overhaul	Planet Cracker overhaul	Hive Queen overhaul	Quantum Mainframe overhaul
endless.e_global	Total optimisation	Total optimisation	Total optimisation	Total optimisation	Total optimisation
endless.e_demand	Mass appeal	Mass appeal	Mass appeal	Mass appeal	Mass appeal
endless.e_value	Premium margin	Premium margin	Premium margin	Premium margin	Premium margin
endless.e_efficiency	Wire thrift	Herbs thrift	Raw ore thrift	Silk thrift	Energy (W) thrift
endless.e_discount	Hard bargaining	Hard bargaining	Hard bargaining	Hard bargaining	Hard bargaining
endless.e_stack	Wire stockpiling	Herbs stockpiling	Raw ore stockpiling	Silk stockpiling	Energy (W) stockpiling
endless.e_cost	Economies of scale	Economies of scale	Economies of scale	Economies of scale	Economies of scale

Research (15)

Key	Subject (the same in every theme, drawn in each theme's style)
research.r_prod_1	Optimised Workflows
research.r_prod_2	Automation Suite
research.r_prod_3	Total Integration
research.r_mkt_1	Market Analysis
research.r_mkt_2	Brand Strategy
research.r_mkt_3	Premium Positioning
research.r_log_1	Resource Efficiency
research.r_log_2	Bulk Procurement
research.r_log_3	Lean Manufacturing
research.r_fin_1	Portfolio Management
research.r_fin_2	Risk Modelling
research.r_fin_3	Negotiation Training
research.r_ins_1	Research Methods
research.r_ins_2	Remote Operations
research.r_ins_3	Price Oracle

Legacy perks (6)

Key	Subject (the same in every theme, drawn in each theme's style)
legacy.lg_prod	Industrial Memory
legacy.lg_demand	Brand Heritage
legacy.lg_cost	Lean Blueprints
legacy.lg_start	Head Start
legacy.lg_offline	Night Shift
legacy.lg_rp	Research Archive

Achievements (23)

Key	Subject (the same in every theme, drawn in each theme's style)
ach.a_prod_1	First Steps
ach.a_prod_2	Getting Serious
ach.a_prod_3	Industrial Scale
ach.a_prod_4	Beyond Imagination
ach.a_prod_5	Cosmic Output
ach.a_gen_1	Small Team
ach.a_gen_2	Big Operation
ach.a_gen_3	Endless Workforce
ach.a_upg_1	Tinkerer
ach.a_upg_2	Perfectionist
ach.a_inv_1	Pocket Money
ach.a_inv_2	Smart Money
ach.a_inv_3	Tycoon
ach.a_gam_1	Beginner's Luck
ach.a_gam_2	High Roller
ach.a_gam_3	Chip Collector
ach.a_con_1	Deal Maker
ach.a_con_2	Reliable Partner
ach.a_res_1	Curious Mind
ach.a_res_2	Master Scientist
ach.a_leg_1	Fresh Start
ach.a_leg_2	Eternal Return
ach.a_evt_1	Quick Hands