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: add 简体中文 translation (Starlight i18n)

yhh037212ff56d6
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 62ef2cac0..93baa1a7d 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -12,6 +12,12 @@ export default defineConfig({
starlight({
title: 'Estella',
description: 'A fast 2D game engine powered by WebAssembly and ECS.',
+ // English is the root locale (served at /docs); 简体中文 at /docs/zh-cn.
+ defaultLocale: 'root',
+ locales: {
+ root: { label: 'English', lang: 'en' },
+ 'zh-cn': { label: '简体中文', lang: 'zh-CN' },
+ },
social: [
{ icon: 'github', label: 'GitHub', href: 'https://github.com/esengine/estella' },
{ icon: 'discord', label: 'Discord', href: 'https://discord.gg/sAX6PXZ9' },
@@ -22,22 +28,25 @@ export default defineConfig({
sidebar: [
{
label: 'Getting Started',
+ translations: { 'zh-CN': '快速开始' },
items: [
- { label: 'Introduction', slug: 'getting-started/introduction' },
- { label: 'Installation', slug: 'getting-started/installation' },
- { label: 'Quick Start', slug: 'getting-started/quick-start' },
+ { label: 'Introduction', translations: { 'zh-CN': '简介' }, slug: 'getting-started/introduction' },
+ { label: 'Installation', translations: { 'zh-CN': '安装' }, slug: 'getting-started/installation' },
+ { label: 'Quick Start', translations: { 'zh-CN': '快速上手' }, slug: 'getting-started/quick-start' },
],
},
{
label: 'Core Concepts',
+ translations: { 'zh-CN': '核心概念' },
items: [
- { label: 'ECS Architecture', slug: 'core-concepts/ecs' },
- { label: 'Components', slug: 'core-concepts/components' },
- { label: 'Systems', slug: 'core-concepts/systems' },
+ { label: 'ECS Architecture', translations: { 'zh-CN': 'ECS 架构' }, slug: 'core-concepts/ecs' },
+ { label: 'Components', translations: { 'zh-CN': '组件' }, slug: 'core-concepts/components' },
+ { label: 'Systems', translations: { 'zh-CN': '系统' }, slug: 'core-concepts/systems' },
],
},
{
label: 'Reference',
+ translations: { 'zh-CN': '参考' },
items: [
{ label: 'C++ API (Doxygen)', link: '/docs/api/html/', attrs: { target: '_blank' } },
{ label: 'Architecture', link: 'https://github.com/esengine/estella/blob/master/docs/ARCHITECTURE.md' },
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx
new file mode 100644
index 000000000..d11121f1a
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx
@@ -0,0 +1,40 @@
+---
+title: 组件
+description: 用 defineComponent 声明和使用组件。
+---
+
+**组件**是挂在实体上的一小块纯数据结构。用 `defineComponent` 声明一个组件,给它一个
+名字和默认值:
+
+```typescript
+import { defineComponent } from 'esengine';
+
+const Speed = defineComponent('Speed', { value: 200 });
+const Health = defineComponent('Health', { current: 100, max: 100 });
+```
+
+默认值同时定义了组件的形状(字段与类型)和新实例的初始值。组件是纯数据——没有方法、
+没有行为。行为存在于[系统](/docs/zh-cn/core-concepts/systems/)里。
+
+## 内置组件
+
+SDK 自带一批引擎组件,你可以和自己的组件一起查询,例如:
+
+- `LocalTransform` —— 位置、旋转与缩放。
+- `Sprite` —— 一个带贴图的四边形。
+- `Camera` —— 观察世界的视图。
+
+## 读取与写入
+
+系统通过查询拿到组件数据。当系统要写入某个组件时,把它包进 `Mut(...)`,这样变更检测
+和渲染器就知道这块数据被改动过:
+
+```typescript
+Query(Mut(LocalTransform), Speed)
+// LocalTransform 会被写入;Speed 只读
+```
+
+<br />
+
+在底层,一个组件是带 `ES_COMPONENT` / `ES_PROPERTY` 注解的 C++ 结构体;跨边界的内存
+布局是生成的,因此 TypeScript 组件与 C++ 结构体始终保持一致。
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx
new file mode 100644
index 000000000..8f8e6d8f1
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx
@@ -0,0 +1,37 @@
+---
+title: ECS 架构
+description: Estella 中的实体、组件与系统。
+---
+
+Estella 构建在 **Entity-Component-System**(ECS,实体-组件-系统)架构之上。
+它不用层层继承的类,而是把游戏状态放进纯数据的组件里,把行为放进遍历这些数据的
+系统里。
+
+- **实体(Entity)** —— 一个标识符。它不持有数据、也不含行为,只是组件挂载的句柄。
+- **组件(Component)** —— 一小块纯数据结构(位置、速度、精灵)。一个实体由它拥有
+ 哪些组件来定义。
+- **系统(System)** —— 每帧运行的函数,遍历所有匹配某个查询的实体,读写它们的组件。
+
+## 为什么要数据导向
+
+组件存放在单一、缓存友好的存储层(稀疏集,sparse set)里,因此一个系统遍历
+「所有同时拥有 `LocalTransform` 与 `Speed` 的实体」时走的是连续内存。存储位于
+C++/WebAssembly 内核中,SDK 通过一份生成并经哈希校验的内存布局**零拷贝**读取它——
+于是同一个组件的 TypeScript 视图与 C++ 视图永远不会悄悄地对不上。
+
+## 你编写的界面
+
+你用三个 SDK 原语组装一个游戏:
+
+- [`defineComponent`](/docs/zh-cn/core-concepts/components/) —— 声明一个组件类型。
+- [`defineSystem`](/docs/zh-cn/core-concepts/systems/) —— 声明一个系统及其查询。
+- `App` / 插件 —— 把系统、资源与各子系统(物理、Spine、瓦片地图、UI、音频、场景)
+ 组装成一个运行中的游戏。
+
+```typescript
+import { App } from 'esengine';
+
+const app = new App();
+// 在 app 上注册组件、系统与插件……
+app.run();
+```
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
new file mode 100644
index 000000000..e54512474
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
@@ -0,0 +1,47 @@
+---
+title: 系统
+description: 用 defineSystem、Query、Res 和 Mut 声明系统。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**系统**是每帧运行的函数。你声明它需要什么——一个组件查询,加上资源和事件——
+Estella 就会在调度中用恰好这些参数调用它。
+
+```typescript
+import {
+ defineComponent, defineSystem, addSystem,
+ Query, Mut, Res, Time, LocalTransform
+} from 'esengine';
+
+const Speed = defineComponent('Speed', { value: 200 });
+
+addSystem(defineSystem(
+ [Res(Time), Query(Mut(LocalTransform), Speed)],
+ (time, query) => {
+ for (const [entity, transform, speed] of query) {
+ transform.position.x += speed.value * time.delta;
+ }
+ }
+));
+```
+
+## 参数
+
+系统的第一个参数是它的**参数列表**——它将按顺序收到的数据:
+
+- **`Query(...)`** —— 遍历同时拥有列出的每个组件的实体。每次迭代产出
+ `[entity, ...组件]`。
+- **`Mut(Component)`** —— 系统会写入的组件。未包裹的组件是只读的。
+- **`Res(Resource)`** —— 一个共享资源,例如提供帧计时的 `Time`。
+
+<Aside type="caution">
+ 只有当你确实要写入某个组件时才把它包进 `Mut`。只读查询让引擎可以跳过多余的变更
+ 检测,也让更多系统能并行运行。
+</Aside>
+
+## 运行顺序
+
+系统由**调度(schedule)**组织。用 `addSystem` 注册一个系统,或通过 `App` 上的插件
+加入它。场景系统只在其所属场景处于激活状态时运行,因此多个场景可以共存于同一个世界
+而互不干扰。
diff --git a/docs/astro/src/content/docs/zh-cn/getting-started/installation.mdx b/docs/astro/src/content/docs/zh-cn/getting-started/installation.mdx
new file mode 100644
index 000000000..581560f6a
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/getting-started/installation.mdx
@@ -0,0 +1,61 @@
+---
+title: 安装
+description: 安装 Estella 编辑器,或从源码构建引擎。
+---
+
+import { Tabs, TabItem, Steps, Aside } from '@astrojs/starlight/components';
+
+<Tabs>
+ <TabItem label="使用编辑器">
+ <Steps>
+
+ 1. 从[发布页](https://github.com/esengine/estella/releases)下载最新版编辑器。
+
+ 2. 安装并打开,点击 **New Project**(新建项目)。
+
+ 3. 填写项目名称与位置,点击 **Create**(创建)。编辑器会打开一个带有相机实体的
+ 默认场景。
+
+ </Steps>
+
+ <Aside type="note">
+ 安装包目前尚未签名,因此首次启动时 Windows SmartScreen 或 macOS Gatekeeper
+ 可能提示「未知开发者」——请选择**仍要运行**,或在**系统设置 → 隐私与安全性**中
+ 放行。
+ </Aside>
+ </TabItem>
+
+ <TabItem label="从源码构建">
+ 环境要求:
+
+ - **Node.js** ≥ 18 与 **pnpm** ≥ 8
+ - **Emscripten** 5.0.0(需精确版本,与 CI 对齐)
+
+ <Steps>
+
+ 1. 克隆并安装依赖:
+
+ ```bash
+ git clone https://github.com/esengine/estella.git
+ cd estella
+ pnpm install
+ ```
+
+ 2. 构建引擎、SDK 并同步到编辑器:
+
+ ```bash
+ node build-tools/cli.js build -t all
+ ```
+
+ 3. 运行编辑器:
+
+ ```bash
+ cd desktop && pnpm dev
+ ```
+
+ </Steps>
+
+ 完整构建说明见
+ [CONTRIBUTING.md](https://github.com/esengine/estella/blob/master/CONTRIBUTING.md)。
+ </TabItem>
+</Tabs>
diff --git a/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx
new file mode 100644
index 000000000..3a4d9cbe4
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx
@@ -0,0 +1,34 @@
+---
+title: 简介
+description: Estella 是什么,以及它为什么存在。
+---
+
+Estella 是一个 **2D 游戏引擎**:上层是 TypeScript SDK,底层由高性能的
+**C++/WebAssembly** 内核驱动。它自带一个用于场景编辑与项目管理的可视化编辑器,
+产出的游戏可运行在 **Web 浏览器**与**微信小游戏**中。
+
+## 为什么选择 Estella?
+
+- **快** —— C++ 渲染管线编译为 WebAssembly,而非解释执行的 JavaScript。
+- **类型安全** —— 一流的 TypeScript SDK,提供 `defineSystem`、`defineComponent`、
+ `Query`。
+- **数据导向** —— Entity-Component-System 架构,游戏逻辑可规模化扩展。
+- **可视化编辑器** —— 场景层级、检视面板、资源浏览器,无需手写 JSON。
+- **跨平台** —— 一套代码,发布到 Web 浏览器与微信小游戏。
+- **Spine 与物理** —— 内置 Spine 骨骼动画与物理支持。
+
+## 各层如何协作
+
+| 层 | 职责 |
+|----|------|
+| **TypeScript SDK**(`esengine`) | 你编写的界面:`App`、`World`、系统、组件、查询、插件。 |
+| **WasmBridge** | SDK 与引擎之间的唯一边界,内存布局由生成器产出并经哈希校验。 |
+| **C++ / WebAssembly** | 引擎内核:ECS 存储、渲染器(`GfxDevice`)、资源、粒子、瓦片地图、文本。 |
+
+完整架构见
+[`ARCHITECTURE.md`](https://github.com/esengine/estella/blob/master/docs/ARCHITECTURE.md)。
+
+## 下一步
+
+- [安装](/docs/zh-cn/getting-started/installation/) —— 获取编辑器或从源码构建。
+- [快速上手](/docs/zh-cn/getting-started/quick-start/) —— 创建项目并写下你的第一个系统。
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
new file mode 100644
index 000000000..642c7d950
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/getting-started/quick-start.mdx
@@ -0,0 +1,47 @@
+---
+title: 快速上手
+description: 创建项目并写下你的第一个系统。
+---
+
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+下面走一遍「让一个实体动起来」:在编辑器里把它加进场景,再用一段 TypeScript
+系统驱动它。
+
+<Steps>
+
+1. **创建项目。** 在编辑器中点击 **New Project**,命名后点击 **Create**。你会得到
+ 一个带相机实体的默认场景。
+
+2. **添加实体。** 在场景层级里新建一个实体,在检视面板中给它加上 `Sprite` 与
+ `LocalTransform` 组件。
+
+3. **编写系统。** 在项目的脚本里新建一个 TypeScript 文件,注册一个系统,让所有带
+ `Speed` 组件的实体移动:
+
+ ```typescript
+ import {
+ defineComponent, defineSystem, addSystem,
+ Query, Mut, Res, Time, LocalTransform
+ } from 'esengine';
+
+ const Speed = defineComponent('Speed', { value: 200 });
+
+ addSystem(defineSystem(
+ [Res(Time), Query(Mut(LocalTransform), Speed)],
+ (time, query) => {
+ for (const [entity, transform, speed] of query) {
+ transform.position.x += speed.value * time.delta;
+ }
+ }
+ ));
+ ```
+
+4. **预览。** 给实体加上 `Speed` 组件,然后按 **F5** 运行场景,精灵就会移动。
+
+</Steps>
+
+<Aside type="tip">
+ `Res(Time)` 提供帧计时,`Query(...)` 遍历同时拥有列出的每个组件的实体,`Mut(...)`
+ 标记一个你打算写入的组件。完整的查询词汇见[系统](/docs/zh-cn/core-concepts/systems/)。
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/index.mdx b/docs/astro/src/content/docs/zh-cn/index.mdx
new file mode 100644
index 000000000..0ef2b8844
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/index.mdx
@@ -0,0 +1,33 @@
+---
+title: Estella
+description: 由 WebAssembly 与 ECS 驱动的高性能 2D 游戏引擎。
+template: splash
+hero:
+ tagline: 一个搭配 TypeScript SDK、由 C++/WebAssembly 内核驱动的 2D 游戏引擎。一次开发,发布到 Web 与微信小游戏。
+ actions:
+ - text: 快速开始
+ link: /docs/zh-cn/getting-started/introduction/
+ icon: right-arrow
+ - text: 在 GitHub 查看
+ link: https://github.com/esengine/estella
+ icon: external
+ variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+<CardGrid stagger>
+ <Card title="快" icon="rocket">
+ C++ 渲染管线编译为 WebAssembly,而不是解释执行的 JavaScript。
+ </Card>
+ <Card title="类型安全" icon="seti:typescript">
+ 一流的 TypeScript SDK:`defineComponent`、`defineSystem`、`Query`、
+ `Commands`、`Res`。
+ </Card>
+ <Card title="数据导向" icon="puzzle">
+ Entity-Component-System 内核,单一且缓存友好的组件存储层。
+ </Card>
+ <Card title="跨平台" icon="laptop">
+ 一套代码,发布到 Web 浏览器与微信小游戏。
+ </Card>
+</CardGrid>