Skip to content

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.

docs: add v0.12.1 changelog (en + zh)

esengine372c4aa5bd8a
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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`)