How Cloverleaf's traffic works

Detail only where someone is looking

This is a city seen from above, with you (the Mayor) at the center. Cars inside the yellow bubble are full agents: each one steers, brakes and keeps its distance on its own. Out to the dashed 1.5 km ring, cars are still drawn, but their positions come from the cheaper queue model (the meso), so nothing pops in when you turn around. Past the ring, nothing is drawn: each street is just a queue with a color for how busy it is. Every car is still simulated there, only more cheaply.

The bubble leans the way you face, and when you turn it swings round after a short delay.

Schematic. The real bubble's size, lean and delay are still being tuned.

Most of the city runs as queues, which are far cheaper than steering every car. We expect about 25× fewer full agents E. The handover can't be seen, because the agents and the queues follow the same traffic law (Picture 1).

How many cars a road can carry

Add cars to an empty road and, at first, everyone drives at the speed limit, so each extra car adds to the flow. Past a certain density, cars are too close to keep the speed limit. Everyone slows down, and fewer cars get through per minute even though more are on the road. Draw flow against density and you get a triangle. Its peak is the road's capacity.

q is the flow (cars per hour), k the density (cars per km), v_f the free speed, k_j the density of a stopped queue, δ the spacing in a stopped queue, and τ the time gap a driver keeps. Lane capacity v_f/(v_fτ + δ) equals the road table's number exactly.

Example numbers: 50 km/h, δ = 7.5 m, τ = 1.5 s. The game uses one triangle per road type × vehicle, from the road table.

For Cloverleaf: both levels of detail are built on this one curve, so they agree by construction. The within-10% match is a test that should pass, not a tuning job.

Every driver copies the car ahead, a moment late

Newell's rule is short: drive at the speed limit, unless that would bring you closer than a set gap to where the car ahead was a moment ago. Watch a queue at a light that turns green. The front car pulls away, and each car behind starts one reaction time later. The "go" signal travels backward through the queue at a steady speed, the slope −w of the triangle in Picture 1.

The lower chart is a time–space diagram: each line is one car, with time going right and distance going up. A flat line is a stopped car, and a steep line a fast one.

Car i's next position is the smaller of two limits: where speeding up toward the speed limit v_f at acceleration a would take it, and where its leader i−1 was τ seconds ago, less the gap δ. The outer max means it never reverses.

For Cloverleaf: on a long, steady road, Newell's rule settles exactly onto the triangle. So the agents up close and the queues far away agree with no tuning. That's why it replaced IDM, a popular car-following model that, with our road data, missed the capacity by as much as 2× E.

Book the arrival, then stop thinking about it

If the road ahead is clear, a truck's arrival time is just distance over speed, added up edge by edge. So on departure, write the arrival in the calendar once and do nothing more until it's due. The truck still drives, and you still see it. Only when an edge on its route changes congestion band (a band event) do the trucks that still have to cross that edge work their times out again.

Both rows below move the same trucks the same way. The counters show the work each method does. Try jamming an edge.

L_e is each edge's length, and v_f,e its free speed. Recompute only when an edge on the route changes congestion band.

One work unit = updating one truck for one tick, or booking one route. Example road and speeds, shown 10× faster than real time.

For Cloverleaf: in a healthy city most trucks are free-flowing, so most per-tick truck work disappears E. This is still a lead: the gain hasn't been measured yet.

Supply lines fall into a rhythm, and then they can sleep

In a supply line, each event waits for the last of the things it depends on, then takes a fixed time. Example: a truck leaves once it's loaded and the dock is free. "Wait for the latest" is a max, and "then add a fixed time" is a plus. Mathematicians call a system built only from max and plus max-plus algebra, and it has a lovely property: after a short settling-in, it repeats exactly, step after step.

The chart plots three event times, with the steady pace removed. While the system settles, the lines wobble. Once they repeat, the line has found its rhythm. It can then sleep with a certificate, a guarantee of exactly when every future event happens, at the cost of one calendar check.

x(k) holds the times of the kth round of events, and A_ij is the fixed time event i waits after event j. After a finite transient, the sequence repeats every c rounds, advancing by λ per round, where λ is the slowest loop's average time (the maximum cycle mean, found by Karp's algorithm). That gives an exact settling test, so there's no need to wait three round trips.

Example matrix, times in minutes. Here the slowest loop alternates two events, so the rhythm repeats every 2 rounds.

For Cloverleaf: settled lines sleep up to about 3× sooner E. The same algebra also tells the city's Problems page which loop sets the pace: the exact "why" behind a slow line.

Keeping route search sharp when the player builds a bridge

To find a truck's route, A* search explores outward from the start, guided by a hint: a guess of the time left to the goal. A better hint means less exploring. The one rule is that the hint must never overstate the time, or the search can skip past the true best route.

Landmarks make an excellent hint. We measure the time from a few far-off reference points (the black diamonds; switch on a landmark hint to see them) to everywhere, ahead of time. If the depot is 10 minutes from a landmark and you're 25 minutes from it, you must be at least 15 minutes from the depot. But a new road makes those measured times out of date, and then the hint can overstate. Build the bridge below and try plain landmarks: the search misses the bridge. The old fix was to fall back to the straight-line hint, which is safe but slow (7.5× slower on our bench M). The overlay repairs the hint: either the route avoids the new bridge, and the old hint still holds, or it uses the bridge, and then it's at least the time to reach the bridge, plus the crossing, plus the rest. The smaller of the two is always safe and still sharp.

h_ALT is the landmark hint, and h_Euclid the straight-line hint. Each new road e_i runs from u_i to v_i with time c(e_i), and LB is a lower bound on the time to reach it. Any shortest path either avoids every new road or uses one first, so this stays a true lower bound after roads are added.

Example map. Off-road cells cost 1 and road cells cost 0.3. The numbers in the table are this map's real search results.

For Cloverleaf: routes stay correct and fast while the player builds, avoiding the 7.5× fallback M, at about 1.5–2× the cost per explored node while the overlay is active E. We haven't found this repair rule published anywhere.

How long a city takes to recover from a blueprint paste

Pasting a big blueprint dumps a pile of work on the sim at once: routes to re-check, queues to rebuild. Meanwhile ordinary building keeps adding a trickle. The sim clears a fixed amount per tick and no more, so no frame ever spikes. While the trickle is slower than the clearing rate, the pile shrinks at the difference, and we can say in advance exactly when it's gone.

In the chart, the yellow line is all the work that has arrived so far, and the green line is all the work cleared so far. The gap between them is the pile. Where they meet, the city has recovered.

σ is the burst: the pile waiting when clearing starts (the paste plus whatever trickled in during the delay T). ρ is the steady rate, and R the per-tick drain. The ρ/R ratio is the early warning: the closer it gets to 1, the slower a city recovers while you keep building.

Example numbers, in work units per tick.

For Cloverleaf: this turns "is it solid?" into a formula before any playtest. It's math from guaranteeing internet routers, reused to prove that a city recovers from a pasted blueprint.

How many cars can slip into a busy road

A car waiting to join a priority road needs a big enough gap in the traffic: it goes if the next car is at least t_c seconds away, and the cars queued behind it can follow every t_f seconds. The busier the main road, the rarer the big gaps, so side-road capacity falls away smoothly, as an exponential. The animation runs the gap rule and counts the cars that get in. Over time the count should settle near the formula's curve.

c is the side-road capacity, q_p the priority flow and s = 1/t_f the rate if the main road were empty. Our constant 0.07 means t_c − t_f/2 = 4.2 s, a realistic gap (here t_c = 5.8 s and t_f = 3.2 s).

The start-up lag

A car pulling away from a stop takes a while to reach speed, so it falls behind a car that was already moving. The shaded triangle is the distance it loses. Divide by the speed and you get the time it loses, ℓ, which is owed once per platoon start at a junction, not once per car.

For Cloverleaf: junction rates come straight from these two formulas and each vehicle's acceleration in the game data, with no hand-tuned "lost time".

Why a blueprint paste never hitches the game

Each bar is one sim tick, and the line is the 4 ms budget. Paste a blueprint with "all at once" and the work lands in a single tick, blowing the budget: you'd feel a hitch. With "capped and sliced", the same work waits in a queue and each tick takes only a capped slice, so every bar stays under the line. Picture 6 is the math that says how long the queue takes to drain.

Example tick times. The spike we measured on the bench was 1.75 ms for a single edit burst M, an estimated 3.5 ms at 8× E.

Spotting gridlock the instant it happens

Every stuck car points at the car blocking it. Usually the arrows form trees, which all lead back to a car that will move eventually (a root). Gridlock is the one case where the arrows go round in a loop and nobody can ever move. Each car remembers its root, so when a new arrow is added, one look tells you whether it points back to its own chain. If it does, that's a loop, found the moment it closes, with no "stuck for 60 seconds" timer.

For Cloverleaf: exact gridlock detection at about O(1) per event and 2.6 MB E. The same arrows give the city's Problems page its "blocked by" chain for free: it shows what is wrong and where, never the fix.