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(guides): catch up to shipped features (en + zh-cn)

yhhcc331577c69a
diff --git a/docs/astro/src/content/docs/getting-started/quick-start.mdx b/docs/astro/src/content/docs/getting-started/quick-start.mdx
index 96228ade4..542198a17 100644
--- a/docs/astro/src/content/docs/getting-started/quick-start.mdx
+++ b/docs/astro/src/content/docs/getting-started/quick-start.mdx
@@ -10,8 +10,10 @@ with a system written in TypeScript.
<Steps>
-1. **Create a project.** In the editor, click **New Project**, name it, and
- click **Create**. You get a default scene with a Camera entity.
+1. **Create a project.** In the editor, click **New Project**, pick the
+ **Blank** starter template, name it, and click **Create**. You get a default
+ scene with a Camera entity. (The **Examples** templates are full sample
+ projects if you'd rather explore a finished game.)
2. **Add an entity.** In the scene hierarchy, add an entity and give it a
`Sprite` and a `Transform` component in the inspector.
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index 8ba62a842..e25be3317 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -111,9 +111,10 @@ textures) instead of the network.
## Cooking, compression & content addressing
-At build time the **cook** walks the dependency graph from your entry scene(s),
-**culls anything unreachable**, stages the reachable files, and writes the
-manifest. Along the way it can:
+At build time the **cook** walks the dependency graph from every scene in the
+build (the Package dialog's **Scenes in build** list), **culls anything
+unreachable**, stages the reachable files, and writes the manifest. Along the
+way it can:
- **Compress textures** — encode PNGs to GPU-ready **KTX2** (Basis Universal),
which the runtime transcodes to the best format the device supports (ASTC → ETC2
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdx
index 75aafa8c1..b6918a08c 100644
--- a/docs/astro/src/content/docs/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/guides/build-export.mdx
@@ -17,23 +17,54 @@ the **same runtime you played in the editor**, so what you shipped is what you t
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.
+ **output folder**, source maps, and the [asset cook options](#asset-cook-options).
+4. Check the **Scenes in build** list — untick scenes you don't want to ship, and
+ pin a different startup scene if needed (see below).
+5. Click **Package** and watch the live build log. When it finishes, the output
+ folder opens (there's a checkbox to turn that off), and Web / Playable builds
+ offer **Preview over http**.
</Steps>
Your choices are saved into `project.esproject`, so the dialog remembers them next
time.
+## Scenes in build
+
+Every scene in the project's scenes folder ships with the export and becomes a
+`SceneManager.switchTo` target — see [Scenes](/docs/guides/scene/) for how a game
+script switches between them. The dialog's **Scenes in build** list controls the
+set:
+
+- The **startup scene** is pinned first with a play badge. It always ships — move
+ the pin to another scene by clicking its play button, or right-click any scene in
+ the Content Browser and choose **Set as Startup Scene**.
+- **Untick a scene** to leave it out of the build (saved as
+ `packaging.excludeScenes` in `project.esproject`). Excluded scenes stay fully
+ editable and playable in the editor; assets referenced only by excluded scenes
+ are not cooked into the build.
+- **Playable** ships the startup scene only — it's a size-capped single file.
+
+## Preview an export
+
+After a **Web** or **Playable** build, click **Preview over http** — the editor
+serves the output folder on a local loopback server (`http://127.0.0.1:<port>/`)
+and opens it in your browser.
+
+<Aside type="caution">
+ A web build needs an **http origin** — opening `index.html` directly from disk
+ (`file://`) won't stream the WebAssembly. Use the preview button, or upload the
+ folder to any static host.
+</Aside>
+
## 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. |
+| **Web** | A static, self-contained web build. | `dist-web/` | **Preview over http**, 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. |
+| **Playable** | One self-contained `index.html` with everything inlined — no external requests, as ad networks require. | `dist-playable/` | **Preview over http** (its real surface is an ad-network iframe). Note a full engine usually exceeds ad-network size limits. |
## Runtime prerequisites
@@ -49,7 +80,12 @@ node build-tools/cli.js build -t wechat
node build-tools/cli.js build -t playable
```
-The Package Project dialog reminds you when a target's runtime is missing.
+The Package Project dialog reminds you when a target's runtime is missing, and a
+WeChat export **fails fast** — naming the exact build command — rather than
+producing a package that breaks at runtime. WeChat also needs a matching side
+module for each engine feature the game uses (`physics-wechat`, `spine-wechat`,
+`basis-wechat` for compressed textures) — see
+[WeChat MiniGame](/docs/guides/wechat/).
## Build config & source maps
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index f94fd0205..957f6a14e 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -16,6 +16,9 @@ When no project is open, the editor shows the **Launcher**:
- **Recent** — reopen a project you've worked on, with search and grid/list views.
- **New project** — pick a template, give it a name and location, and create it.
+ Templates come in two groups: **Starters** (the **Blank** template — an empty
+ scene with a camera) and **Examples** (the bundled sample projects, ready to
+ explore and edit).
A project is a folder on disk. The pieces the editor cares about:
@@ -112,6 +115,8 @@ There are several ways to add an entity:
The Outliner is the scene's hierarchy. You can:
- Reparent by dragging entities onto one another, and organize with **folders**.
+- **Type to jump** — with the tree focused, type the first letters of a name to
+ jump to the matching entity.
- **Rename** with `F2`, **Duplicate** with Ctrl/⌘ + D, **Delete** with Delete.
- **Hide/Show** and **Lock/Unlock** entities (independent of whether the component is
enabled at runtime).
@@ -138,7 +143,10 @@ assets in place:
**Import** by dragging files in from Finder / Explorer, or via Import…. Each asset gets
a `.meta` sidecar the first time it's seen. Per-asset context actions include Rename,
-Duplicate, Copy Path, Copy Reference, Show in Explorer, and Delete.
+Duplicate, Copy Path, Copy Reference, Show in Explorer, and Delete. Rename, move,
+and duplicate each post a toast with an **Undo** action; Delete asks for
+confirmation and moves the files to the OS trash. The folder tree is fully
+keyboard-driven — arrows walk and collapse/expand, Enter opens a folder.
## Play-in-editor
@@ -161,9 +169,12 @@ Double-click an asset in the Content Browser to open its editor in a document ta
[Timeline](/docs/guides/timeline/).
- **Tilemap painter** — tools for **brush, erase, rectangle, line, bucket, select,
eyedropper**, and **terrain (autotile)**, plus stamp **flip-H / flip-V / rotate-90°**
- (`H` / `V` / `R` while a paint tool is active). See [Tilemaps](/docs/guides/tilemap/).
+ (`H` / `V` / `R` while a paint tool is active) and a **random-scatter mode**. The
+ palette selects with the arrow keys (`Shift` grows a multi-tile stamp). See
+ [Tilemaps](/docs/guides/tilemap/).
- **Tileset editor** — mark per-tile **collision** (box or polygon) and **terrain**
- membership for autotiling.
+ membership for autotiling, and author **animated tiles** (frame sequences with
+ per-frame durations and a live preview).
- **State Machine** (`.esfsm`) and **Behavior Tree** (`.esbt`) editors — visual graphs
for AI. See [Gameplay AI](/docs/guides/ai/).
- **Material Graph** (`.esmatgraph`) — a node editor that compiles to a shader. See
@@ -210,6 +221,12 @@ Settings → Keyboard Shortcuts.
| Content Drawer | `Ctrl + Space` |
| Project Settings | `mod + ,` |
+Beyond the command shortcuts, the editor is keyboard-navigable throughout: menus
+and context menus move with the arrow keys (plus type-ahead, Home/End, and `→` /
+`←` for submenus), the Outliner jumps to entities as you type, the Content
+Browser's folder tree and the tile palette both walk with arrows, and keyboard
+focus is always shown with a visible focus ring.
+
<Aside type="tip">
For headless automation and AI agents, the editor also exposes an
`EditorControlSurface` (load a scene, step the sim, read the scene tree/inspector,
diff --git a/docs/astro/src/content/docs/guides/scene.mdx b/docs/astro/src/content/docs/guides/scene.mdx
index d85643382..27b0c83c3 100644
--- a/docs/astro/src/content/docs/guides/scene.mdx
+++ b/docs/astro/src/content/docs/guides/scene.mdx
@@ -34,6 +34,19 @@ await scenes.loadAdditive('pause-menu', (loaded, total) => { /* progress */ });
await scenes.unload('pause-menu');
```
+## Scenes in a build
+
+Every scene in the project's scenes folder ships with an export and registers as a
+`switchTo` target. A scene's **name** is its path relative to the scenes folder,
+without the `.esscene` extension — `assets/scenes/levels/boss.esscene` is
+`switchTo('levels/boss')`. The startup scene loads eagerly; the others are fetched
+on their first switch, so extra scenes don't slow the initial load.
+
+Scenes you untick in the Package dialog's **Scenes in build** list are left out of
+the export (they stay editable and playable in the editor), and Playable-ad builds
+ship the startup scene only. See
+[Building & Exporting](/docs/guides/build-export/).
+
## `SceneManager` reference
| Method | Description |
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdx
index f8b881786..4eb176697 100644
--- a/docs/astro/src/content/docs/guides/spine.mdx
+++ b/docs/astro/src/content/docs/guides/spine.mdx
@@ -31,6 +31,27 @@ main `esengine` package.
| `material` | asset | none | Optional custom material. |
| `enabled` | boolean | `true` | Disable to freeze and hide. |
+**Skeleton and atlas are asset slots** in the Details panel: pick from the popover,
+drag a file in from the Content Browser, or use the slot's locate / clear actions.
+The scene serializes them as portable `@uuid:` references, so moving or renaming
+the files never breaks the link. The editor previews the skeleton live in the
+viewport — including across Play/Stop — and once it loads, the `animation` and
+`skin` fields become dropdowns of that skeleton's actual animations and skins.
+
+<Aside type="note">
+ The skeleton pick popover lists **`.skel`** files. A **`.json`** skeleton loads
+ just as well — assign it by **dragging it from the Content Browser** onto the
+ slot.
+</Aside>
+
+## Atlases
+
+Spine `.atlas` files work as exported — including **multi-page** atlases (each
+page texture loads alongside the atlas) and **premultiplied alpha**: a `pma: true`
+atlas header is honored automatically, no import setting needed. When you export
+with **Compress textures** enabled, atlas pages cook to KTX2 and transcode on
+device like any other texture.
+
## Play & blend animations
The `Spine` resource controls tracks, mixing (crossfade), and per-track blending:
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index 8bb7c1f49..f4a2d608e 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -1,28 +1,60 @@
---
title: Tilemaps
-description: The complete guide to tile layers — loading Tiled maps, the Tilemap/TilemapLayer components, building and editing layers in code, multi-tileset layers, animation, infinite chunked maps, and collision.
+description: The complete guide to tile layers — painting in the editor, loading Tiled maps, the Tilemap/TilemapLayer components, building and editing layers in code, multi-tileset layers, animation, infinite chunked maps, and collision.
---
import { Aside } from '@astrojs/starlight/components';
Estella renders tile layers in the C++/WebAssembly core, batched per tileset
-texture and stored in chunks. Load a whole map from a [Tiled](https://www.mapeditor.org/)
-file with the `Tilemap` component, or build and edit layers yourself with the
-`Tilemaps` resource — including multi-tileset layers, per-tile animation, and
-infinite streaming maps.
+texture and stored in chunks. Paint levels directly in the editor, load a whole
+map from a [Tiled](https://www.mapeditor.org/) file with the `Tilemap` component,
+or build and edit layers yourself with the `Tilemaps` resource — including
+multi-tileset layers, per-tile animation, and infinite streaming maps.
## How it works
-There are two entry points. The **`Tilemap`** component points an entity at a Tiled
-JSON file and, at load, spawns one **`TilemapLayer`** entity per layer. The
-**`Tilemaps`** resource is the imperative API for creating and editing layers from
-code. Either way the data ends up in the same runtime layer model. Tile ids are
-**1-based** (`0` = empty). **Orthogonal, isometric, staggered, and hexagonal** maps
-all render — the orientation is read from the Tiled file, no extra setup.
+There are three entry points. The editor's **Tilemap painter** authors layers
+visually, backed by a `.estileset` tileset asset. The **`Tilemap`** component
+points an entity at a Tiled JSON file and, at load, spawns one **`TilemapLayer`**
+entity per layer. The **`Tilemaps`** resource is the imperative API for creating
+and editing layers from code. Every way the data ends up in the same runtime
+layer model. Tile ids are **1-based** (`0` = empty). **Orthogonal, isometric,
+staggered, and hexagonal** maps all render — the orientation is read from the
+Tiled file, no extra setup.
+
+## Paint in the editor
+
+Select an entity with a `TilemapLayer` component and the **Tilemap painter**
+panel opens with the tileset palette. Pick a tool and paint directly in the
+viewport — a stamp ghost previews every stroke:
+
+| Tool | Key | What it does |
+|---|---|---|
+| Brush | `B` | Paint the current stamp; drag for strokes. |
+| Erase | `E` | Clear tiles. |
+| Rectangle | `U` | Fill a dragged rectangle with the stamp pattern. |
+| Line | `L` | Lay the stamp along a straight line. |
+| Bucket | `G` | Flood-fill the connected region of matching tiles. |
+| Select | `M` | Marquee a region — `mod + C` / `X` copy / cut it, `Delete` clears it, `mod + V` pastes it as the brush. |
+| Eyedropper | `I` | Pick the stamp from tiles already on the layer. |
+| Terrain | `T` | Autotile brush — paints a terrain and fixes up the neighbors. |
+
+While a paint tool is active, `H` / `V` flip the stamp and `R` rotates it 90°.
+`Q`, `W`, or `Esc` leave paint mode and hand the keys back to the transform tools.
+
+- **Multi-tile stamps** — drag across the palette to grab a block of tiles as one
+ stamp. The palette is keyboard-friendly too: **arrow keys** move the selection,
+ **Shift + arrows** grow it into a stamp.
+- **Random mode** — toggle the dice button and each painted cell samples one tile
+ at random from the stamp instead of repeating the pattern — quick scatter for
+ grass, rubble, and other variation.
+- **Layer strip** — when the scene has several tilemap layers, a strip at the top
+ of the panel switches the active layer and toggles per-layer visibility and lock.
## Load a Tiled map
-The `Tilemap` component loads a `.tmj`/`.tmx` map via its one field:
+The `Tilemap` component loads a `.tmj` map (Tiled's JSON format — in Tiled, use
+*File → Export As → JSON*) via its one field:
```typescript
import { defineSystem, Commands, Tilemap } from 'esengine';
@@ -95,7 +127,16 @@ tilemap.setTilesets(layer, [
## Tile animation
-Set an animation on a tile id once — the plugin advances it every frame:
+Author animated tiles in the **Tileset editor**: open the `.estileset`, switch the
+mode control to **Animation**, click the tile to animate, then click other atlas
+tiles to append frames. A strip below the toolbar shows a live looping preview,
+per-frame duration inputs (in milliseconds), and remove/clear actions; animated
+tiles carry a ▶ mark in the atlas. The frames are saved into the `.estileset`, and
+every layer that uses the tileset plays them automatically — in the editor viewport
+and at runtime, no code required.
+
+For procedural layers, `setTileAnimation` does the same from code — the plugin
+advances it every frame:
```typescript
tilemap.setTileAnimation(layer, 10, [
@@ -142,6 +183,10 @@ for (const group of src?.objectGroups ?? []) {
}
```
+Objects that carry a tile reference (a **gid** — tiles stamped onto an object layer
+in Tiled) render as sprite children of the map, honoring Tiled's horizontal,
+vertical, **and diagonal** flip flags.
+
An object group whose name is `collision` (case-insensitive) or that carries a
`collision=true` property also **spawns static colliders in play mode** — rectangles,
ellipses, polygons, and polylines become the matching Box2D shape, on the same
@@ -172,8 +217,9 @@ origin / pixels-per-unit / play-mode lifecycle as tile collision.
## Best practices
-- **Prefer Tiled** (`Tilemap` + `.tmj`) for hand-authored levels; use the `Tilemaps`
- API for procedural or runtime-generated maps.
+- **Paint hand-authored levels in the editor** (or import from Tiled with
+ `Tilemap` + `.tmj`); use the `Tilemaps` API for procedural or runtime-generated
+ maps.
- **Batch by tileset**: fewer tileset textures per layer = fewer draw calls; atlas
your tiles.
- **Use `setTiles` / `setChunkTiles`** for bulk writes instead of per-tile `setTile`
diff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/guides/wechat.mdx
index 7df1c6211..9f1c0ce35 100644
--- a/docs/astro/src/content/docs/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/guides/wechat.mdx
@@ -15,27 +15,63 @@ The WeChat target compiles the C++ core with WeChat's `WXWebAssembly` shims:
```bash
node build-tools/cli.js build -t wechat
-# optional side modules, only if your game uses them:
-node build-tools/cli.js build -t spine-wechat
-node build-tools/cli.js build -t physics-wechat
+# side modules, only if your game uses them:
+node build-tools/cli.js build -t physics-wechat # physics
+node build-tools/cli.js build -t spine-wechat # Spine (builds 3.8 + 4.1 + 4.2)
+node build-tools/cli.js build -t basis-wechat # KTX2 / compressed textures
```
+<Aside type="note">
+ **A missing runtime is a hard export error, not a warning.** If a scene uses
+ physics or Spine, or the build ships KTX2 textures, and the matching
+ `*-wechat` module isn't built, the export stops and names the exact build
+ command to run. The exporter stages only the side modules your scenes
+ actually need, so unused ones add no package weight.
+</Aside>
+
## Export from the editor
<Steps>
1. In **Project Settings → Packaging → WeChat**, set your AppID and orientation.
-2. Click **Export Game**. Estella cooks assets, bundles the SDK + your scripts
- (as CommonJS, via esbuild), transforms scenes, and writes a standalone
- MiniGame package.
+2. Open **File → Build…**, pick the **WeChat** platform in the Package Project
+ dialog, review the **Scenes in build** list, and click **Package**. Estella
+ cooks assets, bundles the SDK + your scripts (as CommonJS, via esbuild),
+ transforms scenes, and writes a standalone MiniGame package.
+
+3. Open the output folder in **WeChat DevTools** to compile, test, and submit.
+ If you left the AppID empty, fill it in `project.config.json` from DevTools.
</Steps>
-The output directory contains `game.js` (entry), `game-bundle.js` (SDK +
-scripts), `game.json` / `project.config.json` (WeChat config), the
-`asset-manifest.json`, your scenes, and the `wasm/` engine + side modules. Open
-that directory in WeChat DevTools to compile, test, and submit.
+The output directory contains `game.js` (the entry, which boots
+`game-bundle.js` — the SDK + your scripts), `game.json` /
+`project.config.json` (WeChat config), the `asset-manifest.json`, your scenes
+as `scenes/<name>.json`, and a `wasm/` folder holding the engine plus exactly
+the side modules your scenes need. Every scene in the build is a
+`SceneManager.switchTo` target — non-startup scenes load on their first switch
+(see [Scenes](/docs/guides/scene/)).
+
+<Aside type="caution">
+ Don't hand-edit `game.js` or move files under `wasm/` — the boot sequence
+ instantiates exactly those staged files, so renames break the game in
+ DevTools.
+</Aside>
+
+## Compressed textures
+
+Enable **Compress textures** in the Package dialog to cook PNGs to KTX2 —
+a smaller package and faster first load. Two WeChat-specific details, both
+handled automatically:
+
+- The Basis transcoder ships as the `basis-wechat` side module — build it once
+ (above), or the export fails with the exact command to run.
+- WeChat's code package only accepts whitelisted file suffixes, and `ktx2`
+ isn't one — so the exporter stages every `.ktx2` as `.ktx2.bin`, and the
+ runtime resolves both spellings. The exporter also emits
+ `packOptions.include` rules in `project.config.json` for every staged custom
+ extension (`.skel`, `.atlas`, `.bin`, …) so DevTools packs and serves them.
## Subpackages (分包)
@@ -52,27 +88,20 @@ levels download on demand rather than bloating the initial package:
}
```
-<Aside type="caution">
- **Build the side modules your game needs.** If a scene uses Spine or physics
- but you didn't build `spine-wechat` / `physics-wechat`, the export warns and
- the game fails at runtime. The exporter only wires in the side modules the
- entry scene actually requires, so unused ones add no weight.
-</Aside>
-
## Best practices
-- **Stay under the main-package limit** (WeChat caps the initial package) by moving
- on-demand content into `subpackages/<name>/` — see [Assets](/docs/guides/assets/).
-- **Compress textures** — enable **Compress textures** in the Package dialog to cook
- PNGs to KTX2, shrinking the package and speeding first load.
-- **Build only the side modules you use** — each unused `*-wechat` module you skip is
- weight you don't ship.
-- **Test in WeChat DevTools**, not just the browser — the file system, storage, and
- socket backends differ from the web.
-- **Preload the next level's group** (`loadGroup`) during play so the subpackage
- download doesn't stall the transition.
+- **Stay under the 4 MB main-package limit** by moving on-demand content into
+ `subpackages/<name>/` — see [Assets](/docs/guides/assets/). The export sets
+ `bigPackageSizeSupport`, so an oversized package still *previews* in
+ DevTools — but upload enforces the cap.
+- **Compress textures** — see above; the single biggest package-size win.
+- **Test in WeChat DevTools**, not just the browser — the file system, storage,
+ and socket backends differ from the web.
+- **Preload the next level's group** (`loadGroup`) during play so the
+ subpackage download doesn't stall the transition.
## See also
- [Assets](/docs/guides/assets/) — addressable groups and cooking map onto subpackages.
+- [Building & Exporting](/docs/guides/build-export/) — the Package Project dialog.
- [Networking](/docs/guides/networking/) — sockets use `wx.connectSocket` here.
diff --git a/docs/astro/src/content/docs/zh-cn/getting-started/quick-start.mdx b/docs/astro/src/content/docs/zh-cn/getting-started/quick-start.mdx
index 455de0c28..a792e44f1 100644
--- a/docs/astro/src/content/docs/zh-cn/getting-started/quick-start.mdx
+++ b/docs/astro/src/content/docs/zh-cn/getting-started/quick-start.mdx
@@ -10,8 +10,9 @@ import { Steps, Aside } from '@astrojs/starlight/components';
<Steps>
-1. **创建项目。** 在编辑器中点击 **New Project**,命名后点击 **Create**。你会得到
- 一个带相机实体的默认场景。
+1. **创建项目。** 在编辑器中点击 **New Project**,选 **Blank** 起始模板,命名后点击
+ **Create**。你会得到一个带相机实体的默认场景。(想直接看成品的话,**Examples**
+ 模板是完整的示例项目。)
2. **添加实体。** 在场景层级里新建一个实体,在检视面板中给它加上 `Sprite` 与
`Transform` 组件。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
index 23f2245ae..8743afaf7 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -100,8 +100,8 @@ const { failed } = await assets.preload(
## 烘焙、压缩与内容寻址
-构建时,**烘焙**从入口场景出发遍历依赖图,**剔除一切触达不到的资源**,暂存可达文件,
-并写出清单。过程中它还能:
+构建时,**烘焙**从构建里的每个场景(打包对话框的**构建场景**列表)出发遍历依赖图,
+**剔除一切触达不到的资源**,暂存可达文件,并写出清单。过程中它还能:
- **压缩纹理** —— 把 PNG 编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。在打包对话框勾选**压缩纹理**。
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
index 400ff765e..744933134 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
@@ -15,22 +15,47 @@ import { Aside, Steps } from '@astrojs/starlight/components';
1. 打开 **文件 → Build…** 调出 **打包项目(Package Project)** 对话框。
2. 选一个**平台**(Web / 桌面 / 微信 / Playable)。
-3. 选一个**构建配置**——*Development* 或 *Shipping*(Shipping 会压缩)——一个**输出目录**,以及
- 是否输出 source map。
-4. 点 **导出**,看实时构建日志。完成后输出目录会自动打开。
+3. 选一个**构建配置**——*Development* 或 *Shipping*(Shipping 会压缩)——一个**输出目录**、
+ source map,以及[资产烘焙选项](#资产烘焙选项)。
+4. 检查**构建场景(Scenes in build)**列表——取消勾选不想发布的场景,需要的话换一个
+ 启动场景(见下文)。
+5. 点 **Package**,看实时构建日志。完成后输出目录会自动打开(有复选框可关掉),
+ Web / Playable 构建还会提供 **Preview over http**。
</Steps>
你的选择会存进 `project.esproject`,所以对话框下次会记住它们。
+## 构建场景
+
+项目场景目录下的每个场景都随导出发布,并成为 `SceneManager.switchTo` 的目标——游戏脚本
+如何切换见[场景](/docs/zh-cn/guides/scene/)。对话框的**构建场景**列表控制这个集合:
+
+- **启动场景**置顶并带播放徽标。它总是发布——点其他场景的播放按钮可把启动权移过去,
+ 或在内容浏览器里右键任意场景选**设为启动场景(Set as Startup Scene)**。
+- **取消勾选一个场景**把它排除出构建(存为 `project.esproject` 里的
+ `packaging.excludeScenes`)。被排除的场景在编辑器里仍可正常编辑和运行;只被排除场景
+ 引用的资产不会烘焙进构建。
+- **Playable** 只带启动场景——它是一个有体积上限的单文件。
+
+## 预览导出
+
+**Web** 或 **Playable** 构建完成后,点 **Preview over http** ——编辑器把输出目录架在
+本机回环服务器上(`http://127.0.0.1:<端口>/`)并用浏览器打开。
+
+<Aside type="caution">
+ Web 构建需要 **http 源**——直接从磁盘打开 `index.html`(`file://`)无法流式加载
+ WebAssembly。用预览按钮,或把文件夹上传到任意静态托管。
+</Aside>
+
## 各个目标
| 目标 | 产出什么 | 输出 | 下一步 |
|---|---|---|---|
-| **Web** | 一个静态、自包含的 Web 构建。 | `dist-web/` | 打开 `index.html`,或把文件夹上传到任意静态托管。 |
+| **Web** | 一个静态、自包含的 Web 构建。 | `dist-web/` | **Preview over http**,或把文件夹上传到任意静态托管。 |
| **桌面** | 一棵 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`。注意完整引擎通常超出广告网络的体积限制。 |
+| **Playable** | 一个自包含的 `index.html`,一切内联——无外部请求(广告网络的要求)。 | `dist-playable/` | **Preview over http**(它的真实宿主是广告网络的 iframe)。注意完整引擎通常超出广告网络的体积限制。 |
## 运行时前置条件
@@ -45,7 +70,10 @@ node build-tools/cli.js build -t wechat
node build-tools/cli.js build -t playable
```
-当某个目标的运行时缺失时,打包项目对话框会提醒你。
+当某个目标的运行时缺失时,打包项目对话框会提醒你,而微信导出会**直接失败**并给出确切的
+构建命令——而不是产出一个运行时才崩的包。微信还需要为游戏用到的每个引擎特性构建对应的
+侧模块(`physics-wechat`、`spine-wechat`,压缩纹理用 `basis-wechat`)——见
+[微信小游戏](/docs/zh-cn/guides/wechat/)。
## 构建配置与 source map
diff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
index 8d887463d..43427d386 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -14,7 +14,9 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
没有项目打开时,编辑器显示 **启动器(Launcher)**:
- **最近** — 重新打开你做过的项目,带搜索和网格/列表视图。
-- **新建项目** — 选一个模板,起名字、选位置,创建。
+- **新建项目** — 选一个模板,起名字、选位置,创建。模板分两组:**Starters**
+ (**Blank** 模板——只有一个相机的空场景)和 **Examples**(随附的示例项目,
+ 可直接探索和修改)。
一个项目就是磁盘上的一个文件夹。编辑器关心的几块:
@@ -101,6 +103,7 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
Outliner 是场景的层级。你可以:
- 把实体拖到彼此上重设父子,并用**文件夹**归类。
+- **按名跳转** — 树聚焦时,输入名字的前几个字母即可跳到匹配的实体。
- 用 `F2` **重命名**、`mod + D` **复制**、`Delete` **删除**。
- **隐藏/显示**和**锁定/解锁**实体(与组件在运行时是否 enabled 解耦)。
- 从选择**创建预制体**,再把实例拖回场景。
@@ -121,6 +124,8 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
**导入**可从访达/资源管理器把文件拖进来,或用"导入…"。每个资产首次出现时会得到一个 `.meta`
边车。按资产的上下文动作包括重命名、复制、复制路径、复制引用、在文件管理器中显示、删除。
+重命名、移动和复制各会弹出一个带**撤销**按钮的 toast;删除会先确认,然后把文件移进系统
+回收站。文件夹树完全可用键盘操作——方向键行走与折叠/展开,Enter 进入文件夹。
## 编辑器内运行
@@ -138,9 +143,11 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
- **Sequencer** — 关键帧动画的时间轴/曲线编辑器。见 [时间轴](/docs/zh-cn/guides/timeline/)。
- **瓦片地图画笔** — **画笔、擦除、矩形、直线、油漆桶、选区、吸管**和**地形(autotile)**等工具,
- 外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)。见
+ 外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)和一个
+ **随机散布模式**。调色板用方向键选择(`Shift` 扩成多瓦片图章)。见
[瓦片地图](/docs/zh-cn/guides/tilemap/)。
-- **瓦片集编辑器** — 标记每瓦片的**碰撞**(盒或多边形)和**地形**归属以做 autotile。
+- **瓦片集编辑器** — 标记每瓦片的**碰撞**(盒或多边形)和**地形**归属以做 autotile,并创作
+ **动画瓦片**(帧序列 + 逐帧时长,带实时预览)。
- **状态机**(`.esfsm`)和**行为树**(`.esbt`)编辑器 — AI 的可视化图。见
[游戏 AI](/docs/zh-cn/guides/ai/)。
- **材质图**(`.esmatgraph`) — 编译成着色器的节点编辑器。见
@@ -183,6 +190,10 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
| 内容抽屉 | `Ctrl + Space` |
| 项目设置 | `mod + ,` |
+在命令快捷键之外,编辑器整体都可用键盘导航:菜单与右键菜单用方向键移动(还有输入即跳、
+Home/End、`→` / `←` 进出子菜单),Outliner 输入名字即跳转,内容浏览器的文件夹树和瓦片
+调色板都用方向键行走,键盘焦点始终有可见的焦点环。
+
<Aside type="tip">
用于无头自动化和 AI 代理,编辑器还暴露了一个 `EditorControlSurface`(加载场景、步进模拟、读取
场景树/检视器、抓取视口),通过一个 MCP server 提供——这是一个由脚本驱动的开发/自动化面,与上面
diff --git a/docs/astro/src/content/docs/zh-cn/guides/scene.mdx b/docs/astro/src/content/docs/zh-cn/guides/scene.mdx
index 67a512ba9..61b9678e5 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/scene.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/scene.mdx
@@ -31,6 +31,16 @@ await scenes.loadAdditive('pause-menu', (loaded, total) => { /* progress */ });
await scenes.unload('pause-menu');
```
+## 构建里的场景
+
+项目场景目录下的每个场景都会随导出发布,并注册为 `switchTo` 的目标。场景的**名字**是它
+相对场景目录的路径去掉 `.esscene` 扩展名——`assets/scenes/levels/boss.esscene` 就是
+`switchTo('levels/boss')`。启动场景立即加载;其余场景在首次切换时才拉取,所以多余的场景
+不会拖慢首屏。
+
+在打包对话框的**构建场景**列表里取消勾选的场景不会进入导出(在编辑器里仍可正常编辑和
+运行),Playable 广告构建只带启动场景。见[构建与导出](/docs/zh-cn/guides/build-export/)。
+
## `SceneManager` 参考
| 方法 | 说明 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
index f1a638e00..137ffad77 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
@@ -29,6 +29,22 @@ Estella 内置 [Spine](https://esotericsoftware.com/) 骨骼动画:骨骼、网
| `material` | asset | 无 | 可选的自定义材质。 |
| `enabled` | boolean | `true` | 关掉即冻结并隐藏。 |
+**骨骼与图集是 Details 面板里的资产槽位**:从弹出选择器里挑,从内容浏览器拖进来,
+或用槽位的定位 / 清除操作。场景把它们序列化为可移植的 `@uuid:` 引用,移动或重命名
+文件都不会断链。编辑器在视口里实时预览骨骼——跨越播放/停止也不丢——骨骼加载完成后,
+`animation` 和 `skin` 字段会变成该骨骼实际动画与皮肤的下拉列表。
+
+<Aside type="note">
+ 骨骼选择器只列出 **`.skel`** 文件。**`.json`** 骨骼同样能加载——从内容浏览器
+ **拖拽**到槽位上即可。
+</Aside>
+
+## 图集
+
+Spine 导出的 `.atlas` 文件即用即好——包括**多页**图集(每页纹理随图集一起加载)和
+**预乘 alpha**:图集头里的 `pma: true` 自动生效,无需导入设置。导出时开启**压缩纹理**,
+图集页会烘焙成 KTX2,并像其他纹理一样在设备上转码。
+
## 播放与混合
`Spine` 资源控制轨道、混合(crossfade)与逐轨道混合:
diff --git a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
index 8ef649b30..246f43ad6 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -1,24 +1,53 @@
---
title: 瓦片地图
-description: 瓦片图层的完整指南——加载 Tiled 地图、Tilemap/TilemapLayer 组件、用代码构建与编辑图层、多图集图层、动画、无限分块地图与碰撞。
+description: 瓦片图层的完整指南——在编辑器里绘制、加载 Tiled 地图、Tilemap/TilemapLayer 组件、用代码构建与编辑图层、多图集图层、动画、无限分块地图与碰撞。
---
import { Aside } from '@astrojs/starlight/components';
-Estella 在 C++/WebAssembly 内核里渲染瓦片图层,按图集纹理合批并以分块(chunk)存储。用
-`Tilemap` 组件从 [Tiled](https://www.mapeditor.org/) 文件加载整张地图,或用 `Tilemaps`
-资源自己构建与编辑图层——包括多图集图层、逐瓦片动画和无限流式地图。
+Estella 在 C++/WebAssembly 内核里渲染瓦片图层,按图集纹理合批并以分块(chunk)存储。
+直接在编辑器里绘制关卡,用 `Tilemap` 组件从 [Tiled](https://www.mapeditor.org/) 文件
+加载整张地图,或用 `Tilemaps` 资源自己构建与编辑图层——包括多图集图层、逐瓦片动画和
+无限流式地图。
## 工作原理
-有两个入口。**`Tilemap`** 组件把实体指向一个 Tiled JSON 文件,加载时为每个图层生成一个
-**`TilemapLayer`** 实体。**`Tilemaps`** 资源是用代码创建与编辑图层的命令式 API。两种方式最终
-都落到同一个运行时图层模型。瓦片 id 是**从 1 开始**的(`0` = 空)。**正交、等距、交错
+有三个入口。编辑器的**瓦片画笔面板**以可视方式创作图层,背后是 `.estileset` 图集资源。
+**`Tilemap`** 组件把实体指向一个 Tiled JSON 文件,加载时为每个图层生成一个
+**`TilemapLayer`** 实体。**`Tilemaps`** 资源是用代码创建与编辑图层的命令式 API。三种方式
+最终都落到同一个运行时图层模型。瓦片 id 是**从 1 开始**的(`0` = 空)。**正交、等距、交错
(staggered)、六边形**地图都能渲染——朝向从 Tiled 文件里读取,无需额外设置。
+## 在编辑器里绘制
+
+选中带 `TilemapLayer` 组件的实体,**瓦片画笔**面板会带着图集调色板打开。选一个工具,
+直接在视口里绘制——每一笔都有印章虚影(stamp ghost)预览:
+
+| 工具 | 键 | 作用 |
+|---|---|---|
+| 画笔 | `B` | 绘制当前印章;拖动连续作画。 |
+| 橡皮 | `E` | 清除瓦片。 |
+| 矩形 | `U` | 用印章图案填充拖出的矩形。 |
+| 直线 | `L` | 沿直线铺设印章。 |
+| 油漆桶 | `G` | 泛洪填充相连的同类瓦片区域。 |
+| 框选 | `M` | 框选一块区域——`mod + C` / `X` 复制 / 剪切,`Delete` 清空,`mod + V` 作为画笔粘贴。 |
+| 吸管 | `I` | 从图层上已有的瓦片取印章。 |
+| 地形 | `T` | 自动拼接画笔——绘制地形并自动修正邻居。 |
+
+绘制工具激活期间,`H` / `V` 翻转印章,`R` 旋转 90°。按 `Q`、`W` 或 `Esc` 离开绘制模式,
+键位交还给变换工具。
+
+- **多瓦片印章** —— 在调色板上拖动,把一整块瓦片抓成一个印章。调色板也支持键盘:
+ **方向键**移动选择,**Shift + 方向键**扩成印章。
+- **随机模式** —— 打开骰子按钮,每个落笔格从印章里随机取一个瓦片,而不是重复图案——
+ 给草地、碎石等做变化最快的方式。
+- **图层条** —— 场景里有多个瓦片图层时,面板顶部的图层条切换活动图层,并可逐层切换
+ 可见性与锁定。
+
## 加载 Tiled 地图
-`Tilemap` 组件通过它唯一的字段加载一个 `.tmj`/`.tmx` 地图:
+`Tilemap` 组件通过它唯一的字段加载一个 `.tmj` 地图(Tiled 的 JSON 格式——在 Tiled 里
+用*文件 → 导出为 → JSON*):
```typescript
import { defineSystem, Commands, Tilemap } from 'esengine';
@@ -91,7 +120,12 @@ tilemap.setTilesets(layer, [
## 瓦片动画
-对某个瓦片 id 设一次动画——插件每帧推进它:
+动画瓦片在**图集编辑器**里创作:打开 `.estileset`,把模式切到**动画**,点击要动画的
+瓦片,再依次点击其他图集瓦片追加帧。工具栏下方的条带里有实时循环预览、逐帧时长输入
+(毫秒)和删除/清空操作;带动画的瓦片在图集里有 ▶ 标记。帧数据保存进 `.estileset`,
+所有使用该图集的图层都会自动播放——编辑器视口和运行时皆然,无需一行代码。
+
+程序化图层用 `setTileAnimation` 从代码做同样的事——插件每帧推进它:
```typescript
tilemap.setTileAnimation(layer, 10, [
@@ -137,6 +171,9 @@ for (const group of src?.objectGroups ?? []) {
}
```
+携带瓦片引用(**gid**——在 Tiled 里盖到对象层上的瓦片)的对象会渲染为地图的精灵
+子实体,并遵守 Tiled 的水平、垂直**和对角**翻转标志。
+
名字为 `collision`(大小写不敏感)或携带 `collision=true` 属性的对象组还会**在播放模式
生成静态碰撞体**——矩形、椭圆、多边形、折线各自变成对应的 Box2D 形状,与瓦片碰撞走相同的
origin / 每单位像素 / 播放模式生命周期。
@@ -165,7 +202,8 @@ origin / 每单位像素 / 播放模式生命周期。
## 最佳实践
-- 手工关卡**优先用 Tiled**(`Tilemap` + `.tmj`);程序化或运行时生成的地图用 `Tilemaps` API。
+- 手工关卡**在编辑器里绘制**(或用 `Tilemap` + `.tmj` 从 Tiled 导入);程序化或运行时
+ 生成的地图用 `Tilemaps` API。
- **按图集合批**:每图层的图集纹理越少,draw call 越少;把瓦片打成图集。
- 批量写入**用 `setTiles` / `setChunkTiles`**,而不是循环里逐个 `setTile`。
- 流式世界**用无限图层**;只写玩家附近的块。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
index f0c046ca9..b30e5f267 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
@@ -14,25 +14,55 @@ Estella 能把同一个项目导出为**微信小游戏**。你为微信目标
```bash
node build-tools/cli.js build -t wechat
-# 可选的侧模块,仅当你的游戏用到时:
-node build-tools/cli.js build -t spine-wechat
-node build-tools/cli.js build -t physics-wechat
+# 侧模块,仅当你的游戏用到时:
+node build-tools/cli.js build -t physics-wechat # 物理
+node build-tools/cli.js build -t spine-wechat # Spine(一次构建 3.8 + 4.1 + 4.2)
+node build-tools/cli.js build -t basis-wechat # KTX2 / 压缩纹理
```
+<Aside type="note">
+ **缺失运行时是导出硬错误,不是警告。** 如果某个场景用了物理或 Spine,或构建里
+ 带 KTX2 纹理,而对应的 `*-wechat` 模块没构建,导出会直接停下,并给出要运行的
+ 确切构建命令。导出器只暂存场景实际需要的侧模块,未用到的不会增加包体。
+</Aside>
+
## 从编辑器导出
<Steps>
1. 在**项目设置 → 打包 → 微信**中,填写 AppID 与横竖屏方向。
-2. 点击**导出游戏**。Estella 会烘焙资源,把 SDK 与你的脚本打包(用 esbuild 打成
- CommonJS),转换场景,并写出一个独立的小游戏包。
+2. 打开**文件 → 构建…**,在 Package Project 对话框里选 **WeChat** 平台,
+ 检查**构建场景**列表,点击 **Package**。Estella 会烘焙资源,把 SDK 与你的
+ 脚本打包(用 esbuild 打成 CommonJS),转换场景,并写出一个独立的小游戏包。
+
+3. 用**微信开发者工具**打开输出目录,编译、测试、提交。如果 AppID 留空了,
+ 在开发者工具里填进 `project.config.json` 即可。
</Steps>
-输出目录包含 `game.js`(入口)、`game-bundle.js`(SDK + 脚本)、`game.json` /
-`project.config.json`(微信配置)、`asset-manifest.json`、你的场景,以及 `wasm/` 引擎
-和侧模块。用微信开发者工具打开该目录即可编译、测试、提交。
+输出目录包含 `game.js`(入口,负责引导 `game-bundle.js` —— SDK + 你的脚本)、
+`game.json` / `project.config.json`(微信配置)、`asset-manifest.json`、以
+`scenes/<名字>.json` 存放的场景,以及 `wasm/` 目录 —— 引擎加上场景实际需要的
+侧模块。构建里的每个场景都是 `SceneManager.switchTo` 的切换目标——非启动场景在
+首次切换时才加载(见[场景](/docs/zh-cn/guides/scene/))。
+
+<Aside type="caution">
+ 不要手改 `game.js` 或移动 `wasm/` 下的文件——引导序列按暂存时的确切文件名
+ 实例化,改名会让游戏在开发者工具里直接挂掉。
+</Aside>
+
+## 压缩纹理
+
+在打包对话框勾选**压缩纹理**,把 PNG 烘焙为 KTX2 —— 包更小、首屏更快。两个微信
+特有的细节,都已自动处理:
+
+- Basis 转码器以 `basis-wechat` 侧模块的形式随包发布——构建一次(见上),否则
+ 导出会失败并给出确切命令。
+- 微信的代码包只接受白名单后缀,`ktx2` 不在其中——所以导出器把每个 `.ktx2` 暂存为
+ `.ktx2.bin`,运行时两种拼写都能解析。导出器还会在 `project.config.json` 里为每个
+ 暂存的自定义扩展名(`.skel`、`.atlas`、`.bin` 等)生成 `packOptions.include`
+ 规则,让开发者工具打包并读取它们。
## 分包(subpackages)
@@ -49,22 +79,17 @@ node build-tools/cli.js build -t physics-wechat
}
```
-<Aside type="caution">
- **构建你的游戏需要的侧模块。** 如果某个场景用了 Spine 或物理,但你没构建
- `spine-wechat` / `physics-wechat`,导出会警告且游戏在运行时失败。导出器只接入入口
- 场景实际需要的侧模块,未用到的不会增加体积。
-</Aside>
-
## 最佳实践
-- **保持在主包限制以内**(微信对初始包有上限):把按需内容移到 `subpackages/<name>/`——见
- [资源](/docs/zh-cn/guides/assets/)。
-- **压缩纹理** —— 在打包对话框勾选**压缩纹理**,把 PNG 烘焙为 KTX2,缩小包体、加快首屏加载。
-- **只构建你用到的侧模块**——每跳过一个未用的 `*-wechat` 模块就是少发的体积。
-- **在微信开发者工具里测试**,而不只是浏览器——文件系统、存储与套接字后端都与 Web 不同。
-- **在游玩中预加载下一关的分组**(`loadGroup`),让子包下载不卡过渡。
+- **保持在 4 MB 主包限制以内**:把按需内容移到 `subpackages/<name>/`——见
+ [资源](/docs/zh-cn/guides/assets/)。导出会设置 `bigPackageSizeSupport`,超限的包
+ 在开发者工具里仍可*预览*——但上传照样卡限制。
+- **压缩纹理** —— 见上文;这是包体最大的一笔节省。
+- **在微信开发者工具里测试**,而不只是浏览器——文件系统、存储与套接字后端都与 Web 不同。
+- **在游玩中预加载下一关的分组**(`loadGroup`),让分包下载不卡过渡。
## 参见
-- [资源](/docs/zh-cn/guides/assets/) —— 可寻址分组与 cook 映射到子包。
+- [资源](/docs/zh-cn/guides/assets/) —— 可寻址分组与 cook 映射到分包。
+- [构建与导出](/docs/zh-cn/guides/build-export/) —— Package Project 对话框。
- [联网](/docs/zh-cn/guides/networking/) —— 那里套接字用 `wx.connectSocket`。