西风逍遥游andCursor Agent 0f14ca97e5 SilPOM vs SSDM: restore edge protrusion, keep mid solid (#399)
* Add SilPOM and SSDM comparison helpers plus demo

Expose silhouette-POM coverage and educational SSDM screen-offset
references on CPU/GLSL, and add a three-panel example that contrasts
classic POM, SilPOM UV clipping, and view-space SSDM-style relief.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Polish SilPOM/SSDM demo camera and UBO layout

Disable auto-orbit by default, use a frontal grazing pose for clearer
side-by-side comparison, shrink procedural textures for faster boot, and
align the compare shader Frame UBO with the full mesh3d layout.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Ignore runtime eve_inspect_cache for SilPOM/SSDM demo

Remove the generated MCP inspect frame artifacts from the example tree
and ignore that cache directory going forward.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Fix SSDM floor occlusion in the SilPOM comparison demo.

Write Vulkan ZO FragDepth without the OpenGL remap, never punch holes on
SSDM misses, seat the cards slightly above the floor, and fade relief at
the chart bottom so parallax no longer looks like the floor covers the wall.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Seal SSDM floor contact while keeping side silhouettes.

Out-of-chart SSDM hits discard on the left/right/top edges for silhouette,
but the bottom edge falls back to POM so the floor cannot show through the
contact line. Also soften rim lighting and fade relief near the chart base.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Switch SilPOM/SSDM demo to two-face dihedral corners.

A crease is where SilPOM chart discard opens gaps while SSDM-style
FragDepth keeps the intersection filled; each face is its own UV chart.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Drop unused flat-card ssdmSample from the corner compare shader.

Corner UV comes from per-face TBN/POM; the old local.xy chart helper
assumed a single XY plane and was dead after the dihedral switch.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Switch SilPOM/SSDM demo to brick cylinders for seam comparison.

Cylinder UV charts wrap in U (seam at 0/1) and open at top/bottom; SilPOM
discards off-chart samples while SSDM wraps U and keeps the seam filled via
FragDepth.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Implement full planar SilPOM and SSDM algorithms.

Replace the teaching approximations with steep POM + soft chart coverage,
horizon trim, height normals, self-shadow, and FragDepth for SilPOM, and
model-space heightfield raymarch through an extruded slab for planar SSDM.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Fix SilPOM mid-panel hollow mortar (镂空).

Horizon-trim + softCoverage discard punched holes through low mortar, and
packing softCoverage into the SSDM hit flag caused false misses. Switch
SilPOM to a solid planar heightfield march with border-only feather,
front-face miss fill, softer brick slopes, and forced texture rebuild.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Fix SilPOM mid-panel 镂空 from horizon discard and cliff tunnels.

SilPOM was discarding mortar via softCoverage×horizonTrim, and packing
softCoverage into the SSDM hit flag caused false misses. Both silhouette
modes now share a solid planar heightfield march with chart-fill on miss,
no coverage discard, softer brick ramps, texture/shader version invalidation,
and sendFloat integer casts so the demo stays alive under persist.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Clarify SilPOM mid-panel no longer uses horizon-trim discard.

Document that SilPOM and SSDM share the solid planar heightfield march;
remaining mid-panel shelling at grazing angles is view-dependent.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Document SilPOM hollow root cause and shared solid march.

Explain that horizon-trim discard caused mortar punch-through, and that
remaining mid-panel shelling at grazing angles is view-dependent.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Restore SilPOM/SSDM edge protrusion without interior 镂空.

SilPOM again uses steep POM with chart-border limb discard (not full-face
horizon trim). SSDM chart-fills front misses only; side misses discard so
brick caps form the extruded silhouette. Sharper brick heights and thicker
slabs bring the edge pop back.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Restore edge protrusion via side-face heightfield hits.

Hollow-fix chartFill on slab sides flattened the silhouette to a
rectangle. Side misses discard again so brick caps extrude; SilPOM keeps a
jagged brick-only side limb while SSDM keeps a continuous thickness
profile. Front mortar stays opaque (no rim height discard). Thicker slabs
and a slightly more oblique default camera make the edge pop visible.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Fix SilPOM/SSDM demo: hard flat bricks, no pillow height.

Soft sine height and soft mortar ramps made every brick a blob. Use binary
flat plateaus at 512² nearest, keep front geometric depth (no cliff shells),
and differentiate SilPOM jagged brick-cap limbs from SSDM continuous sides.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Differentiate SilPOM (POM front) from SSDM march; tame POM grazing.

SilPOM now shades the front with steep POM and only uses side-face
heightfield hits for jagged brick-cap limbs. SSDM keeps the full
geometric march. Grazing fade + linear albedo reduce left-card zebra
from hard cliff sampling; height stays nearest for flat plateaus.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Solid SilPOM front march again; adaptive cliffs; 1-texel bevel.

POM-on-front shredded mid-panel cliff walls versus SSDM. Share the solid
heightfield march for SilPOM/SSDM (side brick-cap discard still differentiates),
add adaptive near-surface steps, and a one-texel mortar bevel to cut POM zebra
without soft pillows.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* Tame classic POM relief scale on the left compare card.

Hard cliff heights still zebra under full POM scale; send about half
relief to mode 0 while SilPOM/SSDM keep the full slab thickness.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* List silpom-ssdm-compare in the examples overview table.

CI Source quality runs check_examples.py; the new demo directory was
missing from examples/README.md, which fails the example contract.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2026-09-18 11:29:17 +08:00
2026-09-15 10:02:14 +00:00
2026-09-15 19:26:55 +00:00

EVEngine

=======================

Evolutionary Vision Engine

中文版

Documentation

  • Want to see what the engine renders before running anything? Browse the example render gallery — every screenshot is a real presented frame written by the engine itself.
  • Game developer docs: download the engine, create and run a game, debug, and publish; the module handbook covers the script APIs and examples one by one.
  • Online API reference (Doxygen): published continuously to GitHub Pages; includes the C++ API and the user manual.
  • Engine developer docs: for engine maintainers and contributors — architecture, module design, testing strategy, and implementation notes.

For game developers: you do not need to compile EVEngine. Download the prebuilt SDK for your platform from the official release page, 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:

Status legend: ✅ shipped · 🟡 partially shipped · 🛠 roadmap (not implemented yet)

  1. ✅ A Love2D-style interpretive engine that loads scripts and data directly
  2. ✅ Many high-performance C++ modules; you can compile your own C++ libraries as shared libs and interact with them directly (see examples/native-plugin)
  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); scripts can build editing GUIs at runtime (see examples/terrain-editor)
  4. ✅ Built-in asset management and hot reload—no separate pipeline required
  5. 🛠 Class scanning with auto-generated editing GUIs (property reflection not landed yet; editor.Inspector currently registers fields manually—see roadmap)
  6. 🟡 GUIs that create and sync live from scripts (declarative ui module + hot reload; reflective two-way binding is on the roadmap)
  7. ✅ Pause the game loop for debugging (eve run --debug, F-keys / DAP / snapshots, see examples/devlab)
  8. 🟡 Independent state-machine models (e.g. animation) exist; systematic "edit code → affected state machines hot-update" support is on the roadmap
  9. ✅ Mixed 3D and 2D rendering

Fastest way to feel goals 3 / 4 / 7: make devlab (a developer-experience example that walks you through F4 / F6 / F7 / F9 and hot reload).

Built-in systems:

  1. 2D tilemap — with an extensible map editor
  2. 2D camera
  3. Simple database
  4. Box2D / Box3D physics
  5. RPG framework
  6. Extensible combat model components
  7. Dialogs and scripting
  8. Layered avatar rendering
  9. 2D fluid engine (Physics.newFluid2D; also interactive cloth via newCloth)
  10. Particle system
  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)

1. Download the engine from the official site

Go to the EVEngine release page, pick the latest stable release, and download the SDK archive for your target platform:

Target platform Download Notes
Windows eve-sdk-win32-<version>.zip Windows 10/11 x64
Linux eve-sdk-linux-<version>.zip Ubuntu 20.04+ etc. (requires a Vulkan driver)
macOS eve-sdk-macosx-<version>.zip macOS 12+ (Apple Silicon / Intel)
Android eve-sdk-android-<version>.zip Assemble an arm64 APK on a dev machine
iOS eve-sdk-ios-<version>.zip Assemble an arm64 .app on a macOS dev machine

Unzipping gives you a self-contained SDK directory — no installation required. Windows example:

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

# 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

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.

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 by EveScript (Squirrel-compatible). Start with the EveScript tutorial, then use the module handbook.
  • 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 <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 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
Git Any recent version Clone the repo; first configure may download third-party
CMake ≥ 3.21 Primary build system
C++ compiler C++20 MSVC / GCC / Clang
Vulkan SDK ≥ 1.2 Graphics backend; environment variables must be set correctly

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. Manual installs are usually unnecessary.

Windows

Component Recommended
OS Windows 10 / 11 (x64)
IDE / toolchain Visual Studio 2026 (with the “Desktop development with C++” workload)
CMake generator Visual Studio 18 2026 (matches the root Makefile)
Vulkan SDK Install from LunarG. Confirm user env VULKAN_SDK (e.g. C:\VulkanSDK\1.4.357.0) and add %VULKAN_SDK%\Bin to PATH (includes glslc). Open a new terminal / restart Cursor before running cmake
Optional Git for Windows; add CMake / Ninja to PATH

If you use Visual Studio 2022, change the generator in Makefile to "Visual Studio 17 2022".

Linux

Component Recommended
Distro Ubuntu 20.04+ or equivalent (including WSL2)
Compiler GCC 10+ or Clang 12+
Base packages build-essential, cmake, git, ninja-build, pkg-config
System libs X11 / SDL2: libx11-dev, libxext-dev, libxxf86vm-dev, libxrandr-dev, libxcursor-dev, libxi-dev, libxinerama-dev, libxss-dev; optional Wayland: libxkbcommon-dev, libwayland-dev; OpenAL/audio: libasound2-dev, libpulse-dev; image compression: zlib1g-dev, libpng-dev, libbz2-dev
Vulkan libvulkan-dev + glslang-tools (provides glslc), or install the full Vulkan SDK from LunarG

Ubuntu / WSL example:

sudo apt update
sudo apt install -y \
    build-essential cmake git ninja-build pkg-config \
    libx11-dev libxext-dev libxxf86vm-dev libxrandr-dev \
    libxcursor-dev libxi-dev libxinerama-dev libxss-dev \
    libxkbcommon-dev libwayland-dev \
    libgl1-mesa-dev libegl1-mesa-dev \
    libasound2-dev libpulse-dev \
    zlib1g-dev libpng-dev libbz2-dev libbrotli-dev \
    libvulkan-dev vulkan-tools glslang-tools \
    python3
# Or install the full Vulkan SDK per LunarG docs (includes validation layers)

macOS

Component Recommended
OS macOS 12+ (Apple Silicon / Intel)
Toolchain Xcode Command Line Tools (xcode-select --install)
CMake Homebrew: brew install cmake (≥ 3.21)
Vulkan Install the macOS Vulkan SDK from LunarG (includes MoltenVK) — build/development only; dist/eve-sdk/macosx bundles the Vulkan loader + MoltenVK, so player machines do not need the SDK

Set up the environment (run in each new terminal, or add to ~/.zshrc):

# Replace <version> with your local SDK folder name, e.g. 1.4.357.0
source ~/VulkanSDK/<version>/setup-env.sh
# Verify:
echo "$VULKAN_SDK"
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)

Component Recommended
Host macOS / Linux (Makefile paths default to macOS Homebrew)
JDK OpenJDK 17 (brew install openjdk@17)
Android SDK command-line tools + platform-tools + platforms;android-34 + build-tools;34.0.0
NDK 27.3.13750724 (sdkmanager "ndk;27.3.13750724")
CMake (SDK) cmake;3.22.1 (for Gradle; the engine itself cross-compiles with host CMake/Ninja)
ABI / minSdk arm64-v8a / 24
Device Physical device with Vulkan (emulator is not a v1 acceptance target)

Environment variables (add to ~/.zshrc or export before building):

export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"
export ANDROID_HOME="$HOME/Library/Android/sdk"
export ANDROID_NDK="$ANDROID_HOME/ndk/27.3.13750724"
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"

Write platform/android/apk/local.properties (do not commit):

sdk.dir=/Users/<you>/Library/Android/sdk

One-shot Debug APK build:

make build/android-debug
# Output: platform/android/apk/app/build/outputs/apk/debug/app-debug.apk

Pipeline: NDK CMake cross-builds third-party + libmain.so → sync/android-libs → sync/android-assets → Gradle assembleDebug.

Default ANDROID_GAME=demo: syncs platform/android/game-shell/ (no main.nut) into the APK and starts with the embedded eve.demoScript. To package an example directory:

make build/android-debug ANDROID_GAME=example
# Or refresh assets only:
make sync/android-assets ANDROID_GAME=example

On launch, the APK copies assets/game into the app’s internal storage and enters the existing CLI via run <internal path>.

Install / run / logs on device:

adb devices
make install/android-debug
make run/android-debug
make log/android

iOS / iPadOS (arm64 device, min 13.0)

Component Recommended
Host macOS + full Xcode (Command Line Tools alone are not enough; need iphoneos SDK)
Deployment target iOS / iPadOS 13.0+
Arch / device family arm64; TARGETED_DEVICE_FAMILY=1,2 (iPhone + iPad)
Vulkan LunarG SDK’s iOS/lib/MoltenVK.xcframework
Signing Apple Development; set IOS_DEVELOPMENT_TEAM=<TeamID>
Acceptance device Physical iPad (iPhone compatible); simulator is not a v1 target

One-shot Debug .app build:

# Team ID is auto-detected when signed into an Apple ID; or set manually:
#   security find-certificate -a -c "Apple Development" -p | openssl x509 -noout -subject
# Use OU=<TeamID> (the ID in parentheses in the certificate name is not the Team ID)
export IOS_DEVELOPMENT_TEAM=XXXXXXXXXX
make build/ios-debug

Pipeline: Xcode generator configures the iOS toolchain → cross-builds third-party (SDL UIKit static libs, etc.) → links/embeds MoltenVK → packs example/ into Resources/game → produces eve.app. If launched with no CLI args, injects run <Resources/game>.

Install / run / logs on device:

# Connect iPad over USB; enable Developer Mode and trust this computer
make install/ios-debug
make run/ios-debug
make log/ios

Optional vars: IOS_DEPLOYMENT_TARGET (default 13.0), IOS_BUNDLE_ID (default com.evengine.example), VULKAN_SDK.

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.
  5. v1 does not cover simulator, App Store distribution, or multi-arch fat binaries.

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/....

Notes:

  1. Install VS 2026 + Vulkan SDK on Windows; install the Linux toolchain and Vulkan inside WSL as above.
  2. Run make from the repo root: Windows targets use cmake.exe, Linux targets use WSL cmake.
  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

git clone --recurse-submodules https://github.com/EVEngine/EVEngine
cd EVEngine
# If you already cloned without submodules:
# git submodule update --init --recursive

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; IK uses external/ik.hpp.

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:

# Host-platform Debug / Release (Darwin → macosx, Linux → linux, Windows → win32)
make debug
make release

# Windows only
make build/win32
make build/win32-debug

# Linux only
make build/linux
make build/linux-debug

# macOS only (source Vulkan SDK setup-env.sh first)
make build/macosx
make build/macosx-debug

# Android arm64 Debug APK (needs ANDROID_HOME / ANDROID_NDK / JAVA_HOME)
make build/android-debug
make install/android-debug
make run/android-debug
make log/android

Faster local rebuilds

If sccache is installed and available on PATH, CMake detects it by default and caches each C/C++ translation unit. Nothing changes when it is unavailable. Use sccache --show-stats to inspect local hits, or configure explicitly with:

# Require sccache (configuration fails instead of silently falling back)
make build/win32-debug CMAKE_EXTRA_ARGS=-DEVENGINE_COMPILER_CACHE=SCCACHE

# Disable compiler-cache auto-detection
make build/win32-debug CMAKE_EXTRA_ARGS=-DEVENGINE_COMPILER_CACHE=OFF

Compiler caching still performs normal dependency evaluation and linking; it does not restore a CMake/Ninja/Make build tree. For a game that needs fewer systems, combine it with the existing module profiles so unused modules are not compiled at all:

make build/win32-debug \
  CMAKE_EXTRA_ARGS="-DEVENGINE_COMPILER_CACHE=SCCACHE -DEVENGINE_PROFILE=2d"

See module trimming for the minimal, 2d, 3d, full, and per-module options.

Inspect object-file growth and expensive public-header fanout after a local build with:

make stats/build                              # build/<host>-debug
make stats/build BUILD_STATS_DIR=build/linux # another build tree

The report lists the largest .o/.obj files, high-impact directly included project headers, and template-bearing headers. It is an explicit target rather than part of every incremental build, so collecting diagnostics does not slow normal development builds. The current top-20 review and the rationale for dependencies that remain are recorded in docs/dev/高引用头文件编译成本审计.md.

Output layout:

Target Build dir Notes
Win32 Release build/win32 VS project + Release binaries
Win32 Debug build/win32-debug Ninja + MSVC Debug binaries
Linux Release build/linux Unix Makefiles
Linux Debug build/linux-debug Unix Makefiles
macOS Release build/macosx Unix Makefiles + MoltenVK
macOS Debug build/macosx-debug Unix Makefiles + MoltenVK
Android Debug build/android-debug + Gradle APK NDK libmain.so → app-debug.apk
iOS Debug build/ios-debug (Xcode) eve.app + embedded MoltenVK for iPad/iPhone

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

1. Configure

Equivalent to the Makefile configure steps; you can also run manually.

Windows (Visual Studio 2026, x64):

cmake.exe -G "Visual Studio 18 2026" -A x64 -DCMAKE_BUILD_TYPE=Release -B build/win32 -S .
# Debug:
cmake.exe -G "Visual Studio 18 2026" -A x64 -DCMAKE_BUILD_TYPE=Debug -B build/win32-debug -S .

Linux:

cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -B build/linux -S .
# Debug:
cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -B build/linux-debug -S .

macOS:

source ~/VulkanSDK/<version>/setup-env.sh
cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_PLATFORM=macosx -B build/macosx -S .
# Debug:
cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DBUILD_PLATFORM=macosx -B build/macosx-debug -S .

Optional CMake variables:

Variable Default Notes
CMAKE_BUILD_TYPE Debug (if unset) Debug or Release; affects third-party install path suffixes (e.g. win32-debug)
BUILD_PLATFORM Auto from host win32 / linux / macosx, etc.
BUILD_TESTING ON Build unit tests
EVENGINE_COMPILER_CACHE AUTO AUTO uses sccache when found; SCCACHE requires it; OFF disables auto-detection
EVENGINE_SCCACHE_EXECUTABLE Auto from PATH Optional explicit path to sccache

2. Build third-party (deps)

Third-party code builds via custom targets deps / third-party. After configure:

# Windows Debug example
cmake.exe --build build/win32-debug --target deps -j 32

# Linux
cmake --build build/linux-debug --target deps -j 32

# macOS
cmake --build build/macosx-debug --target deps -j 32

The first third-party build takes a while. Outputs land in build/third-party/<platform>[-debug]/ and build/third-party-binary/<platform>[-debug]/. Later incremental builds reuse installed results.

3. Build the engine

# Windows (multi-config: pass --config)
cmake.exe --build build/win32 --config Release -j 32
cmake.exe --build build/win32-debug --config Debug -j 32

# Linux
cmake --build build/linux -j 32
cmake --build build/linux-debug -j 32

# macOS
cmake --build build/macosx -j 32
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

BUILD_TESTING is on by default. After building:

make test/win32-debug    # runs build/win32-debug/test/Debug/unit_test.exe
make test/win32          # Release tests
make test/linux-debug
make test/linux
make test/macosx-debug
make test/macosx

Or run unit_test / unit_test.exe from the corresponding path directly.

Docker (optional)

The repo includes an Ubuntu 20.04 Dockerfile (build-essential, cmake, clang-12, etc.) for an isolated Linux build:

docker build . --tag evengine
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

  1. CMake cannot find Vulkan
    Confirm the Vulkan SDK is installed and VULKAN_SDK points at the right path; on macOS, source ~/VulkanSDK/<version>/setup-env.sh before configure. Open a new terminal, then re-run cmake.

  2. Windows generator name mismatch
    The Makefile uses Visual Studio 18 2026. For VS 2022, change the generator string or upgrade the IDE.

  3. First deps is slow or network fails
    third-party is fetched from GitHub. You can manually git clone https://github.com/EVEngine/third-party into the repo-root third-party/, then reconfigure.

  4. CMAKE_BUILD_TYPE and third-party paths
    Debug / Release use different install dirs (with a -debug suffix). After switching build type, re-run deps in the matching directory.

  5. Parallelism
    The Makefile defaults to -j 32. On machines with fewer cores, use -j$(nproc) (Linux) / -j$(sysctl -n hw.ncpu) (macOS) or a smaller number to avoid OOM.

  6. macOS window / rendering fails
    If the error is Installed Vulkan doesn't implement the VK_KHR_surface extension (SDL's wording), the runnable Vulkan lacks surface support — on macOS that means MoltenVK was not loaded. For distributed builds, ship the lib/ folder from dist/eve-sdk/macosx (it contains libvulkan.1.dylib, libMoltenVK.dylib and MoltenVK_icd.json); eve points SDL and the loader at these bundled files at startup (bootstrapBundledVulkan in platform/macosx), so players do not need the SDK. For dev builds, confirm VK_ICD_FILENAMES points at the MoltenVK ICD (setup-env.sh sets this) and the SDK lib is on DYLD_LIBRARY_PATH. The engine uses SDL2 Vulkan surface + MoltenVK; no separate Metal backend is required.

  7. Android APK / device
    Match the NDK version to the Makefile; ensure local.properties sdk.dir is correct; enable USB debugging and check adb devices. v1 expects a Vulkan device; without one, at least verify make build/android-debug produces an APK.

  8. iOS / iPadOS device
    Full Xcode is required (xcode-select -p should point at Xcode.app/Contents/Developer, and xcrun --sdk iphoneos --show-sdk-path must work). Set IOS_DEVELOPMENT_TEAM, connect a trusted iPad/iPhone over USB. MoltenVK comes from the LunarG SDK’s iOS/lib/MoltenVK.xcframework.

Project layout (brief)

EVEngine/
├── CMakeLists.txt      # Root CMake: platform detect, third-party, subdirs
├── Makefile            # Windows / Linux / macOS / Android / iOS shortcuts
├── platform/           # Platform code and packaging (android/apk, ios Info.plist)
├── src/
│   ├── engine/         # Core, DevTools, CLI (Android libmain / iOS eve.app)
│   ├── modules/        # Feature modules
│   └── scripts/        # Script-side integration
├── test/               # Unit tests
├── third-party/        # Auto-downloaded third-party sources (can be pre-placed)
├── cmake/              # Helpers such as source scanning
└── docs/               # User docs (usr) and developer docs (dev)

Usage docs: docs/usr/. Design notes: docs/dev/.

License

EVEngine uses a dual license:

Use License file Cost
Open-source projects; or project Annual Revenue ≤ RMB 100,000 LICENSE-OPENSOURCE Free
Annual Revenue exceeding RMB 100,000 LICENSE-COMMERCIAL Paid; apply within 1 month after exceeding the threshold, or you may not continue use

See LICENSE for the overview. Commercial licensing: sunxfancy@gmail.com.

S
Description
A lightweight, script-driven game engine your AI can drive — download the SDK, then let your AI build the game.
https://evengine.github.io/
Readme
156 MiB
0 Stars 1 Watchers 0 Forks
Languages
C++ 94%
Python 2.3%
GLSL 1.1%
CMake 0.9%
Java 0.5%
Other 1%