OpenVoxel

OpenVoxel 是一个使用 VelarScript 从零构建体素世界的开源教学项目。它先完成没有前端也能独立验收的世界后端，再让浏览器单机模式和 Node 联机模式共享同一套世界模型、生成器和应用运行时。

当前完成的是可在单机与联机间复用的世界纵向切片：创建世界后，openvoxel:survival-v3 会确定性生成气候、海岸、河流、丘陵、山地、洞穴、地下流体、七类矿物，以及由六类树形、花草灌木、作物、藤蔓、枯木和水生群落组成的地表生态。生成的 16³ Chunk 随时可以由种子重建；持久化层只保存世界清单、玩家形成的稀疏覆盖、作物生长锚点和对应 Chunk revision。世界模型还以种子、世界时间和当前采样位置确定性驱动昼夜、月相、四季、空间连续的云/风/雨雪与稳定雷暴，单机 Worker 与联机服务向客户端提供同一种环境锚点。联机服务使用 VelarScript 0.33.1 的声明式 ServeApp、WebSocket 路由和类型化实时会话，本地模式则在专用浏览器 Worker 中运行相同 WorldRuntime，并把清单和增量保存到 IndexedDB。

开始使用

客户端光照包含太阳/月亮方向光、局部 PCF 阴影和动态天空 IBL。世界一年包含四季、每季八个世界日；草地与树叶按当地温度、湿度和季节染色，自然露天地表会结冰、积雪并在回暖后融化。作物以方块行为声明年龄属性和生长节拍，自然作物与玩家种植都按世界时间确定性推进；水草和贴底生物保留同格水体的透明、反射与波纹。冰雪由世界运行时提供，碰撞与显示保持一致；玩家放置的冰雪作为持久化修改保留。地形流送采用碰撞安全邻域、三维视区与保守 Portal 连通裁剪，驻留和任务队列具有固定上限。具体边界见 客户端大世界呈现。

需要 Node.js 24 或更高版本。项目不使用 Bun。

npm install
npm run validate
npm start

validate 运行生成一致性、结构、格式、编译检查和原生 Node 单测。validate:full 额外运行全部 Velar 测试、生产构建以及 Chromium GPU 与 Web UI 验收；validate:static 和 validate:browser 可分别运行完整静态与浏览器门禁。CI 保持完整静态和浏览器覆盖。

验证优先保证开发机可用：workspace 和 Node 测试文件默认并发为 1；子进程降低调度优先级，原生图像工作线程限制为 1。生成、测试、构建和浏览器验收通过本机 127.0.0.1:19479 的互斥槽串行执行，嵌套脚本共享同一任务，独立任务遇忙立即退出。该监听只用于任务协调，进程退出后由系统释放。取消顶层验证命令会终止它的子进程组。多工作区门禁可显式用 OPENVOXEL_VALIDATE_JOBS=2 提高并发（范围 1–4），日常保持默认值。

开发中优先选择受影响的测试；地形大种子集、GPU 截图与全套验收按需执行：

npm run test:file -- packages/world/generation/tests/survival/terrain.test.vel
npm run test:native -- packages/client/game/tests/climate-tint.test.mjs
npm run test:workspaces -- @openvoxel/world-generation
npm run test:terrain -- review --discover

通过 npm 入口运行这些任务，使并发限制和取消清理生效。降低优先级不是 CPU 使用率硬上限；长时间的全量生成或 GPU 验收仍会持续消耗计算资源。

另开一个终端运行 Web 客户端：

npm run dev:web

访问 http://127.0.0.1:7173 后，可以在开始界面创建、打开和切换本地世界，再进入 Canvas 世界视图。点击画布进入第一人称探索：鼠标转向，WASD 移动，Esc 释放指针。Creative 模式使用 Space 上升、Ctrl 下降、Shift 加速；锁定指针后，准星选取六格内已同步的方块，鼠标左键挖掘、右键放置，数字键 1–5 切换快捷栏。编辑经世界会话保存，重新打开同一世界仍可看到修改。Survival 模式使用 Space 跳跃、C 下蹲、Shift 冲刺。生产预览固定使用 7174；无头浏览器验收使用独立的 7273–7275 端口，不会再与其他项目的常用开发端口争用。

游戏图形后端的独立 GPU 门禁不启动正式应用或服务端。它临时构建测试夹具并随机监听空闲本地端口，在 Headless Chromium 中覆盖完整状态目录、纹理数组/PBR 通道、Chunk 接缝、透明排序、动画和上下文恢复；截图证据写入 packages/client/game/generated/gpu-render-probe：

npm run test:gpu

服务默认监听 http://127.0.0.1:3000，SQLite 文件默认位于服务应用目录下的 apps/server/openvoxel.sqlite。项目显式激活 @velarscript/server，监听地址、浏览器允许来源、协议限额和 SQLite 连接限额统一由 apps/server/application.yml 管理；它的位置由 apps/server/velar.json 的 server.configuration 明确声明，开发、检查和生产构建使用同一入口。数据库与 Content Pack 的相对路径以服务应用目录解析；从其他目录直接运行构建物时，用绝对的 OPENVOXEL_ROOT 明确指定该运行时数据根。可以用 OPENVOXEL_HOST、OPENVOXEL_PORT、OPENVOXEL_LOGGER、OPENVOXEL_DB 覆盖部署相关值；密码、令牌等机密只能从部署环境注入，不进入应用配置。

curl http://127.0.0.1:3000/api/health

curl http://127.0.0.1:3000/api

curl -X POST http://127.0.0.1:3000/api/worlds \
  -H 'content-type: application/json' \
  -d '{"id":"lesson-one","name":"Lesson One","seed":"openvoxel","mode":"creative"}'

curl http://127.0.0.1:3000/api/worlds/lesson-one/bootstrap

curl http://127.0.0.1:3000/api/worlds/lesson-one/content

curl -X POST http://127.0.0.1:3000/api/worlds/lesson-one/terrain/chunks \
  -H 'content-type: application/json' \
  -d '{"positions":[{"x":0,"y":0,"z":0},{"x":0,"y":1,"z":0}]}'

curl http://127.0.0.1:3000/api/worlds/lesson-one/terrain/samples/0/0

curl http://127.0.0.1:3000/api/openapi.json

每个连接通过 ws://127.0.0.1:3000/api/worlds/{worldId}/realtime 进入一个共享世界，命令和事件使用 MessagePack。完整契约见 当前协议，可交互文档位于 /api/docs。

Mod 人工源与运行时产物分开构建：源目录包含 content.yml、identities.yml 以及可选的 blocks/、world-generation/、ecosystem.yml，构建目录只接收 content-pack.json。服务器在 application.yml 的 content.packArtifacts 中安装产物，并用 defaultPacks 选择新世界默认内容。

OPENVOXEL_CONTENT_SOURCE=/absolute/mod-source \
OPENVOXEL_CONTENT_BUILD=/absolute/mod-build \
npm run compile:mod --workspace @openvoxel/content

架构

OpenVoxel 专用游戏框架及其公开契约见 ADR 0015：游戏框架：世界页通过 @openvoxel/game 进入和退出世界，game 组合 client、renderer 与 world，并拥有玩家控制、环境呈现和私有 Babylon 后端。包内模块的具体所有者、异步回收规则与后续扩展点见 职责模块与异步所有权。源码边界由编译器模块 metadata 驱动的 structure:check 验证，test:structure 覆盖依赖越界和工具链版本一致性。

flowchart LR
    Web["apps/web 页面与世界管理"] --> Game["@openvoxel/game 世界体验"]
    Game --> C
    Game --> Renderer["@openvoxel/renderer 构网与资源数据"]
    Game --> W
    C["@openvoxel/client 世界会话"] --> L["LocalBackend / Browser Worker"]
    C --> O["OnlineBackend / HTTP + WebSocket"]
    L --> R["@openvoxel/world-runtime"]
    O --> N["VelarScript native HTTP + WebSocket"]
    N --> M["Server modules"]
    M --> R
    R --> W["@openvoxel/world"]
    R --> K["@openvoxel/content"]
    K --> B
    K --> G
    R --> G["@openvoxel/world-generation"]
    G --> W
    W --> B["@openvoxel/blocks"]
    G --> B
    R --> P["WorldManifestStore + WorldDeltaStore"]
    P --> I["Memory / IndexedDB adapter"]
    P --> Q["OpenVoxel SQLite sparse-delta adapter"]
    Q --> A["@velarscript-labs/database operations"]
    A --> S["@velarscript-labs/sqlite"]

Loading

仓库按职责族群组织；族群目录只负责导航，每个叶目录仍是独立包：

• packages/content/identities：拥有跨目录逻辑身份、身份树合并与引用解析；它的 Core 声明表示可被所有目标消费。
• packages/content/blocks：分组方块 YAML 使用权威身份路径，并用唯一 JSON 产物发布编译目录；源码按 definition、compiler、runtime 分层，拥有规范状态键、UInt32 运行时 ID、每世界 Mod 注册表、有限状态和声明式组件契约。
• packages/content/packs：把一个 Mod 的共享身份、方块贡献和生成器贡献编译成独立 content-pack.json，并按精确哈希组合每世界内容集合。
• packages/world/model：坐标、Chunk 调色板和世界清单等稳定世界模型；只维护数据结构与不变量，不选择生成算法或编排存储。
• packages/world/generation：生成器注册入口与确定性生存生成算法；地形、洞穴、地下流体、矿物和植被按阶段分离，不负责后续 Tick 模拟。
• packages/world/runtime：创建世界、解析精确内容、读取固定地形、缓存活动世界增量、顺序提交原子批次和发布有序世界事件等用例与存储端口。
• packages/client/access：拥有客户端世界接入职责；世界会话、OnlineBackend、Worker/IndexedDB LocalBackend 共用一个 WorldBackend 端口和冷热 Chunk 合并状态机。网络地形 DTO 在 OnlineBackend 边界一次压缩成本地 UInt16Buffer 快照，Local Worker 直接转移相同紧凑形状；驻留状态一次展开由热增量维护的 UInt32Buffer 组合视图，供碰撞与构网共享；包清单明确声明 Web/Desktop 与 web 能力。
• packages/client/rendering：拥有体素构网、资源身份、资源包与纯数据契约；资源目录、Chunk 邻域快照和网格生成保持 Core 可消费，资源人工定义与生成管线也归此包。
• packages/client/game：OpenVoxel 专用游戏框架；通过 openLocalWorldGame 提供世界体验，拥有会话和首屏获取、Chunk 流送与构网协调、环境呈现、创造/生存移动、宿主输入及私有 Babylon 后端；包清单声明实际 Web/Desktop 与 web 能力。
• packages/protocol：只拥有 HTTP 和 MessagePack WebSocket 的线上数据类型、协议版本与客户端接入事实；实际 HTTP 路由由服务端注解和 OpenAPI 共同描述。
• apps/server：system、world、chunk、block、realtime 模块，负责把领域值投影成协议响应；同时拥有当前表结构、世界注册表 JSON、稀疏世界规则的 SQLite 适配器与组合根。
• apps/web：正式浏览器客户端；开始界面负责世界创建与管理，世界页消费 game 的体验和统计契约，页面保留路由、HUD 与 UI 生命周期。
• @velarscript/server 是显式激活的官方服务端应用扩展，负责应用配置、启动约定，以及类型化实时会话的一条有界发送队列、唯一 writer 和确定性清理；世界身份、MessagePack 命令、广播范围与错误码仍归 OpenVoxel。
• VelarScript 官方工具链继续使用 @velarscript/*；Libraries 非标准包统一从公开 npm scope @velarscript-labs/* 安装。两个命名空间的所有权在依赖名上直接可见，并由 lockfile 固定版本与完整性。

族群与包目录只按职责命名，运行环境写入各自的 velar.targets 与 velar.requires.capabilities。OpenVoxel 的可移植职责包统一声明 targets: ["core"]，表示 Core、Node、Web、Desktop 都能消费；客户端接入与游戏框架 声明实际需要的 Web 宿主。当前使用的 Labs 清单也显式声明环境：YAML、Noise、 MessagePack、Database、SQL 覆盖全部目标且不要求宿主能力，SQLite 只支持 Node 并 要求 node 能力。npm run structure:check 会同时检查内部依赖与直接 Labs 依赖的 目标、能力和消费方是否兼容。

目录按职责固定：手写运行时代码进入 src/，测试进入 tests/，测试辅助件进入 tests/support/，性能基准进入 benchmarks/，人工数据进入 data/，生成物进入 generated/，生成与检查脚本进入 tools/。src/ 不放测试和生成物，generated/ 禁止生成 .vel；npm run structure:check 和完整门禁会持续检查这两条规则。

应用边界和标准库晋升规则见 ADR 0001，Chunk 格式见 ADR 0002，世界生成裁决见 ADR 0004，原生服务框架裁决见 ADR 0010，稀疏世界存储见 ADR 0006，YAML 定义与 JSON 方块产物见 ADR 0007，每世界方块注册表见 ADR 0008，客户端接入契约见 ADR 0009，方块类型与有限状态地基见 ADR 0011，世界模型与生成边界见 ADR 0012，客户端大世界呈现见 ADR 0013，职责模块与异步所有权见 ADR 0014，OpenVoxel 游戏框架见 ADR 0015。

生成性能基线可以独立运行：

npm run benchmark:worldgen
npm run benchmark:columns
npm run benchmark:caves

世界生成基线会生成固定的 192 个 Chunk，报告总耗时、平均耗时和聚合校验和；地形柱基线比较垂直层重复计算与 64 项水平 LRU 缓存；洞穴基线比较逐 Chunk 重放与有界计划缓存。两个专项基准都要求两条路径的聚合校验和相同，让性能变化与语义变化不会混在一起。

当前边界

世界后端、客户端会话、OnlineBackend 和 LocalBackend 已形成完整闭环：服务端提供最多 64 个固定地形 Chunk 的批量读取、每世界内容目录、地形诊断、按世界隔离的热增量同步与最多 1024 项的原子方块编辑；浏览器端用真实 HTTP、WebSocket、MessagePack、Worker 与 IndexedDB 证明两种模式的共享语义。客户端资源包和最小体素呈现也已接入：少量已同步 Chunk 会生成可更新网格，显示资源只通过内容目录中的逻辑 material、texture、model 与 tint key 解析；一个逻辑 texture 可以在资源包构建期组合多层贴图并生成带权重的稳定表面变体，世界运行时 ID 始终不承担纹理或模型身份。

Canvas 世界视图已接入完整环境呈现：动态天空与 IBL、太阳和八相月亮、星空、连续云层、天气雾、雨雪与溅射粒子、闪电以及随光照变化的 PBR 方块材质共享同一权威世界时间。环境资源与方块纹理一样由独立源文件维护并进入资源哈希；GPU 探针会独立验收六种环境状态、透明深度、四通道材质和上下文恢复。

OpenVoxel 的业务代码不会写入 VelarScript 主仓库或 VelarScript Libraries。只有能力具备领域无关的稳定语义、已有真实复用证据，并能独立承担兼容与验证成本时，才会进入 Libraries；进入 Libraries 也不等于晋升为 velar/* 标准库。

可组合生态包、扩展内容及核心边界见 ADR 0017。