How it works — shared memory, one computed frame, and a bridge for Proton

THE SHAPE

Three layers, and the arrows only go one way. A game is read, a frame is computed once, and every front end is handed the same frame.

# one folder per game, one Sink per place the frame goes,
# and any number of front ends

  Assetto Corsa ──▸ shared memory  ─┐
                                    ├─▸  the engineer  ──▸  one frame
  (your simulator) ────────────────┘                          │
                                                              ├─▸ shared memory ─▸ the CSP panel
                                                              ├─▸ UDP as JSON   ─▸ another machine
                                                              └─▸ the terminal

The split is not decoration. Whatever a front end needs has been worked out before it is asked to draw anything, which is what makes a Lua panel on a render thread affordable at all.

READING THE SIMULATOR

Assetto Corsa publishes physics, graphics and static session data in named shared memory. Reading it costs nothing and requires no hooks, no injected code and no modified game files — it is the interface the game offers for exactly this.

THE COMPUTED FRAME

Everything the front ends need, worked out once and written into one flat C-layout struct: speeds, pressures, temperatures, wear, fuel, the debrief, and up to eight lines of advice with their severity and confidence.

WHERE THE FRAME GOES

A sink is a place the computed frame is delivered. Shared memory for the in-game panel, UDP as JSON for anything else — a second front end, a friend watching from another machine, a relay for a championship.

Nobody types an address unless they want to. Copies announce themselves on a multicast group and appear in each other's list — a couple of hundred bytes every two seconds, carrying a name, a role, a port, the car and the track, and nothing about the driving. Multicast to find, unicast to stream: a group is broadcast to a switch, and thirty readings a second on one is everybody's problem. It is all off unless you switch it on, because it is telemetry about a person.

WATCHING A FRIEND IN ANOTHER CITY

On one network there is nothing to set up: open LAN, one of you presses S and the other W, and you pick each other out of a list. Across the internet, two houses behind two routers is NAT and neither machine can dial the other — so the usual answer is a forwarded port, or a relay in the middle that somebody has to run.

There is a third answer, and it needs no code and no server. A mesh VPN — Tailscale or ZeroTier, both free for a handful of machines — gives each computer an address on one private network wherever it happens to be. Four steps, and nothing about the program changes:

The list stays empty across a mesh, and that is not a fault. Finding each other is multicast, and a mesh VPN does not carry it — neither does most guest Wi-Fi. Typing the address is exactly the case that box has always existed for, and everything after it works identically. Announcing is only how you are found; it has nothing to do with how a session travels.

What each of you sets

On one network, nothing: open LAN, press S to share or W to watch, and pick each other out of the list. Across a mesh VPN there is no multicast, so the list stays empty and the address is typed — which is what that box has always been for.

# the driver, in config.json — send to your friend's mesh address
"overlay": { "broadcast_to": "100.64.0.2:9001" }

# the friend watching — listen on the mesh interface
"overlay": { "receive_from": "0.0.0.0:9001" }

Their screens then draw your session — the dashboard, the traces, the map, the corner table and the engineer. Not a copy of your sentences for them to read: the whole reading travels, so their machine finds the laps, builds the traces, draws the map's line and runs its own engineer over your driving.

What travels, and what does not

Whether it actually arrives

UDP has no retries, so the question that decides whether this is pleasant or flaky is how big each message is. Over about 1472 bytes and IP splits it into fragments; lose any one of them and the whole message is discarded. A tunnel has less room still — Tailscale and ZeroTier both default to 1280.

Checking it without a friend

Two probes ship with the source. The first says which of the four halves of the network is at fault — this machine's addresses, the port a session arrives on, the group copies find each other on, and whether anything is actually arriving:

# on the machine that will watch
cargo run -p ac_core --example lan_probe

# on the other one, aimed back at it
cargo run -p ac_core --example lan_probe -- send 192.168.1.42:9001

The second runs the real engineer, sends the finished frame through the real socket and prints what came out the far end — the older, summary path, which is still what a panel or a relay reads:

# both ends on this machine — proves everything but the network
cargo run -p ac_core --example share_probe

# or aim it at the far end's mesh address, and run it there with
# no argument to watch it arrive
cargo run -p ac_core --example share_probe -- 100.64.0.2:9001

Where this stands, in full

What a complete online telemetry broadcaster would be, and which parts of it exist today. Everything marked done has been run, not reasoned about — the caveats are as interesting as the ticks, so both are here.

✓ works, and has been run ~ works, with something worth knowing · not built, and why

• ✓The computed frame, as JSON over UDP Plain text a receiver of any language can read. MAGIC and a schema number in front, so a datagram on a shared port is recognised or refused rather than mis-parsed.
• ✓The engineer's advice, verbatim All eight slots with their severity — the sentences themselves, not numbers to re-interpret. Checked by sending a frame through the real socket and comparing what came back: four lines out, four identical lines in.
• ✓The lap debrief Three laps, eight lines each, alongside the wheels, fuel, timing and flags.
• ✓One packet for the live stream About 1200 bytes, which crosses one Ethernet frame and one mesh-VPN frame with nothing to reassemble. A test fails if a new field pushes it over.
• ✓The watcher's own panel draws it The receiver rebuilds a frame, so a spectator sees the same layout they use themselves rather than a second application.
• ✓Ten a second, not the tick rate Nobody can tell the difference watching, and twenty cars at tick rate is megabytes a second arriving somewhere.
• ✓Off unless an address is set It is telemetry about a person and it leaves the machine only because they said so.
• ✓Who is driving travels with it So a receiver hearing several drivers can say whose numbers are on screen.
• ✓A dead receiver costs the driver nothing Publishing never waits, and a sink that fails sixty times running is dropped instead of logged sixty times a second.
• ✓A version mismatch says so Rather than drawing a field it does not have. The sender's release travels too.
• ✓A way to test a link before trusting it share_probe runs the real engineer, sends through the real socket and prints what arrived and how many bytes it was.
• ~Across the internet Works, but through a mesh VPN you set up — there is no relay of ours, and there is not going to be one until people who use it on a LAN ask for it.
• ~The debrief burst fragments About 3900 bytes, so three or four packets after each lap. IP reassembles them; a lost fragment costs one update out of ten a second.
• ~The sender's language and units The frame carries finished text, so a Russian driver's advice arrives in Russian on an English watcher's screen. Correct, and occasionally not what somebody expects.
• ·Corner-by-corner analysis The CORNERS table stays on the driver's machine. A corner reaches a spectator only when it is one of the eight advice lines. Sending the sections is a frame version change, not a setting.
• ·Anything resembling authorisation Whoever can reach the port and knows it can listen. On a LAN or a private mesh that is the same set of people who can reach your machine at all; across an open internet it would not be, which is the other reason there is no relay.
• ·Discovery You type an address. There is no browsing for drivers and no lobby.
• ·More than one driver at a time The message carries a name so a receiver could tell them apart. Nothing draws several yet — no championship view and no leaderboard.
• ·Recording what you received A watched stream is drawn and forgotten. Saving it as a lap you can compare against later is not built.
• ·A viewer that is not this program Both ends are the application. The feed is documented enough to write your own in about fifteen lines, and nobody has shipped one.

A mesh VPN is somebody else's service, and that is the trade. Nothing about your telemetry is stored by it — it carries packets between two machines you control — but it is an account with a company, which is a different answer from the rest of this program. On one network you need none of it.

WHY THE PANEL IS FREE

The in-game panel is a Custom Shaders Patch Lua app, and Lua runs on Assetto Corsa's render thread. At 165 Hz a millisecond is a sixth of the frame budget, and LuaJIT collects garbage mid-frame — so a panel that parsed text or built tables every frame would show up as a stutter rather than as a lower average frame rate.

THE BRIDGE, ON LINUX ONLY

On Windows the application creates the shared mapping itself and there is nothing else to run. On Linux the game runs under Proton, so its shared memory lives inside the Wine prefix — and only a Windows process in there can create a mapping under the name the game is allowed to open.

That is the whole job of shm-bridge.exe: it runs inside the prefix and passes the mapping out to the native Linux side. It began as Damir Jelić's work and is used and extended here under its own MIT licence.

ADDING A SIMULATOR

A game is a folder under core/src/games/ implementing one small interface. It is not conditionals through the middle of the engineer, and that is deliberate: the engineer's rules should never have to know which simulator produced a number.

One implementation is not an abstraction, it is a guess. The second game is deliberately not started until the first is finished — the guesses are far cheaper to correct while there is one consumer of them. If you want a particular simulator, say so on the issues page; what it publishes decides how much of the above is even possible.

THE LICENCE

AGPL v3. Use it, race with it, read it, fork it. Change it for yourself and nothing at all is asked of you — the licence conditions passing a copy on, not what runs on your own machine. Publish something built on it and the one condition is that your source is open too, with this project credited.

Keeping your own source closed, or selling a product with this code inside it, needs written permission first: rgoshbbb@gmail.com. LICENSING.md is the plain-language version, including what counts as using the code — a translation into another language, an AI's included, is a derivative work; ideas and algorithms are not.