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: add 简体中文 translation (Starlight i18n)
yhh037212ff56d6
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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>