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: unify branding, fix stale facts, restructure docs index
yhh92b1ea84edcc
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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```bashgit clone https://github.com/esengine/estella.git-cd microes+cd estella```### Optional: Install ccache for Faster Buildsdiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 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, andthe forward roadmap, see the architecture-of-record companions:diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.mdindex 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 Conventionsdiff --git a/docs/Doxyfile b/docs/Doxyfileindex 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 = ./apidiff --git a/docs/README.md b/docs/README.mdindex 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.mdnew file mode 100644index 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.ps1index 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.shindex 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 -ediff --git a/sdk/tests/README.md b/sdk/tests/README.mdindex 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