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: Sprites & Rendering + Building & Exporting guides (en + zh)
esengineddf97c96a851
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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/)。