# SPG Vending — Simulation integration

This is a visualization client. It does not connect to, or send commands to, business systems, readers, accounting software, or vehicle trackers. The initial workday is a deterministic sample. Locations are conceptual, not geocoded DFW addresses.

## Load a replay now

Use **Simulation data → Load simulation JSON**. Download the sample in the same dialog for a complete valid file. Imports remain in browser memory and reset on refresh; they are not uploaded or persisted. Files must be smaller than 10 MB.

The file uses `schemaVersion: 1`, `company: "spg"`, `title`, `startTime` in 24-hour HH:MM, `durationMinutes`, and `frames`. Frames start at minute 0, strictly increase, and are full snapshots. The current model supports up to 20,000 frames / seven days and one route vehicle.

Each frame has:
- `minute`: elapsed simulation minutes, independent of wall time.
- `counters`: numeric, nonnegative values or null. Missing values display “—”. Counters are supplied by the simulation, never inferred from truck arrival.
- `locations`: entries with `id`, `status`, and optional `level` / `progress` (0–100 or null). Omitted locations display “Not reported”.
- `vehicles`: zero or one entry with `id: "truck-1"`, `x`, `z`, optional `heading` (radians), `moving` (boolean), `working` (boolean), `locationId`, `workProgress` (0–100). Omit the vehicle to hide it. Coordinates are schematic world units with x between −179 and 181, and z between −179 and 169, not GPS.
- `activity`: `title`, `detail`, optional `locationId`.

Statuses, inventory and counters step at reported frame times. Only vehicle positions interpolate between frames when `moving` is true. Rewinding recomputes from snapshots and never doubles totals.

## Push snapshots from a future adapter

The renderer exposes `window.WorldSimulation`:

```js
window.WorldSimulation.loadScenario(validatedReplayObject);
window.WorldSimulation.ingestFrame(fullSnapshot);
window.WorldSimulation.getState();
```

`ingestFrame` switches to Simulation feed mode and disables local playback/seek. Its `minute` is relative to the current replay's `startTime` (08:00 in the sample). The world holds the last snapshot if updates stop and shows “Waiting for next update” after 15 seconds. A full snapshot is required; this is not an incremental event endpoint. The bridge runs in the page: an authenticated adapter must be added to connect a remote simulation. Never put upstream secrets in browser code or import files.

## Location mapping

| ID | Scene location | x | z |
|---|---|---:|---:|
| `hq` | SPG Warehouse | -30 | -10 |
| `office` | Office lobby | 48 | -12 |
| `gym` | Fitness center | -43 | 44 |
| `clinic` | Medical center | 49 | 44 |
| `campus` | Campus commons | -37 | -56 |
| `factory` | Factory breakroom | 49 | -56 |

## Counter mapping

- `sales`: Sales
- `revenue`: Revenue
- `restocks`: Restocks
- `service`: Service jobs
- `alerts`: Open alerts
- `online`: Readers online

## Next integration inputs

Provide the simulation endpoint or export, authentication method, event schema, business IDs, update cadence, clock/pause behavior and confirmed completion statuses. Map GPS into an eventual geographic renderer; do not pass latitude/longitude as x/z. Unavailable inventory stays unknown. The simulation owns action approvals and writes.

Based on the five-machine Total Control pilot brief. Vendor API access and remote pricing remain unconfirmed. This viewer sends no commands to readers.

## Interactive sample workdays

**Workday** creates a deterministic nine-hour simulation with five machines. Customer demand can be set to 50–200%. Purchase rates increase during the sample lunch window. An optional reader outage at 10:00 AM reduces the medical-center purchase rate to model cash-only sales until the driver confirms service. These are illustrative assumptions, not SPG measurements.

The sample dispatches one truck when stock reaches 30% or a reader needs service. It picks stock at the warehouse, follows the street network, records actual carried quantities at refill confirmation and returns to the warehouse. Stock continues decreasing during travel and picking. High demand can leave unresolved alerts at closing.

Optional location fields: `machineId`, `units`, `capacity`, `sales`, `revenue`, `refilled`, `readerOnline`, `lastSaleMinute`, `price`. Counts require the complete group (`units`, `capacity`, `sales`, `revenue`, `refilled`, `readerOnline`). Optional top-level replay `events` contain `minute`, `title`, `locationId`, `kind`; the Workday menu uses these as seek points. Optional frame `route` includes known `locationId`, phase (`pick`, `drive`, `work`, `return`) and an array of `{x,z}` path points. Existing schemaVersion 1 replays without these additions remain supported.

Use **Download this replay** for the current workday including chosen assumptions. Controls reset the replay locally and send no external commands.

## Expanded city
The city covers 360 × 348 world units, four times its original area. The 32 city-only businesses are explorable scenery. The five pilot machines and warehouse retain their replay behavior. Decorative traffic contributes no operational metrics.