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 + async_chunk_loader.gd
• Origin → choose one shifter (see decision tree) — floating_origin_shifter.gd or world_origin_shifter.gd
• HLOD → hlod_visibility_config.gd only (no phantom configurator)
• Far logic gate → lod_logic_enabler.gd

Original Expert Patterns

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

Modular Components

• async_chunk_loader.gd - Background world streaming system using threaded resource loading.
• world_origin_shifter.gd - Root+player shift with reset_physics_interpolation + shader world_offset uniform.
• hlod_visibility_config.gd - Distance-based geometry swapping using VisibilityRange (HLOD).
• lod_logic_enabler.gd - Enable/disable AI/physics processing by distance/chunk activity.
• multimesh_foliage_manager.gd - Server-side GPU batching for thousands of landscape entities.
• binary_save_manager.gd - High-performance serialization for large-scale world persistence.
• chunk_limited_pathfinder.gd - NavigationServer-level query limits to optimize AI in dense worlds.
• server_prop_spawner.gd - Extreme optimization using RenderingServer RIDs to bypass SceneTree.
• dynamic_lod_adjuster.gd - Real-time adaptive performance scaling for global mesh LOD.
• group_weather_broadcaster.gd - Efficient decoupled environmental updates using SceneTree grouping.
• landscape_height_query.gd - Nodeless physics floor-height queries for large-scale landscapes.
• 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, async_chunk_loader.gd
Origin: gameplay entities in a group, custom shift policy	Group "world_entities" shift	floating_origin_shifter.gd
Origin: single world_root + player warp + physics interp + shader offset	Root shifter	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
Disable far AI/physics	Distance/chunk gate	lod_logic_enabler.gd
Persist only changes	Binary delta	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.
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
4. Phantom hlod_configurator.gd — does not exist; use hlod_visibility_config.gd

MANDATORY for depth beyond decision trees and script catalog: 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.