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.3 changelog (en/zh)

esengine3ef4f20bba24
diff --git a/docs/astro/src/content/docs/changelog-v0123.mdx b/docs/astro/src/content/docs/changelog-v0123.mdx
new file mode 100644
index 000000000..e86f53731
--- /dev/null
+++ b/docs/astro/src/content/docs/changelog-v0123.mdx
@@ -0,0 +1,88 @@
+---
+title: v0.12.3
+description: Estella v0.12.3 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.12.3 introduces packed Entity handles, a GfxDevice abstraction layer, manifest-driven toolchain sync, and real-time build progress streaming.
+</Aside>
+
+## Packed Entity
+
+`Entity` is now a 32-bit packed struct (20-bit index + 12-bit generation), replacing the raw `u32` alias. This enables generation-based lifetime validation while maintaining the same memory footprint.
+
+- `Entity::make(index, generation)` — construct from parts
+- `entity.index()` / `entity.generation()` / `entity.isValid()` — query
+- `entity.id()` / `Entity::fromRaw(u32)` — FFI serialization at the C++/JS boundary
+- `operator<<` support for logging
+- All Web bindings updated to use typed conversions instead of raw casts
+
+## World Context
+
+New `World` struct bundles `Registry`, `ServiceRegistry`, and `deltaTime` into a single object passed to all `System::update()` calls:
+
+```cpp
+void update(World& world) override {
+ auto& registry = world.registry;
+ auto& input = world.require<Input>();
+ f32 dt = world.deltaTime;
+}
+```
+
+Eliminates global state access patterns across all engine systems.
+
+## ServiceRegistry
+
+Centralized service locator replacing scattered singleton accessors in `EngineContext`. Systems access services through `World::require<T>()` instead of reaching into global state.
+
+## GfxDevice Abstraction
+
+New `GfxDevice` interface isolates all OpenGL calls behind `GLDevice`:
+
+- Strongly-typed `GfxEnums` replace raw GL constants (`GfxBlendFactor`, `GfxDataType`, `GfxTextureFormat`, etc.)
+- `SharedHandle` provides reference-counted resource management for textures, shaders, and framebuffers
+- Enables future graphics backend swaps (Vulkan, WebGPU) without touching rendering logic
+
+## Manifest-Driven Toolchain Sync
+
+Replaced the fragile incremental file sync with a hash-based full sync driven by `toolchain.manifest.json`:
+
+- Computes a content hash of all manifest-declared files (engine source, cmake modules, third-party libraries)
+- On change: clean-and-copy the entire toolchain directory, eliminating stale file issues
+- Build cache key now includes the engine source path, preventing debug/release cache collisions
+- `compute_source_hash` covers the entire `engine-src/` directory for reliable cache invalidation
+
+## Build Progress Streaming
+
+WASM compilation progress now streams to the editor's build panel in real time:
+
+- Ninja output (`[42/100] Building CXX object ...`) parsed for file counts and progress percentage
+- Compile stage transitions (Configure → Compile → Optimize) update the progress bar
+- Build log panel scrolls with live output
+- Error reporting merges stdout + stderr (last 30 lines), so compile errors are no longer silently lost
+
+## Toolchain Repair
+
+New "Repair" button in the toolchain panel downloads only missing tools (e.g. ninja) without reinstalling the full emsdk package. The `package-emsdk.js` script also auto-downloads ninja during packaging.
+
+## SDK Improvements
+
+- Expanded `App` lifecycle with pause/resume support
+- Improved `System` deltaTime handling with new tests
+- `ComponentMask` bitset-based component filtering for efficient archetype queries
+
+## UI Polish
+
+- Unified selected item styling to gold accent (`--es-selection-bg` + `--es-accent-gold`) across all editor panels
+- Selection indicator uses `box-shadow: inset` instead of `border-left` to avoid rounded corners
+
+## Bug Fixes
+
+- Fixed PlayMode entity synchronization during play mode transitions
+- Fixed hierarchy panel selection state persistence
+- Fixed Content Security Policy for production builds
+- Fixed Emscripten `scriptDirectory` detection triggering Chrome warnings in single-file playable builds
+- Fixed Toast overflow — long error messages truncated to 4 lines with "see build output" hint
+- Removed 5000+ build artifact files from git tracking (`desktop/src-tauri/toolchain/`)
diff --git a/docs/astro/src/content/docs/zh/changelog-v0123.mdx b/docs/astro/src/content/docs/zh/changelog-v0123.mdx
new file mode 100644
index 000000000..c730cca05
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/changelog-v0123.mdx
@@ -0,0 +1,88 @@
+---
+title: v0.12.3
+description: Estella v0.12.3 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.12.3 引入打包 Entity 句柄、GfxDevice 图形抽象层、Manifest 驱动的工具链同步,以及实时构建进度流。
+</Aside>
+
+## 打包 Entity
+
+`Entity` 现在是 32 位打包结构体(20 位索引 + 12 位代数),取代原来的 `u32` 别名。在保持相同内存占用的前提下提供基于代数的生命周期校验。
+
+- `Entity::make(index, generation)` — 从索引和代数构造
+- `entity.index()` / `entity.generation()` / `entity.isValid()` — 查询
+- `entity.id()` / `Entity::fromRaw(u32)` — FFI 序列化,用于 C++/JS 边界
+- 支持 `operator<<` 日志输出
+- 所有 Web 绑定层已适配类型化转换,不再使用裸类型转换
+
+## World 上下文
+
+新增 `World` 结构体,将 `Registry`、`ServiceRegistry` 和 `deltaTime` 打包为统一对象,传递给所有 `System::update()` 调用:
+
+```cpp
+void update(World& world) override {
+ auto& registry = world.registry;
+ auto& input = world.require<Input>();
+ f32 dt = world.deltaTime;
+}
+```
+
+消除了引擎系统中的全局状态访问模式。
+
+## ServiceRegistry
+
+集中式服务定位器,取代 `EngineContext` 中分散的单例访问器。系统通过 `World::require<T>()` 访问服务,而非直接操作全局状态。
+
+## GfxDevice 图形抽象层
+
+新增 `GfxDevice` 接口,将所有 OpenGL 调用隔离在 `GLDevice` 实现中:
+
+- 强类型 `GfxEnums` 取代原始 GL 常量(`GfxBlendFactor`、`GfxDataType`、`GfxTextureFormat` 等)
+- `SharedHandle` 提供纹理、着色器和帧缓冲的引用计数资源管理
+- 为未来切换图形后端(Vulkan、WebGPU)铺平道路,无需改动渲染逻辑
+
+## Manifest 驱动的工具链同步
+
+用基于哈希的全量同步取代了脆弱的增量文件同步,由 `toolchain.manifest.json` 驱动:
+
+- 计算 manifest 声明的所有文件的内容哈希(引擎源码、cmake 模块、第三方库)
+- 哈希变化时清空并全量拷贝工具链目录,彻底消除残留文件问题
+- 构建缓存 key 包含引擎源码路径,防止 debug/release 缓存冲突
+- `compute_source_hash` 覆盖整个 `engine-src/` 目录,确保缓存失效可靠
+
+## 实时构建进度
+
+WASM 编译进度实时流式传输到编辑器构建面板:
+
+- 解析 Ninja 输出(`[42/100] Building CXX object ...`)提取文件数和进度百分比
+- 编译阶段切换(配置 → 编译 → 优化)同步更新进度条
+- 构建日志面板实时滚动输出
+- 错误报告合并 stdout + stderr(最后 30 行),编译错误不再被静默丢失
+
+## 工具链修复
+
+工具链面板新增"修复"按钮,仅下载缺失的工具(如 ninja),无需重新安装整个 emsdk 包。`package-emsdk.js` 打包脚本也会自动下载 ninja。
+
+## SDK 改进
+
+- `App` 生命周期扩展 pause/resume 支持
+- `System` 的 deltaTime 处理改进,新增测试用例
+- `ComponentMask` 基于位集的组件过滤,用于高效原型查询
+
+## UI 美化
+
+- 统一所有编辑器面板的选中项样式为金色主题(`--es-selection-bg` + `--es-accent-gold`)
+- 选中指示器使用 `box-shadow: inset` 替代 `border-left`,避免竖线出现圆角
+
+## Bug 修复
+
+- 修复 PlayMode 切换时实体同步问题
+- 修复层级面板选中状态丢失
+- 修复生产构建的 Content Security Policy
+- 修复 Emscripten `scriptDirectory` 检测在单文件 playable 构建中触发 Chrome 警告
+- 修复 Toast 溢出——长错误信息截断为 4 行并提示"查看构建输出"
+- 从 git 追踪中移除 5000+ 构建产物文件(`desktop/src-tauri/toolchain/`)