# Logistics Post (Native)

Logistics Post is a small delivery game where Godot owns the map, input,
selection, pacing and presentation, and one native `LogisticsPost` Node2D owns routing, job
assignment, inventory, and the fixed simulation ticks. Odin's decisions
visibly move the Godot game: workers walk the authored roads, and the
completion feedback arrives through the coarse `job_completed` signal — one
emission per delivered job, never per agent per tick.

## Try it and read the code

Click a source, then a destination, to queue a delivery. Click a worker to
inspect its job. Pause, Step and Reset let you watch the decisions one tick at
a time. Use [Build and run](#build-and-run) after configuring the project.

- [The native component](declarations/logistics_post.odin) exposes configuration,
  jobs, snapshots and the completion signal.
- [The pure subsystem](subsystem/logistics.odin) owns routing and simulation.
- [The scene controller](project/main.gd) turns selections into native requests
  and displays the results.

## The loop

The scene authors the map as an ASCII layout (walls, roads, two sources, two
destinations), imports it once as a bounded whole-grid snapshot
(`configure`), and submits jobs with explicit stable ids (`submit_job`
validates cell kinds). Workers claim the nearest pending job by BFS road
distance — index-ordered tie-breaks — walk one cell per fixed tick, pick up
at the source, deliver at the destination, and return to idle. Pause, Step,
and Reset pace the simulation; Reset re-runs the same seed so the spread and
every route replay identically. A `LogisticsSettings` Resource (worker
count, seed) is the saved authoring input the configure reads.

Presentation reads one bounded batch snapshot per frame
(`worker_snapshot`: five f32s per worker — id, cell x, cell y, state,
claimed job id) and one job-lifecycle accessor for the selected worker's
inspect line. Clicking a worker selects it; clicking a source then a
destination queues a job.

## Build and run

Use a configured copy with its attached SDK; the separate
[project setup guide](../../docs/setup.md) covers that connection.

```sh
/absolute/sdk/bin/gododin build --project-root /absolute/gododin/examples/logistics_post --profile debug
/absolute/sdk/bin/gododin run --project-root /absolute/gododin/examples/logistics_post
```

## Verification

This is the DevX plan's DX-8 example. The following records describe its
executed workload, rather than a general routing or platform claim.

The kernel (`subsystem/logistics.odin`) imports only core:mem. Six Odin
tests cover map/job validation, one worker's full delivery lifecycle with
same-seed replay digests, seed-dependent spawn spread, distinct claims by
two workers, and the batch snapshot under a tracking allocator (zero
outstanding bytes at teardown). The headless probe
(`verify_probe.gd`) drives the real scene: submission validation, delivery
with the `job_completed` signal carrying the stable id, same-seed replay,
and a GDScript-oracle route-length check on the reference map —
`GODODIN_LOGISTICS_PROBE_PASS` (debug and release, zero-owner launcher
runs). Start single-threaded by design; cancellable background routing
re-enters only through measured need and the existing ownership rules.