Civilian traffic (traffic.system) #

What it is for #

traffic.system makes civilian cars drive around a city. Each car follows the road graph of world.roads in its right-hand lane, picks a direction at every junction (straight on first, then a random turn, a U-turn only at a dead end), waits when another car holds the crossing, brakes for the player, pedestrians and cars ahead, and overtakes a stopped obstacle by the left. Cars far from the player are moved back near it, so a small pool looks like a busy street. The cars are driven through vehicle.drive; the kit has no display module and draws nothing.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "traffic.system" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "traffic.system",
                              config: { "density": 0.8, "maxVehicles": 10 } }

It requires vehicle.drive, world.roads, spawn.entities and game.engine. The road graph is the lanes() of the world when it has them, otherwise a grid rebuilt from roadNodes() by joining aligned neighbours. A world without roads gets no cars. Traffic car models are the assets traffic_vehicles (picked at random), then vehicle_variants, then vehicle_default.

First example #

<!-- test: kits/traffic_system/tests/traffic_system.rs::the_pool_is_sized_by_density_and_max_vehicles --> The number of cars on the road is density times maxVehicles, capped at 64:

Every car is an entity of kind vehicle tagged traffic and civilian, announced by traffic.spawned.

Settings and defaults #

A scene can set its own density, speed and obeySignals (in layers["traffic.system"] of the scene): leaving a scene removes its cars, entering the next one rebuilds the graph from its roads and fills it again.

Service methods #

Service traffic.vehicles:

• vehicles(): the ids of the traffic cars.
• setDensity(n): change the density, clamped to 0 to 1 (a non-number changes nothing). It is kept in the save.
• stopAll(): halt every car. resume(): let them go again.

Events and hooks #

• traffic.spawned { entity }: a car appeared.
• traffic.blocked { entity, by }: a car was held by the same obstacle for three seconds.
• The kit listens to vehicle.collided (the cars involved are held for a while), vehicle.destroyed (a wreck leaves the pool and is replaced after a delay), vehicle.entered (a car the player takes leaves the pool) and world.ready.
• Hook traffic.spawn: asked once per spawn attempt, with { reason, from, to, x, y, z, yaw, archetype, variant, speed, count }. reason is fill (the pool is below its target) or replace (a wreck or stolen car is replaced). Mutable: speed, the cruise speed of that car (a slow truck, a hurried taxi; kept in the save). Cancellable: no car appears, as for a failed spawn; a fill is tried again two seconds later on another lane.

{ "id": "slow_fill", "hook": "traffic.spawn", "match": { "reason": "fill" }, "set": { "speed": 5 } }

Hooks and modding #

All six settings are moddable. A mod can slow some cars or forbid a spawn with the traffic.spawn hook; it cannot change the lane, the place or the look, which are already drawn.

Engines #

Web, native player, Godot, Unity and Unreal run the same lane graph, waypoint driving, crossing hold, braking and recycling. The traffic.spawn hook runs on the web and in the native player.

When it does not do what you expect #

• No car at all: density is 0, the world has no roads, or vehicle.drive has no room (maxVehicles of that kit is reached).
• Fewer cars than expected: the pool is density times maxVehicles; raise either.
• Cars stop at a crossing: another car holds it, or a collision holds them for a while. Set obeySignals to false to drive through.
• A car the player takes is no longer traffic: it leaves the pool and a replacement appears after a delay.

Limits #

The kit does not spawn pedestrians and draws nothing: the cars only follow the lane graph and react to what is in front of them.

Versions #

Kit version 1.3.0 (the traffic.spawn hook and moddable settings); 1.2.0 attached traffic to the scenes; 1.1.0 added the Godot, Unity and Unreal deliveries; first runtime in 1.0.0.