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: update changelog with latest fixes, add Sprite tiling guide

esenginef91b5fdfa389
diff --git a/docs/astro/src/content/docs/changelog-v0121.mdx b/docs/astro/src/content/docs/changelog-v0121.mdx
index fb8c8c31c..726946a07 100644
--- a/docs/astro/src/content/docs/changelog-v0121.mdx
+++ b/docs/astro/src/content/docs/changelog-v0121.mdx
@@ -11,11 +11,12 @@ v0.12.1 brings Sprite tiling, MCP on the startup page, a unified script compilat
## Sprite Tiling
-The `Sprite` component now supports `tileSize` and `tileSpacing` for seamless or spaced tiling:
+The `Sprite` component now supports `tileSize` and `tileSpacing` for repeating a texture across a larger area:
-- **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
+- Set `tileSize` to the desired tile dimensions (e.g. `{x: 64, y: 64}`) — the texture repeats to fill the sprite `size`
+- Set `tileSpacing` to add gaps between tiles (e.g. `{x: 4, y: 4}`) — appears in the Inspector only when `tileSize` is non-zero
+- Both modes emit N×M quads auto-merged into a single draw call via the batch system
+- Respects sprite flip and pivot settings
## MCP on Startup Page
@@ -116,3 +117,6 @@ Property edits in the editor now use field-level WASM direct writes instead of f
- 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`)
+- Fixed Sprite seamless tiling (`tileSpacing = 0`) rendering only a single tile — textures default to `ClampToEdge`, now uses quad-based tiling for both modes
+- Fixed Inspector `visibleWhen` / `hiddenWhen` rules not updating dynamically when controlling property changes — previously required deselecting and reselecting the entity
+- Removed `worldPosition`, `worldRotation`, `worldScale` from Transform Inspector — these are system-computed read-only values
diff --git a/docs/astro/src/content/docs/guides/sprite.mdx b/docs/astro/src/content/docs/guides/sprite.mdx
index fad1c94f2..11851357e 100644
--- a/docs/astro/src/content/docs/guides/sprite.mdx
+++ b/docs/astro/src/content/docs/guides/sprite.mdx
@@ -20,6 +20,8 @@ The `Sprite` component is the primary way to display 2D graphics. Add it to an e
| `flipX` | boolean | `false` | Flip horizontally |
| `flipY` | boolean | `false` | Flip vertically |
| `pivot` | Vec2 | `{x: 0.5, y: 0.5}` | Pivot point for rotation and scaling |
+| `tileSize` | Vec2 | `{x: 0, y: 0}` | Tile dimensions for tiling (0 = no tiling) |
+| `tileSpacing` | Vec2 | `{x: 0, y: 0}` | Gap between tiles |
| `material` | number | `0` | Material ID |
| `enabled` | boolean | `true` | Whether this sprite is rendered |
@@ -120,6 +122,25 @@ addSystem(defineSystem(
));
```
+## Tiling
+
+Set `tileSize` to repeat a texture across the sprite area. Each tile is drawn at the specified size, filling the sprite's `size` region.
+
+```typescript
+sprite.tileSize = { x: 64, y: 64 }; // each tile is 64×64
+sprite.size = { x: 256, y: 256 }; // 4×4 grid of tiles
+```
+
+Add `tileSpacing` for gaps between tiles:
+
+```typescript
+sprite.tileSpacing = { x: 4, y: 4 }; // 4px gap between tiles
+```
+
+<Aside type="note">
+ In the Inspector, the **Tile Spacing** field only appears when **Tile Size** is non-zero. Set Tile Size first to enable tiling.
+</Aside>
+
## Render Order
Sprites are sorted by the following priority (highest first):
diff --git a/docs/astro/src/content/docs/zh/changelog-v0121.mdx b/docs/astro/src/content/docs/zh/changelog-v0121.mdx
index 577f2bc35..e6fa86759 100644
--- a/docs/astro/src/content/docs/zh/changelog-v0121.mdx
+++ b/docs/astro/src/content/docs/zh/changelog-v0121.mdx
@@ -11,11 +11,12 @@ v0.12.1 新增 Sprite 平铺、启动页 MCP 支持、统一脚本编译管线
## Sprite 平铺
-`Sprite` 组件新增 `tileSize` 和 `tileSpacing` 属性,支持无缝或间隔平铺:
+`Sprite` 组件新增 `tileSize` 和 `tileSpacing` 属性,支持纹理重复平铺:
-- **无缝平铺**(`tileSpacing = 0`):使用 `uvScale` + `GL_REPEAT`,零额外 draw call 开销
-- **间隔平铺**:生成 N×M 个四边形并设置间距,通过批处理系统自动合并为单次 draw call
-- 两种模式均支持精灵翻转和锚点设置
+- 设置 `tileSize` 为期望的 tile 尺寸(如 `{x: 64, y: 64}`),纹理会重复填满 Sprite 的 `size` 区域
+- 设置 `tileSpacing` 在 tile 之间添加间距(如 `{x: 4, y: 4}`),该字段仅在 `tileSize` 非零时出现在 Inspector 中
+- 两种模式均生成 N×M 个四边形,通过批处理系统自动合并为单次 draw call
+- 支持精灵翻转和锚点设置
## 启动页 MCP
@@ -116,3 +117,6 @@ MCP 工具现在在打开项目前即可使用:
- 修复 WASM toolchain 同步拷贝了根目录的 `CMakeLists.txt`(引用了不可用的 yogacore 源码)
- 修复新增组件到 `WebBindings.generated.cpp` 后 WASM 构建缓存未失效
- 修复 Assets API 文档引用了不存在的 `loadJson`/`loadText`/`loadBinary` 方法(实际 API 为 `fetchJson`/`fetchText`/`fetchBinary`)
+- 修复 Sprite 无间隔平铺(`tileSpacing = 0`)只渲染一个 tile——纹理默认为 `ClampToEdge`,改为两种模式统一使用 quad 平铺
+- 修复 Inspector 的 `visibleWhen`/`hiddenWhen` 规则在控制属性变化时不会动态更新——此前需要取消选中再重新选中实体
+- Transform Inspector 中移除 `worldPosition`、`worldRotation`、`worldScale` 显示——这些是系统计算的只读值
diff --git a/docs/astro/src/content/docs/zh/guides/sprite.mdx b/docs/astro/src/content/docs/zh/guides/sprite.mdx
index 7ecd78fb6..8e1b2468f 100644
--- a/docs/astro/src/content/docs/zh/guides/sprite.mdx
+++ b/docs/astro/src/content/docs/zh/guides/sprite.mdx
@@ -19,6 +19,8 @@ import { Aside } from '@astrojs/starlight/components';
| `layer` | number | `0` | 渲染顺序(越大越靠前) |
| `flipX` | boolean | `false` | 水平翻转 |
| `flipY` | boolean | `false` | 垂直翻转 |
+| `tileSize` | Vec2 | `{x: 0, y: 0}` | 平铺 tile 尺寸(0 = 不平铺) |
+| `tileSpacing` | Vec2 | `{x: 0, y: 0}` | tile 之间的间距 |
| `material` | number | `0` | 材质 ID |
| `enabled` | boolean | `true` | 是否渲染精灵 |
@@ -119,6 +121,25 @@ addSystem(defineSystem(
));
```
+## 平铺
+
+设置 `tileSize` 可以让纹理在精灵区域内重复。每个 tile 按指定尺寸绘制,填满精灵的 `size` 区域。
+
+```typescript
+sprite.tileSize = { x: 64, y: 64 }; // 每个 tile 64×64
+sprite.size = { x: 256, y: 256 }; // 4×4 网格
+```
+
+添加 `tileSpacing` 在 tile 之间留间距:
+
+```typescript
+sprite.tileSpacing = { x: 4, y: 4 }; // tile 之间 4px 间距
+```
+
+<Aside type="note">
+ 在 Inspector 中,**Tile Spacing** 字段仅在 **Tile Size** 非零时出现。先设置 Tile Size 即可启用平铺。
+</Aside>
+
## 渲染顺序
精灵按以下优先级排序绘制(高优先级在前):