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.3 changelog (en/zh)
esengine3ef4f20bba24
diff --git a/docs/astro/src/content/docs/changelog-v0123.mdx b/docs/astro/src/content/docs/changelog-v0123.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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/`)