godot-genre-open-world

name

godot-genre-open-world

description

Expert blueprint for open world games including chunk-based streaming (load/unload regions dynamically), floating origin (prevent precision jitter beyond 5000 units), HLOD (hierarchical LOD for distant meshes), persistent state (track entity changes across unloaded chunks), POI discovery systems (compass, markers), and threaded loading (prevent stutters). Use for RPGs, sandboxes, or exploration games. Trigger keywords: open_world, chunk_streaming, floating_origin, HLOD, persistent_state, POI_discovery, threaded_loading.

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.