A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs: add v0.12.1 changelog (en + zh)
esengine372c4aa5bd8a
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 5c631ff6e..acbd52361 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -156,6 +156,7 @@ export default defineConfig({label: 'Changelog',translations: { 'zh-CN': '更新日志' },items: [+ { label: 'v0.12.1', slug: 'changelog-v0121' },{ label: 'v0.12.0', slug: 'changelog-v0120' },{ label: 'v0.11.0', slug: 'changelog-v0110' },{ label: 'v0.10.0', slug: 'changelog-v0100' },diff --git a/docs/astro/src/content/docs/changelog-v0121.mdx b/docs/astro/src/content/docs/changelog-v0121.mdxnew file mode 100644index 000000000..fb8c8c31c--- /dev/null+++ b/docs/astro/src/content/docs/changelog-v0121.mdx@@ -0,0 +1,118 @@+---+title: v0.12.1+description: Estella v0.12.1 release notes+---++import { Aside } from '@astrojs/starlight/components';++<Aside type="tip">+v0.12.1 brings Sprite tiling, MCP on the startup page, a unified script compilation pipeline, and a large SDK/editor architecture overhaul with explicit DI, typed event bus, and component-aware query caching.+</Aside>++## Sprite Tiling++The `Sprite` component now supports `tileSize` and `tileSpacing` for seamless or spaced tiling:++- **Seamless tiling** (`tileSpacing = 0`): uses `uvScale` override with `GL_REPEAT` for zero extra draw-call overhead+- **Spaced tiling**: emits N×M quads with configurable gaps, auto-merged into a single draw call via the batch system+- Both modes respect sprite flip and pivot settings++## MCP on Startup Page++MCP tools are now available before opening a project:++- Bridge server starts in Tauri `setup()` before the frontend loads+- New MCP tools on the startup page: `get_editor_status`, `list_recent_projects`, `list_examples`, `open_project`, `create_from_example`+- New MCP build tools: `build_project` (trigger playable/wechat build) and `list_build_configs` (query available configs)+- `LauncherBridge` handles project management tools; editor-mode tools lazy-discover the editor on first call++## Unified Script Compilation++Script compilation is now handled by a single `ScriptCompiler` class, merging two previously divergent VirtualFS plugins and SDK resolution strategies:++- Play Mode uses incremental compilation via esbuild context+- Build export uses one-shot compilation+- Circular dependency between `ScriptLoader` and `ScriptCompiler` broken by extracting `scriptDiscovery.ts`++## SDK Core Decomposition++### App Slimdown++`app.ts` reduced from 1090 to 729 lines by extracting the camera system and math utilities:++- **CameraPlugin** (`camera/CameraPlugin.ts`): multi-camera collection, ortho/perspective projection, Canvas scale mode adaptation, and the render system are now a standalone plugin+- **mat4** (`math/mat4.ts`): `ortho`, `perspective`, `invertTranslation`, `multiply` extracted as pure functions with pooled Float32Array buffers+- `createWebApp()` is now a pure assembly function — plugin registration only, no inline system definitions++### World Facade Refactoring++`world.ts` reduced from 1101 to 674 lines by splitting into 5 focused internal classes:++| Module | Responsibility |+|--------|---------------|+| `ecs/BuiltinBridge` | C++ Registry method cache, ptr layout direct reads/writes, color format conversion |+| `ecs/ScriptStorage` | TypeScript Map-based component storage, entity-component tracking |+| `ecs/NameIndex` | Bidirectional name-to-entity lookup |+| `ecs/ChangeTracker` | Tick-based added/changed/removed detection |+| `ecs/QueryCache` | Cached entity queries with component-aware invalidation |++All public `World` API signatures remain identical — the split is internal (Facade pattern).++### AppContext Replaces globalThis++Three `globalThis.__esengine_*` implicit coupling points replaced with an explicit `AppContext`:++- `getDefaultContext().componentRegistry` replaces `globalThis.__esengine_componentRegistry`+- `getDefaultContext().pendingSystems` replaces `globalThis.__esengine_pendingSystems`+- `getDefaultContext().editorBridge` replaces `globalThis.__esengine_registerComponent`++Enables multi-app instance isolation and proper test cleanup via `setDefaultContext()`.++### Component-Aware Query Cache++The query cache previously invalidated all cached queries on any entity change. Now each cache entry tracks which component types it depends on, and only invalidates when a relevant component changes.++## Editor Architecture++### EditorEventBus++A new typed pub-sub event bus replaces 6 manual listener sets on `EditorStore`:++- Immediate delivery via `emit()` for structural changes+- Batched delivery via `emitBatched()` using `requestAnimationFrame` — same-type events within a frame are merged (last-write-wins)+- Events: `selection:changed`, `scene:synced`, `property:changed`, `hierarchy:changed`, `entity:lifecycle`, `component:changed`, `visibility:changed`, `tiletool:changed`, `gizmo:requested`++### Store Decomposition++`EditorStore` split into focused stores:++- **SelectionStore**: entity/asset selection state, focus tracking+- **TileToolStore**: tile brush tool, stamp, flip state+- **EditorStore** (slimmed): scene data, command history, world transform cache — notifications routed through EventBus++All stores registered in the IoC container with typed tokens.++### IncrementalSync++Property edits in the editor now use field-level WASM direct writes instead of full component re-adds:++- Utilizes `PTR_LAYOUTS` to write individual fields directly to `HEAPF32`/`HEAPU32`/`HEAPU8`+- Transform drag operations write only `position.x/y/z` (3 floats) instead of the full 20+ field component+- Falls back to full component sync for components without ptr layouts++## Build Pipeline++- **WASM build cache hash validation**: cache now computes a hash of all C++/HPP source files and `CMakeLists.txt`, invalidating on source changes instead of only checking output existence+- **Engine source resolution**: dev mode now prefers the live project root `src/esengine/` over the stale toolchain copy, ensuring new components are included in builds+- **Toolchain manifest**: added yoga library to `toolchain.manifest.json` for UILayoutSystem flex support+- **Playable build fix**: replaced hardcoded `COMPONENT_TO_PLUGIN` mapping (missing 10+ components) with SDK's `uiPlugins` array as single source of truth++## Bug Fixes++- Fixed `Assets.baseUrl` not propagating to `HttpBackend` for `loadTexture`, `loadMaterial`, `loadFont`, `loadSpine` and all Loader-based methods — only `fetchJson` worked previously+- Fixed `Assets.fetchJson`/`fetchText`/`fetchBinary` not resolving relative paths through `baseUrl`, causing Play Mode JSON loading to fail in Tauri+- Fixed `HttpBackend.resolveUrl` only recognizing `http://`/`https://` — now handles `asset://`, `blob://`, and other URI schemes+- Fixed `UIRenderOrderPlugin` requiring `CollectionView` plugin to be installed — execution order is already guaranteed by system-level `runBefore/runAfter`+- Fixed WASM toolchain sync copying root `CMakeLists.txt` which references unavailable yogacore sources+- Fixed stale WASM builds when new components are added to `WebBindings.generated.cpp`+- Fixed Assets API documentation referencing non-existent `loadJson`/`loadText`/`loadBinary` methods (actual API is `fetchJson`/`fetchText`/`fetchBinary`)diff --git a/docs/astro/src/content/docs/zh/changelog-v0121.mdx b/docs/astro/src/content/docs/zh/changelog-v0121.mdxnew file mode 100644index 000000000..577f2bc35--- /dev/null+++ b/docs/astro/src/content/docs/zh/changelog-v0121.mdx@@ -0,0 +1,118 @@+---+title: v0.12.1+description: Estella v0.12.1 更新日志+---++import { Aside } from '@astrojs/starlight/components';++<Aside type="tip">+v0.12.1 新增 Sprite 平铺、启动页 MCP 支持、统一脚本编译管线,以及 SDK/编辑器架构大幅重构——显式依赖注入、类型化事件总线和组件级查询缓存失效。+</Aside>++## Sprite 平铺++`Sprite` 组件新增 `tileSize` 和 `tileSpacing` 属性,支持无缝或间隔平铺:++- **无缝平铺**(`tileSpacing = 0`):使用 `uvScale` + `GL_REPEAT`,零额外 draw call 开销+- **间隔平铺**:生成 N×M 个四边形并设置间距,通过批处理系统自动合并为单次 draw call+- 两种模式均支持精灵翻转和锚点设置++## 启动页 MCP++MCP 工具现在在打开项目前即可使用:++- Bridge 服务器在 Tauri `setup()` 阶段启动,早于前端加载+- 启动页新增 MCP 工具:`get_editor_status`、`list_recent_projects`、`list_examples`、`open_project`、`create_from_example`+- 新增 MCP 构建工具:`build_project`(触发 playable/wechat 构建)和 `list_build_configs`(查询可用构建配置)+- `LauncherBridge` 处理项目管理工具;编辑器模式工具在首次调用时延迟发现编辑器++## 统一脚本编译++脚本编译统一为单一 `ScriptCompiler` 类,合并了此前两套分散的 VirtualFS 插件和 SDK 解析策略:++- Play Mode 使用 esbuild context 增量编译+- 构建导出使用单次编译+- 提取 `scriptDiscovery.ts` 打破 `ScriptLoader` 与 `ScriptCompiler` 的循环依赖++## SDK 核心拆分++### App 瘦身++`app.ts` 从 1090 行减少到 729 行,提取了相机系统和数学工具:++- **CameraPlugin**(`camera/CameraPlugin.ts`):多相机收集、正交/透视投影、Canvas 缩放模式适配和渲染系统现在是独立插件+- **mat4**(`math/mat4.ts`):`ortho`、`perspective`、`invertTranslation`、`multiply` 提取为纯函数,带 Float32Array 对象池+- `createWebApp()` 变为纯组装函数——只做插件注册,不再内联系统定义++### World 门面重构++`world.ts` 从 1101 行减少到 674 行,拆分为 5 个聚焦内部类:++| 模块 | 职责 |+|------|------|+| `ecs/BuiltinBridge` | C++ Registry 方法缓存、ptr 布局直读直写、颜色格式转换 |+| `ecs/ScriptStorage` | TypeScript Map 组件存储、实体-组件追踪 |+| `ecs/NameIndex` | 双向名称-实体索引 |+| `ecs/ChangeTracker` | 基于 tick 的 added/changed/removed 检测 |+| `ecs/QueryCache` | 缓存实体查询,支持组件级失效 |++所有 `World` 公开 API 签名保持不变——拆分是内部的(Facade 模式)。++### AppContext 替代 globalThis++3 个 `globalThis.__esengine_*` 隐式耦合点被替换为显式 `AppContext`:++- `getDefaultContext().componentRegistry` 替代 `globalThis.__esengine_componentRegistry`+- `getDefaultContext().pendingSystems` 替代 `globalThis.__esengine_pendingSystems`+- `getDefaultContext().editorBridge` 替代 `globalThis.__esengine_registerComponent`++支持多 App 实例隔离,测试时通过 `setDefaultContext()` 清理状态。++### 组件级查询缓存++查询缓存此前在任何实体变更时全部失效。现在每个缓存条目追踪其依赖的组件类型,仅在相关组件变更时失效。++## 编辑器架构++### EditorEventBus++新的类型化发布-订阅事件总线替代 `EditorStore` 上的 6 套手动监听器:++- `emit()` 立即投递,用于结构性变更+- `emitBatched()` 通过 `requestAnimationFrame` 批量投递——同一帧内的同类事件合并(最后一次写入生效)+- 事件类型:`selection:changed`、`scene:synced`、`property:changed`、`hierarchy:changed`、`entity:lifecycle`、`component:changed`、`visibility:changed`、`tiletool:changed`、`gizmo:requested`++### Store 拆分++`EditorStore` 拆分为聚焦的独立 Store:++- **SelectionStore**:实体/资源选择状态、焦点追踪+- **TileToolStore**:Tile 笔刷工具、图章、翻转状态+- **EditorStore**(瘦身后):场景数据、命令历史、世界变换缓存——通知全部走 EventBus++所有 Store 注册到 IoC 容器,使用类型化 token。++### 增量同步++编辑器属性编辑现在使用字段级 WASM 直写,而非整个组件重新添加:++- 利用 `PTR_LAYOUTS` 直接写入 `HEAPF32`/`HEAPU32`/`HEAPU8` 中的单个字段+- Transform 拖拽操作只写 `position.x/y/z`(3 个 float),而非完整的 20+ 字段组件+- 没有 ptr 布局的组件回退到完整组件同步++## 构建管线++- **WASM 构建缓存哈希校验**:缓存现在计算所有 C++/HPP 源文件和 `CMakeLists.txt` 的哈希值,在源码变更时失效,而非仅检查输出文件是否存在+- **引擎源码解析**:开发模式现在优先使用项目根目录的 `src/esengine/`,而非过时的 toolchain 副本,确保新组件被包含在构建中+- **Toolchain 清单**:在 `toolchain.manifest.json` 中添加 yoga 库,支持 UILayoutSystem 的 flex 布局+- **Playable 构建修复**:用 SDK 的 `uiPlugins` 数组(唯一数据源)替代硬编码的 `COMPONENT_TO_PLUGIN` 映射(缺少 10+ 组件)++## Bug 修复++- 修复 `Assets.baseUrl` 未传播到 `HttpBackend`,导致 `loadTexture`、`loadMaterial`、`loadFont`、`loadSpine` 等 Loader 方法忽略 baseUrl——此前仅 `fetchJson` 有效+- 修复 `Assets.fetchJson`/`fetchText`/`fetchBinary` 未通过 `baseUrl` 解析相对路径,导致 Play Mode 中 Tauri 的 JSON 加载失败+- 修复 `HttpBackend.resolveUrl` 仅识别 `http://`/`https://`——现在支持 `asset://`、`blob://` 等 URI scheme+- 修复 `UIRenderOrderPlugin` 强制要求安装 `CollectionView` 插件——执行顺序已通过系统级 `runBefore/runAfter` 保证+- 修复 WASM toolchain 同步拷贝了根目录的 `CMakeLists.txt`(引用了不可用的 yogacore 源码)+- 修复新增组件到 `WebBindings.generated.cpp` 后 WASM 构建缓存未失效+- 修复 Assets API 文档引用了不存在的 `loadJson`/`loadText`/`loadBinary` 方法(实际 API 为 `fetchJson`/`fetchText`/`fetchBinary`)