monster
59fd95b707
Five incremental games disguised as boring 1998-era desktop utilities, launched from a Win98 shell (ENTROPY OS): - Vol I qBitTorrz (index.html) — torrent-client idler; seed, climb hardware tiers, migrate - Vol II DEFRAG.EXE (defrag.html) — steer a disk defragmenter; drag-select; outrun entropy - Vol III MACRO_VIRUS.XLS(spreadsheet.html) — build a compounding economy by drag-filling formulas - Vol IV UPLINK (terminal.html) — terminal + live htop; manage load/heat; escalate to root - Vol V INBOX ZERO (inbox.html) — keyboard-triage an exponential inbox; write regex rules - ENTROPY OS (desktop.html) — the Win98 launcher that holds them all Each is a single self-contained HTML file (vanilla JS, no deps, no build), with idle/offline progress, scientific-scale numbers, diegetic upgrades, and a prestige that re-frames the fiction. Also includes MANIFESTO.md (design thesis) and docs/ — the Collector's Edition companion: a Dev Handbook and a Lore Bible (lore complete; 5 handbook chapters land in the next commit). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
102 lines
6.1 KiB
Markdown
102 lines
6.1 KiB
Markdown
# Introduction — How This Machine Is Built
|
||
|
||
*The engineering commentary track. What this handbook is, what it assumes, and the handful of laws that every line of the anthology obeys.*
|
||
|
||
This is the maintainer's manual for **BORING SOFTWARE** — an anthology of incremental games, each
|
||
disguised as a boring 1998-era desktop utility, all launched from a Windows-98 shell called
|
||
**ENTROPY OS**. If the Lore Bible (Disc Two) is the soul, this is the schematic. Read it before you
|
||
touch a balance constant.
|
||
|
||
## What you are looking at
|
||
|
||
Six files. Each is a complete, self-contained program:
|
||
|
||
| File | Volume | Lines (approx) |
|
||
|------|--------|----------------|
|
||
| `index.html` | **Vol I — qBitTorrz** | ~1,870 |
|
||
| `defrag.html` | **Vol II — DEFRAG.EXE** | ~1,660 |
|
||
| `spreadsheet.html` | **Vol III — MACRO_VIRUS.XLS** | ~1,620 |
|
||
| `terminal.html` | **Vol IV — UPLINK** | ~1,870 |
|
||
| `inbox.html` | **Vol V — INBOX ZERO** | ~1,760 |
|
||
| `desktop.html` | **ENTROPY OS** (the shell) | ~370 |
|
||
|
||
There is no framework. There is no bundler. There is no `node_modules`. Each game is inline HTML,
|
||
inline CSS, and inline vanilla JavaScript in one `.html` file you can open by double-clicking it.
|
||
Persistence is `localStorage`. The entire stack is *the browser*. This is a deliberate constraint,
|
||
not a limitation we regret — see the law of **Fidelity over flash** below. A self-contained file is
|
||
honest software: it boots instantly, it survives being emailed around, and it will still run in a
|
||
decade because it depends on nothing that can rot out from under it. (Which, given what these games
|
||
are *about*, is a small joke we are proud of.)
|
||
|
||
## How this handbook is organized
|
||
|
||
- **Chapter 01 — Architecture & the Shared DNA.** The reference architecture every volume
|
||
re-implements: the number formatter, the global state object, the save/load/sanitize round-trip,
|
||
the tick loop, offline catch-up, toasts, prestige. Read this once and you understand the skeleton
|
||
of all five games.
|
||
- **Chapter 02 — Building a New Volume.** The cookbook. A copy-paste skeleton, the requirements
|
||
checklist, how to choose an interaction hook, the balance-tuning methodology, and how to wire a
|
||
new app into the desktop. This is how Volume VI gets made.
|
||
- **Chapter 03 — QA Playbook & Post-Mortems.** How these games are actually tested, and the candid
|
||
autopsies of every bug we shipped and caught. The most useful chapter and the most humbling.
|
||
- **Chapters 10–14 — The Volume Internals.** One deep, source-accurate dive per game: the state
|
||
shape, the core model, the signature hook's implementation, the upgrade and prestige tables, and
|
||
the balance levers. When you need to change a specific game, start in its chapter.
|
||
- **Chapter 15 — The Desktop Shell.** ENTROPY OS itself: the Win98 chrome technique, the windowing
|
||
system, the program registry, and how to add an app.
|
||
|
||
Throughout, you will find these:
|
||
|
||
> **DEV NOTE** — a sidebar for the traps, the war stories, and the reasoning behind a choice that
|
||
> looks wrong until you know why. When a chapter says "we tried the obvious thing and it broke,"
|
||
> this is where the body is buried.
|
||
|
||
## The prime directives
|
||
|
||
Every volume in this anthology obeys six design laws. The handbook treats them as load-bearing; the
|
||
chapters cite them by name. They are reproduced from `_STYLE.md §5`, which is canon.
|
||
|
||
1. **Every boring app is a secret incremental game.** Find the loop already in the chrome. A torrent
|
||
client's throughput, a defragmenter's consolidation, a spreadsheet's recalculation — the idle
|
||
game is already there. We just make the subtext text.
|
||
2. **The clutter line.** No mascots. No rarity gems. No reroll buttons. No confetti. Status bars,
|
||
monospace, dense tables, dialog boxes with OK/Cancel. *If it looks like a video-game menu, it is
|
||
wrong.* This is the single most important aesthetic rule and the easiest to violate.
|
||
3. **One hook, fully committed.** Each game lives or dies on its one novel interaction. Build that
|
||
first and make it *feel good*; the incremental scaffolding is the easy part you can copy from the
|
||
next chapter.
|
||
4. **Legible numbers.** The player must always know where the next number comes from. Diegetic
|
||
upgrades, visible formulas, honest gauges. No black boxes.
|
||
5. **Respect the idle contract.** The game must play itself while the player is gone and reward them
|
||
for coming back. This law has a body count — see the **DEFRAG entropy death-spiral** in Chapter
|
||
03. The corollary every engineer must tattoo somewhere: *idle must reach equilibrium, never
|
||
death.*
|
||
6. **Fidelity over flash.** Nail the boring original first; the game emerges from honest software,
|
||
not decoration.
|
||
|
||
## Two invariants the code must never break
|
||
|
||
Beyond the design laws, there are two engineering invariants. Violating either is, by definition, a
|
||
release blocker:
|
||
|
||
- **A save must never brick boot.** Every game loads through `sanitizeState()`, which repairs
|
||
partial, stale, or hand-corrupted saves so that no value of `localStorage` can throw on startup.
|
||
If you add a state field, you add its guard. Chapter 01 shows the pattern; Chapter 03 shows what
|
||
happens when you forget (the **MACRO_VIRUS soft-lock**).
|
||
- **The tick must never throw.** The main loop runs ~10 times a second forever. A single uncaught
|
||
exception in `tick()` silently kills the game — the UI freezes mid-number and the player never
|
||
sees an error. The original **qBitTorrz `renderStatus()` crash** (Chapter 03) is the cautionary
|
||
tale: one stale element reference, one throw per tick, a dead game that *looked* alive for exactly
|
||
one frame.
|
||
|
||
· · ·
|
||
|
||
A note on tone before we go in: these games are small, but they are not toys, and this handbook is
|
||
not a lark. The numbers are tuned, the saves are hardened, the idle contract is honored, and every
|
||
bug in Chapter 03 is real and was really fixed. Boring software, built seriously. That is the whole
|
||
joke, and the whole craft.
|
||
|
||
> **If you change anything in this handbook's scope:** keep the two invariants sacred, keep the
|
||
> clutter line, and re-run the QA playbook in Chapter 03 against the game you touched. The anthology
|
||
> is robust precisely because nothing in it is clever where it does not need to be.
|