Skip to content

feat(web): request and arrival hooks for the split background packs (phase B step 3) - #124

Merged
KunalSiyag merged 3 commits into
mainfrom
droid/phase-b-export-hooks
Oct 28, 2026
Merged

KunalSiyag merged 3 commits into
mainfrom
droid/phase-b-export-hooks

Conversation

@KunalSiyag

@KunalSiyag KunalSiyag commented Oct 28, 2026 •

Copy link
Copy Markdown
Owner

What

Phase B step 3 of the web split-pack plan (docs/round3/web/phase-b-runtime-plan.md implementation order): Option A export classification tests + the runtime request/arrival hooks. Builds on #91 (loader hardening + WebPackStream, flag still off).

Runtime hooks

  • CityView asks WebPackStream.request_path() on an asset miss before any ResourceLoader.exists/cache decision (_scene, warm_scenes, _warm_one all route through one _pack_gate). A pending pack returns null without writing the cache, so a download in flight no longer poisons _scenes with a permanent null; the wait is recorded per pack.
  • On pack_ready, exactly the recorded paths are retried (warm_scenes), stale null entries are dropped, and loaded scenes keep their tuned materials. Genuine misses (no pack claims the path) and stream-less desktop runs keep the exact old behavior.
  • The one boot-side caller with its own exists() guard that could never register a miss — the tree props in _make_tree_kits, which ride in the props pack — now demands through the gate. Re-kitting chunks on arrival is part of the step-4 feature coverage.
  • FpContext.pack_stream (filled before player/collision/feature setup), GameBus.pack_ready(pack), FpMode forwards coordinator arrivals onto the bus and disconnects on teardown.
  • midlod demands the midlod pack on a baked-twin miss, keeps completed runtime twins across arrival (no _meshes/_jobs clearing, no _activate), and lets fresh mesh_for calls pick up baked files. render_opt passes the stream through.

Export classification (Option A pinned as tests)

  • tools/pytests/test_pack_closure.py: zone/service geometry, hero bodies/animation/roster/bonemaps, textures, fonts, UI sounds and all unmatched paths classify to boot; the eight decorative packs classify as background; BOOT_PATHS wins over prefix rules.
  • A project-wide closure test fails on any static cross-pack reference (preload, class-level load, scene ext_resource) — the boot pack can never statically depend on a download. Current tree: zero violations.
  • A parity test keeps PACK_RULES pack names inside WebPackStream.DEFAULT_ORDER so no pack silently queues in the unknown tail.

Tests

  • New tools/tests/pack_request_gate_test.gd (20 checks): pending pack demands once + no null poisoning, _warm_one yields without caching, arrival clears the wait set / drops stale nulls / the scene then loads and caches, genuine miss keeps the old completed-null behavior, no-stream desktop unchanged, teardown with a pending pack is safe, midlod demands once and the completed twin survives arrival.
  • tools/gate.sh quick PASS, tools/gate.sh full PASS, pytest 96 passed (coverage 97.11%), pre-commit checks pass (API docs regenerated).

Second commit tracks the people_pool.gd.uid that #112 missed (import noise for every fresh worktree).

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

KunalSiyag and others added 2 commits October 29, 2026 00:41
…phase B step 3)

CityView now asks WebPackStream.request_path() on an asset miss instead of
caching a permanent null: the scene cache, warm_scenes and _warm_one all pass
through a pack gate that demands the pack once and records the wait, so a
pending download no longer poisons the session cache. On pack_ready exactly
the waiting paths are retried and stale null entries dropped; loaded scenes
and their tuned materials are untouched. The one boot-breaking caller with
its own exists() guard (tree props, which ride in the props pack) now demands
through the same gate.

FpContext carries the stream, GameBus gains pack_ready(pack), and FpMode
forwards coordinator arrivals onto the bus before feature setup, disconnecting
on teardown. midlod demands its pack on a baked-twin miss, keeps completed
runtime twins across arrival, and lets fresh mesh_for calls pick up the baked
files; render_opt passes the stream through from the context.

Export side pins Option A as tests: zone/service geometry, hero and gameplay
inputs stay in boot, the eight decorative packs classify as background, and a
project-wide closure test fails on any static cross-pack reference (preload,
class-level load or scene ext_resource) so the boot pack never depends on a
download. A parity test keeps PACK_RULES aligned with WebPackStream.DEFAULT_ORDER.

Gate quick + full PASS; tools/tests/pack_request_gate_test.gd covers the
pending/arrival/genuine-miss/teardown matrix (20 checks); pytest 96 passed.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown

Automated review

No new findings on the 12 changed files (gdlint, complexity, TODO policy, dead code).

Run python3 tools/checks/run_all.py locally for the full set of checks.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
@KunalSiyag
KunalSiyag merged commit 8314f60 into main Oct 28, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant