Elements

A scenario is one local frame in metres. origin is a longitude/latitude pair stored for the fixture; the integrator does not project coordinates. Every geometry vertex is already in that frame.

Features share an id (unique) and a ped_role. Unknown roles are rejected.

Floor

Walkable slab. floor_z is the height in metres. Geometry is a GeoJSON polygon. The exterior is oriented counter-clockwise and holes clockwise, so a left-hand normal points into walkable space. Holes (shafts, open voids) stay voids: their edges become wall segments. A hole that sits on a connector can be muted while the walker is on that flight, so the shaft does not push them off the stair. A column is an obstacle drawn as its own feature, not a hole filled in.

A walker is always snapped to the nearest floor height. Stairs still report a progress along the flight for display; the stored z is the floor they currently belong to.

Obstacle

A solid on one floor (kiosk, planter, column drawn as its own feature). Geometry is a polygon oriented so the normal points away from the object. Obstacles are walls and are excluded from spawn points.

Wall

A partition drawn as a LineString (or multi-segment polyline) on one floor. The parser offsets the line by half thickness into an obstacle of the same id, square-capped and miter-joined (offset_polyline in geom.rs, then Polygon::obstacle). The editor keeps the line; the sim sees the thick polygon. Walls are not joined into the floor outline.

Portal

A region that emits walkers, receives them, or both.

See behaviours.md for trips and the street-id convention, and for visitors.

Store

A shop on one floor, solid to walkers, entered through its door. See behaviours.md.

The block is also an obstacle with the same id. The parser adds a door portal, {store}_door, a strip 1 m deep in front of the door; only a visitor bound for that store arrives through it.

Crossing

A road crossing on one floor: a polygon walkers may only step onto while it shows walk. A signalled one runs a fixed cycle of walk, flashing, then don't walk. One with lanes and none of the three phase fields is a zebra: it shows walk while every vehicle coming on those lanes could stop short of it (vehicles.md).

The polygon is walkable floor like any other; the road around it is simply not part of the floor. See behaviours.md for how walkers treat the signal.

Lane

One lane of carriageway, drawn as a LineString along its centreline in the direction of travel. Vehicles drive it as described in vehicles.md. A lane is not a wall. To keep walkers off the road, leave the carriageway out of the floor.

Where lanes meet, cross or fork is found from their geometry; see vehicles.md.

Vehicle signal

A vsignal is a LineString stop line drawn across one or more lanes on its floor. It must cross at least one. Each lane it crosses gets a stop line where it crosses. Vehicles stop there on red, and on amber if they can stop comfortably (vehicles.md).

Vehicle source

A Point that emits vehicles onto the lane whose centreline passes nearest it, within 3 m, on its floor.

Vehicle sink

A Point bound to the nearest lane in the same way. Vehicles bound for it leave when their front passes it. It has no fields except floor.

Drop-off kerb

A dropoff is a Polygon drawn beside a lane on its floor: the kerb vehicles pull in to, to set down or pick up. It binds to the lane nearest its middle (the mean of its corners), within 6 m. The kerb's stretch is the polygon's span along that lane. Bays split it evenly, bay 0 at the downstream end. A vehicle standing in a bay is drawn at the polygon middle's offset from the lane. How vehicles queue, pull in and leave is in vehicles.md.

Parking

A parking lot is a Polygon on its floor holding bays for one mode, off an entry lane. Its bays are either a count, laid side by side along the polygon's span on the entry lane, nose in, each centred at the polygon middle's offset; or child bay polygons. Each bay's mouth is where its middle is nearest the entry lane, and its exit mouth likewise on the exit lane. The gate stands 6 m before the first bay mouth, or at the start of the entry lane.

A bay is a Polygon with parking set to its lot's id and nothing else. A vehicle in it faces from the entry lane towards the bay's middle.

Zone

A polygon that changes speed or carries a walker between floors.

A zone is a connector when it has a pair_id. It is a stair when it is a connector and not an escalator or a gate. It is single file when it is a gate, an escalator, has lane: 1, has a fixed speed, or is at most 1.2 m wide.

Escalators are walkable only on the entry floor (z_from when dir is along, z_to when against). Stairs are walkable from either end, and only on the two floors at their end heights, so flights stacked in one well on a taller building do not block each other. A two-way stair is taken when its far end is nearer the destination floor; a one-way stair or escalator only when it serves that ascent. Gates serve a same-floor crossing: one-way along the rise (or against it), or both ways when dir is both.

A zone may face any angle. Its shape is read as the rectangle that bounds the polygon along rise_along: the foot edge is where travel starts, the top edge where it ends, and the two sides run with travel. Every end, mouth, lane and progress test is made in that rectangle, so a stair drawn at 30 degrees behaves like the same stair drawn along x.

Long sides of a zone are walls, so a flight keeps people on the tread. The open ends are the mouths.

Teleport

A landing of a vertical pair. A stair or escalator has exactly two landings. An elevator may have a landing on every floor it serves, each on a different floor. delay_s is how long the walker is frozen (for an elevator, the ride of one storey); the pair uses the largest delay. An elevator pair also has capacity (people per car) and hold_s (how long the doors wait after the last person boards), again the larger of the landings. Each elevator landing may name a door, the doorway segment on its edge; walkers then board and step out only through it. Pair each landing with a floor hole of the same outline so the shaft is solid on every floor.

Geometry is a polygon (area trigger) or a line (the trigger segment). For a walked stair or escalator, a leftover pad uses the hallway’s exit edge as the trigger. A walked stair's line on each floor sits at the end away from that floor: the lower floor's at the top, the upper floor's at the foot. Elevator pairs have no zone; the walker must enter the landing polygon. Elevator doors may sit at a shaft edge, so a landing slightly inside a floor hole is still reachable (about 1 m).

Attractor

A polygon on one floor that may capture a walker. See behaviours.md.

Track

A platform edge with a train timetable. Geometry is a two-point line along the edge; the train runs from the first point to the second, on the side away from the platform. The platform is the side given by platform_side, or else the side with more open floor (floor not covered by an obstacle or a store) just beyond each door, at 0.6, 1.5 and 3 m in; a tie goes to the left. So a floor drawn under the track still works when the track bed is an obstacle, and platform_side settles any case the floor cannot. Doors are placed by the train, so they move with cars, car_length and stop_at instead of being drawn. Each door is a walkable inset DOOR_DEPTH (0.8 m) into the train: the floor plate grows a U-bay at the doorway, and the three far sides are walls.

Each door becomes a portal ({track}_d0, _d1, … in car order) that boarders target and alighters spawn from. See behaviours.md.

Seed agents

Optional agents array: already-placed walkers with id, x, y, optional z or floor, a target portal, and route (stair or elevator, default stair). Portals do the bulk of the population; seed agents are the sample already on the floor when the run loads.