godot-genre-open-world

NEVER Do (Expert Anti-Patterns)

World & Persistence

• NEVER prioritize Map Size over Density; empty landscapes are poor design. Strictly focus on Points of Interest (POIs) within every 30 seconds of travel.
• NEVER save the entire world state; strictly use Delta Persistence to record only unique changes (chopped trees, looted chests) to prevent massive save files.
• NEVER load large chunks or scenes synchronously; strictly use ResourceLoader.load_threaded_request() to prevent "Loading Hitches" and frame freezes.
• NEVER manipulate the active SceneTree directly from a background thread; strictly use call_deferred() to safely apply background thread chunk instantiations back to the main thread.
• NEVER keep distant, unloaded chunks in memory; strictly queue_free() and nullify references to prevent Out-Of-Memory (OOM) crashes.
• NEVER bake massive collision into one mesh; strictly break the world into chunks with local collision regions for efficient physics queries.
• NEVER save high-volume entity states in text formats (.tscn/.json); strictly use Binary Serialization (store_var) for high-speed I/O.

Physics & Performance

• NEVER ignore the "Floating Origin" jitter beyond 8,192 units; strictly implement a World-Shift system or enable Large World Coordinates (Double Precision) in project settings.
• NEVER process physics or AI at extreme distances; strictly use Spatial Partitioning to disable logic for entities in far-away, inactive chunks.
• NEVER calculate physics-sensitive state in _process(); strictly use _physics_process() for deterministic interaction at fluctuating framerates.
• NEVER spawn individual MeshInstance3D nodes for massive foliage; strictly use MultiMeshInstance3D to batch hundreds of thousands of meshes into a single GPU draw call.
• NEVER move OccluderInstance3D nodes at runtime; this forces a CPU BVH rebuild and causes severe micro-stuttering.
• NEVER leave CSGShape3D nodes active in exported builds; strictly bake them into static ArrayMesh geometry before shipping.
• NEVER compile complex shaders during gameplay; strictly perform "warm-up" during loading or enable project-wide caching.
• NEVER rely solely on automatic mesh decimation; strictly use VisibilityRange (HLOD) to substitute complex materials with cheap imposters or completely hide objects at extreme distances.

Logic & Architecture

• NEVER perform global A* searches across the entire massive world; strictly use NavigationPathQueryParameters3D to limit pathfinding to localized active regions.
• NEVER use find_child() or deep tree iteration for global state (e.g., Time of Day); strictly use Scene Groups (call_group()) for optimized broadcasting.
• NEVER synchronize complex Resource types over the network; strictly serialize world changes into primitive Dictionaries or PackedByteArrays.
• NEVER spawn raw Thread.new() for chunk I/O when ResourceLoader.load_threaded_request() already covers scene streaming — prefer ResourceLoader; custom threads only for non-Resource work with deferred SceneTree apply.

---

🛠 Expert Components (scripts/)

> MANDATORY by concern (read before implementing):

> - Streaming → [world_streamer.gd](scripts/world_streamer.gd) + [async_chunk_loader.gd](scripts/async_chunk_loader.gd)

> - Origin → choose one shifter (see decision tree) — [floating_origin_shifter.gd](scripts/floating_origin_shifter.gd) or [world_origin_shifter.gd](scripts/world_origin_shifter.gd)

> - HLOD → [hlod_visibility_config.gd](scripts/hlod_visibility_config.gd) only (no phantom configurator)

> - Far logic gate → [lod_logic_enabler.gd](scripts/lod_logic_enabler.gd)

Original Expert Patterns

• [world_streamer.gd](scripts/world_streamer.gd) - Professional-grade chunk management and streaming engine with background threading.
• [floating_origin_shifter.gd](scripts/floating_origin_shifter.gd) - Group-based world-offset correction for float precision jitter.

Modular Components

• [async_chunk_loader.gd](scripts/async_chunk_loader.gd) - Background world streaming system using threaded resource loading.
• [world_origin_shifter.gd](scripts/world_origin_shifter.gd) - Root+player shift with reset_physics_interpolation + shader world_offset uniform.
• [hlod_visibility_config.gd](scripts/hlod_visibility_config.gd) - Distance-based geometry swapping using VisibilityRange (HLOD).
• [lod_logic_enabler.gd](scripts/lod_logic_enabler.gd) - Enable/disable AI/physics processing by distance/chunk activity.
• [multimesh_foliage_manager.gd](scripts/multimesh_foliage_manager.gd) - Server-side GPU batching for thousands of landscape entities.
• [binary_save_manager.gd](scripts/binary_save_manager.gd) - High-performance serialization for large-scale world persistence.
• [chunk_limited_pathfinder.gd](scripts/chunk_limited_pathfinder.gd) - NavigationServer-level query limits to optimize AI in dense worlds.
• [server_prop_spawner.gd](scripts/server_prop_spawner.gd) - Extreme optimization using RenderingServer RIDs to bypass SceneTree.
• [dynamic_lod_adjuster.gd](scripts/dynamic_lod_adjuster.gd) - Real-time adaptive performance scaling for global mesh LOD.
• [group_weather_broadcaster.gd](scripts/group_weather_broadcaster.gd) - Efficient decoupled environmental updates using SceneTree grouping.
• [landscape_height_query.gd](scripts/landscape_height_query.gd) - Nodeless physics floor-height queries for large-scale landscapes.
• [global_state.gd](scripts/global_state.gd) - Chunk-keyed delta persistence (set_entity_dead pattern).

---

Core Loop

Traverse → Discover POIs → Quest/travel → Persist deltas → Weather/day cycle immersion.

Decision Tree: Streamer / Origin / HLOD

| Concern | Choose | Script |

|---------|--------|--------|

| Chunk load/unload around player | ResourceLoader threaded + deferred add_child | MANDATORY [world_streamer.gd](scripts/world_streamer.gd), [async_chunk_loader.gd](scripts/async_chunk_loader.gd) |

| Origin: gameplay entities in a group, custom shift policy | Group "world_entities" shift | [floating_origin_shifter.gd](scripts/floating_origin_shifter.gd) |

| Origin: single world_root + player warp + physics interp + shader offset | Root shifter | [world_origin_shifter.gd](scripts/world_origin_shifter.gd) |

| Origin: planetary / >~few×10k units, physics-heavy | Large World Coordinates (double-precision build) | Project setting — may still use a shifter for shader/audio sync |

| Distant mesh swap / impostor | VisibilityRange HLOD | MANDATORY [hlod_visibility_config.gd](scripts/hlod_visibility_config.gd) |

| Disable far AI/physics | Distance/chunk gate | [lod_logic_enabler.gd](scripts/lod_logic_enabler.gd) |

| Persist only changes | Binary delta | [binary_save_manager.gd](scripts/binary_save_manager.gd) |

Pick one origin strategy — do not dual-own floating_origin_shifter and world_origin_shifter on the same world root.

---

Architecture (no duplicated Elite dumps)

1. Streamer — Active chunk set from player cell; unload with queue_free; load via threaded ResourceLoader; instantiate with call_deferred. Do not re-inline streamer pseudocode — read the MANDATORY scripts.
2. Delta state — Dictionary keyed by chunk id for dead entities / looted chests; write with binary saver when chunks unload.
3. HLOD — Proxy mesh visibility_range_begin; detail children use visibility_parent — configure via [hlod_visibility_config.gd](scripts/hlod_visibility_config.gd).
4. POI / compass — Density > size; angle map UI from player forward to POI; no need for a second floating-origin code block.

Common Pitfalls

1. Empty world — density over km² vanity
2. Save bloat — delta-only persistence
3. Far physics — [lod_logic_enabler.gd](scripts/lod_logic_enabler.gd)
4. Phantom hlod_configurator.gd — does not exist; use [hlod_visibility_config.gd](scripts/hlod_visibility_config.gd)

> MANDATORY for depth beyond decision trees and script catalog: [open-world-elite-implementations.md](references/open-world-elite-implementations.md). Do NOT Load on first-pass wiring — use bundled scripts/ first.

Godot-Specific Tips

• VisibilityRange: Use visibility_range_begin / end on MeshInstance3D for HLOD without a dedicated LOD node.
• Threading: Prefer ResourceLoader.load_threaded_request() for chunks; custom Thread only when not loading Resources.
• OcclusionCulling: Bake occlusion for cities; open fields often need distance culling only.

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Background loading — ResourceLoader threaded chunk requests so streaming never hitch-stalls the main thread.
• Large world coordinates — when floating-origin shifts vs double-precision builds for maps beyond ~8k units.
• Visibility ranges — GeometryInstance3D begin/end + hysteresis for HLOD impostor swaps.
• Mesh level of detail (LOD) — importer auto-LOD and Viewport mesh_lod_threshold for adaptive outdoor quality.
• Using MultiMesh — batching foliage/props into one draw call with spatial partitions for culling.
• Occlusion culling — baked OccluderInstance3D for cities; why not to move occluders at runtime.
• Saving games — delta persistence patterns for entity changes across unloaded chunks.
• Binary serialization API — FileAccess.store_var/get_var for compact high-volume world state.
• Using multiple threads — Thread/Mutex/Semaphore worker patterns used by custom streamers.
• Thread-safe APIs — what may run off-thread vs what must be call_deferred onto the SceneTree.
• Using NavigationPathQueryObjects — region-limited NavigationServer3D queries for chunk-scoped AI.
• Ray-casting — PhysicsDirectSpaceState3D height/placement queries without per-tile nodes.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, resources, and project settings before streaming PackedScenes and groups.
• godot-3d-world-building — GridMap/CSG/occlusion/LOD primitives that open-world chunks and HLOD build on.
• godot-physics-3d — collision layers, space queries, and origin-shift-safe physics for large maps.
• godot-gdscript-mastery — typed Resources, signals, and deferred/thread handoffs used by streamers and saves.

Complements

• godot-scene-management — scene packing and load queues that pair with chunk streamers.
• godot-performance-optimization — draw-call budgets, MultiMesh partitions, and process throttling at world scale.
• godot-navigation-pathfinding — NavigationRegion3D baking and path queries limited to active chunks.
• godot-camera-systems — camera distance drives load radii, visibility ranges, and floating-origin thresholds.
• godot-save-load-systems — durable delta saves for POI/quest flags when chunks are unloaded.
• godot-signal-architecture — origin-shift and weather broadcasts without find_child tree walks.
• godot-monte-carlo-balancer — POI density, encounter/loot pacing, and travel-time balance across the streamed map.

Downstream / consumers

• godot-quest-system — quests that reference chunk-scoped entities and discovery markers.
• godot-genre-sandbox — player-built worlds that reuse streaming, MultiMesh, and persistence patterns.
• godot-genre-survival — exploration/survival loops that inherit open-world streaming and delta state.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.