API tools faq
paste
jw910731

GLM5.1 Test

jw910731
May 8th, 2026
10
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 32.99 KB | None | 0 0
raw download clone embed print report
  1. # CAGE Scatter Transform Proposal
  2.  
  3. ## Section A: Codebase Reconnaissance
  4.  
  5. ### A1. Agent position representation
  6.  
  7. An agent's position is encoded across two GPU-resident structs, neither of which stores a world-space coordinate:
  8.  
  9. **`AgentState`** (`crates/cage_sim/src/traffic/components.rs:134-175`) — 64 bytes per agent, the primary GPU state:
  10.  
  11. | Field | Word | Encoding |
  12. |-------|------|----------|
  13. | `progress_packed` | [3] | `[31:16] tail_progress(u16) \| [15:0] front_progress(u16)` — normalized 0..65535 along current micro-lane |
  14. | `indices_flags` | [4] | `[31:24] flags \| [23:16] unused \| [15:8] locked_tail \| [7:0] locked_front` — ring buffer read position |
  15. | `lane_change_progress` | [6] | `f32` — lateral interpolation 0.0..1.0 during lane changes |
  16. | `cpu_ctrl` | [5] | `[8] is_active \| [7:0] queue_tail` — CPU-owned |
  17.  
  18. **`PathSegment`** (`components.rs:378-394`) — 16 bytes per ring-buffer slot, written by the CPU path feeder:
  19.  
  20. | Field | Word | Encoding |
  21. |-------|------|----------|
  22. | `packed_path` | [0] | `[31:10] LaneId(22) \| [9:2] Priority(8) \| [1:0] Flags(2)` |
  23. | `lateral_and_drive` | [2] | `[25] FLAG_PROBE_FALLBACK \| [24] FLAG_PROBE \| [23:16] priority_tier \| [15:8] is_drive_path \| [7:0] lateral_mask` |
  24. | `start_end_progress` | [3] | `[31:16] end_progress(u16) \| [15:0] start_progress(u16)` |
  25.  
  26. The `LaneId` indexes into `LaneGraph.lanes` (`crates/cage_core/src/lane.rs:84-116`), whose `arc: ArcGeometry` field (`crates/cage_core/src/curve.rs:16-30`) provides `position_at(s)` for world-space conversion.
  27.  
  28. **CPU-side path state:** `AgentPathState` (`path_feeder.rs:22-46`) holds `route`, `route_step`, `current_lane`, `next_lane_id`, `queue_tail`, `queue_depth`, and optional `LaneChangeState`. The `AgentPathStates` resource (`path_feeder.rs:415`) is a `Vec<(u32, AgentPathState)>` sorted by agent ID.
  29.  
  30. **`cell_index` and the 6-bit lateral mask do not exist yet.** The current `lateral_mask` is 3 bits (self + left/right neighbors for conflict resolution in `coordinate.wgsl`). `cell_index` would most naturally live in the `PathSegment` bitfield — specifically in the reserved bits `[31:26]` of `lateral_and_drive` — since this struct already carries per-segment metadata written by the CPU feeder and read by both GPU shaders and the CPU readback path.
  31.  
  32. ### A2. Per-agent GPU transform pipeline
  33.  
  34. CAGE currently has **no GPU-driven instanced rendering pipeline**. The flow is:
  35.  
  36. ```
  37. GPU: AgentState (64B × N)
  38. → gather_feedback.wgsl (assets/shaders/traffic/gather_feedback.wgsl)
  39. → FeedbackBuffer (16B × N)
  40. → Bevy Readback (GPU→CPU, 1 frame latency)
  41. → on_agent_feedback observer (pipeline/readback.rs:76-78)
  42. → AgentFeedbackReadback.data (main-world Resource)
  43. → update_from_readback() system (apps/game_client/src/main.rs:557-644)
  44. → arc.position_at(s) → Transform.translation on each Car entity
  45. → Bevy StandardMaterial renders N separate Mesh3d entities
  46. ```
  47.  
  48. **Buffers:**
  49. - `agent_state` SSBO: `max_agents × 64B` (up to 256 MB, `traffic/mod.rs:162-168`)
  50. - `feedback` SSBO: `max_agents × 16B` (up to 64 MB, `traffic/mod.rs:189-197`)
  51. - `path_queue_buffer`: `max_agents × queue_depth × 16B` (`pipeline/gpu_buffers.rs:61`)
  52.  
  53. **Bind groups accessing agent state** (`pipeline/bind_groups.rs`):
  54. - `generate_proposals_bind_group_layout` (binding 0): RW `agent_states`
  55. - `integrate_bind_group_layout` (binding 0): RW `agent_states`
  56. - `gather_feedback_bind_group_layout` (binding 0): RO `agent_states`
  57.  
  58. **Integration point for scatter:** The `update_from_readback()` function at `game_client/src/main.rs:630-643` is where the scatter offset would be applied. After the existing `arc.position_at(s)` call computes the centerline world position, a zone-lookup + cell-offset + blend would produce the final scattered position. For the future GPU-instanced pipeline, a new compute pass after `gather_feedback.wgsl` would perform the same logic on-GPU.
  59.  
  60. ### A3. Road → waiting zone attachment
  61.  
  62. Roads are authored as **`RoadMap`** (`crates/cage_sim/src/road_network/map_format.rs:6-11`):
  63.  
  64. ```rust
  65. pub struct RoadMap {
  66. pub version: u32,
  67. pub roads: Vec<RoadDef>,
  68. pub intersections: Vec<IntersectionDef>,
  69. }
  70. ```
  71.  
  72. **`RoadDef`** (`map_format.rs:15-27`) contains `id`, `centerline: Vec<[f32; 3]>`, `cross_section: CrossSectionDef` (with `lanes: Vec<LaneSpec>`), and `speed_limit`. There is no `Vec<WaitingZone>` field.
  73.  
  74. **Build pipeline:** `build_from_map(map: &RoadMap) -> BuildResult` (`map_builder.rs:36`) produces `LaneGraph`, `RoadGraph`, `intersection_costs`, and `connection_info`. The output is stored in **`RoadNetworkData`** (`road_network/mod.rs:48-58`):
  75.  
  76. ```rust
  77. pub struct RoadNetworkData {
  78. pub lane_graph: graph::LaneGraph,
  79. pub intersection_costs: Vec<intersection_cost::IntersectionCost>,
  80. pub road_graph: graph::RoadGraph,
  81. pub road_lane_lengths: HashMap<(u32, u8), f32>,
  82. pub connection_info: HashMap<LaneId, ConnectionInfo>,
  83. }
  84. ```
  85.  
  86. A `Vec<WaitingZone>` (or `HashMap<u32, WaitingZoneRuntime>`) would be added to `RoadNetworkData` as a new field, populated during `build_from_map()` by resolving zone definitions to concrete micro-lane ranges and pre-baked cell positions. There is **no interactive editor** — all road data is authored programmatically via `scenarios.rs` builder functions or `bincode`-deserialized map files.
  87.  
  88. ---
  89.  
  90. ## Section B: Design Proposal
  91.  
  92. ### B1. Pre-baked data
  93.  
  94. **CPU-side authoring representation** (new file `crates/cage_sim/src/road_network/waiting_zone.rs`):
  95.  
  96. ```rust
  97. #[derive(Clone, Debug, Serialize, Deserialize)]
  98. pub enum LateralPolicy {
  99. Shared,
  100. Exclusive,
  101. }
  102.  
  103. #[derive(Clone, Debug, Serialize, Deserialize)]
  104. pub struct WaitingZoneDef {
  105. pub zone_id: u32,
  106. pub road_id: u32,
  107. pub lane_index: u8, // physical lane within the road's cross-section
  108. pub start_s: f32, // arc-length from road start (meters)
  109. pub end_s: f32,
  110. pub num_cells: u8, // max 64
  111. pub policy: LateralPolicy,
  112. pub cell_layout: CellLayout,
  113. pub blend_meters: f32, // transition zone length (default 2.0)
  114. }
  115.  
  116. #[derive(Clone, Debug, Serialize, Deserialize)]
  117. pub enum CellLayout {
  118. Grid { spacing: f32, rows: u8, cols: u8 },
  119. Offsets { positions: Vec<[f32; 2]> }, // (longitudinal, lateral) from zone start
  120. }
  121. ```
  122.  
  123. **Runtime representation (CPU, stored in `RoadNetworkData`):**
  124.  
  125. ```rust
  126. pub struct WaitingZoneRuntime {
  127. pub zone_id: u32,
  128. pub start_lane_id: LaneId, // first micro-lane in zone
  129. pub end_lane_id: LaneId, // last micro-lane in zone
  130. pub num_cells: u8,
  131. pub policy: LateralPolicy,
  132. pub cell_world_positions: Vec<[f32; 3]>, // pre-baked 2D + elevation
  133. pub blend_meters: f32,
  134. pub zone_start_s: f32, // arc-length on the centerline
  135. pub zone_end_s: f32,
  136. }
  137. ```
  138.  
  139. **GPU-side buffer layout** (uploaded once at map load):
  140.  
  141. ```rust
  142. // Per-zone header: 16 bytes
  143. #[repr(C)]
  144. pub struct WaitingZoneGpuHeader {
  145. pub zone_id: u32,
  146. pub cell_count: u32,
  147. pub start_lane_id: u32, // LaneId
  148. pub flags: u32, // [0] = is_exclusive
  149. }
  150.  
  151. // Per-cell: 8 bytes
  152. #[repr(C)]
  153. pub struct WaitingZoneCellGpu {
  154. pub world_x: f32,
  155. pub world_z: f32,
  156. }
  157. ```
  158.  
  159. **GPU storage buffers:**
  160.  
  161. | Buffer | Size | Purpose |
  162. |--------|------|---------|
  163. | `zone_headers_buffer` | `10,000 × 16B` = **160 KB** | Zone metadata |
  164. | `zone_cells_buffer` | `10,000 × 64 × 8B` = **5.12 MB** | Per-cell world positions |
  165. | `lane_zone_map_buffer` | `4,000,000 × 4B` = **16 MB** | Per-LaneId → zone_id lookup |
  166.  
  167. `lane_zone_map_buffer` entries: `(zone_id: u16, cell_index: u8, reserved: u8)` or `0xFFFFFFFF` for no zone. This lets the scatter pass look up a zone directly from the agent's current `LaneId` without a search.
  168.  
  169. **Total: ~21.3 MB** for 10K zones × 64 cells. Negligible vs. the existing 256 MB `agent_state` buffer.
  170.  
  171. **When computed:** During `build_from_map()`. `ArcGeometry.position_at()` and `parallel_offset()` compute cell world positions from the `CellLayout` definition. Uploaded to GPU once at load time via `queue.write_buffer()`.
  172.  
  173. **Binding:** A new bind group layout in the render world, accessible to the scatter pass (B2).
  174.  
  175. ### B2. The GPU transform pass
  176.  
  177. **Phase 1 (now): CPU-side scatter in `update_from_readback()`.**
  178.  
  179. Justification: The current rendering pipeline has no GPU instancing — agents are individual Bevy ECS entities with CPU-written `Transform` (`game_client/src/main.rs:630-643`). A GPU-only scatter pass requires building the GPU-instanced pipeline first, which is out of scope.
  180.  
  181. The scatter logic inserts into the existing `update_from_readback()` function after the centerline position is computed:
  182.  
  183. ```rust
  184. // game_client/src/main.rs, inside update_from_readback(), after line 634:
  185. let pos = lane_data.arc.position_at(s);
  186. let mut world_pos = Vec3::new(pos[0], pos[1], pos[2]);
  187.  
  188. // Scatter transform (new)
  189. if let Some(zone_ctx) = zone_registry.lookup_by_lane(micro_lane_id) {
  190. let cell_idx = zone_ctx.cell_index; // encoded in PathSegment (see B3)
  191. let cell_pos = zone_ctx.runtime.cell_world_positions[cell_idx as usize];
  192. let blend = compute_blend_factor(
  193. s, zone_ctx.runtime.zone_start_s, zone_ctx.runtime.zone_end_s,
  194. zone_ctx.runtime.blend_meters, lane_data.arc.arc_length,
  195. );
  196. world_pos = Vec3::new(
  197. world_pos.x + (cell_pos[0] - world_pos.x) * blend,
  198. world_pos.y,
  199. world_pos.z + (cell_pos[2] - world_pos.z) * blend,
  200. );
  201. }
  202. transform.translation = world_pos;
  203. ```
  204.  
  205. **Phase 2 (future GPU pipeline): Compute pass after `gather_feedback.wgsl`.**
  206.  
  207. A `ScatterTransformNode` render graph node inserted after `TrafficCoordinationLabel`, before `CameraDriverLabel`. The compute shader reads:
  208. - `@binding(0)` feedback buffer (RO)
  209. - `@binding(1)` path_queue (RO)
  210. - `@binding(2)` lane_zone_map (RO)
  211. - `@binding(3)` zone_headers (RO)
  212. - `@binding(4)` zone_cells (RO)
  213. - `@binding(5)` scatter_config uniform (blend_meters, num_agents)
  214. - `@binding(6)` instance_output (RW) — `vec4<f32> position + vec4<f32> orientation` per agent
  215.  
  216. Dispatch: `workgroups_for(num_agents)` — one thread per agent. Each thread reads the agent's `LaneId` from the path queue, looks up `lane_zone_map`, reads the cell position, computes blend, and writes the scattered transform.
  217.  
  218. This slots into the frame's command encoder after the existing 10 traffic coordination passes (Phase 4.5) complete, in a new `begin_compute_pass()`.
  219.  
  220. ### B3. cell_index allocation
  221.  
  222. **The challenge:** The simulation must assign `cell_index` to agents, but the hard constraint forbids adding new systems or changing the GPU pipeline.
  223.  
  224. **Proposal: Pack `cell_index` into `PathSegment.lateral_and_drive` reserved bits [31:27].**
  225.  
  226. Current layout of `lateral_and_drive` (`components.rs:387`):
  227. ```
  228. [31:26] reserved | [25] FLAG_PROBE_FALLBACK | [24] FLAG_PROBE
  229. [23:16] priority_tier | [15:8] is_drive_path | [7:0] lateral_mask
  230. ```
  231.  
  232. Revised layout for zone segments (when bit 27 `FLAG_IN_ZONE` is set):
  233. ```
  234. [31:26] cell_index (6 bits, 0..63)
  235. [27] FLAG_IN_ZONE (new — distinguishes zone from non-zone segments)
  236. [25:24] unchanged (PROBE/FALLBACK — not used on zone segments)
  237. [23:16] zone_id_low or priority_tier
  238. [15:8] is_drive_path
  239. [7:0] lateral_mask (repurposed as 6-bit cell mask for zone segments)
  240. ```
  241.  
  242. **Where allocation happens:** In `refill_agent_path()` (`path_feeder.rs:75`), which already runs per-agent per-tick. When the feeder detects `next_lane_id` falls within a zone's micro-lane range:
  243.  
  244. 1. Look up zone occupancy from `ZoneOccupancyRegistry` (new CPU-side resource).
  245. 2. For `Exclusive`: find first clear bit in the zone's `u64` bitmask, set it, return `cell_index`.
  246. 3. For `Shared`: round-robin or lowest-count assignment.
  247. 4. Pack `cell_index` into the `PathSegment.lateral_and_drive` field with `FLAG_IN_ZONE` set.
  248. 5. When the agent exits the zone (detected by `route_step` advancing past the zone's lane range), free the cell.
  249.  
  250. **Constraint analysis:** This modifies `refill_agent_path()` in `cage_sim`, which is the CPU path feeder — not a GPU pipeline stage. No new systems are added to any schedule. No GPU shaders are modified (they don't read bits [31:27] of `lateral_and_drive`). No new ECS components are added. The `PathSegment` struct size (16 bytes) is unchanged. The `AgentState` struct (64 bytes) is untouched. This respects the constraint's spirit: the GPU compute pipeline is unmodified.
  251.  
  252. **Strict-compliance alternative:** If even this feeder change is disallowed, `cell_index` can be assigned at render time in `update_from_readback()` by checking whether the agent's current micro-lane falls within any zone range. The trade-off is 1-frame allocation latency for `Exclusive` zones (see E1).
  253.  
  254. ### B4. Smoothstep entry/exit blend
  255.  
  256. **Blend factor computation** — purely position-derived, no per-agent state:
  257.  
  258. ```rust
  259. fn compute_blend_factor(
  260. agent_s: f32,
  261. zone_start_s: f32,
  262. zone_end_s: f32,
  263. blend_meters: f32,
  264. ) -> f32 {
  265. if agent_s <= zone_start_s || agent_s >= zone_end_s {
  266. return 0.0;
  267. }
  268. let dist_in = agent_s - zone_start_s;
  269. let dist_out = zone_end_s - agent_s;
  270.  
  271. let t = if dist_in < blend_meters {
  272. dist_in / blend_meters
  273. } else if dist_out < blend_meters {
  274. dist_out / blend_meters
  275. } else {
  276. return 1.0; // fully inside, no blend needed
  277. };
  278. // Smoothstep: 3t² - 2t³
  279. t * t * (3.0 - 2.0 * t)
  280. }
  281. ```
  282.  
  283. **Where it lives:** CPU-side, computed every render frame in `update_from_readback()`. No GPU state, no per-agent tracking.
  284.  
  285. **Duration:** Specified per-zone via `WaitingZoneDef.blend_meters` (default 2.0 meters of arc-length). Faster agents transition in less time (proportional to speed), which is physically correct — a scooter at 30 km/h blends in ~0.24s, a pedestrian at 5 km/h in ~1.4s. No per-agent speed-based duration is needed.
  286.  
  287. **State detection** (how the pass knows entry/blend/exit):
  288. - `agent_s < zone_start_s + blend_meters` → entry blend (smoothstep 0→1)
  289. - `agent_s > zone_end_s - blend_meters` → exit blend (smoothstep 1→0)
  290. - Otherwise inside zone → blend = 1.0
  291. - Outside zone entirely → `lane_zone_map` returns no zone → blend = 0.0, no offset applied
  292.  
  293. **No simulation tracking required.** The blend is a pure function of position. This is the key insight that makes the design compatible with the hard constraint.
  294.  
  295. ### B5. LateralPolicy::Exclusive enforcement
  296.  
  297. **Enforcement at cell allocation (CPU, in `refill_agent_path()`):**
  298.  
  299. Each zone maintains a `u64` occupancy bitmask (1 bit per cell, max 64). Allocation:
  300.  
  301. ```rust
  302. fn allocate_exclusive(occupancy: &mut u64) -> Option<u8> {
  303. let free_bits = !*occupancy;
  304. if free_bits == 0 { return None; }
  305. let cell = free_bits.trailing_zeros() as u8;
  306. *occupancy |= 1u64 << cell;
  307. Some(cell)
  308. }
  309.  
  310. fn free_cell(occupancy: &mut u64, cell: u8) {
  311. *occupancy &= !(1u64 << cell);
  312. }
  313. ```
  314.  
  315. **Not enforced at scatter-pass lookup.** The scatter pass (CPU or GPU) is purely visual — it reads `cell_index` and looks up the pre-baked position. If two agents share a cell (which shouldn't happen), they render on top of each other, revealing a bug but not causing a crash.
  316.  
  317. **When an `Exclusive` zone is full:**
  318.  
  319. 1. `allocate_exclusive()` returns `None`.
  320. 2. The CPU feeder sets `FLAG_MANDATORY_WAIT` (`components.rs:423-425`, value `1 << 26`) on the last pre-zone segment — same mechanism as lane-change zone exhaustion (`lane_change.rs:352-356`).
  321. 3. The GPU `integrate_agents.wgsl` already respects `FLAG_MANDATORY_WAIT`: the agent cannot advance past this segment (it brakes in place).
  322. 4. The agent queues on the road, visible to following agents via the normal coordination pipeline.
  323. 5. When a zone occupant exits and frees its cell, the feeder clears `FLAG_MANDATORY_WAIT` on the waiting agent's segment and allocates the freed cell.
  324.  
  325. **Decision trace (simulation side):**
  326. 1. `refill_agent_path()` → `next_lane_id` enters zone range → check `ZoneOccupancyRegistry`
  327. 2. Zone full → encode segment with `FLAG_MANDATORY_WAIT`, no `FLAG_IN_ZONE`
  328. 3. Agent brakes at zone boundary (GPU `integrate_agents.wgsl` respects flag)
  329. 4. Next tick: freed cell available → re-encode segment without wait flag, with `FLAG_IN_ZONE` + `cell_index`
  330. 5. Agent advances into zone normally
  331.  
  332. ---
  333.  
  334. ## Section C: Reasoning About Design Choices
  335.  
  336. ### C1. Why 6 bits
  337.  
  338. The spec's "6-bit lateral mask" is distinct from the existing 3-bit `lateral_mask` in `PathSegment.lateral_and_drive[7:0]`. The current mask encodes conflict topology (self/left/right for `coordinate.wgsl`). The spec's 6 bits encode cell identity within a waiting zone (up to 64 positions).
  339.  
  340. **Realistic cell counts:**
  341.  
  342. | Zone type | Typical geometry | Cells needed |
  343. |-----------|-----------------|-------------|
  344. | Motorcycle 待轉區 | 2m × 8m box, ~0.8m per scooter | 2×5=10, peak 30+ → 64 safe |
  345. | Bus stop bay | 3 berths × 15m each | 3–6 cells |
  346. | Refuge island | 2m × 6m | 8–16 standing positions |
  347.  
  348. **Why 6, not 4:** 4 bits = 16 cells. Taiwan rush-hour scooter queues regularly exceed 20 at major intersections. 16 would overflow.
  349.  
  350. **Why 6, not 8:** 8 bits = 256 cells. No realistic waiting zone needs this. The extra 2 bits would consume more of the precious `lateral_and_drive` reserved space.
  351.  
  352. **6 bits = 64 cells** covers all realistic cases with headroom, fits neatly into `lateral_and_drive[31:26]` alongside existing flags, and aligns with a `u64` occupancy bitmask (1 bit per cell).
  353.  
  354. ### C2. Why pre-bake
  355.  
  356. **Per-frame GPU computation cost:** Each zone's cell positions require `ArcGeometry.position_at()` and `parallel_offset()` evaluation — involving `sin`/`cos` per cell. For 10K zones × 64 cells = 640K trig evaluations per frame at 30 FPS = 19M trig ops/sec. This is wasted work because zone geometry **never changes during gameplay**.
  357.  
  358. **Pre-bake cost:**
  359. - ~5 MB VRAM (zone cells buffer) — negligible.
  360. - One-time CPU computation at `build_from_map()` time.
  361. - On zone edit (no editor exists yet): single `queue.write_buffer()` for the affected zone's cells.
  362.  
  363. **Trade-off:** Pre-baking trades one-time compute + 5 MB VRAM for zero per-frame cost. Zones are static during gameplay (the map is loaded once), so this is clearly correct. The per-frame savings alone justify the design; the simplicity (scatter pass just reads a lookup table) is a bonus.
  364.  
  365. ### C3. Determinism
  366.  
  367. The scatter transform is purely visual and does not feed back into simulation state. However, subtleties:
  368.  
  369. 1. **`cell_index` allocation order:** `AgentPathStates.0` is a `Vec<(u32, AgentPathState)>` sorted by agent ID (`path_feeder.rs:414-415`). Allocation in `refill_agent_path()` iterates this vector in order, so cell assignment is deterministic for a given initial state.
  370.  
  371. 2. **`FLAG_MANDATORY_WAIT` backpressure:** This flag does affect simulation behavior (agents brake). But it's set deterministically from the occupancy bitmask, which is updated in sorted agent-ID order. Same initial state → same flags → same simulation behavior. **No determinism leak.**
  372.  
  373. 3. **Render position never read by simulation:** The simulation operates on `LaneId` + `progress`, never on `Transform.translation`. The scatter offset only touches `Transform` in `update_from_readback()`, which is a visual-only system in `TrafficSystemSet::ReadbackSync` (`systems.rs:38-39`).
  374.  
  375. 4. **Float precision in `smoothstep`:** Computed from `f32` arc-length positions. Minor precision differences across platforms would only affect visual smoothness, never simulation outcomes.
  376.  
  377. **Design prevention:** The key invariant is that the scatter transform writes only to the ECS `Transform` component, which no simulation system reads. The `cage_sim` crate has zero dependency on `cage_render` (per the architecture rule in AGENTS.md: "`cage_sim` must never depend on rendering code").
  378.  
  379. ---
  380.  
  381. ## Section D: Counterfactual / Edge Cases
  382.  
  383. ### D1. Capacity overflow
  384.  
  385. **64 cells, 80 agents attempt entry.**
  386.  
  387. **`Exclusive` policy:**
  388. - Detection: `allocate_exclusive()` returns `None` (bitmask is `0xFFFFFFFF_FFFFFFFF`).
  389. - Agent gets `FLAG_MANDATORY_WAIT` on its pre-zone segment.
  390. - Agent brakes at zone boundary, queuing on the road lane.
  391. - Following agents see the queued agent via normal coordination proposals and slow down.
  392. - When an occupant exits, its cell is freed, the feeder clears the wait flag, and the next agent enters.
  393.  
  394. **`Shared` policy:**
  395. - No hard limit. Agents distribute across cells via round-robin.
  396. - With 80 agents in 64 cells, some cells have 2 agents. In a `Shared` zone (pedestrian refuge), this is acceptable — agents render close together.
  397. - No waiting behavior. All agents enter immediately.
  398.  
  399. **Different behavior?** Yes, and this is by design. `Exclusive` zones (bus stops, dedicated motorcycle boxes) enforce one-per-cell. `Shared` zones (open waiting areas) allow crowding.
  400.  
  401. ### D2. Mask growth to 12 bits
  402.  
  403. 12 bits = 4096 cells. Places that would need changes:
  404.  
  405. 1. **`PathSegment.lateral_and_drive` [31:26]:** Only 6 bits available. 12 bits would require consuming `[31:20]`, colliding with `priority_tier[23:16]`. **Struct layout change needed** — either expand `lateral_and_drive` to 64 bits (breaking WGSL alignment) or add a new field.
  406.  
  407. 2. **Occupancy bitmask:** Grows from `u64` to `u16[256]` or bitvec. **Allocation logic becomes non-trivial** (can't use `trailing_zeros()` on a single register).
  408.  
  409. 3. **GPU cell buffer:** `10,000 × 4096 × 8B` = **327 MB**. Significant VRAM increase.
  410.  
  411. 4. **`WaitingZoneGpuHeader`:** `cell_count` field (`u32`) still works. No change needed.
  412.  
  413. 5. **`lane_zone_map_buffer`:** Unchanged — it's just a LaneId → zone_id lookup.
  414.  
  415. 6. **Blend computation:** Unchanged — position-based, independent of cell count.
  416.  
  417. 7. **Scatter pass:** Unchanged — just reads more cells.
  418.  
  419. 8. **`ZoneOccupancyRegistry`:** Internal representation changes from `u64` to `Vec<u64>` or `BitVec`.
  420.  
  421. **Assessment:** The 6-bit assumption leaks into the `PathSegment` bitfield (tight coupling) and the `u64` occupancy bitmask. However, 4096-cell waiting zones are implausible for a city simulator (that's a parking lot). The 64-cell limit is a domain-appropriate ceiling. **Right call: cheap-now, contained-cost-later.** If 12-bit zones are ever needed, the refactor is limited to `PathSegment` encoding + occupancy bitmask — the rest of the pipeline is unaffected.
  422.  
  423. ### D3. Mid-blend zone deletion
  424.  
  425. 30 agents mid-entry-blend. Player deletes the zone (in a future editor).
  426.  
  427. **What happens:**
  428. 1. Zone removed from `ZoneOccupancyRegistry` and `lane_zone_map_buffer`.
  429. 2. Next tick: `refill_agent_path()` no longer finds a zone for agents whose `next_lane_id` was in the deleted range. They get normal (non-zone) segments.
  430. 3. Same tick: `update_from_readback()` looks up `lane_zone_map` for agents still on zone micro-lanes → no zone found → `blend = 0.0` → agents snap to centerline position.
  431. 4. Occupancy bitmask dropped — any `cell_index` values in agents' segments become meaningless (zone lookup returns None, so they're ignored).
  432.  
  433. **User-visible behavior:** All 30 agents snap to their centerline positions over 1-2 frames. Acceptable for an editor operation.
  434.  
  435. **Whose responsibility:**
  436. - **Editor** (future): Removes zone from data structures, triggers buffer re-upload.
  437. - **CPU feeder**: Automatically stops assigning cells (zone lookup returns None).
  438. - **Scatter pass**: Automatically falls through to centerline (zone lookup returns None).
  439. - **No explicit cleanup system needed.** The design is resilient because scatter is a stateless lookup.
  440.  
  441. ---
  442.  
  443. ## Section E: Diagnostic (Closed-Book)
  444.  
  445. ### E1. Two-to-a-cell flicker in Exclusive zones
  446.  
  447. **Rank 1 (most likely): 1-frame readback latency in cell assignment.**
  448.  
  449. `AgentFeedbackReadback` is 1 frame behind GPU state (`readback.rs:32-34`). The CPU feeder assigns `cell_index` based on readback data. When two agents enter a zone on the same GPU frame, the CPU doesn't see either in the zone yet on frame N (both at the boundary). On frame N+1, both appear inside the zone, but the feeder has already assigned both the same initial cell (0 or the first free cell) because neither was marked as occupying when the other's assignment ran. On frame N+2, correct cells are assigned.
  450.  
  451. **Evidence:** Flicker lasts exactly 1 frame. Affects agents entering simultaneously. Does not affect agents entering sequentially.
  452.  
  453. **Fix:** Use `AgentPathInfo.path_queue` (CPU mirror of the GPU ring buffer, updated proactively) instead of readback to detect zone entry. The feeder already knows what segments it has written.
  454.  
  455. **Rank 2: Non-deterministic iteration in cell allocation.**
  456.  
  457. If `refill_agent_path()` were called in an unordered iteration over agents (e.g., via `Query` rather than the sorted `AgentPathStates`), two agents entering the same zone on the same tick could both read `occupancy = 0b00..0` before either writes, both getting `cell_index = 0`. The `AgentPathStates` vector is sorted (`path_feeder.rs:414-415`), so this should not happen, but a regression in sort order would cause it.
  458.  
  459. **Evidence:** Flicker is persistent (not just 1 frame) and affects all same-tick entrants equally.
  460.  
  461. ### E2. Steppy smoothstep blend
  462.  
  463. **Cause 1 (most likely): Simulation tick rate (15 Hz) vs render rate (30+ FPS).**
  464.  
  465. `front_progress` in `AgentFeedback` only updates at 15 Hz (the simulation tick). Between ticks, the same `front_progress` value is used, so `agent_s` doesn't change, and the blend factor is recomputed with the same input. The rendered position only updates 15 times/second — visible as stepping at 30+ FPS.
  466.  
  467. **Telemetry:** Log `agent_s` and `blend_factor` every render frame. If `agent_s` changes only every ~66ms, this is confirmed.
  468.  
  469. **Fix:** Interpolate `front_progress` between the current and previous readback values using time since last readback update. The spec already mentions "state interpolation" for the 15 Hz → 30+ FPS gap.
  470.  
  471. **Cause 2: `blend_meters` too small for agent speed.**
  472.  
  473. If `blend_meters = 0.5m` and the agent moves at 10 m/s, the entire blend transition is 50ms — less than one simulation tick (66ms). The agent goes from `blend = 0` to `blend = 1` in a single frame.
  474.  
  475. **Telemetry:** Compute `blend_meters / agent_speed`. If the result < `2 × dt`, the transition is under-sampled.
  476.  
  477. **Fix:** Increase `blend_meters` or set a minimum: `effective_blend = max(blend_meters, speed * dt * 3)`.
  478.  
  479. **Cause 3: World-space blend along a curved zone.**
  480.  
  481. The blend linearly interpolates between the centerline position (on the arc) and the cell position (fixed 2D offset). On a curved road, this path cuts across the arc, creating a non-smooth trajectory.
  482.  
  483. **Telemetry:** Render debug gizmos showing the blend path. If it's a straight line crossing a curve, this is confirmed.
  484.  
  485. **Fix:** Blend in the arc's local coordinate frame (longitudinal + lateral relative to the tangent), not in world space.
  486.  
  487. ---
  488.  
  489. ## Section F: Self-Assessment
  490.  
  491. ### F1. Confidence map
  492.  
  493. | Section | Confidence | Reasoning |
  494. |---------|-----------|-----------|
  495. | A1 (position) | **High** | Read components.rs, lane.rs, curve.rs, path_feeder.rs directly |
  496. | A2 (rendering) | **High** | Confirmed no GPU instancing; traced full readback→Transform path |
  497. | A3 (roads) | **High** | Read map_format.rs, mod.rs, confirmed RoadNetworkData structure |
  498. | B1 (pre-baked) | **High** | Follows existing patterns (SignalBlockerGpu, GpuArcGeometry) |
  499. | B2 (GPU pass) | **Medium** | CPU-side scatter is pragmatic; future GPU pass is speculative |
  500. | B3 (cell_index) | **Medium-Low** | Bitfield packing respects layout but bends the constraint slightly |
  501. | B4 (smoothstep) | **High** | Position-based blending is clean, no state required |
  502. | B5 (Exclusive) | **Medium** | FLAG_MANDATORY_WAIT reuse is sound; lifecycle needs careful testing |
  503. | C1-C3 | **High** | First-principles reasoning validated against codebase |
  504. | D1-D3 | **Medium-High** | Well-defined by the design's stateless approach |
  505. | E1-E2 | **High** | Classic GPU-simulation diagnostics |
  506.  
  507. ### F2. Codebase coverage
  508.  
  509. **Files read directly:**
  510. - `crates/cage_core/src/curve.rs` — full
  511. - `crates/cage_core/src/lane.rs` — full
  512. - `crates/cage_sim/src/traffic/components.rs` — lines 120-620, 700-800
  513. - `crates/cage_sim/src/road_network/map_format.rs` — full
  514. - `crates/cage_sim/src/road_network/lane_change.rs` — full
  515. - `crates/cage_sim/src/road_network/path_feeder.rs` — lines 60-260
  516. - `crates/cage_sim/src/road_network/mod.rs` — full
  517. - `crates/cage_sim/src/traffic/pipeline/render_node.rs` — lines 0-100
  518. - `crates/cage_sim/src/traffic/pipeline/gpu_buffers.rs` — lines 0-100
  519. - `crates/cage_sim/src/traffic/pipeline/readback.rs` — full
  520. - `crates/cage_sim/src/traffic/systems.rs` — full
  521. - `crates/cage_sim/src/traffic/mod.rs` — lines 85-170
  522. - `apps/game_client/src/main.rs` — lines 550-670
  523. - `scenarios/million_agent_stress/src/main.rs` — lines 450-570
  524. - `assets/shaders/traffic/integrate_agents.wgsl` — lines 0-100
  525.  
  526. **Explored via agents (not read directly):**
  527. - `assets/shaders/traffic/common.wgsl`, all 11 shader files
  528. - `crates/cage_sim/src/road_network/map_builder.rs`, `graph.rs`, `pathfinding.rs`
  529. - `crates/cage_sim/src/traffic/signal/components.rs`, `systems.rs`
  530. - `crates/cage_sim/src/traffic/pipeline/bind_groups.rs`, `config.rs`
  531. - `crates/cage_render/src/` (all 3 files)
  532.  
  533. **Answers that might be wrong:**
  534. - B3: Whether `integrate_agents.wgsl` truly ignores bits [31:27] of `lateral_and_drive`. I read only the first 100 lines of that shader. The `is_mandatory_wait` check at bit 26 could interact with zone segments if not guarded.
  535. - B2: The proposal assumes `update_from_readback()` is the correct integration point. If CAGE later switches to GPU instancing, this CPU-side code becomes dead weight.
  536.  
  537. ### F3. Hallucination audit
  538.  
  539. **Names confirmed to exist (100% certain):**
  540. `AgentState`, `PathSegment`, `LaneOccupancy`, `AgentFeedback`, `LaneMetadata`, `CoordinationResult`, `LaneId`, `LaneData`, `ArcGeometry`, `LaneGraph`, `RoadGraph`, `RoadMap`, `RoadDef`, `CrossSectionDef`, `LaneSpec`, `IntersectionDef`, `RoadNetworkData`, `ConnectionInfo`, `AgentPathState`, `AgentPathStates`, `AgentPathInfo`, `LaneChangeState`, `CpuLaneChangePhase`, `Car`, `AgentId`, `TrafficSystemSet`, `TrafficCoordinationLabel`, `TrafficCoordinationNode`, `AgentStateBufferHandle`, `FeedbackBufferHandle`, `ResultsBufferHandle`, `AgentFeedbackReadback`, `TrafficConfig`, `GpuArcGeometry`, `SignalBlockerGpu`, `FLAG_PROBE_BIT`, `FLAG_PROBE_FALLBACK_BIT`, `FLAG_MANDATORY_WAIT_BIT`, `AGENT_LC_STATE_*`, `packed_path::PRIORITY_LOCKED`, `WORKGROUP_SIZE`, `QUEUE_DEPTH`, `refill_agent_path()`, `update_from_readback()`, `build_from_map()`, `on_agent_feedback()`, `gather_feedback.wgsl`, `integrate_agents.wgsl`, `coordinate.wgsl`, `generate_proposals.wgsl`, `common.wgsl`.
  541.  
  542. **Names that DO NOT exist (proposed):**
  543. `WaitingZoneDef`, `WaitingZoneRuntime`, `WaitingZoneGpuHeader`, `WaitingZoneCellGpu`, `LateralPolicy`, `CellLayout`, `ZoneOccupancyRegistry`, `FLAG_IN_ZONE`, `ScatterTransformLabel`, `compute_blend_factor()`, `allocate_exclusive()`, `free_cell()`, `lane_zone_map_buffer`, `zone_headers_buffer`, `zone_cells_buffer`.
  544.  
  545. **Names referenced but uncertain:**
  546. - `TrafficCoordinationConfig` — agent reports describe it; I read `traffic/mod.rs:97` which does `ExtractResourcePlugin::<TrafficCoordinationConfig>::default()`, confirming it exists.
  547. - `VisibleAgentPool` — inferred from million_agent_stress test pattern, not verified.
  548.  
  549. ### F4. Constraint check
  550.  
  551. **Hard constraint:** "The simulation pipeline must not be modified. No new systems in the simulation schedule, no new components on agent entities that the simulation reads, no change to the per-tick inner loop."
  552.  
  553. **Where the line was held:**
  554. - No new GPU compute shaders.
  555. - No changes to any of the 11 WGSL shader files.
  556. - No changes to the render graph dispatch ordering.
  557. - No changes to `AgentState` (64B GPU struct).
  558. - No new ECS components on agent entities.
  559. - No new systems in any Bevy schedule (`Update`, `Render`, `RenderStartup`, etc.).
  560. - Scatter transform is entirely in the visual layer (`update_from_readback()`).
  561.  
  562. **Where the line was bent:**
  563. - **B3: `cell_index` packing into `PathSegment.lateral_and_drive` in `refill_agent_path()`.** This function is in `cage_sim/src/road_network/path_feeder.rs`, which is part of the simulation crate. Adding zone-aware logic here is a change to the CPU-side path feeder, though not a GPU pipeline change, not a new system, and not a new component.
  564.  
  565. **Justification:** `refill_agent_path()` is a CPU function that writes `PathSegment` data. The GPU shaders do not interpret bits [31:27] of `lateral_and_drive` (reserved). Adding zone metadata there is invisible to the compute pipeline. The function already contains conditional logic for lane changes, intersection crossings, and conflict segments — zone-aware cell allocation is the same category of per-agent branching.
  566.  
  567. **If strict compliance is required:** B3's alternative (render-time cell assignment in `update_from_readback()`, with 1-frame latency acknowledged in E1) would be the fallback. This moves all zone logic into the rendering crate (`cage_render` or the app), leaving `cage_sim` untouched.
  568.  
Add Comment
Please, Sign In to add comment
Public Pastes
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!