diff --git a/Readme.en.md b/Readme.en.md index 43318e52..e6d11526 100644 --- a/Readme.en.md +++ b/Readme.en.md @@ -1,22 +1,27 @@ -EVEngine +# EVEngine + ======================= + Evolutionary Vision Engine [中文版](Readme.md) ## Documentation -- [Game developer docs](docs/usr/README.md): install, run, and project layout; [module handbook](docs/usr/MODULES.md) covers script APIs and examples one by one. -- [Engine developer docs](docs/dev/README.md): architecture, module design, testing strategy, and implementation notes. -- [C++ API reference (Doxygen)](docs/api/html/index.html): generated from `src/` and `docs/usr/` — run `make docs` after installing doxygen (config: [`docs/Doxyfile.in`](docs/Doxyfile.in)). +- [Game developer docs](docs/usr/README.md): download the engine, create and run a game, debug, and publish; the [module handbook](docs/usr/MODULES.md) covers the script APIs and examples one by one. +- [Online API reference (Doxygen)](https://evengine.github.io/EVEngine/): published continuously to GitHub Pages; includes the C++ API and the user manual. +- [Engine developer docs](docs/dev/README.md): for engine maintainers and contributors — architecture, module design, testing strategy, and implementation notes. -Many game engines are slow to iterate, hard to debug, and awkward for rapid prototyping. EVEngine aims to be a simple, practical engine focused on 2D and third-person 3D gameplay components—not a full-featured 3D scene-management suite. +> **For game developers:** you do **not** need to compile EVEngine. Download the prebuilt SDK for your platform from the [official release page](https://github.com/EVEngine/EVEngine/releases), unzip it, and start creating — no Git, CMake, C++ compiler, or Vulkan SDK required. Only developers who want to modify the engine itself need to read "Building from source" below. +## Introduction + +Many game engines are slow to iterate, hard to debug, and awkward for rapid prototyping. EVEngine is designed to be a simple, practical engine focused on 2D, third-person 3D, and mixed 2D/3D gameplay components — not a heavyweight 3D scene-management suite. Design goals: 1. A Love2D-style interpretive engine that loads scripts and data directly -2. Many high-performance C++ modules; you can compile other C++ libraries as shared libs and interact with them directly +2. Many high-performance C++ modules; you can compile your own C++ libraries as shared libs and interact with them directly 3. A full development stack: your logic can be edited with GUI tools; the editor runtime is the game runtime—only the shipping runtime strips DevTools (or you can keep them for player modding) 4. Built-in asset management and hot reload—no separate pipeline required 5. Class scanning with auto-generated editing GUIs @@ -25,7 +30,6 @@ Design goals: 8. Independent state-machine models for partial hot updates 9. Mixed 3D and 2D rendering - Built-in systems: 1. 2D tilemap — with an extensible map editor @@ -41,14 +45,79 @@ Built-in systems: 11. Sprite-stacking pseudo-3D 12. Real 3D model rendering +Build an RPG with minimal ceremony, with fast edit/debug for events, logic, and cutscene scripts — for example, hot-patch a function in a script and re-run it to preview the effect. +## Quick start (game developers: download, no build) -Build an RPG with minimal ceremony, with fast edit/debug for events, logic, and cutscene scripts—for example, hot-patch a function in a script and re-run it to preview the effect. +### 1. Download the engine from the official site +Go to the [EVEngine release page](https://github.com/EVEngine/EVEngine/releases), pick the latest stable release, and download the SDK archive for your target platform: -## Requirements +| Target platform | Download | Notes | +|-----------------|----------|-------| +| Windows | `eve-sdk-win32-.zip` | Windows 10/11 x64 | +| Linux | `eve-sdk-linux-.zip` | Ubuntu 20.04+ etc. (requires a Vulkan driver) | +| macOS | `eve-sdk-macosx-.zip` | macOS 12+ (Apple Silicon / Intel) | +| Android | `eve-sdk-android-.zip` | Assemble an arm64 APK on a dev machine | +| iOS | `eve-sdk-ios-.zip` | Assemble an arm64 .app on a macOS dev machine | -### Common dependencies +Unzipping gives you a self-contained SDK directory — no installation required. Windows example: + +```text +eve-sdk-win32/ +├── bin/eve.exe # engine runtime +├── lib/ # Windows: import lib for plugins; macOS: runtime dylibs +├── include/eve/ # native plugin headers (not needed for script-only games) +├── cmake/ # native plugin CMake support (not needed for script-only games) +├── platform/ # target-platform packaging template (e.g. Android APK project) +└── share/eve/ + ├── VERSION # engine version + ├── TARGET_PLATFORM # target platform marker + ├── examples/basic/ # runnable reference game + └── licenses/ # engine and third-party licenses +``` + +### 2. Run the bundled example to verify + +```sh +# Windows +bin\eve.exe run share\eve\examples\basic + +# macOS / Linux +bin/eve run share/eve/examples/basic +``` + +### 3. Create and run your first game + +```sh +bin\eve.exe create mygame # Windows (macOS / Linux: bin/eve create mygame) +bin\eve.exe run mygame +``` + +`eve create` generates a minimal game template: `config.nut` (window and dev options) and `main.nut` (game logic). Edit `main.nut`, save, and watch the hot reload in action. For game directory layout, lifecycle callbacks (`eve_init` / `eve_update` / `eve_render`), modules, debugging, and publishing, see the [user guide](docs/usr/README.md). + +### What you can do with the engine + +- **Make 2D / third-person 3D / mixed 2D+3D games**: 40+ modules — tilemap, cameras, Box2D/Box3D physics, particles, animation, RPG, inventory, UI, procedural generation, and more — all driven from Squirrel scripts. See the [module handbook](docs/usr/MODULES.md). +- **Hot reload for scripts and assets**: on desktop, edits take effect immediately; on mobile, push changes to the device with the `eve dev` dev server — no reinstall. +- **Debug**: pause the game loop, breakpoints, watches, snapshots; VS Code debug adapter and AI (MCP) assisted development. +- **Package and publish**: `eve zip` compresses a game into a `.eve` archive; `eve package --sdk ` produces a distributable folder containing the runtime and your game; Android/iOS use the SDK's bundled templates to assemble APK / .app. +- **Native extensions**: when you need C++ performance code, write a plugin dynamic library with the SDK's CMake package (see `examples/native-plugin`) — script-only users never need this. + +### What to keep in mind + +1. **The runtime needs a Vulkan driver, but not the Vulkan SDK**: rendering is Vulkan-based. Windows GPU drivers usually include the Vulkan runtime; macOS is covered by the bundled MoltenVK; Linux needs `mesa-vulkan-drivers` (AMD/Intel) or the vendor driver (NVIDIA). Installing Git, CMake, a compiler, or the LunarG SDK only matters for building from source. +2. **SDKs are per-platform and versions must match**: each SDK targets exactly one platform; native plugins must match the host platform and SDK version — mixing platforms or versions is not supported. +3. **Stable vs. development**: Releases and the `main` branch are the stable line; to try the latest features or modify the engine, build from source and develop on `dev`. +4. **License**: EVEngine uses a dual license — read the [license](#license) before use; commercial revenue above the free threshold requires a commercial license. + +## Building from source (engine developers / contributors) + +> The requirements and build steps below are only for developers who need to modify the engine source, contribute to engine development, or build the SDK themselves. Game developers should use the prebuilt version from "Quick start" above. + +### Requirements + +#### Common dependencies | Dependency | Version | Notes | |------------|---------|-------| @@ -59,7 +128,7 @@ Build an RPG with minimal ceremony, with fast edit/debug for events, logic, and Third-party libraries (SDL2, Box2D, Squirrel, Poco, ImGui, OpenAL Soft, FreeType, GLM, VKBuilder, etc.) are fetched and built automatically via CMake `ExternalProject` from [EVEngine/third-party](https://github.com/EVEngine/third-party). Manual installs are usually unnecessary. -### Windows +#### Windows | Component | Recommended | |-----------|-------------| @@ -71,7 +140,7 @@ Third-party libraries (SDL2, Box2D, Squirrel, Poco, ImGui, OpenAL Soft, FreeType > If you use Visual Studio 2022, change the generator in `Makefile` to `"Visual Studio 17 2022"`. -### Linux +#### Linux | Component | Recommended | |-----------|-------------| @@ -98,7 +167,7 @@ sudo apt install -y \ # Or install the full Vulkan SDK per LunarG docs (includes validation layers) ``` -### macOS +#### macOS | Component | Recommended | |-----------|-------------| @@ -119,7 +188,7 @@ ls "$VULKAN_SDK/lib/libvulkan.dylib" "$VULKAN_SDK/lib/libMoltenVK.dylib" `setup-env.sh` sets `VULKAN_SDK`, `VK_ICD_FILENAMES` (MoltenVK ICD), and related vars. On Apple hosts, CMake **requires** a successful `find_package(Vulkan)` and will not fall back to Windows `vulkan-1.lib`. -### Android (arm64-v8a Debug APK) +#### Android (arm64-v8a Debug APK) | Component | Recommended | |-----------|-------------| @@ -142,7 +211,7 @@ export PATH="$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME Write `platform/android/apk/local.properties` (**do not commit**): -``` +```text sdk.dir=/Users//Library/Android/sdk ``` @@ -174,7 +243,7 @@ make run/android-debug make log/android ``` -### iOS / iPadOS (arm64 device, min 13.0) +#### iOS / iPadOS (arm64 device, min 13.0) | Component | Recommended | |-----------|-------------| @@ -213,10 +282,10 @@ Troubleshooting: 1. **Signing**: Sign in via Xcode → Settings → Accounts with an Apple ID that has an Apple Development certificate; `security find-identity -v -p codesigning` should list it. Without `IOS_DEVELOPMENT_TEAM`, `make build/ios-debug` can still produce an unsigned `.app`, but it will not install on device. `No Account for Team "XXXX"` usually means you used a certificate ID instead of the Team ID (`OU` in the certificate subject). 2. **Device**: USB-connect the iPad, enable Developer Mode, trust the computer; `xcrun devicectl list devices` should show `connected`. If you see `no DDI`, open the device once in Xcode to install the Developer Disk Image. 3. **Dependencies**: Third-party builds use Ninja + `cmake/ios.toolchain.cmake` (SDL UIKit). On failure, clear `build/third-party/ios-debug` and `build/third-party-binary/ios-debug` and retry. -4. **MoltenVK**: Current LunarG xcframeworks may require iOS 14+; the device OS must meet that requirement (e.g. iPadOS 26 is fine). +4. **MoltenVK**: Current LunarG xcframeworks may require iOS 14+; the device OS must meet that requirement. 5. v1 does not cover simulator, App Store distribution, or multi-arch fat binaries. -### WSL (develop Windows and Linux together) +#### WSL (develop Windows and Linux together) Prefer **WSL2 (Ubuntu)** for Linux targets and Visual Studio on the Windows host for Win32. Keep the source on the Windows filesystem (e.g. `C:\Users\...\EVEngine`) and access it from WSL via `/mnt/c/...`. @@ -227,8 +296,7 @@ Notes: 3. Third-party outputs are per-platform (`build/third-party/win32`, `build/third-party/linux-debug`, etc.) and do not overwrite each other. 4. Building under `/mnt/c` can be slow; for speed, clone into the WSL native filesystem (e.g. `~/src/EVEngine`) and keep a separate Windows clone if needed. - -## Get the source +### Get the source ```sh git clone --recurse-submodules https://github.com/EVEngine/EVEngine @@ -237,12 +305,11 @@ cd EVEngine # git submodule update --init --recursive ``` -The default clone is `main` (latest release). Engine development happens on `dev`: `git checkout dev && git pull`. +The default clone is `main` (latest stable release). Engine development happens on `dev`: `git checkout dev && git pull`. The first CMake configure pulls `third-party` automatically; if the directory already exists with a `CMakeLists.txt`, the local copy is used. ECS uses submodule [`external/ECS.hpp`](https://github.com/sunxfancy/ECS.hpp); IK uses [`external/ik.hpp`](https://github.com/sunxfancy/ik.hpp). - -## Quick start (recommended: root Makefile) +### Quick build (recommended: root Makefile) The root `Makefile` wraps Debug / Release configure and build for Windows / Linux / macOS. With `make` available (Git Bash, WSL, Linux, macOS), from the repo root: @@ -285,10 +352,9 @@ Output layout: The main executable is usually `eve` (`eve.exe` on Windows; path depends on VS `Release` / `Debug` config subdirs). On Android, SDLActivity loads `libmain.so` (package `com.evengine.example`). +### Step-by-step build -## Step-by-step build - -### 1. Configure +#### 1. Configure Equivalent to the Makefile configure steps; you can also run manually. @@ -325,7 +391,7 @@ Optional CMake variables: | `BUILD_PLATFORM` | Auto from host | `win32` / `linux` / `macosx`, etc. | | `BUILD_TESTING` | `ON` | Build unit tests | -### 2. Build third-party (deps) +#### 2. Build third-party (deps) Third-party code builds via custom targets `deps` / `third-party`. After configure: @@ -342,7 +408,7 @@ cmake --build build/macosx-debug --target deps -j 32 The first third-party build takes a while. Outputs land in `build/third-party/[-debug]/` and `build/third-party-binary/[-debug]/`. Later incremental builds reuse installed results. -### 3. Build the engine +#### 3. Build the engine ```sh # Windows (multi-config: pass --config) @@ -360,8 +426,7 @@ cmake --build build/macosx-debug -j 32 Or use `make build/win32` / `make build/macosx-debug` etc. to configure and build in one step. - -## Unit tests +### Unit tests `BUILD_TESTING` is on by default. After building: @@ -376,8 +441,7 @@ make test/macosx Or run `unit_test` / `unit_test.exe` from the corresponding path directly. - -## Docker (optional) +### Docker (optional) The repo includes an Ubuntu 20.04 `Dockerfile` (`build-essential`, `cmake`, `clang-12`, etc.) for an isolated Linux build: @@ -388,8 +452,7 @@ docker run -it --rm --volume="$(pwd):/home/evengine/src" evengine /bin/bash Inside the container, configure and build with the Linux flow. You still need to supply Vulkan runtime/SDK yourself (the image does not ship a full Vulkan SDK). - -## FAQ +### FAQ 1. **CMake cannot find Vulkan** Confirm the Vulkan SDK is installed and `VULKAN_SDK` points at the right path; on macOS, `source ~/VulkanSDK//setup-env.sh` before configure. Open a new terminal, then re-run cmake. @@ -417,7 +480,7 @@ Inside the container, configure and build with the Linux flow. You still need to ## Project layout (brief) -``` +```text EVEngine/ ├── CMakeLists.txt # Root CMake: platform detect, third-party, subdirs ├── Makefile # Windows / Linux / macOS / Android / iOS shortcuts diff --git a/Readme.md b/Readme.md index 93c3e730..5bad713d 100644 --- a/Readme.md +++ b/Readme.md @@ -1,54 +1,123 @@ -EVEngine +# EVEngine + ======================= + Evolutionary Vision Engine [English](Readme.en.md) ## 文档导航 -- [游戏开发者文档](docs/usr/README.md)：安装、运行与项目结构；[模块使用手册](docs/usr/MODULES.md)逐个说明脚本 API 和示例。 -- [开发者文档](docs/dev/README.md)：架构、模块设计、测试策略与实施记录。 -- [C++ API 参考（Doxygen）](docs/api/html/index.html)：由 `src/` 与 `docs/usr/` 生成，安装 doxygen 后执行 `make docs` 即可（配置见 [`docs/Doxyfile.in`](docs/Doxyfile.in)）。 +- [游戏开发者文档](docs/usr/README.md)：下载引擎、创建并运行游戏、调试与打包发布；[模块使用手册](docs/usr/MODULES.md) 逐个说明脚本 API 和示例。 +- [在线 API 参考（Doxygen）](https://evengine.github.io/EVEngine/)：随 GitHub Pages 持续发布，包含 C++ API 与用户手册。 +- [开发者文档](docs/dev/README.md)：面向引擎维护者与贡献者，包含架构、模块设计、测试策略与实施记录。 -针对很多游戏引擎开发效率低，难以调试，难以动态快速实现游戏原型，我们这里设计一款非常简单好用的游戏引擎。主要提供对2d、第三人称3d的游戏组件功能，不提供复杂3d游戏引擎中的3d场景管理等功能 +> **给游戏开发者**：使用 EVEngine 做游戏**不需要编译引擎**。请直接到[官网发布页](https://github.com/EVEngine/EVEngine/releases)下载对应平台的预编译 SDK，解压即可开始创作——无需安装 Git、CMake、C++ 编译器或 Vulkan SDK。只有想修改引擎本身的开发者才需要阅读下文“从源码构建”。 +## 简介 + +针对很多游戏引擎开发效率低、难以调试、难以动态快速实现游戏原型的问题，我们设计了一款非常简单好用的游戏引擎。它主要提供 2D、第三人称 3D 与 2D/3D 混合的游戏组件能力，不提供复杂 3D 引擎中的场景管理等重量级功能。 设计思路： -1. 采用类似Love2D的解析式引擎，可以直接加载脚本和数据 -2. 内部有众多C++编写的高性能模块，你可以写其他C++库编译成动态链接库来和这些库直接交互 -3. 有完整的开发模块，你自己写的逻辑代码可以直接用GUI的编辑工具进行开发，同时，开发系统也是游戏的运行时，只有发布用的运行时是裁剪掉开发工具的（或者你也可以选择保留供玩家2次创作） -4. 无需进行资产管理，和hot reload，已经内置了此功能 -5. 可以扫描类，自动为其生成编辑用的GUI -6. 确保GUI可以即时根据脚本动态创建和同步 -7. 可以暂停游戏循环进行调试 -8. 有很多独立的状态机模型，可以实现局部热更新 -9. 支持3d与2d混合渲染 +1. 采用类似 Love2D 的解析式引擎，可以直接加载脚本和数据； +2. 内部有众多 C++ 编写的高性能模块，你还可以把自己的 C++ 库编译成动态链接库与这些模块直接交互； +3. 有完整的开发环境：自己写的逻辑可以直接用 GUI 工具编辑，且编辑器运行时就是游戏运行时——只有发布用的运行时才会裁剪开发工具（也可以选择保留，供玩家二次创作）； +4. 内置资产管理、热重载，无需额外管线； +5. 可扫描类并自动为其生成编辑用 GUI； +6. GUI 可以即时根据脚本动态创建和同步； +7. 可暂停游戏循环进行调试； +8. 拥有众多独立状态机模型，支持局部热更新； +9. 支持 3D 与 2D 混合渲染。 +内置系统： -内置模型： -1. 2d tilemap - 并且包含可扩展的地图编辑器 -2. 2d 摄像机 -3. 简单的数据库 -4. box2d / box3d 物理 -5. rpg框架 -6. 可扩展战斗模型组件 -7. 对话框及脚本 -8. avatar分层渲染 -9. 2d 流体引擎（`Physics.newFluid`；另含可交互布料 `newCloth`） -10. 粒子系统 -11. sprite-stacking的伪3d技术 -12. 真实3d模型渲染 +1. 2D tilemap——含可扩展的地图编辑器； +2. 2D 摄像机； +3. 简单的数据库； +4. Box2D / Box3D 物理； +5. RPG 框架； +6. 可扩展的战斗模型组件； +7. 对话框及脚本； +8. Avatar 分层渲染； +9. 2D 流体引擎（`Physics.newFluid`；另含可交互布料 `newCloth`）； +10. 粒子系统； +11. Sprite-stacking 伪 3D 技术； +12. 真实 3D 模型渲染。 +支持以最简单的方式实现一个 RPG 游戏，并提供对事件、逻辑、过场脚本等快速编辑调试的功能。例如你可以修改脚本中的某个函数并反复执行，实时观察效果（热更新）。 +## 快速开始（游戏开发者：下载即用，无需编译） -支持以最简单的方式实现一个rpg游戏，并提供对事件、逻辑、过场脚本等快速编辑调试的功能 -比如你可以设定一个脚本，对脚本中的一个函数进行热修改，并且反复执行观看效果 +### 1. 从官网下载引擎 +前往 [EVEngine 发布页](https://github.com/EVEngine/EVEngine/releases)，选择最新正式版，下载目标平台的 SDK 压缩包： -## 环境要求 +| 目标平台 | 下载文件 | 说明 | +|----------|----------|------| +| Windows | `eve-sdk-win32-<版本>.zip` | Windows 10/11 x64 | +| Linux | `eve-sdk-linux-<版本>.zip` | Ubuntu 20.04+ 等（需 Vulkan 驱动） | +| macOS | `eve-sdk-macosx-<版本>.zip` | macOS 12+（Apple Silicon / Intel） | +| Android | `eve-sdk-android-<版本>.zip` | 在开发机上组装 arm64 APK | +| iOS | `eve-sdk-ios-<版本>.zip` | 在 macOS 开发机上组装 arm64 .app | -### 通用依赖 +解压后即为一个独立的 SDK 目录，无需安装。以 Windows 为例： + +```text +eve-sdk-win32/ +├── bin/eve.exe # 引擎运行时 +├── lib/ # Windows：插件链接库；macOS：运行时动态库 +├── include/eve/ # 原生插件头文件（做纯脚本游戏用不到） +├── cmake/ # 原生插件 CMake 支持（做纯脚本游戏用不到） +├── platform/ # 目标平台打包模板（如 Android APK 工程） +└── share/eve/ + ├── VERSION # 引擎版本号 + ├── TARGET_PLATFORM # 目标平台标记 + ├── examples/basic/ # 可运行的参考游戏 + └── licenses/ # 引擎与第三方许可 +``` + +### 2. 运行内置示例，验证安装 + +```sh +# Windows +bin\eve.exe run share\eve\examples\basic + +# macOS / Linux +bin/eve run share/eve/examples/basic +``` + +### 3. 创建并运行你的第一个游戏 + +```sh +bin\eve.exe create mygame # Windows（macOS / Linux：bin/eve create mygame） +bin\eve.exe run mygame +``` + +`eve create` 会生成最小的游戏模板：`config.nut`（窗口与开发选项）和 `main.nut`（游戏逻辑）。修改 `main.nut` 后保存即可看到热重载效果。游戏目录结构、生命周期回调（`eve_init` / `eve_update` / `eve_render`）、模块用法、调试与发布，详见[用户指南](docs/usr/README.md)。 + +### 拿到引擎后，你可以做这些事 + +- **制作 2D / 第三人称 3D / 2D+3D 混合游戏**：Tilemap、摄像机、Box2D/Box3D 物理、粒子、动画、RPG、背包、UI、程序化生成等 40+ 模块，全部通过 Squirrel 脚本调用，逐个模块的手册见[模块使用手册](docs/usr/MODULES.md)。 +- **脚本与资源热重载**：桌面端改完脚本/贴图立即生效；移动端用 `eve dev` 开发服务器把改动推送到真机，无需重装应用。 +- **调试**：暂停游戏循环、断点、监视、快照，支持 VS Code 调试适配器与 AI（MCP）辅助开发。 +- **打包发布**：`eve zip` 把游戏压缩为 `.eve` 归档；`eve package --sdk ` 生成包含运行时与游戏的可分发目录；Android / iOS 用 SDK 自带模板组装 APK / .app。 +- **原生扩展**：需要 C++ 性能代码时，用 SDK 的 CMake 包编写插件动态库（见 `examples/native-plugin`），纯脚本用户完全不需要。 + +### 需要注意什么 + +1. **运行时需要 Vulkan 驱动，但不需要 Vulkan SDK**：引擎基于 Vulkan 渲染。Windows 的显卡驱动通常已自带 Vulkan 运行时；macOS 由 SDK 内置 MoltenVK 承担；Linux 需要安装 `mesa-vulkan-drivers`（AMD/Intel）或厂商驱动（NVIDIA）。安装 Git、CMake、编译器、LunarG SDK 只对“从源码构建”有意义。 +2. **SDK 按平台独立、版本需匹配**：每个 SDK 只面向一个目标平台；原生插件必须与宿主平台及 SDK 版本一致，不同平台/版本的 SDK 不能混用。 +3. **正式版与开发版**：Release 与 `main` 分支对应正式版；想尝鲜最新功能或修改引擎，请从源码构建，并基于 `dev` 分支开发。 +4. **许可**：EVEngine 采用双许可，请在使用前阅读[许可证](#许可证)；商用营收超过免费门槛后需要商业授权。 + +## 从源码构建（引擎开发者 / 贡献者） + +> 下面的环境要求与编译步骤只面向需要修改引擎源码、参与引擎开发或自行打包的开发者。普通游戏开发者请使用上方“快速开始”的预编译版本，无需阅读本节。 + +### 环境要求 + +#### 通用依赖 | 依赖 | 版本要求 | 说明 | |------|----------|------| @@ -59,7 +128,7 @@ Evolutionary Vision Engine 第三方库（SDL2、Box2D、Squirrel、Poco、ImGui、OpenAL Soft、FreeType、GLM、VKBuilder 等）由 CMake 的 `ExternalProject` 自动从 [EVEngine/third-party](https://github.com/EVEngine/third-party) 拉取并编译，一般无需手动安装。 -### Windows +#### Windows | 组件 | 推荐配置 | |------|----------| @@ -71,7 +140,7 @@ Evolutionary Vision Engine > 若使用 Visual Studio 2022，可将 `Makefile` 中的生成器改为 `"Visual Studio 17 2022"`。 -### Linux +#### Linux | 组件 | 推荐配置 | |------|----------| @@ -98,7 +167,7 @@ sudo apt install -y \ # 也可按 LunarG 官方文档安装完整 Vulkan SDK（含 validation layers） ``` -### macOS +#### macOS | 组件 | 推荐配置 | |------|----------| @@ -119,7 +188,7 @@ ls "$VULKAN_SDK/lib/libvulkan.dylib" "$VULKAN_SDK/lib/libMoltenVK.dylib" `setup-env.sh` 会设置 `VULKAN_SDK`、`VK_ICD_FILENAMES`（MoltenVK ICD）等。CMake 在 Apple 宿主上**要求**能 `find_package(Vulkan)` 成功，不会回退到 Windows 的 `vulkan-1.lib`。 -### Android（arm64-v8a Debug APK） +#### Android（arm64-v8a Debug APK） | 组件 | 推荐配置 | |------|----------| @@ -142,7 +211,7 @@ export PATH="$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME 在 `platform/android/apk/local.properties` 写入（**勿提交**）： -``` +```text sdk.dir=/Users//Library/Android/sdk ``` @@ -174,7 +243,7 @@ make run/android-debug make log/android ``` -### iOS / iPadOS（arm64 真机，最低 13.0） +#### iOS / iPadOS（arm64 真机，最低 13.0） | 组件 | 推荐配置 | |------|----------| @@ -200,7 +269,7 @@ make build/ios-debug 真机安装 / 运行 / 日志： ```sh -# 用 USB 连接 iPad，开启开发者模式与信任此电脑 +# 用 USB 连接 iPad，开启开发者模式并信任此电脑 make install/ios-debug make run/ios-debug make log/ios @@ -213,10 +282,10 @@ make log/ios 1. **签名**：本机需在 Xcode → Settings → Accounts 登录 Apple ID，并有可用的 Apple Development 证书；`security find-identity -v -p codesigning` 应能看到证书。未设置 `IOS_DEVELOPMENT_TEAM` 时 `make build/ios-debug` 仍可产出未签名 `.app`，但无法安装到真机。若报 `No Account for Team "XXXX"`，说明用的是证书 ID 而非 Team ID（Team ID 是证书主题里的 `OU`）。 2. **设备**：USB 连接 iPad，开启开发者模式并信任此电脑；`xcrun devicectl list devices` 应显示 `connected`。若提示 `no DDI`，先用 Xcode 打开一次设备窗口以安装 Developer Disk Image。 3. **依赖**：第三方用 Ninja + `cmake/ios.toolchain.cmake` 交叉编译（SDL UIKit）；失败时可清 `build/third-party/ios-debug` 与 `build/third-party-binary/ios-debug` 后重跑。 -4. **MoltenVK**：当前 LunarG xcframework 可能按 iOS 14+ 构建；真机系统需满足该要求（本机 iPadOS 26 无妨）。 +4. **MoltenVK**：当前 LunarG xcframework 可能按 iOS 14+ 构建；真机系统需满足该要求。 5. 首版不做模拟器、App Store 分发与多架构 fat binary。 -### WSL（同时开发 Windows / Linux） +#### WSL（同时开发 Windows / Linux） 推荐在 **WSL2（Ubuntu）** 中开发 Linux 目标，在 Windows 主机侧用 Visual Studio 编译 Win32 目标。源码放在 Windows 文件系统（例如 `C:\Users\...\EVEngine`），通过 `/mnt/c/...` 挂载到 WSL。 @@ -227,8 +296,7 @@ make log/ios 3. 第三方产物按平台分目录存放（如 `build/third-party/win32`、`build/third-party/linux-debug`），互不覆盖。 4. 若在 WSL 里编译位于 `/mnt/c` 的源码，I/O 可能较慢；追求速度可将仓库 clone 到 WSL 原生文件系统（如 `~/src/EVEngine`），Windows 侧再单独 clone 一份。 - -## 获取源码 +### 获取源码 ```sh git clone --recurse-submodules https://github.com/EVEngine/EVEngine @@ -241,8 +309,7 @@ cd EVEngine 首次 CMake 配置时会自动拉取 `third-party`；若目录已存在且含 `CMakeLists.txt`，则直接使用本地副本。ECS 使用子模块 [`external/ECS.hpp`](https://github.com/sunxfancy/ECS.hpp)；IK 使用子模块 [`external/ik.hpp`](https://github.com/sunxfancy/ik.hpp)。 - -## 快速开始（推荐：根目录 Makefile） +### 快速构建（推荐：根目录 Makefile） 仓库根目录的 `Makefile` 封装了 Windows / Linux / macOS 的 Debug / Release 配置与编译。在已安装 `make` 的环境中（Git Bash、WSL、Linux、macOS）于仓库根目录执行： @@ -285,10 +352,9 @@ make log/android 主程序可执行文件名一般为 `eve`（Windows 下为 `eve.exe`，路径随 VS 的 `Release` / `Debug` 配置子目录变化）。Android 为 SDLActivity 加载的 `libmain.so`（包名 `com.evengine.example`）。 +### 分步编译说明 -## 分步编译说明 - -### 1. 配置（Configure） +#### 1. 配置（Configure） 等价于 Makefile 中的配置步骤，也可手动执行。 @@ -325,7 +391,7 @@ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DBUILD_PLATFORM=macosx -B bu | `BUILD_PLATFORM` | 按宿主自动选择 | `win32` / `linux` / `macosx` 等 | | `BUILD_TESTING` | `ON` | 是否编译单元测试 | -### 2. 编译第三方依赖（deps） +#### 2. 编译第三方依赖（deps） 第三方通过自定义目标 `deps` / `third-party` 构建。配置完成后： @@ -342,7 +408,7 @@ cmake --build build/macosx-debug --target deps -j 32 首次编译第三方耗时较长，产物位于 `build/third-party/<平台>[-debug]/` 与 `build/third-party-binary/<平台>[-debug]/`。之后增量构建会复用已安装结果。 -### 3. 编译引擎本体 +#### 3. 编译引擎本体 ```sh # Windows（需指定 --config，因为是多配置生成器） @@ -360,28 +426,7 @@ cmake --build build/macosx-debug -j 32 也可直接用前文的 `make build/win32` / `make build/macosx-debug` 等目标一步完成配置 + 编译。 - -## 资源脚本全平台热更新（`eve dev`） - -开发调试时，改完脚本 / 资源想立刻看到效果： - -- **桌面（macOS / Windows / Linux）**：`eve run <游戏目录>` 默认开启本地 watcher（`config.hotReload`），改 `main.nut` / JSON / 贴图后自动 `dofile` 或重载资源。 -- **移动端（iOS / Android）**：应用包内资源只读，无法直接改设备文件。改在**开发机**上编辑，由设备拉取： - -```sh -# 1. 开发机上启动开发服务器（服务当前游戏目录） -eve dev --port 8765 - -# 2. 设备端 config.nut 配置开发机地址（或命令行注入） -config.devServer = "http://192.168.1.5:8765" # 开发机局域网 IP -``` - -设备端会按清单轮询 `eve dev`，把变更文件下载到可写覆盖目录并复用本地热更新管线（脚本 `dofile`、资源 `tryReload`），无需重装应用。命令行也可用 `eve run --dev-server http://192.168.1.5:8765`。 - -iOS / Android 构建已默认放行明文 HTTP（开发机内网），见 `platform/ios/Info.plist.in` 与 `platform/android/apk/app/src/main/AndroidManifest.xml`。 - - -## 运行单元测试 +### 运行单元测试 默认开启 `BUILD_TESTING`。编译完成后： @@ -396,8 +441,7 @@ make test/macosx 或直接执行对应路径下的 `unit_test` / `unit_test.exe`。 - -## Docker（可选） +### Docker（可选） 仓库提供基于 Ubuntu 20.04 的 `Dockerfile`（含 `build-essential`、`cmake`、`clang-12` 等）。可用于隔离的 Linux 构建环境： @@ -408,8 +452,7 @@ docker run -it --rm --volume="$(pwd):/home/evengine/src" evengine /bin/bash 进入容器后，在挂载的源码目录按 Linux 流程配置并编译即可。注意容器内仍需自行准备 Vulkan 相关运行时/SDK（镜像默认未安装完整 Vulkan SDK）。 - -## 常见问题 +### 常见问题 1. **CMake 报找不到 Vulkan** 确认已安装 Vulkan SDK，且 `VULKAN_SDK` 指向正确路径；macOS 请 `source ~/VulkanSDK//setup-env.sh` 后再配置。重新打开终端后再 cmake。 @@ -437,7 +480,7 @@ docker run -it --rm --volume="$(pwd):/home/evengine/src" evengine /bin/bash ## 项目结构（简要） -``` +```text EVEngine/ ├── CMakeLists.txt # 主 CMake：平台检测、第三方、子目录 ├── Makefile # Windows / Linux / macOS / Android / iOS 快捷入口 diff --git a/cmake/sdk/README.md b/cmake/sdk/README.md index 7cf568d8..23ce12b1 100644 --- a/cmake/sdk/README.md +++ b/cmake/sdk/README.md @@ -3,20 +3,43 @@ Each install prefix is an **independent SDK for one publish target** (`win32` / `linux` / `macosx` / `android` / `ios`). -It is used on a **dev machine** to create a game that ships **to that target**. -It is not meant to be “installed and run” on a phone or as a universal multi-platform kit. +You do **not** need to build the engine to use this SDK: download the matching +`eve-sdk--.zip` from the [official release page](https://github.com/EVEngine/EVEngine/releases), +unzip it, and run `bin/eve` directly. It is used on a **dev machine** to create a +game that ships **to that target**. It is not meant to be “installed and run” on a +phone or as a universal multi-platform kit. ## Layout -- `bin/` — host (`eve` / `eve.exe` / iOS `.app`) when applicable -- `lib/` — Android `libmain.so` + packaging `.so`s; Windows `eve.lib` for plugins -- `include/eve/` — public headers for native plugins -- `cmake/` — `find_package(EVEngine)` + `add_eve_plugin()` -- `platform/` — **this target only** packaging template -- `share/eve/TARGET_PLATFORM` — must match the directory name +- `bin/` — host runtime (`eve` / `eve.exe` / iOS `.app`) when applicable +- `lib/` — Android `libmain.so` + packaging `.so`s; macOS runtime dylibs; Windows `eve.lib` for plugins +- `include/eve/` — public headers for native plugins (not needed for script-only games) +- `cmake/` — `find_package(EVEngine)` + `add_eve_plugin()` (not needed for script-only games) +- `platform/` — **this target only** packaging template (e.g. the Android APK project) +- `share/eve/` — `VERSION`, `TARGET_PLATFORM`, runnable `examples/basic`, `licenses/` + +`share/eve/TARGET_PLATFORM` must match the SDK directory name. + +## Quick start (script-only game, no compilation) + +```sh +bin/eve -v # verify the runtime works +bin/eve run share/eve/examples/basic # run the bundled example +bin/eve create mygame # scaffold a game (config.nut + main.nut) +bin/eve run mygame # run it (hot reload is on by default) +bin/eve zip mygame # compress into mygame.eve +bin/eve package mygame -o out --sdk # runnable game folder +``` + +The runtime needs a Vulkan driver (Windows/macOS/Linux desktop; macOS uses the +bundled MoltenVK). No compiler, CMake, or Vulkan SDK is required for script-only +development. The full user guide lives at `docs/usr/README.md` in the source +repository and in the [online docs](https://evengine.github.io/EVEngine/). ## Install (from engine source tree) +This section is only for **engine developers** who build the SDK themselves: + ```bash cmake --install build/macosx-debug --prefix dist/eve-sdk/macosx-debug cmake --install build/android-debug --prefix dist/eve-sdk/android-debug @@ -28,6 +51,9 @@ Do **not** install multiple platforms into the same prefix. ## Native plugin +Only needed when you want to extend the engine with C++ code. The plugin must be +built against the **same platform and version** of the SDK: + ```cmake find_package(EVEngine REQUIRED PATHS /path/to/eve-sdk/macosx-debug) add_eve_plugin(myplugin SOURCES myplugin.cpp) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index a64531f1..5ec5ac44 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -31,13 +31,185 @@ set_property(CACHE EVENGINE_DOC_LANGUAGE PROPERTY STRINGS Chinese English) set(DOC_LANGUAGE "${EVENGINE_DOC_LANGUAGE}") set(DOC_VISIBILITY "PUBLIC") set(DOC_OUTPUT_DIR "${DOC_TOP_DIR}/api") -set(DOC_MAINPAGE "${DOC_SOURCE_ROOT}/Readme.md") set(DOC_EXCLUDE_SYMBOLS "") +# --------------------------------------------------------------------------- +# Generate Doxygen page wrappers. +# +# Doxygen turns a Markdown file into ONE page only when the `\page` command is +# its very first line, and the sidebar tree is built from `\subpage` relations. +# We do not put those commands in the repo's .md files (they would show up on +# GitHub); instead we generate page wrappers in the build directory with the +# metadata prepended. The generated tree mirrors the repository layout, so all +# relative links between the original .md files keep resolving. +# --------------------------------------------------------------------------- +set(_doc_pages_dir "${CMAKE_CURRENT_BINARY_DIR}/pages") +set(DOC_MAINPAGE "${DOC_TOP_DIR}/dox/mainpage.dox") + +# Start from a clean tree so stale wrappers from previous configure runs +# (e.g. an older page set) never leak into the generated documentation. +file(REMOVE_RECURSE "${_doc_pages_dir}") +file(MAKE_DIRECTORY + "${_doc_pages_dir}/docs/usr/modules" + "${_doc_pages_dir}/docs/dev") + +# User guide root: EVEngine 用户指南 -> module handbook / trimming / conventions. +file(READ "${DOC_TOP_DIR}/usr/README.md" _doc_usr_readme ENCODING UTF-8) +file(WRITE "${_doc_pages_dir}/docs/usr/README.md" + "\\page usr_guide EVEngine 用户指南\n\n" + "\\subpage usr_modules\n\n" + "\\subpage usr_trimming\n\n" + "\\subpage usr_conventions\n\n" + "${_doc_usr_readme}") + +# Module handbook: groups the five category pages (defined in docs/dox/). +file(READ "${DOC_TOP_DIR}/usr/MODULES.md" _doc_modules ENCODING UTF-8) +file(WRITE "${_doc_pages_dir}/docs/usr/MODULES.md" + "\\page usr_modules 模块使用手册\n\n" + "\\subpage usr_env\n\n" + "\\subpage usr_assets\n\n" + "\\subpage usr_gameplay\n\n" + "\\subpage usr_scene\n\n" + "\\subpage usr_advanced\n\n" + "${_doc_modules}") + +# Trimming guide and API conventions. +file(READ "${DOC_TOP_DIR}/usr/TRIMMING.md" _doc_trimming ENCODING UTF-8) +file(WRITE "${_doc_pages_dir}/docs/usr/TRIMMING.md" + "\\page usr_trimming 按需裁剪模块\n\n${_doc_trimming}") +file(READ "${DOC_SOURCE_ROOT}/docs/dev/API-CONVENTIONS.md" _doc_conventions + ENCODING UTF-8) +file(WRITE "${_doc_pages_dir}/docs/dev/API-CONVENTIONS.md" + "\\page usr_conventions API 使用约定\n\n${_doc_conventions}") + +# One module page per docs/usr/modules/.md, format: name|page-id|title. +set(_doc_module_pages + "animation.md|mod_animation|动画模块" + "audio.md|mod_audio|音频播放模块" + "building.md|mod_building|建筑放置模块" + "cardgame.md|mod_cardgame|卡牌游戏工具模块" + "data.md|mod_data|数据模块" + "daynight.md|mod_daynight|昼夜循环模块" + "demo.md|mod_demo|内置演示模块" + "editor.md|mod_editor|编辑器构件模块" + "entity.md|mod_entity|脚本 ECS模块" + "event.md|mod_event|事件模块" + "filesystem.md|mod_filesystem|文件系统与热重载模块" + "font.md|mod_font|字体模块" + "gpgpu.md|mod_gpgpu|GPU 计算模块" + "graphics.md|mod_graphics|图形渲染模块" + "i18n.md|mod_i18n|本地化模块" + "ik.md|mod_ik|逆运动学模块" + "image.md|mod_image|图像模块" + "inventory.md|mod_inventory|背包 / 物品栏模块" + "joystick.md|mod_joystick|手柄模块" + "keyboard.md|mod_keyboard|键盘模块" + "map.md|mod_map|Tilemap模块" + "math.md|mod_math|数学模块" + "model3d.md|mod_model3d|3D 模型模块" + "mouse.md|mod_mouse|鼠标模块" + "network.md|mod_network|网络模块" + "particles.md|mod_particles|粒子模块" + "physics.md|mod_physics|物理模块（Box2D + Box3D + 布料 + 流体）" + "plugins.md|mod_plugins|原生插件模块" + "procgen.md|mod_procgen|程序化生成模块" + "rpg.md|mod_rpg|RPG 系统模块" + "rx.md|mod_rx|响应式编程模块" + "scene.md|mod_scene|声明式场景树模块" + "sound.md|mod_sound|声音数据模块" + "spatial.md|mod_spatial|空间索引模块" + "spritestack.md|mod_spritestack|Sprite-Stacking 伪 3D" + "system.md|mod_system|系统信息模块" + "tensor.md|mod_tensor|张量模块" + "thread.md|mod_thread|线程与异步模块" + "timer.md|mod_timer|计时器模块" + "touch.md|mod_touch|触摸模块" + "ui.md|mod_ui|声明式 UI模块" + "voxel.md|mod_voxel|体素（Voxel）" + "weather.md|mod_weather|天气模块" + "window.md|mod_window|窗口模块") +foreach(_doc_spec IN LISTS _doc_module_pages) + string(REPLACE "|" ";" _doc_parts "${_doc_spec}") + list(GET _doc_parts 0 _doc_name) + list(GET _doc_parts 1 _doc_id) + list(GET _doc_parts 2 _doc_title) + file(READ "${DOC_TOP_DIR}/usr/modules/${_doc_name}" _doc_content + ENCODING UTF-8) + file(WRITE "${_doc_pages_dir}/docs/usr/modules/${_doc_name}" + "\\page ${_doc_id} ${_doc_title}\n\n${_doc_content}") +endforeach() + +# --------------------------------------------------------------------------- +# Static sidebar navigation (plain HTML, no JavaScript). +# +# The doxygen treeview is rendered by JavaScript, which can be unavailable in +# embedded browsers; the static sidebar below is baked into every page header +# so "home / user guide / module handbook" is always visible and clickable. +# --------------------------------------------------------------------------- +set(_doc_sidebar_groups + "usr_env|运行环境与输入|mod_window,mod_event,mod_rx,mod_timer,mod_system,mod_keyboard,mod_mouse,mod_touch,mod_joystick" + "usr_assets|资源与 I/O|mod_filesystem,mod_data,mod_image,mod_font,mod_i18n,mod_sound,mod_audio,mod_model3d,mod_network" + "usr_gameplay|游戏玩法|mod_entity,mod_physics,mod_map,mod_particles,mod_animation,mod_rpg,mod_inventory,mod_cardgame,mod_building,mod_procgen" + "usr_scene|表现与场景|mod_graphics,mod_voxel,mod_spritestack,mod_daynight,mod_weather,mod_ui,mod_scene" + "usr_advanced|高级能力|mod_math,mod_spatial,mod_editor,mod_ik,mod_gpgpu,mod_tensor,mod_thread,mod_plugins,mod_demo") + +set(_doc_module_titles "") +foreach(_doc_spec IN LISTS _doc_module_pages) + string(REPLACE "|" ";" _doc_parts "${_doc_spec}") + list(GET _doc_parts 1 _doc_id) + list(GET _doc_parts 2 _doc_title) + list(APPEND _doc_module_titles "${_doc_id}=${_doc_title}") +endforeach() + +set(_doc_sidebar_html + "首页" + "用户指南" + "
模块使用手册") +foreach(_doc_group IN LISTS _doc_sidebar_groups) + string(REPLACE "|" ";" _doc_gparts "${_doc_group}") + list(GET _doc_gparts 0 _doc_cat_id) + list(GET _doc_gparts 1 _doc_cat_title) + list(GET _doc_gparts 2 _doc_cat_mods) + string(REPLACE "," ";" _doc_cat_mod_list "${_doc_cat_mods}") + list(APPEND _doc_sidebar_html + "
${_doc_cat_title}") + foreach(_doc_mid IN LISTS _doc_cat_mod_list) + set(_doc_mtitle "${_doc_mid}") + foreach(_doc_pair IN LISTS _doc_module_titles) + if(_doc_pair MATCHES "^${_doc_mid}=(.*)$") + set(_doc_mtitle "${CMAKE_MATCH_1}") + endif() + endforeach() + list(APPEND _doc_sidebar_html "${_doc_mtitle}") + endforeach() + list(APPEND _doc_sidebar_html "
") +endforeach() +list(APPEND _doc_sidebar_html + "
" + "按需裁剪模块" + "API 使用约定" + "
C++ API 参考
" + "命名空间" + "概念" + "类" + "文件" + "全部页面") +string(JOIN "\n" _doc_sidebar_nav ${_doc_sidebar_html}) + +file(READ "${DOC_TOP_DIR}/theme/header.template.html" _doc_header_tpl ENCODING UTF-8) +string(REPLACE "" "${_doc_sidebar_nav}" _doc_header "${_doc_header_tpl}") +file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/header.html" "${_doc_header}") + +set(DOC_HEADER "${CMAKE_CURRENT_BINARY_DIR}/header.html") +set(DOC_FOOTER "${DOC_TOP_DIR}/theme/footer.html") + +# Doxygen inputs: C++ sources, the generated page wrappers, and the +# doxygen-only category pages. REVIEW.md is deliberately not copied, so it is +# not part of the published user documentation. set(_doc_inputs "${DOC_SOURCE_ROOT}/src" - "${DOC_SOURCE_ROOT}/Readme.md" - "${DOC_TOP_DIR}/usr") + "${_doc_pages_dir}" + "${DOC_TOP_DIR}/dox") string(REPLACE ";" " " DOC_INPUT "${_doc_inputs}") set(DOC_PROJECT_LOGO "") diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 378b1dd0..4632a91b 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -361,7 +361,7 @@ MARKDOWN_SUPPORT = YES # Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -TOC_INCLUDE_HEADINGS = 5 +TOC_INCLUDE_HEADINGS = 0 # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can @@ -996,7 +996,10 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = src/engine/Readme.md \ + src/engine/cmdline/Readme.md \ + src/engine/devtools/Readme.md \ + src/modules/Readme.md # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1260,7 +1263,7 @@ HTML_FILE_EXTENSION = .html # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_HEADER = @DOC_TOP_DIR@/theme/header.html +HTML_HEADER = @DOC_HEADER@ # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank doxygen will generate a standard @@ -1270,7 +1273,7 @@ HTML_HEADER = @DOC_TOP_DIR@/theme/header.html # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_FOOTER = +HTML_FOOTER = @DOC_FOOTER@ # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of @@ -1296,8 +1299,7 @@ HTML_STYLESHEET = # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_STYLESHEET = @DOC_TOP_DIR@/theme/doxygen-awesome.css \ - @DOC_TOP_DIR@/theme/doxygen-awesome-sidebar-only.css \ - @DOC_TOP_DIR@/theme/doxygen-awesome-sidebar-only-darkmode-toggle.css + @DOC_TOP_DIR@/theme/evengine-docs.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1309,9 +1311,7 @@ HTML_EXTRA_STYLESHEET = @DOC_TOP_DIR@/theme/doxygen-awesome.css \ HTML_EXTRA_FILES = @DOC_TOP_DIR@/theme/doxygen-awesome-darkmode-toggle.js \ @DOC_TOP_DIR@/theme/doxygen-awesome-fragment-copy-button.js \ - @DOC_TOP_DIR@/theme/doxygen-awesome-interactive-toc.js \ - @DOC_TOP_DIR@/theme/doxygen-awesome-paragraph-link.js \ - @DOC_TOP_DIR@/theme/doxygen-awesome-tabs.js + @DOC_TOP_DIR@/theme/doxygen-awesome-paragraph-link.js # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to @@ -1594,7 +1594,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -DISABLE_INDEX = NO +DISABLE_INDEX = YES # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag @@ -1611,7 +1611,7 @@ DISABLE_INDEX = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = YES +GENERATE_TREEVIEW = NO # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the # FULL_SIDEBAR option determines if the side bar is limited to only the treeview diff --git a/docs/dev/README.md b/docs/dev/README.md index ed45eb21..111410ea 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -2,6 +2,10 @@ 本目录保存引擎的架构、模块设计、测试策略和实现计划，面向 EVEngine 本身的维护者与贡献者。 +> **如果你是游戏开发者而不是引擎开发者**：请从[官网发布页](https://github.com/EVEngine/EVEngine/releases) +> 下载预编译 SDK 直接使用，**不需要编译引擎**；用户文档见[用户指南](../usr/README.md)与 +> [模块使用手册](../usr/MODULES.md)。本目录及下文“从源码构建”只对需要修改引擎的人有意义。 + ## 架构与工程约定 - [发布流程](发布流程.md)（`main` / `dev` / `vX.X.X`，Pre-release 发版） @@ -48,6 +52,7 @@ 产物位于 `docs/api/html/`（已加入 `.gitignore`）。需要先安装 doxygen： Ubuntu/WSL `sudo apt install doxygen`、macOS `brew install doxygen`、Windows `choco install doxygen`。 文档配置见 [`docs/Doxyfile.in`](../Doxyfile.in) 与 [`docs/CMakeLists.txt`](../CMakeLists.txt)，入口 `src/`、`Readme.md` 与 `docs/usr/`。 + 在线版由 GitHub Pages 持续发布：。 - 运行时断言：引擎统一通过 zeroerr 的 `ASSERT` 系列宏做函数参数校验与内部不变量检查， 入口见 [`src/engine/common/Assert.h`](../../src/engine/common/Assert.h)（`EV_PARAM_CHECK` / `EV_ASSERT`）。 diff --git a/docs/dox/mainpage.dox b/docs/dox/mainpage.dox new file mode 100644 index 00000000..f438812d --- /dev/null +++ b/docs/dox/mainpage.dox @@ -0,0 +1,29 @@ +/** + * @mainpage EVEngine 文档 + * + * @par 简介 + * EVEngine（Evolutionary Vision Engine）是一款以 Squirrel 脚本驱动的轻量游戏引擎， + * 适合快速制作 2D、第三人称 3D 与 2D/3D 混合的游戏原型。引擎内置热重载、调试器、 + * 声明式 UI、ECS、物理、程序化生成、RPG 等 40+ 模块，支持 Windows / Linux / macOS / + * Android / iOS 打包发布。 + * + * 本站在线提供用户手册与 C++ API 参考，随 GitHub Pages 持续发布。 + * + * @par 快速开始（游戏开发者） + * 使用 EVEngine 做游戏不需要编译引擎：到官网发布页 + * （GitHub Releases） + * 下载对应平台的预编译 SDK，解压后执行 `eve run <游戏目录>` 即可开始创作。 + * 完整流程见 @ref usr_guide "EVEngine 用户指南"。 + * + * @par 文档导航 + * - @ref usr_guide "EVEngine 用户指南"：下载、创建并运行游戏、调试与打包发布； + * - @ref usr_modules "模块使用手册"：按功能逐个说明脚本 API 与示例（也可从用户指南进入）； + * - @ref usr_trimming "按需裁剪模块"：从源码构建时按档位裁剪模块； + * - @ref usr_conventions "API 使用约定"：模块对象、生命周期与脚本 API 边界； + * - 本页下方的「命名空间 / 类 / 文件」为 C++ API 参考； + * - 引擎架构与实现文档（面向引擎开发者）见 GitHub 仓库的 docs/dev。 + * + * @par 许可证 + * EVEngine 采用双许可（开源免费 / 商用授权），使用前请阅读 + * Readme 的许可证章节。 + */ diff --git a/docs/dox/usr-pages.dox b/docs/dox/usr-pages.dox new file mode 100644 index 00000000..f3071c89 --- /dev/null +++ b/docs/dox/usr-pages.dox @@ -0,0 +1,78 @@ +/** + * @page usr_env 运行环境与输入 + * + * 窗口、事件、计时器、系统信息与各类输入设备模块。 + * + * @subpage mod_window + * @subpage mod_event + * @subpage mod_rx + * @subpage mod_timer + * @subpage mod_system + * @subpage mod_keyboard + * @subpage mod_mouse + * @subpage mod_touch + * @subpage mod_joystick + */ + +/** + * @page usr_assets 资源与 I/O + * + * 文件系统、数据、图像、字体、本地化、音频与网络等资源模块。 + * + * @subpage mod_filesystem + * @subpage mod_data + * @subpage mod_image + * @subpage mod_font + * @subpage mod_i18n + * @subpage mod_sound + * @subpage mod_audio + * @subpage mod_model3d + * @subpage mod_network + */ + +/** + * @page usr_gameplay 游戏玩法 + * + * 面向具体玩法的模块：ECS、物理、地图、粒子、动画、RPG、背包、卡牌、建造与程序化生成。 + * + * @subpage mod_entity + * @subpage mod_physics + * @subpage mod_map + * @subpage mod_particles + * @subpage mod_animation + * @subpage mod_rpg + * @subpage mod_inventory + * @subpage mod_cardgame + * @subpage mod_building + * @subpage mod_procgen + */ + +/** + * @page usr_scene 表现与场景 + * + * 渲染与场景表现模块：图形、体素、Sprite-Stacking、昼夜、天气、UI 与场景树。 + * + * @subpage mod_graphics + * @subpage mod_voxel + * @subpage mod_spritestack + * @subpage mod_daynight + * @subpage mod_weather + * @subpage mod_ui + * @subpage mod_scene + */ + +/** + * @page usr_advanced 高级能力 + * + * 数学、空间索引、编辑器构件、IK、GPU 计算、张量、线程、原生插件与内置演示。 + * + * @subpage mod_math + * @subpage mod_spatial + * @subpage mod_editor + * @subpage mod_ik + * @subpage mod_gpgpu + * @subpage mod_tensor + * @subpage mod_thread + * @subpage mod_plugins + * @subpage mod_demo + */ diff --git a/docs/theme/evengine-docs.css b/docs/theme/evengine-docs.css new file mode 100644 index 00000000..583c92e1 --- /dev/null +++ b/docs/theme/evengine-docs.css @@ -0,0 +1,144 @@ +/* EVEngine static docs layout: a plain-HTML sidebar that works without JS. */ + +html, body { + margin: 0; + padding: 0; +} + +#ev-layout { + display: flex; + min-height: 100vh; + align-items: flex-start; +} + +#ev-sidebar { + flex: 0 0 310px; + width: 310px; + position: sticky; + top: 0; + height: 100vh; + overflow-y: auto; + box-sizing: border-box; + padding: 18px 14px 24px 14px; + background: var(--side-nav-background, #f7f7f9); + border-right: 1px solid var(--side-nav-arrow-opacity, #e2e2e6); +} + +#ev-brand { + font-size: 19px; + font-weight: 700; + margin-bottom: 12px; +} + +#ev-brand a { + color: inherit; + text-decoration: none; +} + +#ev-version { + font-size: 12px; + font-weight: 400; + color: #888; + margin-left: 6px; +} + +#ev-nav a { + display: block; + padding: 3px 8px; + margin: 1px 0; + color: var(--page-foreground-color, #333); + text-decoration: none; + border-radius: 4px; + font-size: 14px; +} + +#ev-nav a:hover { + background: var(--side-nav-arrow-opacity, #e8e8ec); +} + +#ev-nav summary { + cursor: pointer; + padding: 4px 8px; + margin: 2px 0; + font-weight: 600; + color: var(--page-foreground-color, #333); + border-radius: 4px; +} + +#ev-nav summary:hover { + background: var(--side-nav-arrow-opacity, #e8e8ec); +} + +/* Category headings: the link inside stays inline so it sits on the + * same line as the expand/collapse triangle. */ +#ev-nav summary a { + display: inline; + padding: 0; + margin: 0; + font-weight: 600; + color: inherit; +} + +#ev-nav summary a:hover { + background: none; +} + +#ev-nav details details { + margin-left: 10px; + border-left: 1px solid var(--side-nav-arrow-opacity, #e2e2e6); +} + +#ev-nav .ev-nav-section { + margin: 10px 0 4px 0; + padding: 6px 8px 4px 8px; + border-top: 1px solid var(--side-nav-arrow-opacity, #e2e2e6); + font-size: 12px; + font-weight: 700; + letter-spacing: 0.08em; + color: #888; +} + +#ev-sidebar-note { + margin-top: 18px; + padding: 8px; + font-size: 11px; + color: #999; + border-top: 1px solid var(--side-nav-arrow-opacity, #e2e2e6); +} + +#ev-content { + flex: 1; + min-width: 0; + overflow-x: auto; + padding: 24px 36px 48px 36px; + box-sizing: border-box; +} + +#ev-footer { + padding: 12px 36px; + font-size: 12px; + color: #999; + border-top: 1px solid var(--side-nav-arrow-opacity, #e2e2e6); +} + +/* Keep the doc content readable on narrow panels: sidebar stacks on top and + * the content follows immediately (no dead space between them). */ +@media screen and (max-width: 900px) { + #ev-layout { + flex-direction: column; + } + + #ev-sidebar { + flex: 0 0 auto; + width: 100%; + position: static; + height: auto; + max-height: 45vh; + border-right: none; + border-bottom: 1px solid var(--side-nav-arrow-opacity, #e2e2e6); + } + + #ev-content { + padding: 18px 18px 40px 18px; + } +} diff --git a/docs/theme/footer.html b/docs/theme/footer.html new file mode 100644 index 00000000..e33571f7 --- /dev/null +++ b/docs/theme/footer.html @@ -0,0 +1,7 @@ + + + + + diff --git a/docs/theme/header.template.html b/docs/theme/header.template.html new file mode 100644 index 00000000..cd7c1fa0 --- /dev/null +++ b/docs/theme/header.template.html @@ -0,0 +1,46 @@ + + + + + + + + +$projectname: $title +$title + + +$search +$mathjax + +$extrastylesheet + + + + + + +
+ +
+
diff --git a/docs/usr/MODULES.md b/docs/usr/MODULES.md index a0a7afdf..ba9f42e4 100644 --- a/docs/usr/MODULES.md +++ b/docs/usr/MODULES.md @@ -2,10 +2,12 @@ 本目录按模块说明 EVEngine 面向 Squirrel 游戏脚本公开的能力。每篇包含入口、最小示例、至少两个目标导向任务、当前绑定的 API 快查和生命周期注意事项。 -模块可以按需裁剪：见 [按需裁剪模块](TRIMMING.md)。脚本里用 `has_module("slot")` 判断某个模块在当前构建中是否存在。 +> 使用前提：从[官网发布页](https://github.com/EVEngine/EVEngine/releases)下载并解压对应平台的 SDK（无需编译引擎），然后用 `eve run <游戏目录>` 运行；本手册适用于 SDK 中的全部模块。 -首次查阅前请阅读 [API 使用约定](API-CONVENTIONS.md)，了解模块对象、辅助对象、生命周期与“C++ public 方法不一定是脚本 API”的边界。 -本轮逐章核对的实现、测试证据与结论记录在 [用户模块文档 Review](REVIEW.md)。 +模块可以按需裁剪：见 [按需裁剪模块](TRIMMING.md)。脚本里用 `has_module("slot")` 判断某个模块在当前构建中是否存在（下载的 SDK 默认包含全部模块）。 + +首次查阅前请阅读 [API 使用约定](../dev/API-CONVENTIONS.md)，了解模块对象、辅助对象、生命周期与“C++ public 方法不一定是脚本 API”的边界。 +本轮逐章核对的实现、测试证据与结论记录在 [用户模块文档 Review](https://github.com/EVEngine/EVEngine/blob/main/docs/usr/REVIEW.md)。 ## 运行环境与输入 diff --git a/docs/usr/README.md b/docs/usr/README.md index 62665132..f857ba33 100644 --- a/docs/usr/README.md +++ b/docs/usr/README.md @@ -1,86 +1,55 @@ # EVEngine 用户指南 -EVEngine 是一个以 Squirrel 脚本驱动的轻量游戏引擎，适合快速制作 2D、第三人称 3D，以及 2D/3D 混合的游戏原型。本指南面向“使用引擎制作游戏”的用户；如果你要修改引擎实现，请阅读[开发者文档](../dev/README.md)。 +EVEngine 是一个以 Squirrel 脚本驱动的轻量游戏引擎，适合快速制作 2D、第三人称 3D，以及 2D/3D 混合的游戏原型。本指南面向“使用引擎制作游戏”的用户；如果你要修改引擎实现，请阅读[开发者文档](https://github.com/EVEngine/EVEngine/blob/main/docs/dev/README.md)。 > 在线版文档（API + 用户手册）持续构建于 GitHub Pages： > 。 -> 当前版本为早期开发版本。最可靠的学习方式是运行并修改仓库中的 `examples/`。 +> 当前版本为早期开发版本，API 仍在演进。最可靠的学习方式是运行并修改示例：下载的 SDK 自带 `share/eve/examples/basic/`，仓库中还有更多 `examples/` 可参考。 -本目录不仅包含入门说明，还提供覆盖所有脚本模块的[模块使用手册](MODULES.md)，并按“完成某项游戏开发任务”的方式给出具体步骤。如果你已经能够运行示例，可以直接从模块目录按功能查阅。 +本指南从“下载引擎”讲到“打包发布”；覆盖全部脚本模块的[模块使用手册](MODULES.md)按功能逐章说明 API 与示例。先跑通一个示例，再按需查阅对应模块即可。 -引擎默认包含全部模块。只用到其中一部分时，可以按 [按需裁剪模块](TRIMMING.md) 在构建时把其余的裁掉。 +## 1. 获取引擎：从官网下载，无需编译 -## 1. 开始之前 +做游戏不需要编译引擎。 到[官网发布页](https://github.com/EVEngine/EVEngine/releases)下载目标平台的 SDK 压缩包即可： -桌面平台需要： +| 目标平台 | 下载文件 | 说明 | +|----------|----------|------| +| Windows | `eve-sdk-win32-<版本>.zip` | Windows 10/11 x64 | +| Linux | `eve-sdk-linux-<版本>.zip` | Ubuntu 20.04+ 等（需 Vulkan 驱动） | +| macOS | `eve-sdk-macosx-<版本>.zip` | macOS 12+（Apple Silicon / Intel，内置 MoltenVK） | +| Android | `eve-sdk-android-<版本>.zip` | 在开发机上组装 arm64 APK | +| iOS | `eve-sdk-ios-<版本>.zip` | 在 macOS 开发机上组装 arm64 .app | -- Git； -- CMake 3.21 或更高版本； -- 支持 C++20 的编译器； -- Vulkan SDK 1.2 或更高版本（macOS 还需要 SDK 中的 MoltenVK）； -- `make`（Linux、macOS、WSL 或 Git Bash）。 +解压后即为一个独立的 SDK 目录，无需安装。它包含： -首次构建会准备第三方依赖，因此耗时会比后续增量构建长。Linux 用户还需安装 X11、音频和 Vulkan 等开发包；完整的平台依赖和移动端工具链请参阅仓库根目录的 [`Readme.md`](../../Readme.md#环境要求)。 +- `bin/eve(.exe)`：引擎运行时（桌面平台）； +- `share/eve/examples/basic/`：可直接运行的参考游戏； +- `platform/`：目标平台打包模板（Android APK 工程等）； +- `share/eve/licenses/`：引擎与第三方许可文本； +- `include/`、`lib/`、`cmake/`：原生插件开发文件（做纯脚本游戏用不到）。 -获取源码： +要求只有一条：桌面运行时需要 Vulkan 驱动（显卡驱动通常已自带；macOS 由 SDK 内置 MoltenVK 承担；Linux 需安装 `mesa-vulkan-drivers` 或厂商驱动）。不需要安装 Git、CMake、C++ 编译器或 LunarG Vulkan SDK。 + +验证安装： ```sh -git clone --recurse-submodules https://github.com/EVEngine/EVEngine -cd EVEngine +# Windows +bin\eve.exe run share\eve\examples\basic + +# macOS / Linux +bin/eve run share/eve/examples/basic ``` -默认克隆的是 `main`（最新正式版，可直接编译）。要改引擎请： +能正常打开窗口并看到示例画面，说明引擎可用。下面命令中的 `eve` 均指你解压目录里的 `bin/eve`（Windows 为 `bin\eve.exe`）。 + +## 2. 创建并运行你的第一个游戏 ```sh -git checkout dev -git pull +eve create mygame # 在当前目录生成 mygame/ +eve run mygame # 运行它 ``` -如果克隆时没有拉取子模块： - -```sh -git submodule update --init --recursive -``` - -## 2. 构建并运行第一个示例 - -在仓库根目录执行： - -```sh -# 构建当前宿主平台的 Debug 版本 -make debug - -# 运行内置演示 -make run - -# 运行最适合作为起点的脚本示例 -make basic -``` - -也可以明确指定桌面平台和游戏目录： - -```sh -make run/linux-debug GAME=examples/basic -make run/macosx-debug GAME=examples/basic -make run/win32-debug GAME=examples/basic -``` - -常用快捷入口： - -| 命令 | 内容 | -|---|---| -| `make basic` | Tilemap、Box2D、粒子与基础绘制 | -| `make ecs` | 脚本 ECS 与移动系统 | -| `make rpg` | 属性、状态、技能和战斗结算 | -| `make run/$(平台)-debug GAME=examples/procgen` | 程序化地图与纹理 | -| `make run/$(平台)-debug GAME=examples/roguelike-generator` | Roguelike 风格地牢：房间/走廊、地板图案、墙方向、装饰（2D/2.5D） | -| `make test` | 当前平台 Debug 测试 | - -`$(平台)` 可替换为 `linux`、`macosx` 或 `win32`。Windows 的 Release 构建默认使用 Visual Studio 生成器，Debug 构建使用项目 Makefile 中配置的工具链。 - -## 3. 游戏目录是什么样的 - 一个最小游戏只需要两个文件： ```text @@ -124,18 +93,7 @@ eve_render <- function() { }; ``` -运行它： - -```sh -make run/linux-debug GAME=/绝对路径/my-game -# macOS 或 Windows 请替换目标名 -``` - -也可以直接使用已经构建好的宿主程序。`run` 会切换到指定目录并从该目录读取 `config.nut`、`main.nut` 和资源： - -```sh -build/linux-debug/src/engine/eve run /绝对路径/my-game -``` +运行后修改 `main.nut` 并保存，即可看到热重载效果。也可以直接复制 `share/eve/examples/basic/`，逐步替换脚本和资源。 ### 推荐的目录布局 @@ -152,9 +110,9 @@ my-game/ └── models/ ``` -资源路径以游戏工作目录为基准。可以直接复制 `examples/basic`，逐步替换脚本和资源。 +资源路径以游戏工作目录为基准。 -## 4. 生命周期与热重载 +## 3. 生命周期与热重载 引擎识别以下回调： @@ -180,27 +138,29 @@ function eve_init() { } ``` -把一次性初始化放进 `eve_init`，把可重复执行的声明保留在顶层，并参考 `examples/basic/main.nut` 中的完整写法。 +把一次性初始化放进 `eve_init`，把可重复执行的声明保留在顶层，并参考 `share/eve/examples/basic/main.nut` 中的完整写法。 -## 5. 常用模块 +## 4. 你能用引擎做哪些事 -模块通常由 `eve` 表中的构造器创建；基础运行环境也会提供 `gfx`、`keyboard`、`map`、`particles`、`physics`、`ui` 等常用实例。请以示例实际使用的接口为准。 +引擎默认包含全部模块，脚本侧统一放在全局 `eve` 表中；常用模块也会直接提供 `gfx`、`keyboard`、`map`、`particles`、`physics`、`ui` 等全局实例。模块通常由 `eve` 表中的构造器创建，请以示例实际使用的接口为准。 | 需求 | 入口或模块 | 示例 | |---|---|---| -| 2D/3D 绘制、纹理、字体 | `gfx` / `eve.Graphics` | `examples/basic`、渲染测试 | -| 键盘、鼠标、触摸、手柄 | `keyboard`、`mouse`、`touch`、`joystick` | `examples/procgen`、`test/*_cpp.cpp` | -| 物理 | `physics` / `eve.Physics` | `examples/basic` | -| Tilemap | `map` / `eve.Map` | `examples/basic/maps` | -| 粒子 | `particles` / `eve.Particles` | `examples/basic/particles` | -| 声明式 UI | `ui` / `eve.UI` | `examples/basic/ui_demo.nut`、`ui_component.nut` | -| ECS | `eve.Component`、`eve.Entity`、`eve.System` | `examples/ecs` | -| RPG | `eve.RPG` | `examples/rpg` | -| 程序化生成 | `procgen` / `eve.Procgen` | `examples/procgen` | -| 文件、数据、事件 | `eve.Filesystem`、`eve.DataModule`、`eve.Event` | `test/filesystem.nut` 等 | -| 音频、动画、IK | `eve.Audio`、`eve.Animation`、`eve.IK` | 对应 `test/` 示例 | -| GPU 计算、张量 | `eve.Gpgpu`、`eve.TF` | `examples/basic/compute`、对应测试 | -| 原生扩展 | `eve.Plugins` | `examples/native-plugin` | +| 2D/3D 绘制、纹理、字体 | `gfx` / `eve.Graphics` | `share/eve/examples/basic`、渲染测试 | +| 键盘、鼠标、触摸、手柄 | `keyboard`、`mouse`、`touch`、`joystick` | 仓库 `examples/procgen`、`test/*_cpp.cpp` | +| 物理 | `physics` / `eve.Physics` | `share/eve/examples/basic` | +| Tilemap | `map` / `eve.Map` | `share/eve/examples/basic/maps` | +| 粒子 | `particles` / `eve.Particles` | `share/eve/examples/basic/particles` | +| 声明式 UI | `ui` / `eve.UI` | `share/eve/examples/basic/ui_demo.nut`、`ui_component.nut` | +| ECS | `eve.Component`、`eve.Entity`、`eve.System` | 仓库 `examples/ecs` | +| RPG | `eve.RPG` | 仓库 `examples/rpg` | +| 程序化生成 | `procgen` / `eve.Procgen` | 仓库 `examples/procgen` | +| 文件、数据、事件 | `eve.Filesystem`、`eve.DataModule`、`eve.Event` | 仓库 `test/filesystem.nut` 等 | +| 音频、动画、IK | `eve.Audio`、`eve.Animation`、`eve.IK` | 仓库对应 `test/` 示例 | +| GPU 计算、张量 | `eve.Gpgpu`、`eve.TF` | 仓库 `examples/basic/compute`、对应测试 | +| 原生扩展 | `eve.Plugins` | 仓库 `examples/native-plugin` | + +每个模块的详细 API、最小示例与目标导向任务见[模块使用手册](MODULES.md)。 ### UI 最小示例 @@ -230,16 +190,34 @@ eve_render <- function() { ### ECS 最小思路 -通过继承 `eve.Component` 声明数据，继承 `eve.Entity` 组合组件，再用 `eve.System` 查询并更新实体。可直接从 `examples/ecs/main.nut` 复制完整的可运行模板。 +通过继承 `eve.Component` 声明数据，继承 `eve.Entity` 组合组件，再用 `eve.System` 查询并更新实体。可直接从仓库 `examples/ecs/main.nut` 复制完整的可运行模板。 -## 6. 调试 +### 命令行速查 -命令行调试模式支持暂停、断点、监视、快照，以及面向 AI Agent 的 MCP： +SDK 中的 `eve` 可执行文件本身就是命令行工具： + +| 命令 | 作用 | +|---|---| +| `eve create <名字>` | 从模板创建新游戏 | +| `eve run [目录]` | 运行游戏（不带参数运行当前目录；无游戏时进入内置演示） | +| `eve run --debug` | 调试模式：暂停、断点、监视、快照 | +| `eve run --dap-port=4711` | 启动 VS Code 调试适配器服务 | +| `eve run --mcp-port=7529` | 启动 MCP 服务，供 AI 代理接入 | +| `eve dev [--port 8765]` | 启动热重载开发服务器（移动端真机热更新用） | +| `eve zip <目录>` | 把游戏压缩为 `.eve` 归档 | +| `eve package <目录> -o <输出> --sdk ` | 打包为含运行时的可分发游戏目录 | +| `eve test` | 运行游戏目录中的测试配置 | +| `eve doc <名字>` | 查询在线文档 | +| `eve build` | 从源码构建（需要源码与工具链，见[开发者文档](https://github.com/EVEngine/EVEngine/blob/main/docs/dev/README.md)） | + +## 5. 调试 + +调试模式支持暂停、断点、监视、快照，以及面向 AI Agent 的 MCP： ```sh -build/linux-debug/src/engine/eve run --debug /绝对路径/my-game -build/linux-debug/src/engine/eve run --debug --dap-port=4711 /绝对路径/my-game -build/linux-debug/src/engine/eve run --debug --mcp-port=7529 /绝对路径/my-game +eve run --debug /绝对路径/my-game +eve run --debug --dap-port=4711 /绝对路径/my-game +eve run --debug --mcp-port=7529 /绝对路径/my-game ``` 脚本中可在调试模式下使用： @@ -254,46 +232,77 @@ eve.dev.loadSnapshot("boss.json"); eve.dev.ai.note("boss phase"); // DevTools AI 会话日志；F9 切换面板 ``` -VS Code 调试适配器位于 `tools/vscode-eve-debug/`；Cursor 等 Agent 可通过 `tools/eve-mcp/` 连接 `--mcp-port`（见[开发者文档：AI 与 MCP](../dev/AI与MCP支持.md)）。如果只需快速定位问题，先确认： +VS Code 调试适配器位于仓库 `tools/vscode-eve-debug/`；Cursor 等 Agent 可通过 `tools/eve-mcp/` 连接 `--mcp-port`（见[开发者文档：AI 与 MCP](https://github.com/EVEngine/EVEngine/blob/main/docs/dev/AI与MCP支持.md)）。如果只需快速定位问题，先确认： 1. `config.nut` 和 `main.nut` 位于传给 `run` 的同一游戏目录； 2. 每帧绘制前调用了 `gfx.clear()`； 3. 创建物理、地图或粒子模块后，在 `eve_update` 中调用相应的 `update(dt)`； -4. 资源路径相对于游戏目录，而不是引擎仓库根目录； -5. Vulkan SDK、驱动和运行时环境变量有效。 +4. 资源路径相对于游戏目录，而不是 SDK 根目录； +5. Vulkan 驱动和运行时环境有效。 -## 7. 发布与原生插件 +## 6. 打包发布 -构建目标平台 SDK： +### 桌面平台 ```sh -make sdk/linux-debug -make sdk/macosx-debug -make sdk/win32-debug +# 1. 压缩游戏为 .eve 归档（可选，便于分发单个文件） +eve zip mygame + +# 2. 生成包含运行时 + 游戏的可分发目录 +eve package mygame -o mygame-package --sdk +# Windows 产物含 eve.exe 与运行时 DLL；macOS / Linux 为 eve 与相关动态库 ``` -SDK 输出到 `dist/eve-sdk/<平台>/`。原生插件无需包含完整引擎源码，可使用 CMake 的 `find_package(EVEngine)` 和 `add_eve_plugin(...)`；完整模板见 `examples/native-plugin/`。插件必须与宿主平台及构建配置匹配。 +`eve package` 需要指定与你当前 SDK 同版本、同平台的 SDK 目录（不传时自动从 `bin/eve` 所在位置推断）。把生成的目录整体发给玩家即可运行，玩家无需安装引擎。 -移动端提供仓库级打包入口： +### 移动端真机热更新（`eve dev`） + +应用包内资源只读，无法直接改设备文件。在开发机上编辑，由设备拉取： ```sh -# Android arm64 Debug APK -make build/android-debug ANDROID_GAME=/绝对路径/my-game +# 1. 开发机上启动开发服务器（服务当前游戏目录） +eve dev --port 8765 -# iOS/iPadOS Debug app（需要 macOS、Xcode 和签名配置） -make build/ios-debug IOS_GAME=/绝对路径/my-game +# 2. 设备端 config.nut 配置开发机地址（或命令行注入） +config.devServer = "http://192.168.1.5:8765" # 开发机局域网 IP ``` -移动端的 SDK、NDK、签名和真机要求较严格，请在打包前阅读根目录 [`Readme.md`](../../Readme.md#androidarm64-v8a-debug-apk) 中的对应章节。 +设备端会按清单轮询 `eve dev`，把变更文件下载到可写覆盖目录并复用本地热更新管线（脚本 `dofile`、资源 `tryReload`），无需重装应用。命令行也可用 `eve run --dev-server http://192.168.1.5:8765`。 -## 8. 下一步 +### Android / iOS + +下载对应平台的 SDK，用其自带模板在开发机上组装安装包： + +```sh +# Android：把游戏脚本放进 SDK 的 platform/apk/app/src/main/assets/game/， +# 然后执行 SDK 内的 Gradle 工程生成 APK（需要 Android SDK/NDK） +# iOS：用 SDK 的 platform/ios 模板在 Xcode 中生成 .app（需要 macOS、Xcode 与签名） +``` + +移动端的 SDK、NDK、签名和真机要求较严格，请在打包前阅读根目录 [Readme.md 的 Android 章节](https://github.com/EVEngine/EVEngine/blob/main/Readme.md#androidarm64-v8a-debug-apk)。 + +## 7. 需要注意的事项 + +1. 无需编译，但需要 Vulkan 驱动：运行时基于 Vulkan。Windows 显卡驱动通常自带 Vulkan 运行时；macOS 由 SDK 内置 MoltenVK；Linux 需要安装 Vulkan 驱动（`mesa-vulkan-drivers` 或厂商驱动）。如果游戏启动后窗口黑屏或报 Vulkan 初始化失败，优先检查驱动。 +2. SDK 按平台独立、版本必须匹配：每个 SDK 只面向一个目标平台；`eve package`、原生插件必须与 SDK 的平台、版本一致，不同平台的 SDK 不能混用。 +3. 脚本 API 以“模块手册 + 示例”为准：C++ 头文件中的 public 方法不一定是脚本 API；调用约定见[API 使用约定](../dev/API-CONVENTIONS.md)。 +4. 热重载会重新执行脚本：用 `if (!("x" in getroottable()))` 保护需要跨重载保留的全局引用（见第 3 节）。 +5. 模块可以裁剪，但默认全开：脚本里用 `has_module("slot")` 判断模块是否存在；构建时裁剪只对“从源码构建”的用户有效，下载的 SDK 默认包含全部模块（见[按需裁剪模块](TRIMMING.md)）。 +6. 许可：EVEngine 采用双许可，商用营收超过免费门槛后需商业授权，详见根目录 [许可证](https://github.com/EVEngine/EVEngine/blob/main/Readme.md#许可证)。 +7. 版本与分支：Release 与 `main` 分支对应正式版；早期开发版 API 可能变化，升级 SDK 后请先运行内置示例回归。 + +## 8. 从源码构建 / 修改引擎（可选） + +只有需要修改引擎源码、参与开发或自行打包时才需要从源码构建：环境要求、编译步骤见根目录 [Readme.md 的“从源码构建”章节](https://github.com/EVEngine/EVEngine/blob/main/Readme.md#从源码构建引擎开发者--贡献者)；架构与设计文档见[开发者文档](https://github.com/EVEngine/EVEngine/blob/main/docs/dev/README.md)。 + +## 9. 下一步 建议按以下顺序学习： -1. 运行 `examples/basic`，修改背景色、重力和粒子配置； -2. 运行 `examples/ecs`，添加一个组件和系统； -3. 根据类型选择 `examples/rpg` 或 `examples/procgen`； -4. 查阅 `test/` 中按模块命名的脚本与 C++ 用例，了解尚未进入教程的 API； -5. 需要原生能力时再使用目标平台 SDK 和 `examples/native-plugin`。 +1. 运行 `share/eve/examples/basic/`，修改背景色、重力和粒子配置； +2. 用 `eve create` 建新游戏，熟悉 `eve_init` / `eve_update` / `eve_render` 与热重载； +3. 按需求查阅[模块使用手册](MODULES.md)（UI、ECS、RPG、程序化生成等）； +4. 需要原生能力时，再使用 SDK 的 CMake 包编写插件（见仓库 `examples/native-plugin`）； +5. 发布前阅读第 6 节打包步骤与许可条款。 -本指南讲解稳定的使用流程，内部架构、设计取舍和实现进度统一维护在 [`docs/dev/`](../dev/README.md)，避免把尚未实现的设计稿误当作用户 API。 +本指南讲解稳定的使用流程，内部架构、设计取舍和实现进度统一维护在 [`docs/dev/`](https://github.com/EVEngine/EVEngine/blob/main/docs/dev/README.md)，避免把尚未实现的设计稿误当作用户 API。 diff --git a/docs/usr/TRIMMING.md b/docs/usr/TRIMMING.md index f0f29c66..769d9aff 100644 --- a/docs/usr/TRIMMING.md +++ b/docs/usr/TRIMMING.md @@ -3,7 +3,10 @@ EVEngine 默认把全部模块编进引擎。如果你的游戏只用到其中一部分，可以在构建时把其余的裁掉， 减少编译时间、二进制体积和第三方依赖。 -引擎架构与这套机制的设计依据见[模块编排与裁剪架构](../dev/模块编排与裁剪架构.md)。 +> 下载的预编译 SDK 默认包含全部模块，无需也不支持在安装后裁剪；本节只对“从源码构建”的用户有效 +> （构建方法见根目录 [Readme.md 的“从源码构建”章节](https://github.com/EVEngine/EVEngine/blob/main/Readme.md#从源码构建引擎开发者--贡献者)）。 + +引擎架构与这套机制的设计依据见[模块编排与裁剪架构](https://github.com/EVEngine/EVEngine/blob/main/docs/dev/模块编排与裁剪架构.md)。 ## 预设档位 @@ -18,7 +21,7 @@ cmake -B build -DCMAKE_BUILD_TYPE=Debug -DEVENGINE_PROFILE=2d | `minimal` | 窗口、事件、输入、图形、数学、文件系统、UI | 自己搭一切的引擎壳 | | `2d` | `minimal` + 图片、字体、地图、粒子、动画、物理、音频、空间索引、i18n | LÖVE 级 2D 游戏 | | `3d` | `2d` + 3D 模型、场景树、场景载入、GPGPU、风格化、昼夜、天气、体素、程序化生成、编辑器构件、DevTools | 3D 游戏 | -| `full` | 全部（**默认**） | 不确定时用这个 | +| `full` | 全部（默认） | 不确定时用这个 | | `web` | 浏览器 WASM 可用的集合 | Emscripten 构建自动选中 | 档位只是起点，可以在其上继续微调（见下）。 @@ -50,7 +53,7 @@ cmake -B build -DEVENGINE_PROFILE=2d -DEVENGINE_MODULE_DIALOGUE=ON 打开一个模块，它需要的模块会自动跟着打开 —— 开 `particles` 就会带上 `gpgpu`、`animation`、`ik`，不用自己列。 -反过来，关掉别人还需要的模块是**配置期错误**，而不是等到链接期才冒出一堆 +反过来，关掉别人还需要的模块是配置期错误，而不是等到链接期才冒出一堆 undefined reference： ``` @@ -79,9 +82,9 @@ if (has_module("particles")) { 另外两处目前限制了裁剪范围，配置时会点名提示： -- **DevTools** 直接引用了 `scene` / `physics` / `procgen` / `particles` / `audio` / `ui`， +- DevTools 直接引用了 `scene` / `physics` / `procgen` / `particles` / `audio` / `ui`， 要裁这几个得先 `-DEVENGINE_MODULE_DEVTOOLS=OFF`。 -- **`ui`** 被命令行的 `eve mcp` 子命令引用，目前不可裁，所以 `minimal` 档也带着 ImGui。 +- ui 被命令行的 `eve mcp` 子命令引用，目前不可裁，所以 `minimal` 档也带着 ImGui。 ## 能省多少