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: Sprites & Rendering + Building & Exporting guides (en + zh)

esengineddf97c96a851
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 8a49cdb6b..1525b1021 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -64,6 +64,7 @@ export default defineConfig({
label: 'Graphics & UI',
translations: { 'zh-CN': '图形与 UI' },
items: [
+ { label: 'Sprites & Rendering', translations: { 'zh-CN': '精灵与渲染' }, slug: 'guides/sprites' },
{ label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },
{ label: 'UI', translations: { 'zh-CN': 'UI' }, slug: 'guides/ui' },
{ label: 'Particles', translations: { 'zh-CN': '粒子' }, slug: 'guides/particle' },
@@ -82,6 +83,7 @@ export default defineConfig({
{ label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scene' },
{ label: 'Saving & Loading', translations: { 'zh-CN': '存档与读档' }, slug: 'guides/save' },
{ label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'guides/localization' },
+ { label: 'Building & Exporting', translations: { 'zh-CN': '构建与导出' }, slug: 'guides/build-export' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
{ label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },
],
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdx
new file mode 100644
index 000000000..205615579
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/build-export.mdx
@@ -0,0 +1,90 @@
+---
+title: Building & Exporting
+description: Ship one project to Web, Desktop, WeChat MiniGame, or a single-file Playable Ad from the editor's Package Project dialog — build configs, output folders, packaging settings, and the runtime prerequisites.
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+One Estella project ships to four targets — **Web**, **Desktop**, **WeChat
+MiniGame**, and a single-file **Playable Ad** — all from the editor. The export uses
+the **same runtime you played in the editor**, so what you shipped is what you tested
+(*play == ship*).
+
+## Exporting from the editor
+
+<Steps>
+
+1. Open **File → Build…** to bring up the **Package Project** dialog.
+2. Pick a **platform** (Web / Desktop / WeChat / Playable).
+3. Choose a **build config** — *Development* or *Shipping* (Shipping minifies) — an
+ **output folder**, and whether to emit source maps.
+4. Click **Export** and watch the live build log. When it finishes, the output folder
+ opens.
+
+</Steps>
+
+Your choices are saved into `project.esproject`, so the dialog remembers them next
+time.
+
+## The targets
+
+| Target | What it produces | Output | Next step |
+|---|---|---|---|
+| **Web** | A static, self-contained web build. | `dist-web/` | Open `index.html`, or upload the folder to any static host. |
+| **Desktop** | An Electron app source tree. | `dist-desktop/` | `cd dist-desktop && npm install && npm start` — or `npm run dist` for a native `.dmg` / `.exe` / AppImage installer. |
+| **WeChat** | A WeChat MiniGame package. | `dist-wechat/` | Open the folder in WeChat DevTools and set your AppID. See [WeChat MiniGame](/docs/guides/wechat/). |
+| **Playable** | One self-contained `index.html` with everything inlined — no external requests, as ad networks require. | `dist-playable/` | Open `index.html`. Note a full engine usually exceeds ad-network size limits. |
+
+## Runtime prerequisites
+
+Web and Desktop reuse the engine runtime that ships with the editor, so they export
+with no setup. **WeChat** and **Playable** each need their own engine runtime built
+once, because they use a different WebAssembly loader / single-file packaging:
+
+```bash
+# only before the first WeChat export
+node build-tools/cli.js build -t wechat
+
+# only before the first Playable export
+node build-tools/cli.js build -t playable
+```
+
+The Package Project dialog reminds you when a target's runtime is missing.
+
+## Build config & source maps
+
+- **Development** — an unminified build; pair it with source maps for debuggable
+ output.
+- **Shipping** — minified for size and speed. This is what you release.
+- **Source maps** map the running bundle back to your TypeScript. They're available for
+ Web and Desktop; leave them off for a release build.
+
+## Packaging settings
+
+Per-target metadata lives in **Project Settings → Packaging** and is saved with the
+project:
+
+- **WeChat** — AppID and screen orientation.
+- **Desktop** — application id and product name (used to name the installer).
+- **Playable** — orientation.
+
+See [The Editor](/docs/guides/editor/) for the settings UI.
+
+## The build CLI (advanced)
+
+The editor packages your **game**. The `build-tools/cli.js` command builds the
+**engine and SDK** themselves — you only need it to produce the WeChat / Playable
+runtimes above, or when working on the engine. Common commands:
+
+```bash
+node build-tools/cli.js build -t web # build the engine (web target)
+node build-tools/cli.js build -t wechat # …the WeChat runtime
+node build-tools/cli.js build -t playable # …the single-file runtime
+node build-tools/cli.js sdk # build the SDK only
+node build-tools/cli.js watch # rebuild on change (engine dev)
+```
+
+<Aside type="note">
+ Most game developers never run the build CLI beyond the one-time WeChat / Playable
+ runtime builds — day-to-day work happens in the editor and the SDK.
+</Aside>
diff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/guides/sprites.mdx
new file mode 100644
index 000000000..72b711d68
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/sprites.mdx
@@ -0,0 +1,139 @@
+---
+title: Sprites & Rendering
+description: Draw 2D images with the Sprite component — textures, tint and transparency, size and pivot, flipping, sorting layers and draw order, parallax, and the ShapeRenderer for primitives.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The **`Sprite`** is the workhorse 2D renderer: an entity with a `Sprite` component
+draws a textured quad in the world. For solid primitives without a texture there's
+**`ShapeRenderer`**. Everything is drawn through a [Camera](/docs/guides/camera/), and
+draw order is controlled by **sorting layers**.
+
+## Your first sprite
+
+A sprite needs a `Transform` (where it is) and a `Sprite` (what it draws). Load a
+texture through the [`Assets`](/docs/guides/assets/) resource and put its handle on the
+sprite:
+
+```typescript
+import { defineSystem, Commands, Res, Query, Mut, Transform, Sprite, Assets } from 'esengine';
+
+const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets) => {
+ const tex = await assets.loadTexture('textures/player.png'); // { handle, width, height }
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(Sprite, { texture: tex.handle, size: { x: tex.width, y: tex.height } });
+});
+```
+
+`sprite.texture` is a texture **handle**, not a path — you get one from a loader
+(`assets.loadTexture(ref)`). In the editor you don't write this: drag an image from the
+Content Browser onto an entity, or set the Sprite's texture field in Details.
+
+## Sprite fields
+
+| Field | Default | Description |
+|---|---|---|
+| `texture` | `0` | Texture handle from a loader (`0` = untextured, draws a white quad). |
+| `color` | `{1,1,1,1}` | Tint multiplied into the texture (white = unchanged). |
+| `size` | `{100,100}` | Rendered size in world units. |
+| `pivot` | `{0.5,0.5}` | Anchor point (0–1) the sprite rotates and scales about. |
+| `layer` | `0` | Sorting layer — controls draw order (see below). |
+| `flipX` / `flipY` | `false` | Mirror horizontally / vertically. |
+| `material` | `0` | A custom [material](/docs/guides/material/) handle (`0` = the default sprite shader). |
+| `uvOffset` / `uvScale` | `{0,0}` / `{1,1}` | Sub-rectangle of the texture to show (for atlases / scrolling). |
+| `tileSize` / `tileSpacing` | `{0,0}` | Repeat the texture across the sprite (`0` = no tiling). |
+| `parallax` | `{1,1}` | Parallax scroll factor (see below). |
+| `enabled` | `true` | Hide without removing the component. |
+
+## Tint & transparency
+
+`color` is an RGBA multiplier over the texture. White (`{1,1,1,1}`) draws it unchanged;
+tint it, or fade it by lowering alpha:
+
+```typescript
+sprite.color = { r: 1, g: 0.4, b: 0.4, a: 1 }; // reddened
+sprite.color = { r: 1, g: 1, b: 1, a: 0.5 }; // 50% transparent
+```
+
+`color` (and `size`) are **animatable** — key them in the
+[Sequencer](/docs/guides/timeline/) for flashes and fades.
+
+## Size & pivot
+
+`size` is the quad's size in **world units**, independent of the texture's pixel
+dimensions — set it to `{ tex.width, tex.height }` for 1:1, or anything else to scale.
+Scale on the `Transform` multiplies on top of it. `pivot` is the normalized anchor
+(0–1) the sprite rotates and scales about: `{0.5, 0.5}` is centered, `{0, 0}` is the
+bottom-left corner, `{0.5, 0}` pins the bottom-center (handy for characters standing on
+the ground).
+
+## Draw order & sorting layers
+
+When sprites overlap, draw order decides what's on top. Order is set by the **sorting
+layer** (`sprite.layer`) — a named layer list you define in **Project Settings →
+Rendering**, so the inspector shows a dropdown of *Background*, *Default*, *Foreground*,
+etc. instead of a raw number. Lower layers draw first (behind).
+
+```typescript
+sprite.layer = 0; // e.g. "Background"
+sprite.layer = 2; // e.g. "Foreground" — drawn on top
+```
+
+<Aside type="tip">
+ Sorting layers group things coarsely (background vs gameplay vs UI-in-world). For
+ fine ordering *within* a layer, use the entity's `Transform` z position.
+</Aside>
+
+## Flipping, atlases & scrolling
+
+- **Flip** a sprite with `flipX` / `flipY` — e.g. face a character left or right without
+ a separate texture.
+- **Atlases**: show one cell of a packed sheet by setting `uvOffset` and `uvScale` to
+ the cell's normalized rectangle. (For frame-by-frame animation, drive these from the
+ [Animator](/docs/guides/animation/) instead of by hand.)
+- **Scrolling**: animate `uvOffset` over time to scroll a texture (water, conveyor
+ belts), and set `tileSize` to repeat it across a large sprite.
+
+## Parallax backgrounds
+
+`parallax` scales how much a sprite moves relative to the camera: `1` moves with the
+world, `0` locks it to the camera (a fixed backdrop), and values in between scroll
+slower for depth. Layer a few sprites at `0.2`, `0.5`, `0.8` for a classic parallax
+background.
+
+## Custom materials & lighting
+
+Assign `sprite.material` to draw the sprite with your own shader — a tint, a
+dissolve, a distortion — see [Materials & Shaders](/docs/guides/material/). To make a
+sprite respond to `Light2D` lights, give it a **Lit-2D material**; see
+[2D Lighting & Shadows](/docs/guides/lighting/).
+
+## Shapes without a texture
+
+For solid circles, capsules, and rounded rectangles — placeholders, bars, debug
+overlays — use **`ShapeRenderer`** instead of a texture (`ShapeType.Circle`,
+`Capsule`, or `RoundedRect`):
+
+```typescript
+import { ShapeRenderer, ShapeType } from 'esengine';
+
+cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.RoundedRect,
+ size: { x: 200, y: 80 },
+ cornerRadius: 12,
+ color: { r: 0.2, g: 0.6, b: 1, a: 1 },
+ });
+```
+
+`ShapeRenderer` shares the sorting `layer` and `color` conventions with `Sprite`.
+
+## In the editor
+
+- **Create → Sprite** adds a sprite entity, or **drag an image** from the Content
+ Browser into the viewport to spawn one already textured.
+- Every field above is editable in **Details**; sprites, cameras, and lights show as
+ gizmos in the viewport. See [The Editor](/docs/guides/editor/).
diff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
new file mode 100644
index 000000000..e1d5616c5
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
@@ -0,0 +1,82 @@
+---
+title: 构建与导出
+description: 从编辑器的"打包项目"对话框把一个项目发布到 Web、桌面、微信小游戏或单文件 Playable 广告——构建配置、输出目录、打包设置与运行时前置条件。
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+一个 Estella 项目可发布到四个目标——**Web**、**桌面**、**微信小游戏**和单文件 **Playable 广告**
+——全部从编辑器完成。导出用的是**你在编辑器里运行的同一套运行时**,所以你发布的就是你测过的
+(*play == ship*)。
+
+## 从编辑器导出
+
+<Steps>
+
+1. 打开 **文件 → Build…** 调出 **打包项目(Package Project)** 对话框。
+2. 选一个**平台**(Web / 桌面 / 微信 / Playable)。
+3. 选一个**构建配置**——*Development* 或 *Shipping*(Shipping 会压缩)——一个**输出目录**,以及
+ 是否输出 source map。
+4. 点 **导出**,看实时构建日志。完成后输出目录会自动打开。
+
+</Steps>
+
+你的选择会存进 `project.esproject`,所以对话框下次会记住它们。
+
+## 各个目标
+
+| 目标 | 产出什么 | 输出 | 下一步 |
+|---|---|---|---|
+| **Web** | 一个静态、自包含的 Web 构建。 | `dist-web/` | 打开 `index.html`,或把文件夹上传到任意静态托管。 |
+| **桌面** | 一棵 Electron 应用源码树。 | `dist-desktop/` | `cd dist-desktop && npm install && npm start`——或 `npm run dist` 出原生 `.dmg` / `.exe` / AppImage 安装包。 |
+| **微信** | 一个微信小游戏包。 | `dist-wechat/` | 在微信开发者工具里打开该文件夹并设置你的 AppID。见 [微信小游戏](/docs/zh-cn/guides/wechat/)。 |
+| **Playable** | 一个自包含的 `index.html`,一切内联——无外部请求(广告网络的要求)。 | `dist-playable/` | 打开 `index.html`。注意完整引擎通常超出广告网络的体积限制。 |
+
+## 运行时前置条件
+
+Web 和桌面复用随编辑器附带的引擎运行时,所以导出无需准备。**微信**和 **Playable** 各需先构建一次
+自己的引擎运行时,因为它们用不同的 WebAssembly 加载器 / 单文件打包方式:
+
+```bash
+# 仅在首次微信导出前
+node build-tools/cli.js build -t wechat
+
+# 仅在首次 Playable 导出前
+node build-tools/cli.js build -t playable
+```
+
+当某个目标的运行时缺失时,打包项目对话框会提醒你。
+
+## 构建配置与 source map
+
+- **Development** —— 不压缩的构建;配上 source map 得到可调试的输出。
+- **Shipping** —— 为体积和速度压缩。这是你发布用的。
+- **source map** 把运行的 bundle 映射回你的 TypeScript。Web 和桌面可用;发布构建请关掉。
+
+## 打包设置
+
+每个目标的元数据在 **项目设置 → 打包(Packaging)** 里,并随项目保存:
+
+- **微信** —— AppID 和屏幕朝向。
+- **桌面** —— 应用 id 和产品名(用于命名安装包)。
+- **Playable** —— 朝向。
+
+设置界面见 [编辑器](/docs/zh-cn/guides/editor/)。
+
+## 构建 CLI(进阶)
+
+编辑器打包你的**游戏**。而 `build-tools/cli.js` 命令构建的是**引擎和 SDK 本身**——你只在要产出上面
+的微信 / Playable 运行时、或开发引擎时才需要它。常用命令:
+
+```bash
+node build-tools/cli.js build -t web # 构建引擎(web 目标)
+node build-tools/cli.js build -t wechat # …微信运行时
+node build-tools/cli.js build -t playable # …单文件运行时
+node build-tools/cli.js sdk # 只构建 SDK
+node build-tools/cli.js watch # 改动即重建(引擎开发)
+```
+
+<Aside type="note">
+ 大多数游戏开发者除了那一次性的微信 / Playable 运行时构建外,从不需要动构建 CLI——日常工作都在
+ 编辑器和 SDK 里。
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
new file mode 100644
index 000000000..b55cb308b
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
@@ -0,0 +1,122 @@
+---
+title: 精灵与渲染
+description: 用 Sprite 组件绘制 2D 图像——纹理、着色与透明、尺寸与轴心、翻转、排序层与绘制顺序、视差,以及绘制基本图元的 ShapeRenderer。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**`Sprite`** 是 2D 渲染的主力:一个带 `Sprite` 组件的实体在世界里绘制一个带纹理的四边形。要绘制
+不带纹理的实心图元,有 **`ShapeRenderer`**。一切都经由 [相机](/docs/zh-cn/guides/camera/) 绘制,
+而绘制顺序由**排序层**控制。
+
+## 你的第一个精灵
+
+一个精灵需要 `Transform`(在哪)和 `Sprite`(画什么)。通过 [`Assets`](/docs/zh-cn/guides/assets/)
+资源加载一张纹理,把它的句柄放到精灵上:
+
+```typescript
+import { defineSystem, Commands, Res, Query, Mut, Transform, Sprite, Assets } from 'esengine';
+
+const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets) => {
+ const tex = await assets.loadTexture('textures/player.png'); // { handle, width, height }
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(Sprite, { texture: tex.handle, size: { x: tex.width, y: tex.height } });
+});
+```
+
+`sprite.texture` 是一个纹理**句柄**,而不是路径——你从加载器(`assets.loadTexture(ref)`)拿到它。
+在编辑器里你不用写这个:从内容浏览器把一张图拖到实体上,或在 Details 里设精灵的 texture 字段。
+
+## Sprite 字段
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `texture` | `0` | 加载器给的纹理句柄(`0` = 无纹理,画白色四边形)。 |
+| `color` | `{1,1,1,1}` | 乘进纹理的着色(白 = 不变)。 |
+| `size` | `{100,100}` | 渲染尺寸,世界单位。 |
+| `pivot` | `{0.5,0.5}` | 精灵旋转/缩放所绕的轴心点(0–1)。 |
+| `layer` | `0` | 排序层——控制绘制顺序(见下)。 |
+| `flipX` / `flipY` | `false` | 水平 / 垂直镜像。 |
+| `material` | `0` | 自定义[材质](/docs/zh-cn/guides/material/)句柄(`0` = 默认精灵着色器)。 |
+| `uvOffset` / `uvScale` | `{0,0}` / `{1,1}` | 要显示的纹理子矩形(用于图集 / 滚动)。 |
+| `tileSize` / `tileSpacing` | `{0,0}` | 把纹理在精灵上平铺重复(`0` = 不平铺)。 |
+| `parallax` | `{1,1}` | 视差滚动系数(见下)。 |
+| `enabled` | `true` | 不移除也能隐藏组件。 |
+
+## 着色与透明
+
+`color` 是叠加在纹理上的 RGBA 乘子。白(`{1,1,1,1}`)原样绘制;给它染色,或降低 alpha 让它淡出:
+
+```typescript
+sprite.color = { r: 1, g: 0.4, b: 0.4, a: 1 }; // 泛红
+sprite.color = { r: 1, g: 1, b: 1, a: 0.5 }; // 50% 透明
+```
+
+`color`(和 `size`)都**可动画**——在 [Sequencer](/docs/zh-cn/guides/timeline/) 里给它们打关键帧
+做闪烁和淡入淡出。
+
+## 尺寸与轴心
+
+`size` 是四边形的**世界单位**尺寸,与纹理的像素尺寸无关——设成 `{ tex.width, tex.height }` 得到
+1:1,或设成别的值来缩放。`Transform` 上的缩放会再乘上去。`pivot` 是精灵旋转/缩放所绕的归一化
+轴心(0–1):`{0.5, 0.5}` 居中,`{0, 0}` 是左下角,`{0.5, 0}` 钉住底部中心(适合站在地面上的角色)。
+
+## 绘制顺序与排序层
+
+当精灵重叠时,绘制顺序决定谁在上面。顺序由**排序层**(`sprite.layer`)决定——一个你在
+**项目设置 → 渲染**里定义的命名层列表,于是检视器显示 *Background*、*Default*、*Foreground* 等
+下拉,而不是裸数字。较低的层先画(在后面)。
+
+```typescript
+sprite.layer = 0; // 例如 "Background"
+sprite.layer = 2; // 例如 "Foreground" —— 画在上面
+```
+
+<Aside type="tip">
+ 排序层做粗粒度分组(背景 vs 玩法 vs 世界内 UI)。层**内**的精细排序,用实体 `Transform` 的 z 位置。
+</Aside>
+
+## 翻转、图集与滚动
+
+- 用 `flipX` / `flipY` **翻转**精灵——例如让角色朝左或朝右,而不用另一张纹理。
+- **图集**:把 `uvOffset` 和 `uvScale` 设为某个单元格的归一化矩形,显示打包图集里的一格。(逐帧动画
+ 请用 [Animator](/docs/zh-cn/guides/animation/) 驱动这些,而非手动。)
+- **滚动**:随时间改 `uvOffset` 来滚动纹理(水面、传送带),并设 `tileSize` 把它在大精灵上重复平铺。
+
+## 视差背景
+
+`parallax` 缩放一个精灵相对相机的移动量:`1` 随世界移动,`0` 锁定到相机(固定背景板),中间的值
+滚动更慢以产生纵深。把几张精灵分别设为 `0.2`、`0.5`、`0.8`,就得到经典的视差背景。
+
+## 自定义材质与光照
+
+给 `sprite.material` 赋值,用你自己的着色器绘制精灵——染色、溶解、扭曲——见
+[材质与着色器](/docs/zh-cn/guides/material/)。要让精灵响应 `Light2D` 光源,给它一个 **Lit-2D 材质**;
+见 [2D 光照与阴影](/docs/zh-cn/guides/lighting/)。
+
+## 不带纹理的图元
+
+要画实心圆、胶囊和圆角矩形——占位、进度条、调试覆盖——用 **`ShapeRenderer`** 而不是纹理
+(`ShapeType.Circle`、`Capsule` 或 `RoundedRect`):
+
+```typescript
+import { ShapeRenderer, ShapeType } from 'esengine';
+
+cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.RoundedRect,
+ size: { x: 200, y: 80 },
+ cornerRadius: 12,
+ color: { r: 0.2, g: 0.6, b: 1, a: 1 },
+ });
+```
+
+`ShapeRenderer` 与 `Sprite` 共享排序 `layer` 和 `color` 约定。
+
+## 在编辑器里
+
+- **创建 → 精灵** 添加一个精灵实体,或从内容浏览器**把图拖**进视口,生成一个已带纹理的精灵。
+- 上面每个字段都能在 **Details** 里编辑;精灵、相机、光源在视口里显示为 gizmo。见
+ [编辑器](/docs/zh-cn/guides/editor/)。