Skip to content

Add deferred world spawn tracking and visible failure badge during background population#1138

Open
Copilot wants to merge 3 commits into
mainfrom
copilot/fix-loading-ux-issues
Open

Add deferred world spawn tracking and visible failure badge during background population#1138
Copilot wants to merge 3 commits into
mainfrom
copilot/fix-loading-ux-issues

Conversation

Copilot AI commented Jun 2, 2026

Copy link
Copy Markdown
Contributor

After interactive load completes, deferred/background population could fail silently (console.warn/error only), leaving users with missing objects and no clear signal. This change adds centralized spawn failure accounting and surfaces failures directly in the deferred HUD while preserving normal happy-path behavior.

  • Spawn telemetry + debug surface

    • Added src/world/spawn-tracker.ts to track:
      • attemptCount, successCount, failCount
      • per-type counters (byType)
      • bounded recent error list (errors)
    • Publishes a live report to window.__worldPopulationReport for debugging/tests.
  • Wired into existing failure/creation paths

    • generation-core.ts
      • resets tracker at generateMap start
      • records attempts/success/failures in processMapEntity
      • captures null-factory returns as explicit failures
    • generation-decorators.ts
      • records procedural-extra attempt/success/failure with normalized type tracking
    • background-processor.ts
      • records deferred task failures via task-id → failure-type mapping
    • deferred-loader.ts
      • records deferred loader item failures in aggregated category
  • Deferred indicator: user-visible failure signal

    • Extended deferred HUD markup with .deferred-fail badge.
    • Added setDeferredFailures(failed: number) to loading-screen API surface.
    • Updated deferred progress loop in core/main.ts to sync badge from tracker report.
    • Badge text is explicit and screen-reader friendly ("{n} objects failed to load").
  • API/export updates

    • Re-exported failure badge API through:
      • src/ui/loading-screen.ts
      • src/ui/loading-screen-progress.ts
      • src/ui/index.ts

Example (new debug surface):

// Available during/after FULL population
window.__worldPopulationReport
// {
//   attemptCount: 412,
//   successCount: 409,
//   failCount: 3,
//   byType: { mushroom: { attempted: 40, succeeded: 39, failed: 1 }, ... },
//   errors: [{ type: "mushroom", context: "map-entity:abc123", message: "..." }]
// }

ford442 commented Jun 2, 2026

Copy link
Copy Markdown
Owner

Note from workspace: I pre-seeded the first slice of the plan (SpawnTracker + live failure badge in the deferred populating indicator + wiring + main.ts integration + window.__worldPopulationReport) so the PR can focus on review / polish / remaining bullets rather than starting from zero.

See detailed comment + verification steps on the parent issue #1135.

Files touched in support of this PR:

  • src/world/spawn-tracker.ts (new)
  • src/world/generation-core.ts (import + record on fail)
  • src/world/generation-decorators.ts (import + record on fail)
  • src/utils/background-processor.ts (import + maybeRecord on spawn-ish tasks)
  • src/ui/loading-screen.ts and loading-screen-ui.ts (badge HTML + live update in setDeferredProgress)
  • src/core/main.ts (reset on enter, report + toast on complete)

The changes are intentionally minimal and safe. Happy path perf unaffected.

Please continue with the WIP plan (e.g. also update the duplicate DOM creation path if needed, add a small css rule for .deferred-fail if the inline style is insufficient, consider exposing failed count from BackgroundProcessor.onComplete, etc.). Then open for review.

Copilot AI changed the title [WIP] Fix loading UX for background object population Add deferred world spawn tracking and visible failure badge during background population Jun 2, 2026
Copilot AI requested a review from ford442 June 2, 2026 04:41
@ford442 ford442 marked this pull request as ready for review June 3, 2026 17:58
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.

Loading UX: Visible progress bars, completion guarantee, and error surfacing for deferred / background object population (follow-up to #1133)

2 participants