快速开始
Overworld —— 模块化 Web 3D RPG 游戏开发框架
Overworld 是一个模块化的 Web 3D RPG 游戏开发框架,基于 React 18 + three.js (@react-three/fiber)+ zustand,从实际上线的 3D RPG 项目中提取通用能力沉淀而成。
开发一款新的同类游戏时,你只需要编写游戏内容数据(NPC/对话树/任务表/成就表)和 玩法专属系统,其余交给框架:可探索 3D 世界、玩家控制、NPC 对话、任务、物品、成就、 教程、寻路 AI、昼夜天气、小地图、音频、通知、加载、联机 presence、场景编辑器。
设计哲学
- 系统之间零依赖 —— 所有系统包只依赖
@overworld-engine/core,跨系统通信一律走类型化事件总线 - 数据驱动 + 注册表 —— 内容里只写声明式引用,游戏启动时注册处理函数,框架永不 import 游戏代码
- 内容注入,而非内容内置 —— 引擎都是工厂函数,框架包内零游戏内容
- 事件表可扩展 —— declaration merging 把玩法事件并入
OverworldEventMap,同样类型安全
五分钟上手
pnpm add @overworld-engine/core @overworld-engine/scene @overworld-engine/quest @overworld-engine/dialogue定义内容(纯数据,零代码):
const QUESTS: QuestDefinition[] = [
{
id: 'welcome',
title: 'quest.welcome.title', // 不透明字符串:字面量或 i18n key 均可
autoStart: true,
objectives: [
// 声明式触发器:玩家每移动一步,distance 自动累计
{ id: 'walk', target: 20, trigger: { event: 'player:moved', amountFrom: 'distance' } },
],
rewards: [{ type: 'gold.add', params: { amount: 50 } }],
},
]装配引擎(唯一让内容、注册表与引擎相遇的地方):
import { createConditionRegistry, createEffectRegistry } from '@overworld-engine/core'
import { createQuestEngine } from '@overworld-engine/quest'
const conditions = createConditionRegistry()
const effects = createEffectRegistry()
effects.register('gold.add', (params) => wallet.add(Number(params.amount)))
export const quests = createQuestEngine({ quests: QUESTS, conditions, effects })渲染世界(数据驱动场景):
import { Canvas } from '@react-three/fiber'
import { SceneShell, Player } from '@overworld-engine/scene'
<Canvas shadows>
<SceneShell npcs={NPCS} player={<Player bounds={BOUNDS} />}>
{/* 灯光、地面等场景专属内容 */}
</SceneShell>
</Canvas>Player 移动时发出 player:moved 事件 → 任务引擎自动推进"行走"目标 → 达标后经效果注册表
发放奖励 → quest:completed 事件供 UI 弹 Toast。四个环节零相互引用。
完整可运行示例见示例:Starter,深入设计见架构说明。
包一览
| 分层 | 包 |
|---|---|
| 基础 | core(事件总线/注册表/持久化/存档槽位) |
| 3D 世界 | scene environment(昼夜/天气) minimap |
| 无头引擎 | dialogue quest inventory achievements tutorial |
| AI | ai(A*/HPA* 寻路、行为、行为树、日程、动态避障) |
| 基础设施 | input audio notifications loading analytics net(联机) |
| 工具 | devtools(内容校验/JSON Schema) editor(场景编辑器) |
各包详情见左侧「包参考」。