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(quick-start): the first page ended before anything was playable
yhh837da9cab902
diff --git a/docs/astro/src/content/docs/getting-started/quick-start.mdx b/docs/astro/src/content/docs/getting-started/quick-start.mdxindex 3b0a595c7..48ebe0717 100644--- a/docs/astro/src/content/docs/getting-started/quick-start.mdx+++ b/docs/astro/src/content/docs/getting-started/quick-start.mdx@@ -1,53 +1,88 @@---title: Quick Start-description: Create a project and write your first system.+description: "Five minutes to something you can play — a shape you drive with the arrow keys, with no art and no setup."---import { Steps, Aside } from '@astrojs/starlight/components';-This walks through a first moving entity: add it in the editor, then drive it-with a system written in TypeScript.+Five minutes, no art. By the end you will have a project, something on screen,+and a script that moves it when you press a key — all of it from what ships in+the box: the **Blank** template starts with a camera and nothing else, and a+shape draws without needing a texture.<Steps>-1. **Create a project.** In the editor, click **New project**, pick the- **Blank** starter template, name it, and click **Create project**. 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.--3. **Write a system.** Add a TypeScript file to your project's scripts and- register a system that moves everything with a `Speed` component:-- ```typescript- import {- defineComponent, defineSystem, addSystem,- Query, Mut, Res, Time, Transform- } from 'esengine';-- const Speed = defineComponent('Speed', { value: 200 });-- addSystem(defineSystem(- [Res(Time), Query(Mut(Transform), Speed)],- (time, query) => {- for (const [entity, transform, speed] of query) {- transform.position.x += speed.value * time.delta;- }- }- ));+1. **Create the project.** In the launcher, click **New project**, pick the+ **Blank** starter, name it, and click **Create project**. The editor opens+ `assets/scenes/main.esscene` — one entity, a `Camera`.++2. **Put something on screen.** In the viewport, open **Create…** and choose+ **Shape**. A white circle appears at the origin and the World Outliner gains+ an entity carrying a `Transform` and a `ShapeRenderer`. Press `F2` and rename+ it **Player**.++3. **Write the behaviour.** Open `src/components.ts` — the Blank template's+ declaration entry — and replace its contents with:++ ```typescript title="src/components.ts"+ import { defineBehavior, Transform } from 'esengine';++ export const Player = defineBehavior('Player', {+ state: { speed: 300 },+ update(ctx, dt) {+ const x = (ctx.input.isKeyDown('ArrowRight') ? 1 : 0) - (ctx.input.isKeyDown('ArrowLeft') ? 1 : 0);+ const y = (ctx.input.isKeyDown('ArrowUp') ? 1 : 0) - (ctx.input.isKeyDown('ArrowDown') ? 1 : 0);+ if (x === 0 && y === 0) return;++ const t = ctx.get(Transform); // a copy — Transform lives in the engine+ t.position.x += x * ctx.self.speed * dt;+ t.position.y += y * ctx.self.speed * dt;+ ctx.set(Transform, t); // …so hand it back+ },+ });```-4. **Preview.** Save the script — the editor watches your project's scripts and, a- moment later, extracts your component definitions, so `Speed` appears in the- inspector's **Add Component** list automatically. Add `Speed` to your entity,- then press **F5** to run the scene. The sprite moves.+ Save it. The editor watches your scripts and picks up the new component a+ moment later.++4. **Attach it.** Select **Player** in the Outliner, then in the Details panel+ click **Add Component** and choose **Player**. A `speed` field appears,+ editable like any other — a behaviour's `state` *is* the component's data.++5. **Play.** Press **F5** and hold an arrow key. **Esc** stops, and the scene is+ exactly as you left it: play runs in its own realm and never writes back to+ the scene you are editing.</Steps>-<Aside type="tip">- `Res(Time)` gives you frame timing, `Query(...)` iterates entities that have- every listed component, and `Mut(...)` marks a component you intend to write.- See [Systems](/docs/core-concepts/systems/) for the full query vocabulary.+## What just happened++- **One call gave you a component and a system.** `defineBehavior` registers the+ `update` hook as a system *and* returns a component, which is why **Player**+ showed up in Add Component without you declaring anything else.+- **`state` is the component's data**, so the editor can edit it. Change `speed`+ in Details and the next run uses your number — code and inspector are two doors+ to the same field.+- **`ctx` is the entity's view of the frame** — `ctx.self` is this entity's own+ state, `ctx.input` is the keyboard, `dt` is the seconds since the last frame.+ Multiplying by `dt` is what makes 300 mean *300 units per second* rather than+ per frame.++<Aside type="caution">+ The copy in step 3 is not ceremony. `ctx.get` hands back the stored object for+ a component you declared yourself, but `Transform`, `Sprite`, `RigidBody` and+ every other engine component are decoded out of the wasm heap on each read —+ so `ctx.get(Transform).position.x += …` changes a value nobody keeps, and does+ it silently. Read it, change it, hand it back with `ctx.set`. See+ [Scripting](/docs/scripting/overview/#your-first-behavior).</Aside>++## Next steps++- [Scripting](/docs/scripting/overview/) — behaviours, systems, where declarations+ live, and how hot reload picks them up.+- [The Editor](/docs/editor/overview/) — the workspace you just used, in full.+- [ECS Architecture](/docs/core-concepts/ecs/) — why a component is data and a+ system is behaviour.+- [Sprites & Rendering](/docs/graphics/sprites/) — when you are ready to swap the+ circle for artwork.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.mdxindex c6b1d3ed0..cce26d62e 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@@ -1,50 +1,72 @@---title: 快速上手-description: 创建项目并写下你的第一个系统。+description: "五分钟做出一个能玩的东西——一个用方向键操控的图形,不需要美术,不需要配置。"---import { Steps, Aside } from '@astrojs/starlight/components';-下面走一遍「让一个实体动起来」:在编辑器里把它加进场景,再用一段 TypeScript-系统驱动它。+五分钟,零美术。做完你会有一个项目、一个画面上看得见的东西,以及一段按键就让它动起来的+脚本——全部用开箱即有的东西:**Blank** 模板一开始只有一个相机,而图形不需要纹理就能画。<Steps>-1. **创建项目。** 在编辑器中点击 **New project**,选 **Blank** 起始模板,命名后点击- **Create project**。你会得到一个带相机实体的默认场景。(想直接看成品的话,- **Examples** 模板是完整的示例项目。)+1. **创建项目。** 在启动器里点**新建项目**,选 **Blank** 起始模板,起个名字,点**创建项目**。+ 编辑器会打开 `assets/scenes/main.esscene`——里面只有一个实体:`Camera`。-2. **添加实体。** 在场景层级里新建一个实体,在检视面板中给它加上 `Sprite` 与- `Transform` 组件。+2. **在画面上放个东西。** 在视口里打开**创建…**,选 **Shape**。原点会出现一个白色圆形,+ World Outliner 里多出一个带 `Transform` 和 `ShapeRenderer` 的实体。按 `F2` 把它改名为+ **Player**。-3. **编写系统。** 在项目的脚本里新建一个 TypeScript 文件,注册一个系统,让所有带- `Speed` 组件的实体移动:+3. **写行为。** 打开 `src/components.ts`——Blank 模板的声明入口——把内容替换成:- ```typescript- import {- defineComponent, defineSystem, addSystem,- Query, Mut, Res, Time, Transform- } from 'esengine';+ ```typescript title="src/components.ts"+ import { defineBehavior, Transform } from 'esengine';- const Speed = defineComponent('Speed', { value: 200 });+ export const Player = defineBehavior('Player', {+ state: { speed: 300 },+ update(ctx, dt) {+ const x = (ctx.input.isKeyDown('ArrowRight') ? 1 : 0) - (ctx.input.isKeyDown('ArrowLeft') ? 1 : 0);+ const y = (ctx.input.isKeyDown('ArrowUp') ? 1 : 0) - (ctx.input.isKeyDown('ArrowDown') ? 1 : 0);+ if (x === 0 && y === 0) return;- addSystem(defineSystem(- [Res(Time), Query(Mut(Transform), Speed)],- (time, query) => {- for (const [entity, transform, speed] of query) {- transform.position.x += speed.value * time.delta;- }- }- ));+ const t = ctx.get(Transform); // 拷贝——Transform 活在引擎里+ t.position.x += x * ctx.self.speed * dt;+ t.position.y += y * ctx.self.speed * dt;+ ctx.set(Transform, t); // ……所以要交回去+ },+ });```-4. **预览。** 保存脚本——编辑器会监视项目脚本,片刻后提取你的组件定义,于是 `Speed`- 会自动出现在检视器的**添加组件**列表里。给实体加上 `Speed` 组件,然后按 **F5** 运行- 场景,精灵就会移动。+ 保存。编辑器会监视你的脚本,过一小会儿就认出这个新组件。++4. **挂上去。** 在 Outliner 里选中 **Player**,然后在 Details 面板点 **Add Component**,+ 选 **Player**。会出现一个 `speed` 字段,和别的字段一样可编辑——行为的 `state` **就是**+ 组件的数据。++5. **运行。** 按 **F5**,按住一个方向键。**Esc** 停止,场景和你离开时一模一样:运行跑在+ 它自己的 realm 里,永远不会写回你正在编辑的场景。</Steps>-<Aside type="tip">- `Res(Time)` 提供帧计时,`Query(...)` 遍历同时拥有列出的每个组件的实体,`Mut(...)`- 标记一个你打算写入的组件。完整的查询词汇见[系统](/docs/zh-cn/core-concepts/systems/)。+## 刚才发生了什么++- **一次调用同时给了你一个组件和一个系统。** `defineBehavior` 把 `update` 钩子注册成系统,+ *同时*返回一个组件——所以你什么都没多声明,**Player** 就出现在了 Add Component 里。+- **`state` 就是组件的数据**,所以编辑器能编辑它。在 Details 里改 `speed`,下次运行就用你的+ 数——代码和检视器是通向同一个字段的两扇门。+- **`ctx` 是这个实体对这一帧的视角**——`ctx.self` 是本实体自己的状态,`ctx.input` 是键盘,+ `dt` 是距上一帧的秒数。乘以 `dt` 才让 300 表示*每秒 300 单位*,而不是每帧 300。++<Aside type="caution">+ 第 3 步里那份拷贝不是多余的仪式。对你自己声明的组件,`ctx.get` 给的是存储对象本身;但+ `Transform`、`Sprite`、`RigidBody` 这些引擎组件每次读都是从 wasm 堆里解出来的——所以+ `ctx.get(Transform).position.x += …` 改的是一个没人保存的值,而且是**静默**的。读出来、+ 改完、用 `ctx.set` 交回去。参见[脚本](/docs/zh-cn/scripting/overview/#你的第一个-behavior)。</Aside>++## 下一步++- [脚本](/docs/zh-cn/scripting/overview/) —— 行为、系统、声明放在哪里,以及热重载怎么认出它们。+- [编辑器](/docs/zh-cn/editor/overview/) —— 你刚用过的工作区,完整版。+- [ECS 架构](/docs/zh-cn/core-concepts/ecs/) —— 为什么组件是数据、系统是行为。+- [精灵与渲染](/docs/zh-cn/graphics/sprites/) —— 当你准备好把圆形换成美术资源。