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: unify branding, fix stale facts, restructure docs index

yhh92b1ea84edcc
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5a5d472e8..8251e508d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,15 +8,14 @@ Thank you for your interest in contributing to Estella! This guide will help you
- **Node.js** >= 18
- **pnpm** >= 8
-- **Emscripten** 3.1.51 (for C++/WASM builds, exact version required for CI compatibility)
-- **Rust** >= 1.75 (for Tauri editor)
+- **Emscripten** 5.0.0 (for C++/WASM builds, exact version required for CI compatibility)
- **ccache** (optional, recommended for faster C++ rebuilds)
### Setup
```bash
git clone https://github.com/esengine/estella.git
-cd microes
+cd estella
```
### Optional: Install ccache for Faster Builds
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index aa42cc0d3..63701b8d3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,7 +1,7 @@
-# ESEngine Architecture
+# Estella Architecture
-This document describes the architecture and design decisions of the Estella /
-ESEngine 2D game engine. It is **descriptive of the current code**. For the
+This document describes the architecture and design decisions of the Estella 2D
+game engine. It is **descriptive of the current code**. For the
*target* architecture, the root-cause rationale behind the current design, and
the forward roadmap, see the architecture-of-record companions:
diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index d6a3c3b0a..d97c4d94e 100644
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -1,6 +1,6 @@
-# ESEngine Coding Style Guide
+# Estella Coding Style Guide
-This document describes the coding conventions used in the ESEngine project.
+This document describes the coding conventions used in the Estella project.
## Naming Conventions
diff --git a/docs/Doxyfile b/docs/Doxyfile
index 4ae460d21..f82684936 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -1,13 +1,13 @@
-# Doxyfile for ESEngine
+# Doxyfile for Estella
# Documentation: https://www.doxygen.nl/manual/config.html
#---------------------------------------------------------------------------
# Project Configuration
#---------------------------------------------------------------------------
-PROJECT_NAME = "ESEngine"
+PROJECT_NAME = "Estella"
PROJECT_NUMBER = "0.1.0"
-PROJECT_BRIEF = "A lightweight C++17 game engine for WebAssembly"
+PROJECT_BRIEF = "A fast 2D game engine powered by WebAssembly and ECS"
PROJECT_LOGO =
OUTPUT_DIRECTORY = ./api
diff --git a/docs/README.md b/docs/README.md
index 083373200..7751f8388 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,180 +1,54 @@
-# ESEngine Documentation
+# Estella Documentation
-This directory contains the documentation system for ESEngine, built with **Astro Starlight** and **Doxygen**.
+A map of the docs in this folder — start here. Estella's documentation lives in
+three layers: the developer-facing guides below, the generated C++ API reference
+(Doxygen), and the published site at
+[estellaengine.com/docs](https://estellaengine.com/docs).
-## Structure
+## In this folder (`docs/`)
-```
-docs/
-├── astro/ # Astro Starlight documentation site
-│ ├── src/content/ # MDX documentation files
-│ ├── src/assets/ # Images and assets
-│ └── package.json # Node dependencies
-├── api/ # Doxygen output (generated)
-├── Doxyfile # Doxygen configuration
-├── build.sh # Build script (Linux/macOS)
-├── build.ps1 # Build script (Windows)
-└── dist/ # Final merged output (generated)
-```
+### Architecture & design
-## Prerequisites
+| Document | What it is | Language |
+|---|---|---|
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | The engine's architecture **as it exists today** — modules, data flow, the WASM boundary. | English |
+| [REARCHITECTURE.md](./REARCHITECTURE.md) | Architecture-of-record: the root-cause re-architecture plan (RC1–RC6, F1–F4) and the *target* design. | 中文 |
+| `REARCH_2D_PARITY.md` | Architecture-of-record: the 2D feature-parity & modernization roadmap. *Local only — gitignored.* | 中文 |
-- **Node.js** 18+ (for Astro)
-- **Doxygen** (for API docs)
+### Conventions
-### Installing Doxygen
+| Document | What it is | Language |
+|---|---|---|
+| [CODING_STYLE.md](./CODING_STYLE.md) | C++ and TypeScript naming & formatting rules. | English |
+| [CODE_COMMENTS.md](./CODE_COMMENTS.md) | The comment convention all source code follows (explain *why*, not *what*; English-only comments). | 中文 |
-**Windows:**
-```powershell
-choco install doxygen.install
-# or download from https://www.doxygen.nl/download.html
-```
+### Building & publishing
-**macOS:**
-```bash
-brew install doxygen
-```
+| Document | What it is |
+|---|---|
+| [SITE.md](./SITE.md) | How to build and publish the documentation site (Astro Starlight + Doxygen). |
+| [Doxyfile](./Doxyfile) | Doxygen config; the C++ API reference is generated from `@file`/`@brief` headers in the source. |
-**Linux:**
-```bash
-sudo apt install doxygen # Debian/Ubuntu
-sudo dnf install doxygen # Fedora
-```
+## Language policy
-## Quick Start
+Documentation language follows the **audience**, not the author:
-### Development (Hot Reload)
+- **English** — anything a user or external contributor reads: the root
+ [README](../README.md), [CONTRIBUTING](../CONTRIBUTING.md), `ARCHITECTURE.md`,
+ `CODING_STYLE.md`, and all governance docs.
+- **中文** — internal architecture-of-record and roadmap documents written for
+ maintainers: `REARCHITECTURE.md`, `REARCH_2D_PARITY.md`, and the comment
+ convention itself.
+- **Code comments (TypeScript / C++) are always English** —
+ [CODE_COMMENTS.md](./CODE_COMMENTS.md) is the authoritative rule.
-```bash
-# Windows
-.\build.ps1 dev
+## Elsewhere in the repo
-# Linux/macOS
-./build.sh dev
-```
-
-Opens http://localhost:4321 with live reload.
-
-### Full Build
-
-```bash
-# Windows
-.\build.ps1 build
-
-# Linux/macOS
-./build.sh build
-```
-
-This will:
-1. Build Doxygen API documentation → `docs/api/`
-2. Build Astro site → `docs/astro/dist/`
-3. Merge everything → `docs/dist/`
-
-## Writing Documentation
-
-### Adding a New Guide
-
-1. Create a new `.mdx` file in `astro/src/content/docs/guides/`
-2. Add frontmatter:
- ```mdx
- ---
- title: My Guide
- description: A brief description
- ---
-
- Your content here...
- ```
-3. Add to sidebar in `astro/astro.config.mjs`
-
-### Available Components
-
-Starlight provides several built-in components:
-
-```mdx
-import { Tabs, TabItem, Card, CardGrid, Aside, Steps } from '@astrojs/starlight/components';
-
-<Aside type="tip">
- Helpful tip here
-</Aside>
-
-<Tabs>
- <TabItem label="Tab 1">Content 1</TabItem>
- <TabItem label="Tab 2">Content 2</TabItem>
-</Tabs>
-
-<Steps>
-1. First step
-2. Second step
-</Steps>
-```
-
-### Code Blocks
-
-````mdx
-```cpp title="example.cpp" {3-5}
-int main() {
- // This line is highlighted
- Application app;
- app.run();
- return 0;
-}
-```
-````
-
-## Deployment
-
-### GitHub Actions (Automatic)
-
-Documentation is automatically built and deployed when:
-- Changes are pushed to `master` branch in `docs/`, `src/**/*.hpp`, or `include/**/*.hpp`
-- Workflow is manually triggered
-
-**Setup GitHub Pages:**
-1. Go to repository Settings → Pages
-2. Set Source to "GitHub Actions"
-3. Push changes to trigger deployment
-
-The workflow (`.github/workflows/docs.yml`) will:
-1. Build Doxygen API documentation
-2. Build Astro site
-3. Merge and deploy to GitHub Pages
-
-### Manual Deployment
-
-Build locally and deploy anywhere:
-
-```bash
-./build.sh build # or .\build.ps1 build on Windows
-```
-
-Copy `docs/dist/` to any static hosting:
-- Vercel
-- Netlify
-- Cloudflare Pages
-- Any web server
-
-## Updating API Docs
-
-API documentation is automatically generated from source code comments. To update:
-
-1. Add/update Doxygen comments in source files
-2. Run `./build.sh doxygen`
-
-### Doxygen Comment Format
-
-```cpp
-/**
- * @brief Brief description
- * @details Longer description with more details.
- *
- * @param paramName Description of parameter
- * @return Description of return value
- *
- * @code
- * // Example usage
- * MyClass obj;
- * obj.method();
- * @endcode
- */
-void MyClass::method(int paramName);
-```
+- **Governance (root):** [README](../README.md) · [CONTRIBUTING](../CONTRIBUTING.md) ·
+ [CHANGELOG](../CHANGELOG.md) · [VERSIONING](../VERSIONING.md) ·
+ [SECURITY](../SECURITY.md) · [CODE_OF_CONDUCT](../CODE_OF_CONDUCT.md) ·
+ [BUSINESS_MODEL](../BUSINESS_MODEL.md) · [PROVENANCE](../PROVENANCE.md) ·
+ [LICENSE](../LICENSE) · [NOTICE](../NOTICE)
+- **Subsystem docs:** [`sdk/src/ui/ARCHITECTURE.md`](../sdk/src/ui/ARCHITECTURE.md)
+ (UI layer) · [`sdk/tests/README.md`](../sdk/tests/README.md) (SDK tests) ·
+ [`desktop/README.md`](../desktop/README.md) (editor)
diff --git a/docs/SITE.md b/docs/SITE.md
new file mode 100644
index 000000000..0ca05f347
--- /dev/null
+++ b/docs/SITE.md
@@ -0,0 +1,187 @@
+# Building the Estella Docs Site
+
+The published documentation site ([estellaengine.com/docs](https://estellaengine.com/docs))
+is built with **Astro Starlight** (guides) and **Doxygen** (C++ API reference),
+merged into a single static bundle.
+
+> 🚧 **Status:** the site sources (`docs/astro/`, `docs/landing/`) are being
+> restored into this repository. The `docs.yml` workflow and the `build.sh` /
+> `build.ps1` scripts below reference those directories and only work once the
+> sources land. Until then this document describes the **target** build and
+> publish flow.
+
+## Structure
+
+```
+docs/
+├── astro/ # Astro Starlight documentation site
+│ ├── src/content/ # MDX documentation files
+│ ├── src/assets/ # Images and assets
+│ └── package.json # Node dependencies
+├── landing/ # Landing page + static site assets
+├── api/ # Doxygen output (generated)
+├── Doxyfile # Doxygen configuration
+├── build.sh # Build script (Linux/macOS)
+├── build.ps1 # Build script (Windows)
+└── dist/ # Final merged output (generated)
+```
+
+## Prerequisites
+
+- **Node.js** 18+ (for Astro)
+- **Doxygen** (for API docs)
+
+### Installing Doxygen
+
+**Windows:**
+```powershell
+choco install doxygen.install
+# or download from https://www.doxygen.nl/download.html
+```
+
+**macOS:**
+```bash
+brew install doxygen
+```
+
+**Linux:**
+```bash
+sudo apt install doxygen # Debian/Ubuntu
+sudo dnf install doxygen # Fedora
+```
+
+## Quick Start
+
+### Development (Hot Reload)
+
+```bash
+# Windows
+.\build.ps1 dev
+
+# Linux/macOS
+./build.sh dev
+```
+
+Opens http://localhost:4321 with live reload.
+
+### Full Build
+
+```bash
+# Windows
+.\build.ps1 build
+
+# Linux/macOS
+./build.sh build
+```
+
+This will:
+1. Build Doxygen API documentation → `docs/api/`
+2. Build Astro site → `docs/astro/dist/`
+3. Merge everything → `docs/dist/`
+
+## Writing Documentation
+
+### Adding a New Guide
+
+1. Create a new `.mdx` file in `astro/src/content/docs/guides/`
+2. Add frontmatter:
+ ```mdx
+ ---
+ title: My Guide
+ description: A brief description
+ ---
+
+ Your content here...
+ ```
+3. Add to sidebar in `astro/astro.config.mjs`
+
+### Available Components
+
+Starlight provides several built-in components:
+
+```mdx
+import { Tabs, TabItem, Card, CardGrid, Aside, Steps } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+ Helpful tip here
+</Aside>
+
+<Tabs>
+ <TabItem label="Tab 1">Content 1</TabItem>
+ <TabItem label="Tab 2">Content 2</TabItem>
+</Tabs>
+
+<Steps>
+1. First step
+2. Second step
+</Steps>
+```
+
+### Code Blocks
+
+````mdx
+```cpp title="example.cpp" {3-5}
+int main() {
+ // This line is highlighted
+ Application app;
+ app.run();
+ return 0;
+}
+```
+````
+
+## Deployment
+
+### GitHub Actions (Automatic)
+
+The site is built and deployed by `.github/workflows/docs.yml` when a `docs-v*`
+tag is pushed or the workflow is dispatched manually. The workflow:
+
+1. Builds Doxygen API documentation
+2. Builds the Astro site
+3. Merges and deploys to GitHub Pages
+
+**Setting up GitHub Pages:**
+1. Go to repository Settings → Pages
+2. Set Source to "GitHub Actions"
+3. Push a `docs-v*` tag (or run the workflow manually) to trigger deployment
+
+### Manual Deployment
+
+Build locally and deploy anywhere:
+
+```bash
+./build.sh build # or .\build.ps1 build on Windows
+```
+
+Copy `docs/dist/` to any static host:
+- Vercel
+- Netlify
+- Cloudflare Pages
+- Any web server
+
+## Updating API Docs
+
+API documentation is generated from source-code comments. To update:
+
+1. Add or update Doxygen comments in the source (see [CODE_COMMENTS.md](./CODE_COMMENTS.md))
+2. Run `./build.sh doxygen`
+
+### Doxygen Comment Format
+
+```cpp
+/**
+ * @brief Brief description
+ * @details Longer description with more details.
+ *
+ * @param paramName Description of parameter
+ * @return Description of return value
+ *
+ * @code
+ * // Example usage
+ * MyClass obj;
+ * obj.method();
+ * @endcode
+ */
+void MyClass::method(int paramName);
+```
diff --git a/docs/build.ps1 b/docs/build.ps1
index d761b9e7f..f227ab78a 100644
--- a/docs/build.ps1
+++ b/docs/build.ps1
@@ -1,4 +1,4 @@
-# ESEngine Documentation Build Script (Windows PowerShell)
+# Estella Documentation Build Script (Windows PowerShell)
# Usage: .\build.ps1 [dev|build|all]
param(
diff --git a/docs/build.sh b/docs/build.sh
index 584b1c0fa..672cc708c 100644
--- a/docs/build.sh
+++ b/docs/build.sh
@@ -1,5 +1,5 @@
#!/bin/bash
-# ESEngine Documentation Build Script (Linux/macOS)
+# Estella Documentation Build Script (Linux/macOS)
# Usage: ./build.sh [dev|build|all]
set -e
diff --git a/sdk/tests/README.md b/sdk/tests/README.md
index 757ed94e5..e9cc8a83e 100644
--- a/sdk/tests/README.md
+++ b/sdk/tests/README.md
@@ -1,4 +1,4 @@
-# ESEngine SDK Tests
+# Estella SDK Tests
## Running Tests