The Naval Gaming spec

Written 2026-10-06 and signed off by Marlinspike the same day. It changes only by his decisions, each marked with his name and its date. This page is the spec, served at /spec/.

This is the rebuild's specification for the launch: single-player Battle Builder. It describes what the game does, in player terms, and the shape of the code that will do it. It covers only what Marlinspike kept for launch on 2026-10-06; everything else is listed under Later and Dropped.

1. Rules

What the game is

A game of manoeuvre and crew management (Marlinspike, 2026-10-08: "We want things that enhance the play of maneuver and the play of crew management. Officers is an example of a feature that will enhance crew management play."). A feature earns its place by making one of the two better to play.

Playability comes first, over history and realism, in mechanics as well as in numbers (Marlinspike, 2026-10-08). History and realism are where a value or a mechanic starts, never what it must stay; where they and play disagree, play wins, and the record says why. Fun is judged by playing, so Marlinspike's playtest is the last word. Playable means (Marlinspike, 2026-10-08):

1. The game for its own sake: "something people play for its own sake" (2026-09-24), "not trying to simulate history" (2026-10-06), "released from historical precedent" (2026-10-07). Checked by: tests read their targets from the data, so a value moved for play passes.
2. Responsive: an order shows its effect in seconds (the game clock, 2026-10-06; braking and sternway, 2026-10-07). Checked by: the physics and manoeuvre tests, against each class's handling stats.
3. Paced: a fight lasts minutes, not hours; an even close action takes about five full broadsides (2026-10-09). Checked by: the pace report.
4. Seamanship pays: a tack by hand is worth making, and every class can work to windward (2026-10-07). Checked by: the manoeuvre tests.
5. Choices matter: where you put your ship and what you load change the outcome. A rake kills more than a beam hit, chain is for the rig, double for close in, and enemies that switch shot make each fight different (2026-10-07). Checked by: the shot tests.
6. Readable: you can tell where everyone is and what your orders are doing; you can't fight what you can't place (2026-10-07). Checked by: Marlinspike's playtest.
7. Every class worth playing, under manoeuvre: a smaller ship can beat a bigger one by outsailing it (2026-10-08). Not met yet. Checked by: the pace report's meeting scenario, and Marlinspike's playtest.

For every number

• Play decides the value (Marlinspike, 2026-10-07: "released from historical precedent"; a good game to play comes first, and 2026-10-06: "we are not trying to simulate history"). A value needs no historical base. Where one exists, it is kept beside the game value as a note; a value set or moved for play says why and when.
• A value with no source says so: "tuning guess, set by play". A source that was looked for and not found is "citation needed". Neither is ever dressed up as a fact.
• Tune with global scales first. Time compression covers most of the gap between history and play. Per-value changes are the exception and always carry their reason.
• Historical units stay historical in the spec (feet, pounds, knots, yards). Code converts them in one place.
• Polars and other tables live in JSON data files, where bin/cleanroom_check.sh compares them as tables. A number written into prose or code is checked only one value at a time.

For every word

• A ship is "it", never "she" (Marlinspike, 2026-10-01): in player text, comments, tests and docs.
• No served file and no player text names another game (Marlinspike, 2026-09-24).
• The world is fictional (Marlinspike, 2026-09-30). The Crown and the Cabal are its sides. Real ships appear only as the cited source of a class's numbers, never as names in play. Corona del Mar's look is inspired by 18th-century Southeast Asia (Marlinspike, 2026-10-17); it stays fictional, with no real place, people or power named.

The gate

bin/cleanroom_check.sh (in the station repo, run from the projects root) passes on this repo, and Marlinspike signs off. Hits cleared by a citation are listed in cleanroom-accepted.txt at the repo root.

2. Behaviour

What the player sees and does at launch. Dates and "Marlinspike" mark his decisions; "proposed" marks a choice made in this draft for him to confirm.

The game

Naval Gaming is "something people play for its own sake" (Marlinspike, 2026-09-24), not a testbed for a sailing model. At launch it is one product, Battle Builder: you set up two lines of ships and fight in one of them, alone in your browser, with no account (Marlinspike, 2026-09-29).

Battle Builder

• You choose the ships on each side, any mix of the five classes, up to 8 a side, and for each whether you or an NPC captain commands it (Marlinspike, 2026-10-01). A side is never empty.
• You command one ship. The first ship marked Player is yours, and it may be on either side. At launch only one ship can be marked Player.
• Nothing is stored. The battle is encoded in the page address, so a reload or a copied link restores it exactly (Marlinspike, 2026-10-01). With no battle in the address, the sheet opens on a frigate duel: your frigate against one of the Cabal's (Marlinspike, 2026-10-09).
• The layout is fixed: two lines abreast, facing each other, under a steady wind (Marlinspike, 2026-10-01). Wind, range and map are not choices. The starting range and the wind's direction across the lines are tuning guesses, set by play.
• The sides are the Crown and the Cabal (Marlinspike). Each line flies its side's ensign; the ensign goes by side, not by ship. The Cabal's full name is the Nefarious Plantation Cabal; "the Cabal" is the short form (Marlinspike, 2026-10-06). The Cabal relies heavily on local mercenaries (Marlinspike, 2026-10-17); so far this is only who they are, and changes no rule.
• The ensigns (Marlinspike's designs, brought over 2026-10-06). Both are flat, two colours, and read at a distance:
  • The Crown's: a plain deep-blue field, and centred on it a white royal crown. It has a jewelled band whose jewels show blue, two arches rising from the band's ends and dipping to meet in the middle with pearls along them, the blue cap showing between the arches, and an orb and cross on top.
  • The Cabal's: a bright red field, and centred on it a bone-white goat's skull, snout down. Its horns sweep up and out toward the top corners, ridged across, and its ears droop out to the sides from under the horns. It has a long tapering snout, and its eye sockets and nostrils show the red through.
• The sheet shows each ship drawn in plan, a Player/NPC switch, add and remove, and a tally per line of ships, guns and broadside weight. Its wording, the battle's title and its briefing are Marlinspike's to write. Until he does, the sheet uses plain functional labels and has no title or briefing; the code invents no copy (2026-10-06).
• Under the lines (Marlinspike's design, 2026-10-01, brought over 2026-10-08): a note, "Each line forms abreast, bows to the enemy, n m between ships and n m between the lines.", its distances read from the layout; then the launch button, which stays "Start" (Marlinspike, 2026-10-08). The wording is the old sim's, kept by Marlinspike (2026-10-08). The sheet has no copy-link button (Marlinspike, 2026-10-14: removed): the battle's link is the page's address.

The shipyard

• A page on the site, at /shipyard/, not a screen in the game (Marlinspike, 2026-10-15). It lists every class, and each class has a page of its own: a picture of her under sail, her stats and armament, her lines, sail plan, deck plan, stern and bow, and her polar. Every picture and drawing comes from the same model and data the game sails.
• Sea Trial (Marlinspike, 2026-10-15): each ship's card has a button that takes that ship to sea on her own, with no enemy, so you can try how she handles.
• The brigantine is in the shipyard, and nowhere else (Marlinspike, 2026-10-16): her page and her Sea Trial. She carries no guns, so she is no warship: Battle Builder, the port and Corona's sea do not offer her. See Ships.
• The list is /shipyard/ and each class's page is /shipyard/<class>/. A sea trial lives in the game's address, /play/#trial=<class>: Battle Builder's open sea and wind, her alone. Leave goes back to her shipyard page (built 2026-10-15).

Tutorials

• Two tutorials, Basic Sailing and Basic Gunnery (Marlinspike's design, 2026-09-29 to 10-02, brought over 2026-10-08). Each is a fixed battle: your frigate in open water and a target hulk. Basic Sailing starts with no sail set and the hulk off the starboard bow to steer for; Basic Gunnery starts stopped, with the hulk 200 m off the starboard beam (tuning guesses, set by play).
• Your orders come one at a time, as a line over the sea, top centre. Each teaches a key or two, not seamanship, and is done when your ship shows it: the sail ordered, the heading turned, the helm hard over, the yards braced, a gun side's order, the shot ordered, three hits on the hulk. A line that only points something out stays up a few seconds. A step met turns amber, and the next comes a moment later. A big amber arrow, bobbing, stands over the part of the HUD a step talks about. The last line stays up, and you sail on: a tutorial never ends, like every battle.
• The steps name keys from the key bindings, so they always match the keys (ch. 3). A step about the mouse passes at once where the browser won't hand the camera the mouse, as on a touch screen. There the steps name the buttons instead, and a step whose words don't fit a touch screen (a click, or where the HUD stands) has its own touch words (Marlinspike, 2026-10-10).
• The pause menu has a Tutorials button, which lists them, each with its title, briefing and Start. Leave, from a tutorial, goes back to the list. A tutorial lives in the page address too (#tutorial=basic-sailing), so it can be linked.
• A hulk (Marlinspike, 2026-10-08): any class's hull with nobody aboard. It has no captain and sets no sail, its guns are never manned, and it never strikes, however it is hit. Its topmasts are struck: it shows only its lower masts and their tops, with no yards and no guns run out (Marlinspike, 2026-10-09). Battle Builder does not offer it yet.

The island and grounding

• Every Battle Builder battle has an island (Marlinspike, 2026-10-08), always in the same place: off one end of the two lines, beside the water between them, so either side can use it for cover or come to grief on it. Where exactly is a tuning guess, set by play. The tutorials stay in open water (Marlinspike, 2026-10-09).
• The island (Marlinspike's design, 2026-09-25, brought over 2026-10-08): one low, sandy, wooded island, longer than it is broad, about 2 km by under 1 km, with a bay cut into one side and a long shoal running out from the point at one end, near another kilometre of shallow water. All round it the sea shallows over a shelf. Along its middle runs a wooded spine, high enough to hide a ship's hull and stop shot. Its shape and sizes were set by eye, and are tuning guesses, set by play. No village, dock or buildings yet.
• Land stops shot. A ball that strikes the land ends there, and counts as a miss on the tally.
• Land blocks sight. A gun never fires at a ship it can't see past the land. A captain chooses its target from the ships it can see, the same way.
• Grounding (Marlinspike's rule, 2026-09-25, brought over 2026-10-08): a ship whose leading end (the bow going ahead, the stern going astern) comes into water shallower than her draught stops dead and lies aground until she is backed off: with her sails aback, sternway carries her out into deep water. Grounding does no damage. While she is aground your compass panel says so (Marlinspike, 2026-09-25), and so does her label in the glass (Marlinspike, 2026-10-09).
• Captains keep off the shoals (the old sim's captains, 2026-09-28, brought over 2026-10-08): a captain looks ahead along its course, further the faster it goes, and turns away from water shallower than its draught and a margin. How far ahead and how much margin are tuning guesses, set by play.
• A captain aground backs off (Jim, 2026-10-14). It does what a player must: auto-trim off, each yard group braced to the angle in its range that backs it most and held there, so a sail that can't back is eased edge-on rather than driving her on; sail set; the helm checking any swing, so she goes out straight the way she came in. It keeps on until the water close ahead is clear. Where her sails, weighed by their areas, can't back her (the wind abaft), it takes them in and she stays aground, as a player's ship would.
• The look (copied from the old sim, staged for this repo: see the crossings list, Launch 13): the ground coloured by height, from wet sand at the waterline through dry sand and dune grass to the forest floor; live oaks, longleaf pines and cabbage palmettos, the palmettos along the dunes; the sea lightening and greening over the shoals as it shallows, and bands of surf running in over the last metre and a half.

Sailing: the helm

• The helm turns the rudder to port or starboard. Held, a helm key puts the helm over; let go, it eases back amidships. A double tap puts it hard over and holds it there until the helm is touched again. The rudder goes over at the rate a crew could put the helm across (Marlinspike, 2026-10-14: back to the held helm of 2026-10-06, after four days of a helm stepped a place a press).
• The rudder works only with water flowing past it, so it bites in proportion to speed through the water. Going astern, its effect reverses smoothly, with no snap at zero (Marlinspike, 2026-09-23).

Sailing: sail

• Three sail levels: none, topsails, full (Marlinspike, kept 2026-10-06). Each step up or down is an order to the men aloft, not an instant change (see Crew).
• Ship-rigged and brig-rigged classes trim with yards, in two groups: the fore yards, and the main and mizzen yards together. Each group is braced on its own.
• Auto-trim braces both groups to the wind for you. Touching either group by hand turns it off; one key turns it back on.
• Each yard group drives the ship according to its angle to the wind. A group with the wind on the front of its sails is aback and pushes the ship astern.
• Each group also turns the ship: sail forward of the pivot pushes the bow off the wind, sail aft of it pushes the stern. So the age-of-sail tack works: haul the main yards round as the bow crosses the wind, and hold the fore yards aback until the bow is past it. Split yards can turn a ship that has no way on.
• Headsails, staysails and the spanker (Marlinspike, 2026-10-07, from history: Falconer 1769). A ship-rigged or brig-rigged class also carries fore-and-aft sails: the headsails (fore topmast staysail, jib and flying jib) out on the bowsprit, which push the bow off the wind; the staysails between the masts, near the pivot, which mostly drive; and the spanker (Falconer's mizen; on the brig, her boom mainsail) at the stern, which pushes the stern off and so brings her head up. The headsails, staysails and spanker are set and taken in with the square sails, set while any canvas is (Marlinspike, 2026-10-07: there is no reason to take one in while under sail). R / T sheet the headsails to port or starboard by hand, as the yard keys brace the yards: the way to back them and cast her head off (Marlinspike, 2026-10-07). To windward their clews haul only so far, flat (a tuning guess, about 20°), so hard over to windward is fully backed; to leeward they ease out. From a standstill with her yards edge-on, headsails backed pivot a frigate about 50° in a minute, gathering way as her yards fill. Auto-trim sheets them with the yards; by hand they take the plane of their yard group as far as their sheets allow, the headsails with the fore yards and the staysails and spanker with the main: braced sharp, they stand sharp to leeward; braced aback, they back too. Their areas and places are tuning guesses, chosen so the headsails and the spanker balance: a ship with everything set needs no helm at any canvas. The cited speeds are taken as made with them set. Captains handle them the same way, through the sail level.
• The cutter trims with sheets, not yards (Marlinspike, 2026-10-04). A backed mainsail gives it only a little sternway. The jib's sheet is limited so the jib can't fly out ahead. A boom hauled across to windward stays backed until it is eased or auto-trim takes it.
• The brigantine trims with both (Marlinspike, 2026-09-28; built 2026-10-16). Her fore yards are braced as a brig's fore yards are, on the fore yard keys; her gaff main is sheeted as the cutter's main is, on the main keys, and backs and gybes the same way; her headsails and staysails work as a square rig's, the headsails on R / T. The drive is shared between them: her fore yards brace round no further than a brig's do, so close-hauled her gaff, headsails and staysails carry it, and she points higher than the brig. Hard on the wind her fore yards, braced as far as they go, shiver and give her nothing while the gaff still draws. Each sail turns her on its own: trimmed, she holds her course; with her foremast gone she rounds up into the wind. With her main furled her boom is secured amidships, as the cutter's is.
• Sternway is real (Marlinspike, 2026-09-23). Speed is signed. A square-rigged ship head to wind stops, then gathers sternway; the speed shows it with a minus sign, as "−1.5 kn" (Marlinspike, 2026-10-07; it said "astern" until then).
• The no-go zone is shown on the compass rose as the limit of how close the ship can point ("in irons").

Wind

In Battle Builder and the tutorials the wind is steady for the whole engagement: one direction, one strength (Marlinspike, 2026-10-06). Its strength is a tuning guess, set by play. Corona del Mar's wind follows the clock (see Corona del Mar).

Gunnery

• You don't aim. You steer. Where you put the hull decides what the guns hit; the crew lays and fires them (Marlinspike, 2026-09-24).
• Each side of guns has three orders (Marlinspike, 2026-10-06), cycled in turn:
  • Stand Down: the side is unmanned; its crew goes to the sails. Loaded guns stay loaded.
  • Load: the side is manned; the crew loads and holds.
  • Fire at Will: the side is manned; each loaded gun fires as it bears.
  Both sides stood down is sailing; both manned splits the gun crew between the sides. There is no separate "clear for action": manning a stood-down side is slow, because that is clearing for action; going between Load and Fire at Will is quick (Marlinspike, 2026-09-24). With the sails furled, every man but the sail station's minimum goes to the guns (Marlinspike, 2026-10-07; it was every man, 2026-09-25 and 2026-10-02).
• Gun crews are sized by the guns, from period quarter bills (Marlinspike, 2026-09-25). Below full sail they fill first from men off station, then from the sail crew, but never below the sail station's minimum: half the topsails crew, kept even with the sails furled, so a sail order always starts at once (Marlinspike, 2026-10-07). Full sail, set or ordered, takes its whole crew first, from the guns if it must, and the guns have what is left (Marlinspike, 2026-10-12: "full sail has to have a real cost"). So a ship under full sail can serve one broadside, not both, until she shortens sail.
• Guns start an engagement empty. Marlinspike's decision, kept knowingly (2026-10-09: "keep it as my decision"): a check before the launch found that the old sim had taken this rule from an earlier game. It stays because the opening minute spent loading is what teaches Load and Fire at Will, and makes the first broadside a decision. Reloading goes on whether a side is firing or holding. An unmanned side's loaded guns can still fire, but don't reload.
• Fire at Will ripples. Each loaded gun that bears is laid by its gun captain and fires when he is done. Each takes his own time, drawn up to the layTime lever (3 s, a tuning guess). A gun that stops bearing while being laid starts again when she bears. So a broadside ripples down the side as the target comes into each gun's arc, and even a full broadside rolls out over a few seconds, never in unison (Marlinspike, 2026-10-12: "a fully loaded broadside should not fire in unison, It should take a few seconds for one broadside to fire", replacing "the full broadside at once" of 2026-09-24). Leaving Fire at Will mid-ripple holds the guns that haven't fired. Holding at Load and then going to Fire at Will gives the full broadside within those few seconds.
• "Bears" means some part of a ship that hasn't struck, stem to stern, is inside the gun's arc and range, nearest first, and the gun lays on the part of her that bears nearest her middle, her centre whenever that bears (Marlinspike, 2026-10-12: close aboard, only the middle of a broadside had fired, since the ends could not train on her centre). A gun holds fire while a friendly ship fouls its range. The firing rule is one replaceable rule; Marlinspike plans a later one that scores each shot.
• Each gun fires from its port (Marlinspike, 2026-10-12: a first rate's flash and smoke came from one deck). A gundeck's guns sit in its row of ports, spread evenly along it, the lowest a little above the water and each deck above it a deck's height higher; the weather deck's guns sit in the bulwark, in one line from the quarterdeck forward to the bow; every row rises with the sheer toward the ends. The heights are the drawn hull's, one rule for both, set by eye. The range tables are worked for one reference height, and a gun higher or lower lays for the difference, so an upper-deck gun reaches a little further than a lower-deck one.
• Ammunition (Marlinspike, 2026-10-06, replacing round shot only at launch). Each side of guns has an ammunition order, ball, chain or double, changed in turn by U for port and O for starboard (Marlinspike, 2026-10-07), or by the switch on that side's station. A gun loads the ordered shot at its next reload. Changing the order draws the shot from guns already loaded, and they load again with the new one.
  • Ball: round shot, as now.
  • Chain: two half-balls joined by a chain. It flies slower and scatters wider than ball. The crew lay it on the target's rigging rather than its hull, and it does much more to the rig than ball and little to the men.
  • Double: two balls on a reduced charge. It has a shorter range and a little wider spread, but at close range a hull hit kills and wounds far more. It takes longer to load than ball (Marlinspike, 2026-10-08: the tradeoff for its weight), so loading it early costs a broadside's time.
  How much each differs from ball is a tuning guess, set by play: speed, drag, spread, where it is laid, its harm to hull and rig, and its loading time, each as a share of ball in the guns' data. Each shot flies by its own range table, so chain reaches about half as far as ball and double about three quarters, and a gun holds fire until the enemy is within its shot's reach. The hit-effect levers (Pacing) scale all three alike.
• Smoke: every shot leaves a plume of puffs at the muzzle, thrown out the way the ball went and strung along its line, that bulge, roll slowly, grow, fade and drift downwind, so a broadside leaves a bank to leeward; the sun lights each puff on one side and shades the other (billowy; Marlinspike, 2026-10-21). It is visual only. The bank blocking the view is by design (Marlinspike, 2026-10-21): the player experiences the gunfire through it, so the smoke is never thinned or faded for the camera's sake. The look of firing began as the old sim's, copied (Marlinspike, 2026-10-06): each puff is thrown out the way its ball went, then rises a little and drifts slowly so a bank lingers; balls fly as dark shot, and a miss throws up a white column that rises and falls back.
• Muzzle flash: every shot also throws a short flame at the muzzle, gone in a tenth of a second, and a tight stream of burning powder and wadding out along the ball's line, behind the ball, that cools and goes out in about half a second; nothing falls away. It is visual only, and new, not the old sim's (Marlinspike, 2026-10-12).
• Gunport lids are open while a side is manned or loaded. Guns recoil and run out again as they reload.

Hits

• Shot hits shapes, not the drawn ship. Each ship has a hull shape and a rig shape for hits, kept apart from the model you see, so redrawing a ship never changes a fight (Marlinspike, 2026-09-27). See Physics: hits.
• A hull hit costs men, not planks. There is no hull health and no sinking (Marlinspike, 2026-09-24). A ball that goes through the side kills and wounds in proportion to its path inside the hull, so a rake from astern, end to end, is the great killer; a ball that glances off does little. The bow is a small target (Marlinspike, 2026-10-07): from ahead, only a ball that strikes near the stem goes through, and the bow's heavy timbers turn the rest. Each hit leaves a visible mark.
• A rig hit holes the sails (Marlinspike, 2026-10-06). Each one takes a little of that ship's drive, for good; chain tears more sail than ball does (Marlinspike, 2026-10-06). The holes show (Marlinspike, 2026-10-12): they open in a mast's sails as its wear grows, faster under chain than ball, and the sails between masts take the standing masts' mean.
• Masts come down (Marlinspike's rules, 2026-10-02, brought over 2026-10-08). Each mast has its own strength, and every rig hit wears the mast it lands on as well as holing the sails. The masts of a ship differ in strength, so under a steady fire of chain they fall in turn, not together (Marlinspike, 2026-10-08); how they differ is a tuning guess, set by play. When a mast falls, the drive its sails gave goes with it, and the ship's balance shifts with it: lose a mast forward of the pivot and she gripes up into the wind, lose one aft and she falls off (see Physics, Speed: from polar to speed). A ship with one pole mast and no topmast loses it whole, broken above the deck.
• The wreck is drawn only (Marlinspike, 2026-10-02). A falling mast breaks at the lower masthead and its upper part topples to leeward to lie across the side, then the crew cut it away after a while; it never changes how the ship sails or fights. The lower mast stands as a stump with its top and its lower shrouds. A ship first seen already dismasted shows stumps, with no wreck and no fall.
• No repairs during an engagement (Marlinspike, 2026-09-24).

Crew

• Every ship has a complement (see Ships). Casualties come off it.
• Men are at stations: sail, port guns, starboard guns, or off station. The station bar shows each with men present over men needed.
• Sail handling needs men aloft. An order waits while the topmen go up, then the canvas moves. Its speed is the men at the sail station over the men the sails need. Full sail needs more hands than topsails; furled sails need none.
• Bracing needs men too (Marlinspike, 2026-10-12: "the amount of crew on sail station should affect the speed of bracing"). The yards swing, by hand or under auto-trim, at the men at the sail station over the men it wants: what the canvas needs, never counted below the station's minimum. At least that many brace at full speed, fewer in proportion. So fighting both sides under topsails, the sail station falls to its minimum and the yards come round at about half speed.
• Casualties slow everything they touch: guns reload more slowly with fewer men, and sails are handled more slowly (Marlinspike, 2026-09-24).

Morale and striking

• Morale falls with casualties and recovers in lulls (Marlinspike, 2026-09-24, kept 2026-10-06). Recovery is always slower than the slowest reload, or fights run to near-total casualties (a consistency rule; see Pacing).
• A mast coming down is a heavy blow to morale, though it kills few (Marlinspike, 2026-10-02, brought over 2026-10-08), and part of that loss never comes back. It cannot make an unhurt ship strike on its own, but it can finish one already hurt. The size of the blow and the part kept are tuning guesses, set by play.
• A ship strikes when morale breaks. Striking is an event (Marlinspike, 2026-10-01): the ship loses its commander, stops firing, furls its sails, hauls down its colours, shows a white flag and drifts. It keeps its side. Nothing fires on it.
• Engagements never end (Marlinspike, 2026-09-29). There is no victory, defeat, result screen or time limit. Allies fight on after you strike.
• When your ship strikes (Marlinspike, 2026-10-06): the strike notice shows, the camera stays free so you can watch the fight go on, and the pause menu offers Fight again (a fresh start of the same battle) and Leave. Once her sails are in and she has lost her way, her boat goes down and you with it (see Boats). Marlinspike's notice, shown from the strike until the boat is down: "We are sorry, captain, but the crew is exhausted and cannot continue. We must strike our colors and launch the boat." (Confirmed by Marlinspike, 2026-10-06; the boat restored 2026-10-14.)
• Ship status, shown on its label: Commander (the captain's name; see The view, Names), Status (Under command, In squadron, Adrift, a struck ship's: Marlinspike, 2026-10-09, was Unattended) and Side (Marlinspike, 2026-10-01). A ship aground says so (Marlinspike, 2026-10-09; see The island and grounding); dismasted comes later with that feature. Labels show only through the telescope (Marlinspike, 2026-10-06; see The view).

NPC captains

• An NPC captain sails every ship but yours, enemies and allies alike (Marlinspike, 2026-09-28).
• An NPC captain issues the same commands a player does, through the same command layer, and can do nothing a player can't (Marlinspike, 2026-09-25; architecture 2026-10-06).
• It is scripted, then tuned: a hand-written NPC captain whose few parameters are tuned later by headless self-play. No neural net (Marlinspike, 2026-09-25).
• What an NPC captain does at launch: choose a target, the nearest enemy, and keep it rather than flip between ships; pick a heading from scored candidates, ruling out the no-go zone (inside its windward angle: below) and collisions, and counting its leeway when it works toward a target; tack when the short way round is through the wind and it has way enough, as the tack drill is done by hand, and wear when it hasn't (Marlinspike, 2026-10-06: tacking once it is reliable; 2026-10-13: "NPC need to be able to tack and get out of irons"); a tack once begun is carried through, and one that hangs in stays too long is given up; caught in irons, pay her off on the side her head already lies, the helm and the backed fore yards turning her the same way; shorten to topsails when close; and man the side the enemy will bear on, early, because clearing takes time.
• Each NPC captain has a temper, a brawler or a skirmisher (Marlinspike, 2026-10-13: "a brawler and a kiter", renamed "skirmisher" the same day), fixed for the battle by the seed, half of each, so enemies differ from fight to fight. It replaces two earlier tempers, one for shot (2026-10-08) and one for raking. A brawler is aggressive: it closes to close action and manoeuvres for the rake. It weighs each course by where it would leave the two ships a little ahead, the enemy holding her course: its broadside on her stern is best, on her bow next, on her beam least, and her broadside on its own ends counts as much against it ("attack and defend"), so a brawler that hunts for your stern keeps its own from your guns. A skirmisher keeps its distance: it holds the enemy abeam at its own longer range, opening the range when she comes closer. The odds overrule the temper (Marlinspike, 2026-10-13: "make temper depend on the odds"): an NPC captain with clearly fewer men aboard than its target skirmishes, one with clearly more brawls, and only near even does its own temper decide. Losses count, so a badly hurt ship turns skirmisher. Measured: ship for ship the brawler wins, but a brig skirmishing beat a brawling frigate in half of fair meetings, where brawling it never did; against bigger odds the smaller ship stands off but still loses. The ranges, the share of each, the margin of the odds and the rake's weights are tuning guesses.
• An NPC captain chooses its shot (Marlinspike, 2026-10-08: built here rather than carried over). Close in it loads double. Further out, while chain will reach the rig, a skirmisher loads chain and a brawler ball, and beyond chain's reach both load ball. Chain gives way to ball once the target has lost much of its drive. An NPC captain holds its shot a little past each range's edge, and fires a loaded broadside that still reaches before it changes, since changing draws the loaded shot. The ranges are tuning guesses.
• An NPC captain manages its crew through the sail and gun orders (Marlinspike, 2026-10-13). It mans every side an enemy within manning range lies on, not only its target's. In action it sets full sail while the men left after the sail crew still serve at least half of its manned sides' crews, since speed wins the rake or holds the range; otherwise topsails. Only the men aboard count, so losses take sail off. Its guns fire at will. Holding a broadside to fire it together was tried and dropped (2026-10-13): the only reason to hold is a rake, which is its own reward, and holding for one changed nothing measurable.
• Each NPC captain has a competence (Marlinspike, 2026-10-13), from 0 to 1, drawn from the seed and never shown: most NPC captains middling, a few poor, a few excellent. The best is the NPC captain as above. Less competence looks round less often and, in a brawler, judges the rake less far ahead; between brawlers the better wins more often than not. Only skills that change who wins are kept (Marlinspike, 2026-10-13: no minutiae without a discernible effect): misjudging range and course, and wanting more way before tacking, were tried and dropped. The values for the poorest NPC captain are tuning guesses.
• Allies keep clear of you and hold fire while you foul their range.

The squadron and signals

• Every captained ship on your side is in your squadron from the start (Marlinspike, 2026-10-02). Before any signal, a squadron ship fights as it would alone.
• Six signals (Marlinspike, 2026-10-01 and 2026-10-03; all kept 2026-10-06):
  • line abreast to starboard; line abreast to port; line ahead; line astern: each names a station relative to you, the flagship, with ships stacked outward at equal intervals, nearest first. In line, a ship keeps station and fires as its guns bear, but does not manoeuvre for a shot;
  • engage at will: releases the squadron to fight freely;
  • heave to: each ship lies to where it is, sails in, firing as its guns bear.
• A signal goes to the whole squadron; ships can't be singled out.
• Station-keeping: on station, a ship matches your sail; behind, it sets more; ahead, less. An equal ship can't catch a flagship under full sail; that is a fact of sailing, not a bug.
• Signals take time (Marlinspike, 2026-10-01). Each ship answers after a delay that grows with its distance from you, wherever it is: nothing blocks a signal (Marlinspike, 2026-10-09); it obeys as it answers. The HUD shows which ships have answered. An overtaken signal, or one made by a flagship that strikes, is lost. The delays are tuning guesses, set by play.
• Drawn signal flags (Marlinspike's design, brought over 2026-10-06; built 2026-10-09). Plain shapes in blue, yellow, red and white, told apart at a glance and the same from either side. Each line signal is a hoist of two flags: on top, a white cross on blue for "form line"; beneath, where the line forms. That is plain yellow for abreast to starboard, quartered blue and yellow for abreast to port, yellow over blue for line ahead, and blue over yellow for line astern. Engage at will is plain red, alone. Heave to is plain white over plain red (Marlinspike, 2026-10-09). You, the flagship, fly the signal in force from the main course yard's lee yardarm, and each squadron ship repeats it once it has answered (Marlinspike, 2026-10-09); a struck ship flies none, and a lost signal comes down. The signal list shows each signal's hoist beside its name. The flags are drawing only: they play no part in who answers.
• The signal list opens without pausing; the helm stays live. It shows each signal and the one in force. Choose with ↑/↓ and make it with Enter, or click a signal (Marlinspike, 2026-10-06). While it is open the cursor is free to click with; a click makes the signal, marks it chosen and closes the list, and a click on the sea closes it too (Marlinspike, 2026-10-12).

The view

• One 3D chase view with sky, sea, wakes, splashes and smoke (kept 2026-10-06).
• Ships are generated from their data, not modelled by hand, so yards and sails move with the physics (Marlinspike, 2026-09-24). Flags stream in the apparent wind.
• The ships are the old sim's, copied (Marlinspike, 2026-10-06): a planked hull lofted from each class's length, beam and decks, painted black with an ochre band along each row of ports (the Cabal's in red), copper below the water; its guns, run out once loaded and recoiling when they fire, behind port lids that open when the side is manned; the deck fittings, helm, capstan, belfry, hatches and the boat stowed on deck; carved heads and sterns on the First Rate and the seventy-four; men on deck and aloft; and the masts, yards, standing and running rigging, and sails as cloth that bellies, shivers when it luffs, and furls on its yard. The headsails and staysails are drawn set with the square sails. Ships heel to leeward under sail as well as riding the swell. The fine lines of the rig drop out on a ship too small on screen to show them.
• Ships heave, pitch and roll on the swell. This is visual only; the physics keeps the water flat.
• The sky and the sea are the old sim's, copied (Marlinspike, 2026-10-06): a sky shading from blue overhead to a pale horizon, a haze that takes distant ships, a band of cumulus round the horizon that holds its bearings as you turn, and a sea of long swells running downwind under a finer chop, with the sky in it, the sun's glint and patchy whitecaps, rougher in a stronger wind. Ships ride the same swell the sea draws.
• Wakes (Marlinspike, 2026-10-06, copied from the old sim): faint lacy wisps of foam lying on the water along each ship's track, a froth at the stern breaking up astern. A wake is as long as half a minute's travel at the ship's speed, so a ship losing way loses its wake.
• The camera (Marlinspike, 2026-09-23): above and behind, horizon near the top; it lags the heading in a turn, by the same amount at any time scale; the wheel changes the distance. Free look (Marlinspike, 2026-10-06, copied from the old sim; it replaces drag and swing back): in the chase view the pointer is locked and the mouse swings the camera round the ship, and the camera holds where it was pointed. The first Esc frees the cursor for the HUD (the browser's own rule for leaving pointer lock); the next Esc opens the pause menu; a click on the sea puts the camera back on the mouse. A hint in the top right always says which: Camera, Esc for the cursor; or Cursor, click the sea for the camera, Esc for the menu. Any screen frees the cursor.
• The compass rose turns with the ship: the card, the points, the wind arrow and the yards drawn over the hull. It shows the no-go limit.
• The telescope (Marlinspike, 2026-10-06, copied from the old sim), while Shift is held: the view moves to your own deck, a little above it, looking along the camera's bearing just below the horizon, magnified 6×, and your own ship is not drawn. The wheel or + / − sets the magnification from 3× to 12×, and the mouse swings the glass more slowly the stronger it is. The view is a round eyepiece, black outside it, with its magnification and bearing at the top ("6× · 045°"). The compass rose shows where the glass points and how wide its field is. Ship labels show only in the glass: under each ship at its waterline, the nearest ship on each bearing only, its captain's name, its own name (Marlinspike's design, 2026-10-01, brought over 2026-10-08), its class and side, its status, and a morale bar in its side's colour (blue for yours, red for the enemy's), or STRUCK.
• Names (placeholders kept by Marlinspike, 2026-10-08; the wording is his to change). Captains are numbered in the battle's order, Bartholomew01, Bartholomew02 and on, the Crown's line first; yours is you, and takes no number. A ship is named for her class run together, with a three-figure number counting that class through the battle: FirstRate001, Frigate001, Frigate002. A struck ship has lost her commander and shows no captain's name, and a hulk, with nobody aboard, shows only her own name (Marlinspike, 2026-10-09). "The Seventy-four" runs together as SeventyFour (Marlinspike, 2026-10-09).
• The map (Marlinspike, 2026-10-08), on M: a north-up paper chart of the battle's waters in place of the deck view. Nothing on it moves (Marlinspike, 2026-10-08: "a paper chart; nothing dynamic"): no ships, tracks, shot or smoke are plotted. The fight runs on behind it, and the HUD is hidden. It is drawn as an engraved paper chart of the period: laid paper browning toward its edges, a ruled border graduated in the chart's grid, a compass rose with rhumb lines, a block with the wind (an arrow and its speed in knots) and a scale bar, and a title cartouche that reads "Naval Gaming" (Marlinspike, 2026-10-08). The island is on it, its shore inked and its shoals marked by the 5 m and 10 m depth lines (Marlinspike, 2026-10-09). + / − or the wheel zoom it, and dragging pans it. M or Esc closes it (Marlinspike, 2026-10-08). The map and the minimap are separate (Marlinspike, 2026-10-08): they share no drawing code, so a change to one never changes the other.
• The minimap (Marlinspike, 2026-10-08), lower right in the deck view, as wide as the compass panel; on a narrow screen it stands above the station bar. It is hidden on the map and while the pause menu or controls panel is open. A square of paper, north-up, centred on your ship, marked N at the top. The island's land shows on it, and the shallow water round it (Marlinspike, 2026-10-09). Each ship is its hull in plan, filled in its side's colour, struck ships faded, with hulls kept to their relative size but never too small to see; a ship beyond the edge is a small arrow on the rim, pointing toward it. Shot in flight shows; tracks and smoke do not. A wind arrow, blowing downwind, sits top right, and the range bottom left. N or a click steps the range through three distances from your ship to the edge (tuning guesses, set by play), labelled by the distance alone (Marlinspike, 2026-10-08), and the game remembers the choice. It is drawn by its own code, not the map's.
• The compass panel, bottom left, holds the rose, the speed (with "→" and the speed the sails are driving her toward, while she is still getting there; Marlinspike, 2026-10-07), and rows for sails (the order, with "…" while the canvas moves), yards or sheets (auto or manual), crew aboard over complement, morale, and a rudder scale (Marlinspike, 2026-10-06). A Rig row, after yards or sheets, gives the share of the ship's drive its sails still give after rig hits, 100% when whole; once masts can fall, it also says how many are down (Marlinspike, 2026-10-08).
• The look is the old sim's, copied (Marlinspike, 2026-10-06: "I want the exact ui we had on old sim"). The interface code was copied across the wall by his decision, for the UI only: the compass and station bar as painted fittings (mahogany, a brass rule, IM Fell English; a gun side's rule gilt on Load and vermilion on Fire at Will), the rose as a card in a brass bowl, dark glass cards for the menus, and Battle Builder as a parchment chart in IM Fell DW Pica. No data, mechanics or ship geometry came with it; the hull drawings stay this repo's own.
• The station bar, bottom centre: port guns, sail, starboard guns, painted like the compass, each with its rule brass, gilt while it is working (a side loading, the canvas moving) and vermilion on Fire at Will (Marlinspike, 2026-10-02; the station bar redrawn 2026-10-14).
  • A gun side is marked by the logo's cannon, its muzzle outboard, to port on the left and to starboard on the right, with no name written, and its key beside it ("[J]"). Under it, its order (Stand Down, Load, Fire at Will); clicking it steps the order, the same command as the key. At its right an ammunition switch names the shot ordered ("Ball [U]"), gilt for any shot but ball; clicking it steps to the next, the same command as the key (Marlinspike, 2026-10-06 and 2026-10-09).
  • The broadside (Marlinspike, 2026-10-14): under the order, a port for each gun on that side, set in a run of the ship's side for each of her decks, top deck first, each where her gun lies along the hull, so the waist shows and a first rate looks like one. A port is dark when its gun is empty, fills gilt from its foot as her crew reload it, shows cream when she is loaded, and flashes vermilion as she fires. The bow is outboard: to the left on the port side, to the right on the starboard.
  • The men, while the side is manned: the men at its guns over the men they need ("136 of 212 men").
  • The sail shows its setting as a mast in its middle: the topsail, then the course and topgallant with it, dropping from their yards as the canvas is set, over a faint outline of the sail ordered; under it the men at the sails over the men they need. In a boat, the stroke.
• The tally, top centre: misses, hull hits and rig hits for your own ship's shot, reset on a fresh start (Marlinspike, 2026-10-02; his wording, which he may change). Every number shown comes from the sim's state, never from sums done for the display.
• No start screen (Marlinspike, 2026-10-14): a battle, a tutorial or Corona del Mar opens straight onto the sea, already under way. The first click on the sea takes the mouse for the camera, and the first click or key starts the sound.
• Pause menu, controls panel. Any screen pauses the sim, except the signal list and the map. The pause menu has the time scale, Sound, Controls, Fight again and Leave, and the ways elsewhere: Tutorials, Battle Builder and Corona del Mar. The controls panel lists every key and is generated from the real bindings, so it can't drift from them.
• The time scale: 1×, 2×, 4×, 8×.
• Sparing the device (Marlinspike, 2026-10-12: "my iphone gets hot").
  • Paused: while a screen pauses the game nothing is drawn, and the last picture stays behind the menu. A resize, or a screen or the map opening or closing, draws once.
  • Touch screens: a phone or tablet draws at no more than 1.5 pixels per CSS pixel (2 elsewhere), and its sea leaves off the three finest ripples of chop (3 layers, not 6). It draws 30 frames a second, not the display's 60 or 120; the sim runs at the same pace (Marlinspike, 2026-10-14). Desktop looks as before.
• Without WebGL the page says the game needs it and links the devlog (Marlinspike, 2026-10-06; the old fallback was the 2D view, now dropped).

Sound

Marlinspike, 2026-10-12. Two things sound, the guns and the sea ("sea sound and gun sound is good, remove the rest"). Both are made in code from the physics of what produces them ("be serious about the realism"). The plan is docs/plans/sound.md; both can be heard on their own at /admin/sounds/, the admin section’s sound board (Marlinspike, 2026-10-12).

• Synthesized only. Every sound is built at run time (Web Audio). No recordings, so there is nothing to source or licence.
• A gun, made "bigger" the same day:
  • a blast wave's pressure pulse (the Friedlander waveform), and a longer pulse for its thump;
  • the boom of the charge in the bore, falling in pitch;
  • the powder gas roaring out, and the carriage recoiling.
  A broadside ripples along her side, each gun from its own place across it: wide close to, a point far off.
• The sea round your ship, as it was when Marlinspike called it good (2026-10-12, restored the same day after a remake that sounded worse).
  • The wash: it runs along the hull and breathes with the swell, at a steady level. It no longer follows her speed ("remove the speed sound").
  • The swell: its period comes from the wind (the Pierson-Moskowitz peak).
  • Crests: they break round her from Beaufort 3, and everywhere by Beaufort 6. A calm only laps.
  • The slap: she slaps into each sea, with no bubble pings (Marlinspike, 2026-10-12: "remove bubble").
• A gun is heard from where you look.
  • Spreading: it is placed left or right of the camera and falls off with distance.
  • The air: it takes the top away at the rates of ISO 9613-1, so far guns rumble.
  • Off the sea: a second path arrives a little later, from the gun's image in the surface.
  • The open sea: it leaves a long rolling tail.
  • The delay: the sound arrives at 343 m/s, so a distant broadside's smoke is seen before it is heard. At a faster time scale the delay shortens with it.
  • Range: nothing past 6 km is played.
• Settings live in the pause menu, not on a key (Marlinspike, 2026-10-12): Sound On or Off, and a volume slider. The browser remembers them. Sound starts with the first key, click or tap. A limiter, then a soft clip, keeps a close broadside from overloading the speakers.
• Silent when nobody is listening: while a screen pauses the game, and while the tab is hidden. Studio's videos are silent unless a production asks for the game's sound, rendered offline from the same cues and synth (Marlinspike, 2026-10-20).
• Numbers. The physics constants are cited where they are used. Every level and timbre is a tuning guess, set by ear. Sound only reads the sim, so none of it is a lever and none of it moves the pace report.
• Removed (Marlinspike, 2026-10-12): splashes, hits, a mast falling, grounding, cheers, balls going by, the wind and rigging, creaks, blocks, flapping canvas and the boatswain's calls; then the wash along the hull, the one sound of her own speed ("remove the speed sound").

Accounts

Site stage 2, built 2026-10-12 (proposed; the decisions in it are Marlinspike's of that day). An account exists to carry a player's name; on day one it does nothing else (Marlinspike, 2026-10-12: "just exist with a username"). Saved progress, crew and officers come later on top of it. The game needs no account: Battle Builder plays without one, as before.

• Sign-in is Auth0, through the site's own OpenID Connect client (Jim's code, brought over through the crossings list 2026-10-12): the Authorization Code flow with PKCE, the identity token checked by the site against the tenant's keys. One tenant, so a player of the old site signs in here with the login they already have. Sign up is the same screen, opened on its sign-up side.
• A player is known by issuer and subject, never by email. The verified email is the only bar to membership: a new player gets a record the moment Auth0 returns one, and is asked for a username before anything else. A known player is signed in and sent where they were going; their stored email is refreshed from the verified one.
• The username is 4 to 24 characters, letters, digits and underscore, with at least one letter, and unique without regard to case. It is chosen once.
• Unverified email: the player is not signed in; the page says to open the link in Auth0's message and sign in again. Auth0 sends that message itself; the site sends no mail at sign-up.
• Sign out ends the site's session, then Auth0's, which sends the player home. Sign-out is a form, not a link, so a page cannot sign a player out by loading an image.
• The session is a cookie set only at sign-in (a visitor who never signs in gets none), secure, HTTP-only, same-site; its id is regenerated at sign-in. Forms carry a token from the session.
• Discord linking (Jim's own site code, brought over through the crossings list 2026-10-12; Marlinspike, 2026-10-12: "one role, tell them to join first"). On the account page a player connects their Discord account: the site asks Discord for their id and nothing else (the scope is identify), checks with its bot that they are a member of the Naval Gaming server, and if so stores the id and gives them one role, which opens the members' channels. A player not in the server is told to join first, with the invite; the site never adds them. One Discord account links to one player. Disconnecting takes the role back, so the role means "linked now". Connect and Disconnect are forms with the session's token.
• Pages: /signin/, /signup/, /auth_callback.php (the path registered with Auth0; Marlinspike, 2026-10-12: keep it), /username/, /account/ (the name and email, Discord, and sign out), /signout/, /discord/connect/, /discord_callback.php and /discord/unlink/. The header shows Sign in, or the player's name.
• Admin (Marlinspike, 2026-10-12: "my account will be admin"). The admins are named by player id in the code (player 1, Marlinspike, on dev and production), so adding one is a commit, not a setting.
  • Pages: /admin/, the section's index, /admin/sounds/, the sound board, and /admin/reports/, the error reports (see The logbook).
  • The gate: each page checks on the server. A visitor not signed in is sent to sign in and back. A signed-in player who is not an admin finds the page not there (404), so the section doesn't announce itself.
  • The header: it shows an admin an Admin link beside their name.
• Storage: one table, players (issuer, subject, email, username, Discord id, created, last seen), in a new, small database of this site's own on the droplet, through the site's own mysqli helper with prepared statements. Secrets live in a server-local key file that is never committed. The import of the old site's players (issuer, subject, username) is a later, separate step.

The logbook

Marlinspike, 2026-10-19: every battle and voyage is logged, full enough to recreate it, and shown on the account. The code is www/play/logbook/.

• What it holds. A track: every ship's place, heading, sail and state (struck, aground, a mast down) and the wind, every 2 s of sim time. The battle's log kept whole: every shot fired, splash, hit, strike and prize (the battle itself keeps only a few seconds of it). The player's own entries. And a rerun: the battle as it stood at a start, with every command and clock reading since, which replays it exactly on the version it was sailed with (see One command layer).
• Recreated from the track, and rerun from the orders (Marlinspike, 2026-10-19: "track, plus orders"). The diagrams and the replay are drawn from the track, so they draw the same however the sim changes later; the rerun is for checking an error report on its own version. A Battle Builder battle keeps its rerun from the first step. A voyage keeps the last five to ten minutes of it, since its clock readings would run to a megabyte an hour. A room keeps none: the room server runs the sim, and the page sees only its snapshots.
• The card. F1, or Log entry in the pause menu, opens a card: a text box, an Error report check, Save and Cancel. It pauses as the other screens do, except in a room. The entry is pinned where your ship was. A visitor is asked to sign in.
• When it is sent. A battle's logbook when you leave the fight (Fight again, another page, or closing it); a voyage's back in port, or when all your ships have struck (Marlinspike, 2026-10-19: "leaving the fight"). Error reports go with the logbook, not on their own. Until the site takes it a logbook waits in the browser, and is sent on the next visit: a closing page can't send one. A voyage's logbook is kept in the browser as it is written, and carries on when the voyage is resumed. A logbook with nothing sailed and nothing written is not kept. Only a signed-in player's are kept.
• The account lists your logbooks, newest first. Each has its page, /account/log/<id>/: the battle or voyage drawn on the game's chart, fitted to it, every ship's track, the hits and strikes, and your entries; played back with Play, a speed and a scrubber. The game's own map stays a static chart.
• Ashore (Marlinspike, 2026-10-19: "We won't be tracking; just for keeping log and error report"): F1 opens the same card, and the logbook holds only the entries, each pinned where your ped stood, in the same world metres as at sea. There is one a visit, sent whole on every Save, and the site keeps the latest copy. Its page lists the entries with when and where each was written. For now ashore is the admin's prototype, at /admin/ashore/.
• Error reports reach the admin at /admin/reports/.
• Storage: a logbooks table, one row a logbook, stamped with the commit the site ran (written by the deploy beside the checkout).

Multiplayer rooms

First after the launch (Marlinspike, 2026-10-09). The rules came through the crossings list as a description on 2026-10-14, and the transport and tickets as staged code (Marlinspike, 2026-10-14: split; guests may join). Built 2026-10-14, on dev and production: Battle Builder's Host a room, for a signed-in player, opens the battle as a room.

• The server is the authority. A room server on the droplet runs the same core modules the browser does. Browsers send orders and draw what the server sends back. The browsers do not each run the battle in step: float math differs between browser engines, and their battles would drift apart. The browser does not predict ahead either. A ship answers the helm over seconds, so a fraction of a second of lag shouldn't be felt; add prediction only if play shows it is needed. Randomness runs on the server only.
• A room is one battle. It is held in memory and dropped a minute after the last person leaves, so restarting the server (as a deploy of it does) empties every room. Nothing about a room is saved.
• Hosting and joining. A signed-in player hosts a battle and shares the room's link. Anyone with the link may join, including a visitor who is not signed in. A guest sails under a generated name and cannot host. The site vouches for each player with a short-lived signed ticket, which the browser hands to the room server in its first message, never in a URL, so it stays out of logs. The site and the room server share only the signing secret, a different one on dev and production.
• The lobby. The room lists every ship in the battle. Each player claims one, and may give it up while still in the lobby; a seat whose player has been gone ten seconds is let go. The host starts the fight. An NPC captain sails every ship no player has claimed, so the same battle serves co-op and player against player. Battle Builder's Player mark means nothing in a room.
• Joining a fight under way: no (Marlinspike, 2026-10-14: lobby only). After the start a newcomer watches; a player coming back to her own ship still takes her back.
• Signals: the host's ship is the flagship (Marlinspike, 2026-10-14). The NPC ships on her side are her squadron and answer her signals; no other player signals, and no player's ship is in the squadron. A host who claims no ship leaves the room without a flagship. A flagship under an NPC captain, her player gone, keeps her place, and the signal in force stands.
• Leaving and coming back. When a player has been gone about ten seconds, an NPC captain takes their ship. The same player coming back takes her back, and any older window of theirs is closed. A player whose ship strikes watches.
• Orders. Held controls (the helm and the yards) are sent when they change and replace the last ones. Presses (sail, fire, hold fire, ammunition, trim) queue until the next step and merge as the keyboard's do. No pause and no time scale.
• What the browser draws. The server sends each ship's state about ten times a second, with the shots and hits since the last time. The browser draws a moment about 0.15 s behind the newest it has, judging the lag by the smallest it has seen over the last two seconds, not ever: the lobby's clock stands still until the start, which makes an all-time smallest lag far too small. Judge smoothness by how often a frame shows the same moment as the frame before, not by frames per second.
• Limits. Measured on the droplet with tools/roomcost.js (2026-10-14): a frigate duel with two people costs 1.7% of a core; a full room, sixteen ships and sixteen people, 15%. So six rooms at once, about one of the box's two cores in the worst case, sixteen people to a room, and Battle Builder's eight ships a side. Snapshots are compressed: a full battle's is under 4 KB. Each connection is capped in messages a second and in message size, and each address in open connections.
• Transport. The room server answers secure WebSockets itself, on its own port, with the site's certificate, so it holds none of Apache's workers (the box runs a small, fixed number of them). It refuses to listen beyond the machine without TLS.
• Watching (the build's choice, open for Marlinspike): a watcher, with no ship of her own, follows the battle's first ship.

Boats

Marlinspike's rules (2026-09-27 to 2026-10-01), brought over 2026-10-14 (Corona 8). In Battle Builder and Corona del Mar; not yet in multiplayer rooms, where B does nothing (Marlinspike, 2026-10-14).

• Every ship carries a boat on deck (Marlinspike, 2026-09-30): a launch on the ships with a waist (the first rate, the seventy-four and the frigate), a jolly boat on the brig and the cutter. A boat is a hull of its own, rowed, with its own small crew and no guns. Its sizes are its drawing's; its speeds and handling are tuning guesses, set by play.
• Rowing (2026-09-27): the stroke is back water, hold water, easy or full. Sail steps it round: hold water, easy, full, back water. Hold water is where a boat left alone rests, so it lies still. The wind doesn't move a boat, and it doesn't heel. Backing water, the helm works the other way round, as astern in a ship. The compass panel's sail row reads Oars.
• Lowering (B): in your ship, with her boat on deck and under 2 knots, B lowers the boat, about 10 seconds, and you go down into it. It comes down alongside to leeward.
• Going aboard (B): in a boat within 20 m of a ship's side, both under 2 knots, B puts you aboard, about 15 seconds: the boat's own ship, or any ship you have commanded. Nobody takes a ship that hasn't struck. The boat is hoisted in on its own ship.
• It takes time. The conditions must hold throughout or the work stops, with a short line saying why; refused, B says why the same way (the words are placeholders, Marlinspike's to set). B again stops the work.
• The ship you leave lies to under an NPC captain, where you left her: sails in, helm amidships, and she fights whichever broadside bears from where she lies, standing by the boat. She doesn't hold her course (Marlinspike, 2026-09-30). She stays in your squadron, and you can go back to her.
• The flagship crosses with you (Marlinspike, 2026-10-26): the ship you command is the flagship, and you signal from her, a prize too. The ship you left, under her captain, joins the squadron and answers your signals. A signal in force when you change ships is lost, as one is when a flagship strikes. In a room boats stay stowed, so the host's ship keeps the flag.
• No men move. The boat has its own crew, and the ship's count is unchanged.
• A struck enemy boarded is a prize (Marlinspike, 2026-09-30): no longer struck, on your side, at full morale with her surviving crew, and yours to command; her captain's name goes. Her morale counts only the men she loses from then on. Boarding never un-strikes your own side: a struck ship of yours is no ship to board.
• No limit to the ships at sea, prizes included (Marlinspike, 2026-10-16: "i don't think we need a cap"; it was four, then two, from 2026-10-04): on Corona del Mar, as in Battle Builder, only the crew limits the ships you take.
• Striking (Marlinspike, 2026-10-01): a ship that strikes is a derelict. With you aboard, once she has furled and lost her way below 2 knots, her boat is lowered as B lowers it, and B can't stop it (the strike notice: see Morale and striking). A captained ship that strikes puts no boat off.
• NPC captains take prizes, as you do (Marlinspike, 2026-10-16: "Should work just like a player"): any captain, the Cabal's and your squadron's, in Battle Builder and on Corona del Mar, not in a room. With a struck enemy within 1,500 m and no enemy still fighting that near, a captain closes under topsails, and within 150 m rounds up into the wind and heaves to with his topsails aback; once she is all but stopped he lowers his boat, which rows across and boards her (both tuning guesses, set by play). She is a prize as yours are: no longer struck, on his side, at full morale with her surviving crew, in his squadron if he is in one. He crosses in the boat and commands her, as you would (Marlinspike, 2026-10-25); the boat is hoisted in, and the ship he left sails on under a new captain. One boat goes for each prize; if she is gone before it gets there, it rows home. A ship the Cabal has taken is retaken as any enemy is: made to strike, then boarded.
• A struck captain takes no prize: from the boat of a ship that struck, you may board no struck enemy until you are back in command of a ship. You may still go back to a ship you had.
• No boat is fired on. Guns and captains pass a boat over, a boat in a gun's arc doesn't stop it firing past, and shot passes through one, so a boat loses no men and never strikes. It still takes the ground.
• Drawn rowing (Marlinspike's design, copied from the old sim): her oars pulling and feathering through the stroke, or tossed upright when she lies still; a rower to each oar, two to a thwart, facing aft; the coxswain at the tiller and an officer in the stern sheets. Her ship's deck is empty of her while she is away.

Corona del Mar

Being built, one piece at a time, from the crossings list (Corona 1 to 9). What is built so far is below; the rest stays on the Later list until it lands.

• One world, two sims (Marlinspike, 2026-10-18): the deck and the quay are two simulations over the same world, and the walk ashore runs on the server. The rule is in ch. 7.
• An open world, one sea for everyone, played alone (Marlinspike, 2026-10-14). Corona del Mar is not multiplayer: no other player is ever in your sea. But it is one sea:
  • The world runs on the clock. Everything outside your own ships is worked out from UTC, so every player who looks at the same moment sees the same sea: the wind first, and in time the traffic in and out of Corona; the Cabal's ships come on the clock's slots (below). What you do changes your own sea.
  • What captains do leaves traces. The consequences of every player's voyages are recorded on the server and read back by everyone: what was taken, lost or sunk shows in everyone's sea and in the port, though no one ever meets.
  • Which parts of the world follow the clock, which traces are kept and for how long, and what a pause or the time scale means in a world that runs on the clock are still to be decided.
• The sea (Marlinspike's design, 2026-09-30 to 2026-10-04, brought over 2026-10-14): an enclosed sea about 38 by 23 km, the land all round it. In the middle, an island about 10 by 4 km, with the town of Corona, the Crown's capital, on a bay in its south coast. Off the bay lies a barrier island about 2.6 km long, a wooded ridge along it high enough to stop shot; between it and the shore is the anchorage, sheltered water about 25 m deep, open through a channel of about 500 m to the west and wide to the east. On the east shore, a peninsula, a gulf with an island in it, and the village of Puerto Cabral at the gulf's head; an islet off the peninsula; a sound in the north-east. South of the central island, two low cays and the south bank, a reef about 5 km long with no dry part. The outlines were modelled on real coasts and then edited by hand: the sea is not meant to be any real place (Marlinspike, 2026-10-09). Only the two towns are named; the rest stays unnamed.
• Its look (Marlinspike, 2026-10-17): inspired by 18th-century Southeast Asia, the regional look and local craft first. Palms and mangroves on the low shores; houses of thatch on stilts outside Corona's walls; local craft moored about the harbour. Local craft are scenery for now: the Cabal's ships at sea are still this game's classes.
  • The local craft: two junks and four prahus in the inner harbour, each made fast alongside one of the quay's finger piers (Marlinspike, 2026-10-20), the junks near the fingers' ends where the water is deeper, their sails lowered at the mooring (Marlinspike, 2026-10-17): the junks' folded in stacks on their booms, the prahus' rolled along the deck. Like the moored ships, their hulls are solid and stop neither shot nor sight. Their sizes are tuning guesses, set by look.
  • The land: coconut palms over the low ground, a spreading broadleaf above, and mangroves in patches at the waterline; about fifty thatched houses on stilts on the shores either side of the town, outside its cleared ground. The mangroves and the houses are too low to stop shot or hide a ship; the trees above the tree line still do.
• Its land follows the island's rules (The island and grounding): it stops shot and blocks sight, a ship grounds on its shores and backs off, and captains keep off its shoals. The shores rise behind dunes, as the island's do, to heights set by eye: the land round the sea to about 45 m, the central island to about 40 m. The land all round is a shore like any other: a ship can't leave the sea.
• The south bank: Marlinspike's purpose is that a small, shallow-draught ship crosses it and a larger one runs aground on it. Its crest was set by eye at 3.4 m; against this repo's draughts that let the brig and frigate across, so it is 3 m (2026-10-14), as on the island's shoal: the cutter crosses it and every bigger ship grounds.
• The dredged basin (Jim, 2026-10-17: "dredge deep enough for a first rate on the seaward side of the mole"): off the long mole's seaward face the sea bed is 10 m down, along the mole's whole length and 150 m out, past where ships put to sea lie: a first-rate's 7.8 m draught and the captains' 2 m margin, rounded up. Elsewhere the bed is as the shores make it.
• The town of Corona (Marlinspike's design, 2026-09-30 to 2026-10-04, brought over 2026-10-14; rebuilt as a Southeast Asian trading port, Marlinspike, 2026-10-19: "There are way too many multistory buildings. This is a Southeast Asian trading hub."): a walled town facing the sea due south, with a bastion at each corner of its curtain wall, open on the seaward side to the waterfront, and a land gate at the back. A plaza behind the waterfront. Its quarters: rows of shophouses on the streets, narrow-fronted on deep lots, each with a covered walkway of tiles on posts before its door, mostly of one storey, about a quarter of two near the main street and the plaza; low warehouses along the waterfront; a quarter of timber houses on stilts with thatched roofs on the citadel's side, among gardens and palms, on bare ground; a Chinese temple with a swept roof among the shophouses, and a mosque with a tiered roof in the stilt houses' quarter; and a small European core in masonry: the cathedral, the governor's house, a customs house on the apron and a citadel. In front, an inner harbour closed by a mole and a counter-mole, a light on the mole's head. The port is busy: goods stacked on the apron, a crane on the sea wall, a tall flagstaff flying the Crown's ensign, bollards on the moles cast as old guns set breech up, people walking and standing about the waterfront, the piers, the plaza and the main street, chimney smoke and flags blowing downwind. The people are the townsfolk (Marlinspike, 2026-10-20: "Local fishermen, laborers, Western sea captains and sailors, Chinese mandarins, Seik sepoys, muslim traders, and female versions of all"): seven kinds, a man and a woman of each, each in the dress of his kind, by eye: the fisherfolk dressed as Vietnamese (Marlinspike, 2026-10-20: "Think vietnamese"), man and woman alike in a loose ao to below the hips over wide trousers, barefoot, under a conical hat; a labourer in a long-sleeved shirt and short pants to below the knee, barefoot, half of them in a headcloth and half in the fishers' conical hat (Marlinspike, 2026-10-24; the data holds the hatted half as a kind of its own), a captain in a long brown coat cut as the deck officer's (Marlinspike, 2026-10-24) and tricorne, a sailor in a neckerchief and round hat, a mandarin in a robe and his hat of rank, a sepoy in a red coat, sash and turban, a trader in a long tunic and cap; the other women in skirts or tunics, scarves and their hair up. Most of the town are fishers and labourers (Marlinspike, 2026-10-20: "most of the population will be fishers and laborers"), each of them in a few colourings of their clothes; then more hands than gentlemen. Each kind has its share of the crowd and every figure and colouring is in it. Every man stands the same height and every woman the same (Marlinspike, 2026-10-20: "use standard height for man and women"). Drawing only. The roofs stay cover by the rule below, so the lower town hides less (Marlinspike: "let it follow"). The town's ground is bare (Marlinspike, 2026-10-19: "irregular, splotchy, sandy spots, weeds"; "in the town circle, we want bare ground with cobblestone paths"): packed earth, darker where damp and paler where dusty, with sandy spots and weeds in clumps and crowding the foot of every wall, post and palm, where no foot treads; a cobbled path about 3½ m wide runs down the middle of each street inside the wall, its edges ragged, between bare verges. The plaza and the stilt houses' quarter are bare, and so is the apron (Marlinspike, 2026-10-19: "apply that ground to the apron"). Pebbles lie over all of it, thickest where a path's edge breaks up, and the litter of a port, stones, shards of roof tile and sticks, collects at the foot of walls, posts and works ("add pebbles and debris to the open ground"). The weeds and the litter are drawing only: a ped walks through them. The ground inside the wall is made ground, never lower than 0.5 m above the water (Marlinspike, 2026-10-19: "I am unable to walk from apron to town"; he chose to fill it), so he walks off the apron into the town anywhere along it. Every size, colour and placement was set by eye.
• The waterfront (Marlinspike, 2026-10-19: "replace the quay with a sea wall, periodic stairs from the ground. On the water side, add a pier, and periodic stairs from the top of the sea wall down to the pier"; "same height as the mole"; and later that day: "The seawall and mole needs to be weathered dark large stone blocks. There needs to be a pier running the length of the seawall with fingers that go out into the basin. The steps up and down from the seawall need to paralel the seawall"; "the apron need to be bare ground"; "pier should be weathered dark wood, no bolarde, the piling come up above the peir deck"; "make piliings round, different texture, like a telephone pole"; "put stairs on both sides of landing"). Where the quay was, a sea wall stands at the water, 4 m thick and 3 m high, as high as the moles, turned back up both ends; it and the moles are built of large, dark, weathered stone blocks. Behind it the ground is filled level with the town's at its back edge, the apron, bare ground, so it runs on into the plaza without a step. A pier of weathered dark timber runs the sea wall's whole water face, 6 m wide, its deck 1 m above the water, and four fingers of the same run out from it into the inner harbour, 40 m from the wall; their piles stand up through the deck, round, like telephone poles, and there are no bollards on them. Every 40 m along the wall there is a level landing at the wall's height against each face, one over the apron and one over the pier, each with a flight up to it along the wall from both ends; he steps between the wall's top and a landing anywhere along it (Marlinspike chose landings, 2026-10-19). The same pier runs along both faces of the long mole (Marlinspike, 2026-10-20), from where the water begins at its root, round its bend, to its head, with a landing and its two flights up to the mole's top every 40 m. Each mole has a stair up onto it at its root: off its end where the ground there is clear of the town wall, else up its side from the higher ground. A stair climbs about 35 degrees. Ashore, a ped with no place of his own starts on the apron a few metres seaward of the flagstaff, facing it (Marlinspike, 2026-10-19: "make the ashore spawn point near the flagpole"). All of it by eye.
• The waterfront, its piers, fingers and stairs, and the moles are solid to a ship (Marlinspike, 2026-10-09, for the quay and the moles; the waterfront that replaced the quay, 2026-10-19): there is no water on them, so a ship that runs into one is aground, as on a shore, and backs off the same way. They are too low to stop shot.
• The town wall and the roofs stop shot and hide ships, as the trees do (Marlinspike, 2026-10-09 for shot; 2026-10-14 for sight). No trees grow on the town's ground or on its works.
• Ships lie moored off Corona (Marlinspike, 2026-09-30 and 2026-10-04): eleven of mixed sizes in one line just north of the barrier island, in about 13 m of water, bows east, about 40 m from one's stern to the next one's bow, moored fore and aft with sails furled and people aboard. They are scenery, in no one's fleet, drawn from this game's classes. Their hulls are solid, so a ship whose bow runs into one is aground; they don't stop shot or hide a ship.
• Ashore (Marlinspike, 2026-10-04, brought over 2026-10-14, Corona 3): you start ashore at Corona, with no ship. Ashore nothing happens at sea: the sea is hidden and the port panel stands on its own picture, the tavern (Marlinspike's). The panel is headed "Welcome to Corona" (his title) and shows your name (there are no ranks yet), your crew ("Crew", the men the chosen ships need over the men you have), a row for each warship you may take, smallest crew first. A row has a radio for the ship to command, the class, the crew it needs, and − and + for how many; one the crew can't man is dimmed. To begin, and whenever the crew no longer covers the choice, it is one cutter, commanded.
• The crew (Marlinspike, 2026-10-04, Corona 4): every ship is the same from one voyage to the next; what grows is the crew. Put to Sea takes as many ships as the crew can man, each at her full complement, as many as it can man (no cap: Marlinspike, 2026-10-16); the men not taken wait ashore. Your crew is never below the smallest warship's, the cutter's, so you can always man one. The brigantine, unarmed, is not offered.
• What comes ashore is what counts (Marlinspike, 2026-10-04; built 2026-10-16). Going ashore, your crew becomes the men who waited ashore, the men still aboard every ship of yours that hasn't struck, prizes included, and the men in the boat of a ship that struck; never less than the floor. A ship that struck is lost with her men. Losses at sea cost men; a prize's surviving crew joins yours.
• Kept with your account (Marlinspike, 2026-10-04; built 2026-10-16). Signed in, your crew is saved when you come ashore and follows you between visits and devices. It changes only when you come ashore (Marlinspike, 2026-10-16). The game runs in your browser, so the site takes its count as it comes (Marlinspike, 2026-10-16). A visitor who isn't signed in sails with the floor every time. Hiring is still to come.
• Putting to sea (Put to Sea, or P): the ships lie off the long mole, about 100 m out from its seaward face, bows to seaward, a few metres apart side to side. With the wind ahead of the beam, each lies turned 60° off it, so it can sail off and is never in irons. One that won't fit off the mole lies in the anchorage. You start in the commanded ship's boat at the mole, row out and board her with B (see Boats); the ships lie to with their sails in until then. The other is in your squadron, captained, lying to until you signal. Battle Builder's rule that a side is never empty doesn't apply here.
• Going ashore: within 1 km of Corona the greeting "Welcome to Corona" shows over the station bar, at any speed. Within 1 km and under 3 knots, a Go ashore button comes up beside it; it, or P, takes you ashore. Refused, P says which condition failed, with the distance or the speed (the words are placeholders). The ship you are in counts, or your boat. From the boat of a ship that struck you may go ashore anywhere. Going ashore takes every ship of yours off the sea.
• Leaving keeps your place (Marlinspike, 2026-10-04 and 2026-10-05; built 2026-10-16, Corona 5). Close the page or lose the line at sea, and when you come back to Corona del Mar you are where you were: every ship as she was, yours and the Cabal's (Marlinspike, 2026-10-16: a reload never gets you out of a fight), and the men who waited ashore. Ashore is a place too: leave ashore and you come back ashore. If all your ships have struck, the voyage is over and you are kept ashore with the men left. The wind isn't kept: it is the clock's. Names go on from where they were, so none comes twice. For the same reason Corona del Mar's menu has no Fight again. The voyage is kept in your browser, always, every few seconds; signed in, with your account too, at once on putting to sea, going ashore, a strike or a prize, every half minute at sea and as the page closes. The account's copy wins; an account with none takes the voyage this browser sailed, so a visitor who signs in carries their voyage on. A bad save is no save: it is read as ashore.
• The wind follows the clock (Marlinspike, 2026-10-04, brought over 2026-10-14). It goes once round the compass, clockwise, every two hours of UTC: from the north on each even hour, from the east at half past, from the south on the odd hour and from the west at half past that, turning steadily, three degrees a minute. Everyone at sea has the same wind at the same moment, read off the clock, not set by a seed or a choice. Its strength never changes: one steady strength, Battle Builder's, a tuning guess set by play. There are no random shifts.
• The wind is always the clock's (Marlinspike, 2026-10-14), at any time scale and after a pause. The core never reads a clock itself: the page reads it each step and hands the reading to the core with the step's commands, so a voyage's readings replay it exactly.
• The sea follows behind the wind (Marlinspike, 2026-10-04): the swell doesn't swing round with the wind. A new swell builds from the wind's new direction as the old one dies away: one for every 15° of the wind's turn, five minutes apart, by eye. So the waves run, on average, 15° behind the wind and are never far behind it. The short chop and the whitecaps follow the wind at once.
• The Cabal at sea (Marlinspike, 2026-10-04, brought over and built 2026-10-15, Corona 6):
  • An event (2026-10-17): the first of Corona's events, a patrol. An event is a file the game runs, and most are made from a template, a kind of event with blanks each event fills in; this one, event 1, is the plainest patrol: it fills in the patrol's with the Cabal, ten minutes, a cutter, and south-east (Jim, 2026-10-17). What follows is the patrol as it is filled in.
  • One Cabal ship at a time. None comes while one is afloat unstruck, nor while you are ashore, and going ashore takes it off the sea.
  • On the clock (Marlinspike, 2026-10-15). The clock is cut into slots of ten minutes, a tuning guess; each slot has its one Cabal ship, where it comes drawn from the slot alone, so everyone at sea at the same moment meets the same ship. Each is a cutter (Jim, 2026-10-17: event 1 made the plainest patrol; every fifth was a brig until then).
  • Once a voyage (Jim, 2026-10-17: event 1 doesn't loop). The first slot after you put to sea brings one cutter; once she is beaten, none comes again until you go ashore and put to sea again. A voyage resumed after leaving the game is the same voyage, so it brings no second one.
  • Where it comes: south-east of Corona, on a bearing from the town of 112.5° to 157.5°, no nearer than 1.5 km and no farther than a captain's sight; in water deep enough for her, with a few hundred metres clear of shoals and of every other vessel; on a random heading.
  • It waits, then fights. It lies to where it came until an enemy ship clear of the port (beyond the greeting's 1 km) comes within its captain's sight: the ship you are aboard, or the mail boat (Jim, 2026-10-19), so ships lying off the mole don't rouse it (Marlinspike, 2026-10-15). Then it fights as any NPC captain does, and once roused it may come for your ships at the mole (Jim, 2026-10-19: "let her come").
  • Sight (Marlinspike, 2026-10-15): on Corona del Mar a captain sees 2.8 km, where the haze ends the view, a tuning guess set by play, and the land still blocks it. In Battle Builder a captain sees to any range the land allows.
  • The chart marks it, in sight or not: a red cross in a ring, a placeholder.
  • The guns are for the Cabal only: no player against player, and a ball passes through any ship of the firer's own side.
  • Struck ships: a struck Cabal ship is a prize to board (see Boats). A struck ship that no unstruck ship of the Crown can see, checked once a second, is cleared away with her boat, but never the one you are in, nor one whose boat you are in.
  • Its captain is numbered on from the voyage's captains, its ship on from her class (see Names). Its temper and competence are drawn from the slot, like its place.
  • It is saved with your voyage, a fight included (see Leaving keeps your place, above).
• The mail boat (event 2; Jim, 2026-10-17): something to protect, and the Cabal's prey.
  • Every hour, on the hour, a brigantine of the Crown sails from her berth out in Corona bay, south of the long mole: east out of the bay, through the passage at the barrier island's east end, round the island's south side, back into the bay by the narrow west passage, and to her berth again, where she heaves to and leaves the sea. A boat for each hour, so two can be at sea at once. Her route is a list of named places on the chart.
  • She sails as any captain does, by the real physics in the clock wind. Beating to windward she keeps within a corridor about the line between her places, 400 m either side, a tuning guess, going about at its edges rather than standing off on one long board (Jim, 2026-10-17). In the turning wind a trip begun on the even hour takes about 47 minutes and one on the odd hour about 107.
  • Where the clock says: the wind repeats every two hours, so there are two kinds of trip, worked out ahead and kept as a snapshot every 10 minutes (Jim, 2026-10-17). Put to sea mid-trip and each boat under way is where her last snapshot has her, the same for everyone in the same 10 minutes.
  • Attacked, she runs for her berth by the shorter way, back or on. Attacked is the first shot fired at her by the Cabal (Marlinspike, 2026-10-18), a player's as much as a captain's; a captain merely having her in its sights is not. If one strikes, no more sail that voyage.
  • Her berth is out in the bay, not alongside the mole: the sim has no mooring yet, and a square-rigger beating up to a berth close under the mole runs onto the west mole (see the plan for mooring and warping).
• Corona del Mar is reached from its card on the home page, or the pause menu's Corona del Mar button, at /play/#corona, ashore. The pause menu's Leave goes back to the home page, the voyage kept (Marlinspike, 2026-10-17: it had opened Battle Builder). At sea the page's address names the ships taken (#corona&sail=cutter). The chart letters only the two towns.

3. Controls

The sailing keys are Marlinspike's (2026-10-06): helm and sail on A/D and W/S, yards on Q/E and Z/C, auto-trim on F, a double tap for hard over. Since 2026-10-10 the helm steps a place a press, with no holding and no double tap, and sail is one key, S, stepping round none, topsails, full, and W and ↑ / ↓ are unbound (Marlinspike). The gun and signal keys are his too (2026-10-06). The rebuild plan asked for controls designed fresh; these are Marlinspike's choice as owner, made deliberately. A check before the launch found that the sailing keys match an earlier game's default layout, and Marlinspike kept them (2026-10-09: "keep the key layout, record it as my decision"). The controls panel is generated from the bindings, so this table and the game can't drift apart once the code exists.

The idea: the left hand sails and trims, the right hand fights, the mouse looks.

Keyboard

While the signal list is open, ↑ / ↓ move through the list and ← / → do nothing. A / D / W / S, the yards and the gun keys stay live (Marlinspike, 2026-10-06).

Mouse

Touch

A phone or tablet plays the same game (Marlinspike, 2026-10-10): every touch button is one of the keys above, pressed and let go, so a touch player and a keyboard player sail the same ship, and the yards' hold and double tap work the same. The touch controls show on a touch screen, held either way up; upright, the view keeps its width across, so it shows more sea and sky top to bottom rather than narrowing. Added to the home screen, the game runs without the browser's bars.

Portrait first (Marlinspike, 2026-10-10: "this really is best in portrait"; "keep both, portrait first"). A phone is laid out upright first; held sideways it still plays, and a tablet uses that layout. New touch controls are designed for portrait, then fitted to landscape.

The bindings carry each control's touch form, so the guide's touch table and the in-game Controls screen on a touch screen are generated from them, as the keys' are.

Not bound at launch

Gamepad and rebinding. Keys for later features (range rings) are not reserved; they are chosen when those features are specified.

4. Ships

Five classes at launch (Marlinspike, 2026-10-06): four square-rigged, sharing one rig model, and one fore-and-aft cutter with its own. A sixth, the brigantine (Marlinspike, 2026-10-16), has a rig model of her own, both rigs at once, and sails only in the shipyard's Sea Trial: unarmed, she is no warship. Each class takes its numbers from one real ship or class, cited below. Where armament varied from ship to ship, the class takes its cited ship's exactly and notes the variance (Marlinspike, 2026-10-06). The real ship is the source, not a name in play: in the game a class is "the First Rate", "the Seventy-four" and so on, and individual ships get placeholder names and numbers (Marlinspike, 2026-10-01).

Confidence: H consistent across sources or from a primary or academic text; M one secondary source; L an uncited page or a clash. Source keys are in Sources. Draught is missing for five of the six and best speed for four. Those cells say so; they are not to be filled from memory.

First Rate: HMS Victory (1765), as at Trafalgar, 1805

Source: [VICTORY], which cites Goodwin, Lavery and Winchester.

Seventy-four: the Arrogant class

Source: [ARROGANT], which cites Winfield 2007, pp. 64 and 77, and Lavery 1984, p. 176.

Frigate: HMS Shannon (1806), a 38 of the Leda class

Sources: [SHANNON], [LEDA], citing Winfield 2007 and Gardiner 2000 (no pages given).

Shannon is also the source of the best-recorded single-ship action of the period: it took Chesapeake in 11 minutes (see Pacing).

Brig: the Cruizer class brig-sloop

Source: [CRUIZER], which cites Winfield 2008, pp. 282 and 291.

The brig's broadside is all carronade: heavy at close range and short-ranged. That is a real difference between classes, and play should keep it.

Cutter: HMS Surly (1806), Cheerful class

Source: [SURLY], which cites Winfield, British Warships in the Age of Sail 1817–1863, 2014, p. 267 (the later volume). Kept (Marlinspike, 2026-10-06): built in 1806, it is in period; an earlier cutter replaces it only if a better-suited one turns up.

Brigantine: the merchant brigantine Amazon (1861), later the Mary Celeste

Source: [CELESTE]. Chosen (Marlinspike, 2026-10-16): no brigantine of the period with her particulars on record turned up, and she is well documented. Her numbers are as built, before the 1872 rebuild. A trader, not a warship: no guns, and a small crew (Marlinspike, 2026-10-01); handling goes by shares of the crew, so she sails the same however few they are.

Her best speed (9 knots), her closest angle (5 points, between the cutter's 4 and the brig's 6), her handling times and her whole rig model are tuning guesses, set by play.

What each class needs that history doesn't give

These are tuning guesses, set by play, until a source turns up:

• best speed for the Seventy-four, the brig, the brigantine and the cutter;
• draught, used only for drawing and for hit shapes below the waterline;
• the pivot point for turning, and how the yard groups' push divides between bow and stern;
• the hull and rig hit shapes, derived from the particulars above (see Physics: hits).

5. Physics

How the sim works out speed, turning, shot, hits and morale, and where each number comes from. Every quantity below is either cited (source keys in Sources), derived by stated physics from cited quantities, or marked tuning guess or citation needed.

The sim core runs on a fixed step with a seeded random number generator, so the same inputs give the same battle (Architecture). The water is flat for physics; swell is drawn, not simulated.

Speed: the polar

Each class has a polar: its best speed through the water at each angle off the true wind, under full sail, in the engagement's wind. Polars are generated by a small sail-force model and stored as JSON tables, one per class (from its rig's inputs and its own closest angle), so the clean-room check can compare them as tables. The model has few inputs, each with its source:

The brigantine's rig model (Marlinspike, 2026-09-28; built 2026-10-16) is both at once: fore yards that brace round as far as a brig's, a gaff main and staysails sheeted as the cutter's, and headsails as a square rig's, each group trimmed its own way. Every input is a tuning guess. Her close-hauled share is lower than the other rigs' (0.57), since her fore yards barely fill there; it is set where her fitted lift lands with theirs. Her windward angle is 57½°, inside the brig's 62½°.

Leeway matters: at 7 points close-hauled with a point of leeway, a ship makes good 8 points and gains no ground to windward (Willis 2003). The sim models leeway as a sideways drift, so this comes out of the model rather than being written in. Play uses half a point close-hauled (Marlinspike, 2026-10-07: weatherliness was too harsh). Willis's range, a quarter point for the best ships to a point for most, is the note, not a limit.

Weatherliness is a class trait (Marlinspike, 2026-10-07). With every square-rigger at 7 points, none could gain ground to windward, so the weather gage could be kept but never won. Each class now has its own closest angle, set by play, and the no-go zone grows from each class to the next larger (Marlinspike, 2026-10-09): the brig 6 points, the handy one; the frigate 6½; the Seventy-four 6¾; the First Rate 7, the most leewardly. Willis's 6 to 7 points is the note, not a limit. The frigate's class was "unweatherly" (Gardiner via [LEDA]), nearer 7 than 6; play moved it to 6½. Sailed full and by in 8 m/s of wind, the cutter gains about 3.8 knots to windward, the brig 2.5, the frigate 1.9, the Seventy-four 1.2 and the First Rate 0.8.

Pinching (Marlinspike, 2026-10-09; tried and dropped on 2026-10-07, brought back in this form). Each side of the no-go zone has a shoulder where she pinches: inside the closest angle her sails still draw, at falling speed, down to nothing at the shoulder's inner edge. Inside that is the dead core. Each shoulder is a share of the whole no-go wedge (twice the closest angle), so it grows with the wedge from cutter to First Rate; the share is the pinch lever (Pacing), a tuning guess set by play, at 15%: cutter 13½°, brig 20°, frigate 22°, Seventy-four 23°, First Rate 23½°. A shoulder is held to the sail's luff angle: past it, a square sail braced hard round is aback, not pinching. Pinched a little inside the closest angle, a square-rigger makes more ground to windward than sailed full and by: in 8 m/s, at her best, the brig about 2.6 knots, the frigate 2.35, the Seventy-four 1.7, the First Rate 1.45. The cutter gains nothing by it. The compass rose shows the shoulders pale and the core darker. Captains pinch too (Marlinspike, 2026-10-09): each class's windward angle, where she makes most ground to windward with her leeway allowed for, is worked out with her polar, and a captain sails no closer than that: about 10° inside the closest angle for the First Rate, 5° for the brig, at it for the cutter.

Speed: from polar to speed

• Sail level scales the drive: topsails give a share of full sail's drive (tuning guess), none gives only the drift of the hull and rig.
• Yard angle scales each group's drive by how well it is trimmed to the true wind, the wind the polar and the cited closest angles are measured against (Marlinspike, 2026-10-06: trimmed to the apparent wind, a square rig luffed at speed on a beam reach and made a third of its polar speed). A group with the wind on the front of its sails drives astern (aback), as hard as the same force would drive her ahead.
• Rig damage takes a share of drive per rig hit, for good (Marlinspike, 2026-10-06). The share is a tuning guess (the hit-effect lever, Pacing). A fallen mast takes its own sails' drive, so the drive left comes from the masts still standing, and the turning force each mast's sails give forward or aft of the pivot goes with it (Marlinspike, 2026-10-08).
• Momentum against drag (Marlinspike, 2026-10-07: braking and sternway were far too slow). The sails push and the hull drags as the square of her speed (physics), so she settles at the speed the sails give, a fast ship sheds speed quickly, and backed sails stop her: a frigate at 11 knots, braced aback, stops in about half a minute over two ship lengths. Stern first the hull drags much harder (a tuning guess), so sternway comes quickly and stays at two knots or so. The hull also drags in proportion to her speed (Marlinspike, 2026-10-19: with sail in she carried her way for minutes and never stopped). It is the larger part below about 6 knots, so a ship with sail in comes to rest: a cutter from 10 knots is at half a knot a minute after the order, a frigate in about two and a half minutes. Backing the yards is still the quick way to stop. The sails overcome this drag in proportion to what they set, so full sail still makes the polar's speed and part sail a little less; stern first it is no harder, being the water along her hull, not the water her shape pushes aside. Its strength is a tuning guess, set by play. How quickly she gathers way is set by her displacement (burthen, cited per class), a tuning guess and the same drag, on the game clock: a frigate makes 90% of her speed from rest in about 40 s.

Turning

• The rudder's turning force grows with the square of speed through the water (a foil's lift; physics), so a ship with no way on can't steer, and the turn rate grows with speed.
• The turning circle is on the order of a few ship lengths: even the handiest ships of the period "would only wear in four times the ship's length" (Willis 2003, H). Each class's circle is a tuning guess against that anchor.
• The yards turn the ship too. Each yard group's sideways force acts at its mast, forward or aft of the pivot, so it pushes the bow or the stern (physics). This is what makes the age-of-sail tack and a turn from rest possible. The sail plan balances about the pivot, as ships were rigged (Marlinspike, 2026-10-07): the yards about it, and the headsails against the spanker, so with everything set she sails straight, and with the yards edge-on to the wind she lies still. Bracing the fore yards turns her head off the wind, the main yards up into it. The pivot, a little abaft midships, and the places of the sails are tuning guesses.
• The helm goes over in a few seconds, and a yard group braces across its whole range in a few seconds: both run on the game clock, like sail. Bigger ships are slower at sail, yards and helm than smaller ones (Marlinspike, 2026-10-06). The exact times are tuning guesses.
• Tacking took about 5 minutes for a well-trained crew: citation needed (found only in search summaries). Wearing turned the ship through 20 points, 8 more than tacking (Willis 2003).
• Tacking and box hauling are hand skills (Marlinspike, 2026-10-07). Auto-trim braces for the most drive ahead and doesn't run a tack. By hand, as Falconer gives it: helm alee; as she comes head to wind, haul the main yards round and keep the fore yards aback; once she has fallen off past her closest angle on the new bow, let go and haul. Box hauling, out of stays: the head yards flat aback and the helm put the way she should fall off; she gathers sternway and pays off, and once the wind is abeam she fills and wears round (Falconer 1769).
• Caught in stays is a trap (Marlinspike, 2026-10-07). A ship head to wind on auto-trim, with the helm over, stays in irons; bracing by hand is the way out.
• Targets, set by play (Marlinspike, 2026-10-07): a tack by hand under full sail takes the brig at most 75 s, the frigate 90 s (not much longer than its wear), the Seventy-four 150 s and the First Rate 180 s; a box haul out of stays has her on the other tack within 6 minutes. How hard the yards turn a ship is a tuning guess, raised for these.

Sail handling

• A squadron "made all sail in fourteen minutes"; a lieutenant reckoned "five minutes to strike and stow all of the topgallants and the staysails" in a 90-gun ship (Willis 2004, H). Once the gaskets were off, sail could be set "in a flash".
• These are the historical base, but play runs on a game clock (Marlinspike, 2026-10-06: at the historical times the controls were far too sluggish). A sail order lands in seconds: a short wait while the topmen go up, then a few seconds for each step of canvas. The historical figures stay as the cited anchor and are never edited.
• Handling times are ship stats (Marlinspike, 2026-10-06: "yard speed, rudder speed, sail setting speed will be subject to modification by officers"; built 2026-10-07): the helm's time to hard over, a yard group's time across its range, the wait aloft, and the time for each step of canvas. Each class has its own, tuning guesses on the game clock, from a cutter (helm 2 s, braces 3 s, aloft 1 s, 3 s a step) to a first-rate (4, 6, 3.5 and 6 s). Like every tunable stat they are derived, so an officer can change them; the sail time-scale lever scales the sail's two across the board.
• With fewer men at the sail station, handling slows in proportion to men present over men needed (Marlinspike's rule, 2026-09-24; the proportion is a tuning guess).

Guns: rate of fire

• "A typical broadside… could be fired 2–3 times in approximately 5 minutes" ([ARTILLERY], M). "Three broadsides in five minutes were considered to be the mark of a very well worked up ship, and few warships attained such" ([DRILL], M).
• So the historical base for a full crew is 100 s per round for a crack crew, 150 s for a typical one (derived). That is the anchor; play runs on the game clock, as sail handling does (Marlinspike, 2026-10-07: "gunnery needs similar treatment (load times)"). Reload time and the time to clear a side for action are ship stats, so an officer can change them: from a cutter (14 s a reload, 6 s to clear) to a first-rate (24 s and 18 s), tuning guesses, bigger ships slower. Clearing stays slower than going between Load and Fire at Will. Men shift between stations in a few seconds. The reload time-scale lever scales reloads across the board; it stands at 3 (Marlinspike, 2026-10-07: "loading is way too fast"), so a cutter reloads in 42 s, a frigate in 60 s and a first-rate in 72 s, still quicker than the historical anchor.
• Whether bigger guns reload more slowly: citation needed. At launch, every long gun has the same base; carronades are tuning guesses.

Guns: crews

A gun with fewer men than its crew reloads more slowly, in proportion (tuning guess).

Guns: the shot

• Each ball weighs its nominal pounds; its diameter follows from the density of cast iron (physics). Check: the 1790s Blomefield 32-pdr had a 6.41 in bore with 0.233 in of windage (McConnell 1988, p. 67, via [GUN32], H), so its ball was the bore less the windage.
• Muzzle velocity: the 32-pdr long gun fired a 10 lb charge at about 487 m/s (Goodwin, via [GUN32], H). Other long guns: tuning guess near that. Carronades used ¼–⅓ of the long gun's charge ([CARRONADE], M); their velocity is derived from the charge (physics), then tuned.
• Flight: under gravity, with air drag on a sphere (physics). The drag coefficient is a tuning guess, set so these ranges come out:
  • 32-pdr long gun, extreme range about 2,000 yd ([BROADSIDE], M);
  • 68-pdr carronade, 1,280 yd at 5° elevation with a 5 lb charge ([CARRONADE], M);
  • a 24-pdr carronade's point-blank range "only about 218 yards" (Douglas 1829, pp. 118–19, H).
  Douglas's full range tables (1829, Tables VIII and XV) need a page-image check before they can be used: citation needed.
• Laying: the crew sets elevation for the range to the target as it judges it, lays ball and double halfway up the target's side, not at the waterline, and chain up into its rig (Marlinspike, 2026-10-12; the heights are tuning guesses), and aims where the target is now, with no lead (Marlinspike, 2026-09-24), plus dispersion. The judged range is off by a share of the true one (Marlinspike, 2026-10-12: range has to matter), so near point blank, where the shot flies flat, a misjudged range barely matters, and far off a ball falls short or flies over into the rig. Both errors are the accuracy lever's job (tuning guesses, set by play so that about one ball in ten strikes the hull at 1,000 m). Roll, heel and ricochet are left out.
• Maximum range is where maximum elevation stops reaching (Marlinspike, 2026-09-24). Maximum elevation is a tuning guess, set to give the cited extreme ranges. Carronades get their own, the cited 5° (proposed, 2026-10-06): at the long guns' greater elevation a 68-pdr carronade outranged an 18-pdr long gun, and the brig's carronades must stay short-ranged (see Ships).
• Battle ranges for context: decisive actions were "generally fought at ranges under 100 yd" ([CARRONADE], M); a pistol shot was 25–30 yd, a musket shot about 200 yd, a "gunshot" about 1,000 yd ([BROADSIDE], M).

Hits

• Hit shapes (Marlinspike, 2026-09-27): each ship's hull shape is built from its cited length, beam and height of side; its rig shape from its masts and sail area. Neither depends on the drawn model, and a test enforces that.
• Hull hits: a ball either goes through the side or glances off. Whether it goes through depends on its speed at impact and the angle of the hit; side thickness is citation needed, so the threshold is a tuning guess. A ball that goes through causes casualties in proportion to its path inside the hull (Marlinspike, 2026-09-24), whatever her crew (Jim, 2026-10-19: per hit, not by the crew's density), times the hit-effect lever, times the ball's weight over an 18-pounder's (Marlinspike, 2026-10-14: by weight). The rate per metre is set so a frigate at full complement loses what she did when it went by the crew's density (a tuning guess). So a rake from astern, end to end, is the great killer, a small crew breaks after fewer hits than a large one (the mail boat's eight men after a broadside or two), and a 32-pound carronade ball does nearly twice an 18-pounder's harm, a 4-pounder's under a quarter. A ship's losses no longer ease as her crew thins, so every fight came out bloodier, and the hit-effect lever was lowered with it (0.38 to 0.30, Jim, 2026-10-19): an even close action between frigates takes about five broadsides again, and play settles the rest (Pacing). The cutter is the exception: hits into a cutter take the lever at 0.85 whatever the others take (Marlinspike, 2026-10-17: 89 hull hits on a cutter and she had not struck), and an even cutter duel now takes three to five broadsides, about 15 to 30 hull hits.
• The bow is a small target (Marlinspike, 2026-10-07: a bow rake was too deadly). A ball travelling aft within 45° of the keel that strikes the fore half of the hull goes through only within the stem band, a fifth of the beam about the stem (tuning guess); anywhere else it glances. A bow rake then does about a third of a stern rake's harm, a little more than a ball through the side. The stern, glazed and lightly built, stays open.
• Rig hits hole the sails and take a share of drive (see Speed).

Morale

• Morale falls with casualties, as a share of the complement, and recovers in lulls (Marlinspike, 2026-09-24).
• The historical base for breaking: the losing British ships in four single-ship actions of 1812–13 struck at roughly 29–38% killed and wounded (computed from the figures in [GUERRIERE], [MACEDONIAN], [JAVA], [CHESAPEAKE]; no source states a rule). The trigger was more often dismasting or an unanswerable rake than a set loss. So the base breaking point is about a third of the complement, and the breaking-point lever tunes it.
• At Trafalgar, Redoutable struck "with 99 fit men out of 643" ([TRAFALGAR], H): a ship could fight far past the base. Marlinspike may want captains or crews that do (officers, later).
• Recovery in lulls is a tuning guess, and must stay slower than the slowest reload (the consistency rule in Pacing).
• Two parts (proposed, 2026-10-06, for Marlinspike): losses lower morale for good, by their share of the breaking point, so a ship strikes near the base of about a third; the same losses count again as shock, which fades in lulls, so a sudden heavy loss such as a rake can break a ship well before it. With recovery alone, a trickle of losses never broke anyone: in the first test duel two frigates fought for four hours to 88% casualties and neither struck.

6. Pacing

"I loved the idea of pacing and testing of pacing and making adjustments accordingly" (Marlinspike, 2026-10-06). Pacing is a design principle: how long fights last is measured, given a target, and adjusted by a few known levers, never by editing ship data.

History as the anchor

Real actions ran from minutes to hours. These are the anchors the time scales start from:

A close frigate action could be decided in a quarter of an hour; manoeuvring to it took hours. The game compresses the manoeuvring far more than the fighting.

Targets

An even close action takes about five full broadsides (Marlinspike, 2026-10-09, "increase from 3 broadsides to 5"; it was three from 2026-10-07): two ships of the same class lying abreast at close range, every gun bearing, exchange about five full broadsides before one strikes. On the game clock that is about five minutes for a frigate (reload lever 3). In a fight under sail the same weight of shot comes as partial broadsides, as guns bear, spread over several minutes. The pace tool reports broadsides for every pair; nothing fails on the target yet. Marlinspike may set more, possibly by class: a first-rate's fight may run longer than a cutter's.

Chain brings masts down in minutes (Marlinspike's target, 2026-10-02, brought over 2026-10-08; a tuning guess, set by play): a first rate firing only chain at a frigate brings the frigate's first mast down about 2 minutes after its first rig hit, and all three in about 5. The pace tool reports it; nothing fails on it yet.

The pace tool

Built from the start, alongside Studio. It runs fights headless and deterministically, for every pair of the five classes, each class against itself too (fifteen pairs; Marlinspike's target is set on equal ships), over fixed seeds and set scenarios, and reports how long each took and what each side lost, against the targets once they exist.

Its scenarios (2026-10-06): a meeting, where both ships' captains sail and fight from 2,000 m apart, one starting 50 m off the other's line, once to each side: head-on, each captain's first turn was a tie broken by rounding, and it decided the fight (2026-10-14); and stand-up duels, two ships lying broadside to broadside at 100, 400 and 1,000 m, no sail, the engaged sides at Fire at Will from the start, which test gunnery and morale alone. Its report is docs/pace/report.md.

The levers

Pacing is adjusted only through these, kept in one file:

1. Time scales: reload, crew movement between stations, sail handling. Symptom it fixes: everything is too slow, or too fast, overall.
2. Accuracy: what share of a broadside hits, by range: it divides both dispersion and the misjudged range. Symptom: nobody hits, or every shot hits.
3. Hit effect: casualties per hull hit, drive lost per rig hit. Symptom: fights are too bloody, or hits do too little.
4. Breaking point: the losses that make a ship strike, and how fast morale recovers. Symptom: ships strike too soon, or fight to the last man.
5. Weatherliness (Marlinspike, 2026-10-09): the pinch shoulders of the no-go zone (Physics). Symptom: ships can't work to windward, or claw up it too easily.

Each lever has a global value and optional per-class overrides, so classes can have different targets without forking the model. Naming the symptom first stops pulling whichever knob is nearest.

The log

Every lever change is logged with the pace tool's report before and after, on the same seeds, and its reason. A lever change with no log entry fails review.

Consistency rules

Tests between levers, run with the suite:

• Morale recovery is slower than the slowest reload. When it wasn't, a frigate duel ran 51 minutes to 95% casualties (rebuild plan, 2026-10-06).
• More may be added as play finds them; each comes with the fight that showed the need.

7. Architecture

The shape of the code. These are lessons stated as design (rebuild plan, 2b), not a description of any earlier code. Where a choice is mine rather than the plan's, it says "proposed".

Stack

• Plain ES modules in the browser, no build step. The served files are the source files.
• Types without a build: // @ts-check and JSDoc in every module, with tsc --noEmit run as part of npm test.
• 3D with three.js, vendored into the repo and served from it, never from a CDN (proposed).
• Tests with node --test, beside each module from its first commit.
• The site around the game stays plain PHP.

One pure sim core

• No DOM, no clock, no Math.random. The core advances by a fixed step and draws every random number from a seeded generator it is handed. The same seed and the same commands give the same battle, every time.
• The same core runs everywhere: in the browser, in the pace tool, in Studio, and later in a room server. Nothing outside the core repeats its logic.
• A size budget of about 400 lines per module. A module that grows past it is split by responsibility, not by line count.

One world, two sims

One world, two sims (Marlinspike, 2026-10-18). Corona del Mar is one world: one chart, one clock and its wind, one town, one voyage, one set of ships. It is seen from two places, the deck and the quay, and each is its own simulation over the same world. The sea sim steps ships; the walking sim steps a ped. Neither moves the other's bodies: a ship at the quay is the sea sim's, a ped on her deck is the walking sim's. Nothing is built twice: a second chart, a second town or a second copy of a ship's state for the other view is a fault.

The walking sim runs on the server, as the sea sim does for a room, so that in time players may meet ashore (Marlinspike, 2026-10-18). The plan is docs/plans/one-world-two-sims.md.

From one level to another only by a stair (Marlinspike, 2026-10-19: "stairs only"). A ped walks no ground steeper than 45 degrees, up or down. The town's ground is gentler than 14; a stair climbs about 35, and he walks it as a slope; a wall's face, a pier's or a mole's edge is sheer, and he slides along it as along a house. So the sea wall's top, the pier and the moles are reached by their stairs; a stair that runs along the sea wall ends in a level landing, and he steps sideways between it and the wall. The piers' piles, the palms, the shophouses' walkway posts and the flagstaff's plinth are solid too (Marlinspike, 2026-10-19: "make the piles, palms, posts and plinth solid"): he walks round a post, sliding along its edge, and along the plinth's faces as along a house. A post stops him only where it stands up above his ground, so the piles below the sea wall's top don't stop him on it.

One command layer

• Keyboard, mouse, station bar, NPC captain, and later the network, all issue the same commands to a ship: helm, sail level, brace a yard group, auto-trim, a gun side's order (Stand Down, Load, Fire at Will), signal. A command is plain data.
• A captain can do nothing a player can't, because it has no other way to act.
• Commands are applied at step boundaries, so a recorded list of commands and a seed replays a battle exactly. That record is also what Studio and the tests use.

One ship-state shape

• The core owns ship state. Renderers and the HUD only read it; they never write it or keep their own copy of anything the sim decides.
• Hit shapes are separate from the drawn model, and a test enforces that changing the drawn model can't change a fight (Marlinspike, 2026-09-27).

Ships as data, with a schema

• Each class is a data file. A schema, checked in npm test, requires that every value carries its historical base and citation, and its game value and tuning reason where they differ, or is marked a tuning guess.
• Field names are chosen fresh for this game and recorded in the schema.
• Polars live in JSON tables generated by the sail-force model (Physics), with the model's inputs and their citations stored beside them.
• The global time scales and the pacing levers live in one file, not spread across modules (Pacing).

Every tunable stat is derived

• A stat's effective value is its base value with a list of modifiers applied. Each modifier names the stat, how it changes it (multiply or add), and where it came from.
• The core reads only effective values. A test enforces that no module reads a base stat directly.
• This is the hook for officers (later: collectable cards based on historical warrant and petty officers, Marlinspike, 2026-10-06). An officer is a set of modifiers attached to a ship, so the core never knows about cards. The handling times (Sail handling) are stats for this reason. Morale, rig damage and later weather use the same hook.

Studio

• Studio stages scenes and writes stills and video, for us first: devlog images, video and promotion (Marlinspike, 2026-10-06). It may open to players after launch.
• A scene file names the ships, the commands over time and the camera, and a seed. It is the record of the asset; published videos live in the repo with their scene (Marlinspike, 2026-10-03).
• Studio runs the same core and the same step loop as play, never its own copy of the captain or anything else (Marlinspike, 2026-10-03). Captains sail by default; ships can be frozen, or left without a captain so they follow only the scene's commands (proposed, 2026-10-06: the pace tool's duels and scripted scenes need ships that do only what they are told).
• It renders through the game's own 3D view in a headless browser, MP4, silent unless a production asks for the game's sound (Marlinspike, 2026-10-20; proposed: the only way to get pictures identical to play). A screen mode shoots the real page with its HUD, for guide pictures.

Tests from the first commit

• Each module has its tests beside it.
• The schema check for ship data, the derived-stat check, the hit-shape check, and the pacing consistency rules all run in npm test.
• A test that no served file names another game (Marlinspike, 2026-09-24).
• bin/cleanroom_check.sh runs from the projects root, outside this repo, before each commit of data or sim code is pushed.

Layout

Adopted with the first module (Marlinspike, 2026-10-06). Tests sit beside each module (rng.js and rng.test.js), so they are served with it; they hold nothing private. The test that no served file names another game waits until Marlinspike gives the names to look for; until then bin/cleanroom_check.sh covers it.

www/                  the docroot (as now)
  play/               the game page and its modules
    core/             the sim core: no DOM
    view/             3D view, HUD, menus: read the core's state
    input/            keyboard, mouse, station bar: issue commands
    data/             ship classes, polars, levers (JSON)
  spec/               this spec
  vendor/three/       three.js, vendored
tools/                pace tool, Studio, polar generator: run the core under Node
package.json          npm test: node --test, then tsc --noEmit (TypeScript is a dev tool, not served)

8. Sources

Every source cited in this spec. Pages marked fetched were read on 2026-10-06; books and articles marked read were read in full text. Nothing here comes from a game or game data.

Web pages (fetched 2026-10-06)

Books and articles

• Willis 2003: Sam Willis, "The Capability of Sailing Warships, Part 1: Windward Performance", The Northern Mariner XIII no. 4 (2003), pp. 29–39. Read.
• Willis 2004: Sam Willis, "The Capability of Sailing Warships: Manoeuvrability", The Northern Mariner XIV no. 3 (2004), pp. 57–68. Read.
• Falconer 1769: William Falconer, An Universal Dictionary of the Marine (London, 1769), Project Gutenberg #57705. Read: Box-hauling, Boxing, Aback, Head-sails, Mizen, Driver, Stay-sail and To Tack.
• Douglas 1829: Sir Howard Douglas, A Treatise on Naval Gunnery, 2nd ed., 1829 (archive.org scan). Pp. 118–19 read; Tables VIII and XV (pp. 294, 302) unreadable in the OCR, to be checked against page images.
• Cited through the pages above, not read directly: Rif Winfield, British Warships in the Age of Sail 1714–1792 (2007), 1793–1817 (2008) and 1817–1863 (2014); Robert Gardiner, Frigates of the Napoleonic Wars (2000); Brian Lavery, The Ship of the Line (1984); Peter Goodwin's works on Victory; McConnell 1988.

Looked for, not found

• Draught for the Seventy-four, frigate, brig and cutter.
• Recorded speeds for the Seventy-four, brig and cutter.
• Crew per gun for the 18-pdr and 9-pdr, and for carronades.
• A sourced tacking time.
• John Harland, Seamanship in the Age of Sail (1984): not reached; nothing from it is used.
• Range-by-elevation tables with a reliable source (two uncited pages give them; not used).

Not used

• A search summary crediting a 3½-minute broadside to Collingwood "in 1812". Collingwood died in 1810.

9. Later and dropped

Later (Marlinspike, 2026-10-06, plus sound the same day): shifting wind and a building sea; range rings (the brigantine was built 2026-10-16, for the shipyard: see Ships; boats, prizes and taking to the boat when struck were built 2026-10-14: see Boats); crew carried between battles (built 2026-10-16 for Corona del Mar: see Corona del Mar); crew figures; real-nation ensigns; multiplayer rooms (built 2026-10-14: see Multiplayer rooms); the rest of Corona del Mar (its sea, town, port and clock wind were built 2026-10-14, the Cabal at sea 2026-10-15: see Corona del Mar); shipyard pages; saved progress (sign-in itself was built 2026-10-12: see Accounts); a welcome video. (Gun sound was built 2026-10-12 as the full soundscape: see Sound.)

Dropped (Marlinspike, 2026-10-06): riding as a passenger on an ally's ship; the explored chart; frame reports; any tool that builds numbers from another game's data; the inherited admin, dossier, rank, register and decoration pages.

10. Open for Marlinspike

Nothing open: all eight items were decided by Marlinspike on 2026-10-06.