# Traffic Sandbox: product instructions

This reference consolidates the user's requests in the development chat through October 25, 2026. Entries are paraphrases, not verbatim quotations. Later explicit instructions take precedence. This is a requirements reference; it does not claim every possible traffic situation has been validated.

## Scope and purpose

- **P-01 — Sandbox:** Build an engaging traffic simulator alongside the site's successful solar system simulator. Players experiment with traffic; they should not need to plan or build roads.
- **P-02 — One intersection:** Focus on two perpendicular roads. Remove the other levels/scenes for now.
- **P-03 — Controls:** Offer four-way stop, two-way stop, timer-only lights, presence-detecting lights, and a roundabout. Show how each responds to traffic flow.

## Streets and appearance

- **P-04 — U.S. layout:** Use American road conventions. Study several real examples before rebuilding lane geometry. The examples inspected are linked in [README.md](README.md#intersection-artwork).
- **P-05 — Straight means straight:** Through traffic travels straight across into an aligned receiving lane. Adding an incoming turn pocket must not create a crossed-out extra outgoing lane.
- **P-06 — Optional turn lanes:** Offer no extra turn lane, one dedicated left-turn lane, or two dedicated lanes (left and right). Keep the center left-turn pocket and outside right-turn pocket consistent with their vehicle paths.
- **P-07 — Markings match control:** Change the intersection appearance for the selected control. On a two-way stop, the priority road must not have stop bars or stop signs implying that it must stop. Combine arrows into one branching marking when a lane permits multiple movements.
- **P-08 — Scale and variety:** Size cars accurately relative to lanes. Give cars and grass visual variety; improve the scene and vehicle detail substantially. Current model dimensions are implementation choices documented in README, not dimensions specifically dictated by the user.
- **P-09 — Readable signals:** Make brake lights and blinkers more pronounced. Orient signs and traffic lights so players can tell which approach they control.

## Driver behavior

- **P-10 — Physical realism:** Vehicles cannot pass through one another; P-24 explicitly allows physical collisions and supersedes preventive no-crash interlocks. Traffic should arrive irregularly rather than at perfectly even spacing.
- **P-11 — Path-aware priority:** Cars wait only for relevant conflicts. Opposing straight-through cars can proceed together at a four-way stop after stopping. Compatible right turns and straight-through movements can also proceed together; sharing an exit still requires merging space.
- **P-12 — Main-road flow:** Two-way-stop priority traffic must not stop without a real conflict, queue, or other applicable reason.
- **P-13 — Prompt departures:** Cars should accelerate realistically when leaving. A driver should not wait for a left-turning car to leave the entire intersection when its own arrival at the shared path will be safely later.
- **P-14 — Individual personalities:** Drivers should have different levels of caution/aggression. Provide a slider to adjust the mix. High aggression must visibly reduce unnecessary hesitation.
- **P-15 — Explain decisions:** Clicking a car shows what it is actually doing or waiting for, including the relevant car or signal. Explanations must reflect the simulation's decision, not decorative text.
- **P-16 — Chaos Monkey:** A button makes one randomly selected driver do something irrational. Include stronger disruptions such as a surprise U-turn or illegal movement, with surrounding traffic reacting. A prank must change motion, not merely the displayed thought.

## Interface and maintainability

- **P-17 — Concise controls:** Consolidate the right sidebar and remove unnecessary text. Keep advanced inspection out of the main driving controls.
- **P-18 — Update history:** Add an About menu with a dated entry for each shipped update. Preserve published history.
- **P-19 — Reviewable rules:** Format and organize driving rules so they can be reviewed and improved. [RULES.md](RULES.md) maps behavior to code and regression checks.
- **P-20 — Instruction reference:** Maintain this consolidated record of the user's product instructions alongside the rule reference.
- **P-21 — Evaluation log:** Provide a log that can help assess whether the simulation is working correctly. About → Simulation log exports current-run decisions, blockers, timing calculations, vehicle samples, interventions, and diagnostic flags.

- **P-22 — Aggression-aware evaluation:** Log each car's effective aggression and consider it throughout driving-rule review and scenario evaluation. Distinguish the overall driver-mix slider from individual temperament; evaluate both the waiting driver and relevant blocking drivers using their settings at the time.

- **P-23 — Individual minds and visible communication:** Each car should act from its own observations and personality, rather than cooperate as a group to optimize traffic. Blinkers, brake lights, position, and motion communicate information to other drivers. Record what each driver observed and inferred; do not treat private intentions, aggression, or Chaos commands as information broadcast to the other drivers. Keep physical non-overlap enforcement separate from driver intent.

## Repository constraints

The root [AGENTS.md](../AGENTS.md) and local [AGENTS.md](AGENTS.md) contain the authoritative repository instructions. In particular:

- Use American English and imperial measurements in player-facing content and documentation.
- Preserve viewport scaling, localStorage records, Player Profile integration, and feedback at actual experiment/comparison completion.
- Support Chrome 76 syntax and runtime APIs; run the compatibility and game-procedure checks before committing.
- Work on `main`, commit and push directly, and do not create feature branches or pull requests.
- Add an update-history entry for each visible release, update cache tokens, and check About accessibility and pause preservation on desktop and mobile.
- Libraries, assets, and multiple files are allowed when useful; this game currently uses buildless JavaScript modules.

## Using this reference

When changing a rule, identify the relevant P-number, update the rule documentation and regression checks, and describe the actual shipped behavior in the update history. Keep requirements separate from tuning choices and known model limitations. Do not silently reintroduce rejected road layouts or removed scenes.

## Collisions and identification

- **P-24 — Natural crash consequences:** Drivers should act independently and can collide after bad decisions or missed cues. Crashes should be relatively uncommon in ordinary traffic, not injected randomly. The physical layer resolves contact instead of secretly vetoing risky movement.
- **P-25 — Pull off after a crash:** Crash-involved vehicles stop, then visibly maneuver off the road to clear traffic. Recovery must not teleport them through other cars or remove them while still blocking the roadway. Log the collision, driver aggression/perception, and recovery.
- **P-26 — Optional car numbers:** Provide a toggle showing a number on every car; use the same stable ID as the inspector and logs.

- **P-27 — Gas intervention:** Add Gas beside Brake. It forces the selected driver to accelerate through normal yielding/braking decisions, making a crash a possible natural consequence when barging into busy traffic. Other drivers still react; no scripted guaranteed impact.

## Queue and signal follow-up

- **P-28 — Queue move-up and thoughts:** Address the sluggish move-up observed in the seed-1 four-stop log. Preserve required full stops and individual following reactions. Thoughts must distinguish approaching a stop from actually crossing.
- **P-29 — Left-turn indications:** Distinguish a protected green arrow from a circular green that requires yielding. Offer both signal behaviors and render their actual indications; preserve collision consequences and driver observation.

- **P-30 — Preset efficiency runs (retired by P-37):** Run 60-second scenarios combining driver mixes, traffic directions, and turning shares to compare intersection efficiency. Replay matching inputs across controls and retain results for review.

- **P-31 — Playable preset challenges (retired by P-37):** Make five different fixed traffic sequences clearly selectable in the game. Let the player choose and test the intersection, run for 60 seconds, and receive a performance rating with a fun retry loop.

### P-32 — Readable speeds and entry behavior

- Offer live MPH labels on each vehicle, independently of car numbers; persist both preferences.
- Roundabout entries should resume after the passing vehicle clears their path. Keep approaching-traffic gap checks, personality differences, and normal following space.
- Allow right turns on red after a complete stop and individual checks for conflicting traffic and an open receiving lane. Log these as legal stopped/yielding turns, separately from red-light violations.
- One extra lane means a dedicated left lane plus a shared straight/right lane. Two extra lanes separate left, straight, and right. Keep combined pavement arrows for shared movements.

### P-33 — Higher aggression available

- Extend the population mix to 150%, with an Extreme end. Preserve existing behavior through 100%.
- Above 100%, allow tighter crossing/following gaps, faster reactions, and stronger acceleration while retaining individual temperament, physical limits, signal/stop compliance, and natural consequences.
- Persist/share the expanded setting and show the actual individual level in driver details and diagnostic logs.

### P-34 — Logic review: lifelike behavior, not zero crashes

- A driver bound for one turn pocket must not stop short "leaving room" for a car in the neighboring pocket. Review all traffic and signal logic along with it.
- The goal is to mimic real driving, not to eliminate crashes. Aggressive (especially Extreme) drivers making unsafe decisions, such as running a yellow that has turned red, is intended behavior; fix logic errors, not bold choices.

### P-35 — Drivers that differ: judgment, attention, and the occasional mistake

- If the model is to mimic reality, leave room for drivers to be different: levels of aggression, levels of risk, occasional mistakes. It needs a bit of random.
- Add per-driver judgment error (misjudged speed and distance), a decision wobble (the same driver does not weigh the same gap the same way twice), and an attention trait (lapses, late reactions, rolling stops), all seeded so a run replays, with logging that names the mistake. Re-sweep and commit before pushing.

### P-36 — Honking: when to honk and what it does

- Add honking logic: when drivers honk and the result of a honk.
- Drivers honk from what they see: at a car sitting at its line when the way looks clear to them (after their own patience runs out), and as a warning when someone forces them to brake. A honk is a public cue every nearby driver hears; who it was meant for is not broadcast, so listeners infer it from position and motion.
- Results: drivers who had looked away look again; a nudged driver feels pressure to go; a warned driver stops short or hurries out of the way. Show it on the map, play it with sound on, name it in thoughts, and log honks and reactions.
### P-34 — Sound and music

- Add traffic sound effects and music, with independent saved toggles and a shared volume control. Use an original lighthearted, whimsical instrumental loop with a bouncy rhythm and playful plucked/bell timbres, plus speed/position-dependent engine/tire sounds, braking, warning, and crash effects.
- Unlock audio after a user gesture; silence it during pause, menus/results, hidden tabs, and automatic comparisons. Keep audio independent of the simulation's decisions and seeded randomness.

### P-35 — Optional driver mistakes

- A Driver mistakes checkbox controls distractions, bad estimates, rolling stops, and late red-light choices, plus forgotten turn signals and turns from the wrong lane.
- Other drivers act on lamps and motion they can observe; do not broadcast private mistakes or routes. Wrong-lane turns must follow continuous physical paths and obey the signal for the occupied lane.
- Keep errors occasional and repeatable by seed/driver. Record mistakes in diagnostic evidence. Toggle changes restart the same traffic sample; scoring fixes the setting for comparable challenges.
- Per the user's explicit instruction, concurrent horn-and-driver-reaction work is a separate release. This release's warning sound is read-only audio feedback.

### P-37 — Two ways to play: Sandbox or Traffic Cop

- Kill the game modes we had (the five preset challenges and the 60-second experiment). The first choice is Sandbox or Game.
- The game is Traffic Cop. Start at a simple two-way stop. Click any driver who does not follow the rules; the click must be judged correctly against who actually broke a rule.
- Play in rounds. Each round has a set number of rule breakers to identify (or miss the chance) and points. As rounds progress the intersection becomes more complex with more traffic.
- Make sure mistakes are actually being introduced in every round.