Raw Patch Notes

- RESOLVED (#143): user confirms the stutter is 100% gone — buttery smooth at 25 pawns, zoomed out, at 4x speed. Final root cause was BuildingPortraitSlot's per-pixel CPU portrait compositing on every health/happiness change (plus the earlier contributing fixes: DebugLog per-line flush, synchronized tick fan-out, idle GOAP replanning every frame, effect-rules scans, SocialSystem per-tick bulk passes, synchronized AI refresh timers, physics interpolation off, substep cap spiral). Diagnostics suite (TickProfiler + FrameProbe + per-system labels) is KEPT permanently — single toggle: Settings > Tick Profiler; near-zero cost when off. Docs updated: current-game-setup.txt (TickProfiler/FrameProbe/portrait compositing/frame pacing), AGENTS.md (performance lessons under Engineering Principles). Known remaining scaling wall (separate from the stutter): at 100 pawns, per-pawn physics-step cost (~0.3ms/pawn: movement + AI + anim at 60Hz) exceeds the 16.7ms step budget -> permanent catch-up -> ~6-12 effective FPS. Candidate levers (not yet implemented): pawn simulation LOD (reduced physics rate for off-screen/distant pawns), animation LOD, lower global physics tick rate (interpolation keeps visuals smooth), Stats effective-speed caching.
UPDATE 2026-07-06 #144 - Pawn-Count Scaling Pass (user-approved, targets 100+ pawns)
- Goal: raise the ~50-pawn physics budget ceiling identified in #143 (per-pawn step cost ~0.3ms x 60Hz). Four levers, all approved:
- (1) Pawn simulation LOD (`Scripts/BasicWanderAI.gd`): pawns outside the camera view (+400px margin) execute their physics step only every 3rd frame (`OFFSCREEN_SIM_DIVISOR`), with skipped time folded into the executed step via `_sim_delta_scale` (multiplies both `sdelta` for timers/pacing AND `eff_speed` so move_and_slide displacement matches) — distances, timers, and arrival times are identical, movement is just sampled coarser where invisible. Per-pawn `_lod_phase` jitter de-synchronizes executed frames. The camera world-rect is computed once per rendered frame in a static and shared by all pawns.
- (2) Animation LOD (`Scripts/Characters/CharacterAnimationController.gd`): pose/wobble/vfx skipped entirely for off-screen actors (+200px margin); `_has_last_position` reseeds on re-entry so the first visible frame doesn't read the position delta as motion.
- (3) Effective-speed cache (`Scripts/Stats.gd`): `get_effective_stat("speed")` (called per pawn per step) now returns `_cached_effective_speed` unless `_effective_speed_dirty`; the flag is set conservatively at every mutating site (set_stat, set_state_flag, _set_status_effect_source, effect clears, speed modifier set/clear/clear-all, profile/save load reeval).
- (4) Physics 30Hz EXPERIMENT (`project.godot`): `physics/common/physics_ticks_per_second=30` — halves all per-step spend; physics interpolation keeps motion visually smooth. Revert = delete that one line if walk/input feel degrades.
- Files: `Scripts/BasicWanderAI.gd`, `Scripts/Characters/CharacterAnimationController.gd`, `Scripts/Stats.gd`, `project.godot`, `update-log.txt`, `current-game-setup.txt`, `AGENTS.md`.
- Fix (#144 follow-up): LOD pop-in/out at high game speed — the fixed 400px/200px off-screen margins were too thin at 4x speed (a LOD-stepped pawn covers 4x distance per executed step, crossing from skip-mode into view in one visible jump). Both BasicWanderAI's simulation-LOD margin and CharacterAnimationController's animation-LOD margin now scale with the current TimeSystem time scale. Needs-drain report investigated: NOT a code bug — `Data/Stats/needs.json` configures ALL four needs (hunger/sleep/relax/social) at the identical -5.0 delta_per_in_game_hour, so uniform drain is the configured behavior; pawns that show differing values are the ones that ate/slept/relaxed/socialized in the window (plus time-of-day effects and trait modifiers). Rate retuning offered to the user as a design decision.

*This is an automated post, using Python and LLMs to summarize game updates. Mistakes, while rare, may happen.