open-wc/docs/modules/world-renderer.md

World Renderer

Metadata

Field	Value
Status	Partial
Target/work package	M00 active; декомпозиция M01–M03
Owners	Renderer workstream / milestone integrator
Last verified	M00 visual-diff worktree, 2026-07-11
Profiles/capabilities	Performance, Balanced, High, Custom; Blizzlike fidelity incomplete

Purpose

Загрузить и визуализировать мир WoW 3.3.5a вокруг streaming focus: terrain, ADT placements, M2, WMO, liquids, sky/light и character/world presentation experiments. Система должна скрывать I/O/parsing/finalization latency за prewarm и per-frame budgets.

Non-goals

• Не владеет gameplay/world authoritative state.
• Не читает network packets или server DB.
• Не определяет player input/movement rules.
• Не является Content Project или editor source of truth.
• Текущий module не заявляет визуальное соответствие 1:1; gaps ведутся в ../../RENDER.md.

Context and boundaries

flowchart LR
    Focus[Camera/player/editor focus] --> Loader[StreamingWorldLoader]
    Assets[Extracted WDT/ADT/M2/WMO/BLP] --> Native[Native loaders]
    Cache[Baked terrain/M2/WMO caches] --> Loader
    Native --> Parsed[Parsed tile/model data]
    Parsed --> Loader
    Loader --> Scene[SceneTree nodes]
    Loader --> RS[RenderingServer RIDs/MultiMesh]
    Sky[DBC sky/light data] --> SkyController[WowSkyController]
    SkyController --> Scene

Allowed dependencies:

• native format loaders;
• render builders/material helpers;
• immutable/cached render resources;
• renderer configuration and focus;
• Godot rendering/scene APIs.

Forbidden dependencies:

• packet codecs/world session;
• gameplay reducers/quest/combat state;
• runtime UI Controls;
• direct TrinityCore/AzerothCore database access.

Public API

Текущая система ещё не имеет стабильного facade. Фактический integration surface — StreamingWorldLoader Node3D и exported properties. M03 должен заменить этот surface на WorldRenderFacade.

Symbol	Kind	Purpose	Thread/lifetime	Errors
map_name	Exported property	WDT/map directory name	Set before world load	Missing WDT produces diagnostic/empty world
extracted_dir	Exported property	Root of legally extracted client data	Session lifetime	Missing files reported per loader path
camera_path	Exported property	Current streaming focus compatibility path	Main thread, scene lifetime	Missing camera prevents normal focus update
quality_preset	Exported property	Applies renderer budgets/radii	Before/at runtime depending property	Invalid combination should be diagnosed
runtime_stats_enabled	Exported property	Enables periodic performance snapshot	Runtime mutable	Logging overhead only
hitch_profiler_enabled	Exported property	Enables named hitch sections	Runtime mutable	Logging overhead only

Публичным contract не считаются внутренние dictionaries, queues, job records и generated node names.

Inputs and outputs

Direction	Contract/data	Producer	Consumer	Ownership	Thread/lifetime
Input	Map/focus/configuration	Scene/app/editor	StreamingWorldLoader	Caller config, copied/read	Main thread/session
Input	WDT/ADT/M2/WMO/BLP bytes	Extracted asset repository	Native loaders/builders	Loader result owns parsed data	Worker or controlled load
Input	Baked resources	Cache build tools	Streamer/builders	Shared immutable resource/cache entry	Session/cache lifetime
Output	Desired tile/detail operations	Streaming planner inside loader	Finalize queues	Loader-owned	Cross-frame
Output	Terrain/M2/WMO/liquid instances	Loader/builders	Godot world/renderer	Loader/world owner	Main-thread attach
Output	Metrics/diagnostics	Hitch/stat instrumentation	Logs/baseline tools	Immutable records	Periodic/frame

Side effects:

• reads extracted files and generated caches;
• creates/frees scene nodes, meshes, materials, MultiMeshes and RIDs;
• submits worker tasks;
• mutates shader globals/environment through render/sky paths;
• writes logs and baseline captures through tools.

Data flow

flowchart TD
    F[Streaming focus] --> T[Compute desired ADT tiles]
    WDT[WDT tile catalog] --> T
    T --> Q[Tile load queue]
    Q --> P[Worker parse/cache load]
    P --> R[Result queues]
    R --> B[Per-frame budget scheduler]
    B --> Terrain[Terrain attach/upgrade]
    B --> M2[M2 group/MultiMesh attach]
    B --> WMO[WMO instance/group attach]
    B --> Liquid[Liquid attach]
    Terrain --> World[Godot world]
    M2 --> World
    WMO --> World
    Liquid --> World
    F --> E[Eviction/retention decisions]
    E --> World

Lifecycle/state

stateDiagram-v2
    [*] --> Initializing
    Initializing --> Ready: WDT/catalog/config ready
    Initializing --> Degraded: missing loaders/data/cache
    Ready --> Streaming: focus update
    Streaming --> Streaming: load/finalize/evict ticks
    Streaming --> SwitchingMap: map/focus reset
    SwitchingMap --> Initializing
    Ready --> ShuttingDown
    Degraded --> ShuttingDown
    Streaming --> ShuttingDown
    ShuttingDown --> [*]

Main sequence

sequenceDiagram
    participant Focus as Camera/Player/Editor
    participant Stream as StreamingWorldLoader
    participant Worker as Worker task
    participant Budget as Main-thread budget
    participant Render as SceneTree/RenderingServer
    Focus->>Stream: focus position changed
    Stream->>Stream: desired tiles and priorities
    Stream->>Worker: parse/load tile and detail data
    Worker-->>Stream: immutable result
    Stream->>Budget: enqueue finalize operations
    Budget->>Render: attach bounded terrain/M2/WMO/liquid work
    Stream->>Render: evict outside retention range
    Stream->>Worker: shutdown: wait for WorkerThreadPool tasks
    Stream->>Stream: shutdown: finish registered ResourceLoader requests
    Stream->>Render: clear queues, nodes, caches and RIDs

Ownership, threading and resources

• StreamingWorldLoader владеет tile states, queues, task registries, active world instances и render caches session scope.
• Worker tasks не должны менять SceneTree и shared Resource concurrently.
• Parsed/grouped results передаются обратно через guarded result queues.
• Mesh/material/node/RID finalization выполняется main thread и ограничивается exported budgets.
• Shutdown/map switch обязан дождаться WorkerThreadPool jobs и зарегистрированных threaded ResourceLoader requests до очистки очередей, nodes, caches и RIDs.
• Cache resources считаются immutable после публикации.

Errors, cancellation and recovery

Failure	Detection	Behavior	Diagnostic	Recovery
Missing WDT/ADT	File/catalog check	Tile/map unavailable	Loader warning/error	Fix extraction/profile, reload
Cache version mismatch	Required format constant	Reject stale cache/fallback	Version diagnostic	Rebuild matching cache
Worker failure	Task result/empty data	Skip/degrade affected asset	Queue/task warning	Retry/rebuild source
Main-thread hitch	Named section timing	Frame spike, work remains queued	HITCH log	Lower budget/fix finalize path
D3D12 descriptor exhaustion	Rendering backend error	Render failure/fallback backend	Godot error + baseline report	Dedup resources/fix settings
Teleport/map change	Focus/session transition	Old jobs become stale	Target/session generation	Cancel/drop stale results
Shutdown leak	Godot leak/RID diagnostics	Resource retained	Verbose shutdown report	Drain owned worker and resource requests before clearing registries

Configuration and capabilities

Setting/capability	Default	Profile	Runtime mutable	Effect
Quality preset	Scene-specific	All	Limited	Applies radii and finalize budgets
Terrain control splat	Enabled in current High paths	Render	Limited	Near terrain texture quality
M2/WMO/liquids	Scene/profile-specific	Render	Debug/config	Enables asset categories
Runtime stats/hitch profiler	Usually debug	Dev/test	Yes	Observability cost
Shadow flags	Mostly disabled/limited	Blizzlike/Enhanced	Profile	CPU/GPU cost and visuals

Exact exported settings and cache versions remain documented in ../../RENDER.md until extracted services receive individual specs.

Persistence, cache and migration

• Renderer reads caches under data/cache; caches are not committed.
• Format changes require FORMAT_VERSION/required-version bump and rebuild instructions.
• Atomic cache publication and unified manifest are target-state work from FND/M03.
• Material-only changes may refresh without geometry rebake only when documented safe.

Diagnostics and observability

• Logs: HITCH, PERF, TERRAIN_QUALITY, SKY_LIGHT, SKYBOX_MODEL.
• Metrics: queue depths, active tiles/assets, named finalize times, frame percentiles and max hitch.
• Debug views: render checkpoint scenes/captures; future streaming/LOD/portal overlays.
• Correlation IDs: currently mostly tile/path keys; target architecture adds session/job IDs.

Verification

• Unit/contract tests: material mapping, unique-ID dedupe, placement probes, baseline manifest, five-point coordinate calibration, synthetic perceptual checkpoint diff, camera-pose grid plan.
• Integration/E2E: Eastern Kingdoms/Kalimdor streaming scenes and seven cold/warm checkpoints.
• Fidelity evidence: пять локальных build 12340 reference JPG откалибровали terrain/ADT/M2/WMO/liquid viewpoints; automated paired-image metrics exist, но synthetic animation/dusk и полный human approval ещё не закрыты.
• Performance budgets: M00 report records cold/warm p95 and max hitch; no final acceptance threshold yet.
• Manual diagnostics: ../RENDER_BASELINE.md and ../../RENDER.md.

Extension points

• Target WorldRenderFacade for runtime/editor/capture callers.
• Target StreamingFocus independent of Camera3D.
• Extracted planner, budget scheduler, terrain, M2, WMO, liquid, sky and character services.
• Separate Blizzlike/Enhanced material and quality profiles.

Capability status

Capability	Status	Evidence	Gap/next step
ADT streaming/terrain	Partial	M00 checkpoints and current scenes	Fidelity/performance gaps remain
Static M2 placement	Partial	MultiMesh/dedupe probes	Full materials/animation/effects
WMO rendering	Partial	Cached group rendering	Portals/rooms/material parity
Liquids	Partial	MH2O/MLIQ paths	LiquidType/depth/shore fidelity
Sky/light	Partial	DBC controller/logs	Zone transition paired validation
Character presentation	Prototype	Character creator/player experiment	Full customization/equipment states
Stable renderer facade	Planned	M03	Current caller uses monolithic Node API

Known gaps and risks

• Monolithic streamer mixes planning, jobs, caches and presentation.
• Direct camera path remains until M01/M03.
• Original-client paired fidelity evidence incomplete.
• Первый paired run выявил coordinate/placement mismatch: несколько совпадающих server-derived camera positions оказываются под terrain или внутри WMO/rocks OpenWC.
• Terrain-height probe исключил under-terrain состояние для всех пяти точек; waterfall exact-XZ miss классифицирован как TriangleMesh seam/edge и подтверждён nearby sample в 2 units.
• Camera-occluder probe не нашёл camera containment в пяти точках; paired mismatch локализован прежде всего в manual look direction/target/FOV calibration, с явным ограничением по RID-only geometry.
• Empirical FOV sweep выявил, что checkpoint camera должна явно вызывать make_current(); после исправления projection ranking остаётся inconclusive из-за неизвестного manual yaw/pitch/framing reference.
• Camera-pose sweep can now rank bounded yaw/pitch grids without changing manifest defaults; perceptual ranking remains diagnostic and requires human framing approval.
• The first Goldshire pose grid was invalidated by WMO readiness: the inn is absent after 2 seconds but visible after the manifest-standard 8-second wait. Pose comparisons must stabilize asynchronous checkpoint content first.
• A ready-scene Goldshire 3x3 grid improved mean error from 0.101402 at zero offsets to 0.087952 at yaw 10/pitch -10; pitch/FOV refinement remains required before manifest calibration.
• Joint Goldshire pitch/FOV refinement had no human-approved optimum: full-frame error preferred grass-heavy FOV 62/pitch -25, while FOV 38/pitch -10 better matched building scale. Landmark/region scoring is required before calibration.
• D3D12 descriptor issues remain; the capture-path anonymous RefCounted shutdown leak is regression-covered by a clean verbose dry-run, while other RID/resource diagnostics still require independent evidence.
• M2/WMO/material/particle/ribbon/portal parity incomplete.
• Public API is mostly exported configuration rather than stable contracts.

Source map

Path	Responsibility
src/scenes/streaming/streaming_world_loader.gd	Current runtime orchestration, queues, caches and attachment
addons/mpq_extractor/loaders/adt_builder.gd	Terrain/material/liquid construction
addons/mpq_extractor/loaders/m2_builder.gd	Static M2 mesh/material construction
addons/mpq_extractor/loaders/m2_native_animated_builder.gd	Native animated M2 experiment
addons/mpq_extractor/loaders/wmo_builder.gd	WMO groups/doodads/liquids construction
src/scenes/sky/wow_sky_controller.gd	DBC-driven sky/light/environment
src/native/src/*_loader.cpp	Native binary parsing
src/tools/build_*cache.gd, src/tools/bake_*cache.gd	Offline cache generation
tools/run_render_baseline.ps1	Unified M00 baseline runner
src/tools/compare_render_checkpoints.gd	Offline JPG/PNG paired-image perceptual metrics and JSON pass/fail report
src/tools/capture_render_checkpoints.gd	Deterministic no-roll checkpoint camera, performance and visual capture
tools/sweep_render_checkpoint_camera_pose.ps1	Offline yaw/pitch capture grid and paired-error ranking
src/tools/verify_render_coordinate_calibration.gd	Build 12340 camera-coordinate golden point round-trip diagnostic
src/tools/probe_render_terrain_height.gd	Offline active-mesh terrain height and camera-clearance report
src/tools/probe_render_camera_occluders.gd	Scene-tree placement containment and camera-to-target AABB intersection report

Related decisions and references

• ../../RENDER.md
• ../RENDER_BASELINE.md
• ../CAMERA_POSE_SWEEP.md
• ../../targets/roadmap/02-rendering-and-graphics.md
• ../GODOT_BEST_PRACTICES.md