Roadfolks

Roadfolks gives the traffic in Euro Truck Simulator 2 drivers who talk. It reads the vehicles around you out of shared memory, keeps each one as a tracked person with a nationality, a personality and a memory of you, and lets them speak over the CB, the phone, the radio or the passenger seat.

• Try the live demo
• Install
• Source

374

Python tests, all offline

21

Worker tests

24

event types

66

written characters

239

conversation topics

37

countries with a native voice

Who talks to you, and how

Nine kinds of speaker, on five channels. Every one of them is a person the simulation decided exists, not a line picked from a list.

The channels

How you reply

You press the push-to-talk key and speak. Wingman AI turns that into text and hands it to Roadfolks, which gives it to whoever is currently in range on that channel. You can also start a conversation rather than wait for one.

A car driver shouting through a window cannot hear an answer, and a radio broadcast is one-way. Everything else can be answered.

An example

Marko opens in Croatian because his English is 0.42 and the simulation knows it. He switches when you answer in English, and the reply is short and missing an article because that is what a 0.42 speaker sounds like. A Croatian voice reads it, so the accent is in the audio rather than spelled out in the text.

Features

What is built and covered by tests today.

Live demo

Eight of the written characters, in the browser. Dialogue only: no game, no voice, and nothing is remembered between visits.

The replies come from a model on Cloudflare Workers AI, using the same character sheets the mod uses. The demo is rate limited to six messages a minute per visitor and a fixed number a day for everybody together, so the free allowance survives.

Bojan answers in Slovenian and Marko in Croatian if you write to them in those languages.

How it works

The simulation decides the facts. The model only writes the words.

A model asked to invent an interesting trucker produces a different disposable person every time. Roadfolks never asks it to invent anything. It hands over a driver who already exists, an event that already happened and a grudge from last Tuesday, and asks for one line:

vehicle 1834, 12 m behind, followed you 4 min,
passed aggressively on the left, driver Marko,
Croatian, impatient, English 0.45, met once
before near Maribor

The pipeline

Why the layouts are the fragile part

Two modules know the binary shared-memory layouts, and nothing else does. They are transcribed from ETS2LA's own C# readers: bare arrays of fixed records, with no header, no magic number and no write counter. The record arithmetic is a test. A wrong layout produces plausible-looking floats rather than an exception, so every vehicle is checked against NaNs and physical limits before it reaches the simulation.

When ETS2LA changes the layout, the fix is a new entry in the layout table and a config change. roadfolks diagnose scores every known layout against the real buffer, and roadfolks diagnose --search finds the vehicle array with no layout knowledge at all, by looking for a repeating record that holds a position, a bounding box and a speed, then confirming the positions move between two samples a second apart.

Where the state lives

Story beats, relationships and memories are rows in SQLite, not context in a prompt. A restart does not lose them, and a player who talks constantly cannot rush somebody through a whole story in one afternoon.

Requirements

Both game plugins are required. Neither one alone is enough.

The ETS2LA blocks contain traffic, parked vehicles and traffic lights. None of them contains your own position, which is why the SCS telemetry plugin is not optional. Without it the engine would have to measure every distance from the map origin, so it refuses to start instead.

Install

About fifteen minutes on a Windows game PC.

1. Install the game plugins

Put the ETS2LA game plugin and the SCS telemetry plugin in bin\win_x64\plugins inside the Euro Truck Simulator 2 folder. Create the folder if it is not there. Start the game once and leave it running in a job.

2. Install Roadfolks

git clone https://github.com/DavidKolsek/roadfolks-ets2 roadfolks
cd roadfolks
py -m venv .venv
.venv\Scripts\activate
pip install -e .

Use pip install -e ".[dev]" instead if you intend to run the test suite.

3. Add one model API key

setx CLOUDFLARE_ACCOUNT_ID "your-account-id"
setx CLOUDFLARE_API_TOKEN "your-token"

setx keeps the variable after a restart, but it does not affect the terminal you typed it in. Open a new terminal before the next step. Other providers are in docs/PROVIDERS.md.

4. Check what is missing

roadfolks doctor

One line per part: Python, the content library, the config, the database, the API keys, all four shared-memory blocks and the voice skill. Every part that is not ready prints one instruction. NOT READY stops the mod; MISSING costs a feature. The game has to be running or the three game items fail.

5. Start the service

roadfolks serve

The world engine listens on port 8731 over HTTP and WebSocket.

6. Add the voice skill

Copy wingman-skill\roadfolks into the Wingman AI skills folder and turn the skill on. Wingman owns the microphone, speech recognition, the voices and playback; Roadfolks does not reimplement any of that.

Without a game

roadfolks demo

Runs a whole encounter, with real dialogue, and prints each line beside the facts that produced it. Without an API key the lines are canned, which still proves the pipeline. The full first run on a game PC, with a check after every step, is in docs/GAME_PC.md.

Model providers

About half a cent per hour of play, and usually nothing.

Each line is a small request: under 2,500 tokens in and usually under 80 out. Speech recognition runs on your own PC through Wingman. The voices use Edge TTS, which is free.

The five are tried in order. A provider that hits its quota sits out for as long as it asks, or for a cooldown that doubles each time up to an hour. A refused key sits out for six hours and the log names the environment variable to fix. One success clears the record.

If every provider is out, the driver says something short and fixed rather than nothing. Silence caused by a fault would look exactly like silence by design, and nobody can debug that from inside the game.

Status

What is done, and what has not met the real game yet.

The full to-do list is in the repository.