godot-genre-open-world

切勿这样做（专家级反模式）

世界与持久化

• 切勿优先考虑地图大小而忽视密度；空旷的景观设计很差。务必确保每隔 30 秒的行程内都有兴趣点（POI）。
• 切勿保存整个世界状态；务必使用增量持久化，只记录独有的变更（砍伐的树木、被搜刮的箱子），以防存档文件过大。
• 切勿同步加载大型区块或场景；务必使用 ResourceLoader.load_threaded_request()，以防“加载卡顿”和帧冻结。
• 切勿直接从后台线程操作活动的 SceneTree；务必使用 call_deferred()，将后台线程实例化的区块安全地应用到主线程。
• 切勿让远处未加载的区块留在内存中；务必使用 queue_free() 并将引用设为 null，以防内存耗尽（OOM）崩溃。
• 切勿将大量碰撞体烘焙到单个网格中；务必将世界划分为区块，并为每个区块设置局部碰撞区域，以提高物理查询效率。
• 切勿以文本格式（.tscn/.json）保存大量实体状态；务必使用二进制序列化（store_var），实现高速 I/O。

物理与性能

• 切勿忽视超过 8,192 个单位后的“浮动原点”抖动；务必实现世界偏移系统，或在项目设置中启用大型世界坐标（双精度）。
• 切勿在极远距离处理物理或 AI；务必使用空间分区，停用远处非活动区块中实体的逻辑。
• 切勿在 _process() 中计算对物理敏感的状态；务必使用 _physics_process()，以便在帧率波动时实现确定性的交互。
• 切勿为大量植被分别生成 MeshInstance3D 节点；务必使用 MultiMeshInstance3D，将数十万个网格批处理为一次 GPU 绘制调用。
• 切勿在运行时移动 OccluderInstance3D 节点；这会强制重建 CPU BVH，并导致严重的微卡顿。
• 切勿在导出的构建版本中保留活动的 CSGShape3D 节点；务必在发布前将其烘焙为静态 ArrayMesh 几何体。
• 切勿在游戏过程中编译复杂着色器；务必在加载期间进行“预热”，或启用项目级缓存。
• 切勿仅依赖自动网格简化；务必使用 VisibilityRange（HLOD），以低成本的替代模型替换复杂材质，或在极远距离完全隐藏对象。

逻辑与架构

• 切勿在整个庞大世界中执行全局 A* 搜索；务必使用 NavigationPathQueryParameters3D，将寻路范围限制在局部活动区域。
• 切勿使用 find_child() 或深度遍历场景树来获取全局状态（例如，一天中的时间）；务必使用场景组（call_group()）进行高效广播。
• 切勿通过网络同步复杂的 Resource 类型；务必将世界变更序列化为基本类型的 Dictionary 或 PackedByteArray。
• 若 ResourceLoader.load_threaded_request() 已能处理场景流式加载，切勿为区块 I/O 直接启动 Thread.new()；优先使用 ResourceLoader。仅在处理非 Resource 工作时使用自定义线程，并通过 deferred 将变更应用到 SceneTree。

---

🛠 专家组件（scripts/）

按关注领域必须使用（实施前请阅读）：

• 流式加载 → world_streamer.gd + async_chunk_loader.gd
• 原点 → 选择一种偏移器（参见决策树）——floating_origin_shifter.gd 或 world_origin_shifter.gd
• HLOD → 仅使用 hlod_visibility_config.gd（不要使用虚构的配置器）
• 远距离逻辑门控 → lod_logic_enabler.gd

原始专家模式

• world_streamer.gd - 专业级区块管理与流式加载引擎，支持后台线程。
• floating_origin_shifter.gd - 基于组的世界偏移校正，用于消除浮点精度抖动。

模块化组件

• async_chunk_loader.gd - 使用线程资源加载的后台世界流式加载系统。
• world_origin_shifter.gd - 移动根节点和玩家，并使用 reset_physics_interpolation 和着色器 world_offset uniform。
• hlod_visibility_config.gd - 使用 VisibilityRange 按距离切换几何体（HLOD）。
• lod_logic_enabler.gd - 按距离或区块活动状态启用／禁用 AI／物理处理。
• multimesh_foliage_manager.gd - 在服务端使用 GPU 批处理处理数千个景观实体。
• binary_save_manager.gd - 面向大规模世界持久化的高性能序列化。
• chunk_limited_pathfinder.gd - 限制 NavigationServer 层级的查询，以优化稠密世界中的 AI。
• server_prop_spawner.gd - 使用 RenderingServer RID 绕过 SceneTree，实现极致优化。
• dynamic_lod_adjuster.gd - 实时自适应调整全局网格 LOD 性能。
• group_weather_broadcaster.gd - 使用 SceneTree 分组，高效、解耦地更新环境。
• landscape_height_query.gd - 无节点的物理地面高度查询，适用于大规模景观。
• global_state.gd - 以区块为键的增量持久化（set_entity_dead 模式）。

---

核心循环

探索 → 发现 POI → 接取任务／旅行 → 持久化增量 → 沉浸于天气／昼夜循环。

决策树：流式加载／原点／HLOD

关注点	选择	脚本
玩家周围区块的加载／卸载	ResourceLoader 线程加载 + 延迟 add_child	必需 world_streamer.gd、async_chunk_loader.gd
原点：将游戏实体放入组中，使用自定义移动策略	移动组 "world_entities"	floating_origin_shifter.gd
原点：单个 world_root + 玩家瞬移 + 物理插值 + 着色器偏移	根节点移动器	world_origin_shifter.gd
原点：行星尺度／超过约几万单位，且物理计算密集	Large World Coordinates（双精度构建）	项目设置 — 仍可使用移动器同步着色器／音频
远处网格切换／伪像	VisibilityRange HLOD	必需 hlod_visibility_config.gd
禁用远处的 AI／物理	距离／区块门控	lod_logic_enabler.gd
仅持久化变更	二进制增量	binary_save_manager.gd

选择一种原点策略 — 不要在同一个 world root 上同时管理 floating_origin_shifter 和 world_origin_shifter。

---

架构（不重复 Elite 转储内容）

1. 流式加载器 — 根据玩家所在单元格确定活动区块集；使用 queue_free 卸载；通过线程 ResourceLoader 加载；使用 call_deferred 实例化。不要重新内嵌流式加载器伪代码 — 请阅读必需脚本。
2. 增量状态 — 使用以区块 ID 为键的字典记录死亡实体／已搜刮的宝箱；区块卸载时用二进制保存器写入。
3. HLOD — 代理网格使用 visibility_range_begin；细节子节点使用 visibility_parent — 通过 hlod_visibility_config.gd 配置。
4. POI／指南针 — 密度优先于尺寸；根据玩家朝向与 POI 的夹角绘制地图 UI；无需第二段浮动原点代码块。

常见陷阱

1. 空旷世界 — 注重密度，而非每平方公里的表面数据
2. 存档臃肿 — 仅持久化增量
3. 远距离物理 — lod_logic_enabler.gd
4. 幽灵 hlod_configurator.gd — 并不存在；请使用 hlod_visibility_config.gd

深度探讨决策树和脚本目录之外的内容时，必须阅读：open-world-elite-implementations.md。首次接线时不要加载 — 请先使用捆绑的 scripts/。

Godot 专属技巧

• VisibilityRange：在 MeshInstance3D 上使用 visibility_range_begin / end，无需专用的 LOD 节点即可实现 HLOD。
• 线程：处理区块时优先使用 ResourceLoader.load_threaded_request()；仅在不加载 Resource 时使用自定义 Thread。
• OcclusionCulling：为城市烘焙遮挡数据；开阔地带通常只需距离剔除。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在转向相关领域时加载相关技能 — 不要预加载整个知识网络。

官方文档

• 后台加载 — 使用 ResourceLoader 的线程化区块请求进行流式加载，避免主线程卡顿。
• 大型世界坐标 — 针对超过约 8k 单位的地图，了解浮动原点偏移与双精度构建的取舍。
• 可见性范围 — GeometryInstance3D 的起始/结束范围与滞后机制，用于 HLOD 替身切换。
• 网格细节层次（LOD） — 导入器自动 LOD，以及用于自适应室外画质的 Viewport mesh_lod_threshold。
• 使用 MultiMesh — 将植被/道具批处理为一次绘制调用，并通过空间分区进行剔除。
• 遮挡剔除 — 为城市烘焙 OccluderInstance3D；了解为何不应在运行时移动遮挡体。
• 保存游戏 — 用于持久化已卸载区块中实体变更的增量模式。
• 二进制序列化 API — 使用 FileAccess.store_var/get_var 紧凑存储大量世界状态。
• 使用多个线程 — 自定义流式加载器使用的 Thread/Mutex/Semaphore 工作线程模式。
• 线程安全 API — 了解哪些操作可在线程外运行，哪些必须通过 call_deferred 调用 SceneTree。
• 使用 NavigationPathQueryObjects — 用于区块范围 AI 的区域限定 NavigationServer3D 查询。
• 射线投射 — 使用 PhysicsDirectSpaceState3D 查询高度/放置位置，无需为每个地块创建节点。

相关技能

前置条件

• godot-project-foundations — 在流式加载 PackedScenes 和组之前，先了解场景树、资源和项目设置。
• godot-3d-world-building — GridMap/CSG/遮挡/LOD 基础功能，是开放世界区块和 HLOD 的构建基础。
• godot-physics-3d — 适用于大型地图的碰撞层、空间查询和安全原点偏移物理。
• godot-gdscript-mastery — 流式加载器和存档所用的类型化 Resources、信号及延迟/线程交接。

互补内容

• godot-scene-management — 与区块流式加载器配合使用的场景打包和加载队列。
• godot-performance-optimization — 世界规模下的绘制调用预算、MultiMesh 分区和处理节流。
• godot-navigation-pathfinding — 仅限活动区块的 NavigationRegion3D 烘焙和路径查询。
• godot-camera-systems — 摄像机距离决定加载半径、可见距离范围和浮动原点阈值。
• godot-save-load-systems — 区块卸载时，为 POI/任务标记提供持久化增量存档。
• godot-signal-architecture — 无需使用 find_child 遍历场景树，即可广播原点偏移和天气信息。
• godot-monte-carlo-balancer — 平衡流式地图中的 POI 密度、遭遇/战利品节奏和旅行时间。

下游 / 使用方

• godot-quest-system — 引用区块范围实体和探索标记的任务。
• godot-genre-sandbox — 复用流式加载、MultiMesh 和持久化模式的玩家建造世界。
• godot-genre-survival — 沿用开放世界流式加载和增量状态的探索/生存循环。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。