ZEngine

<p align="center"> <a href="https://zentia.github.io"> <img src="engine/source/editor/resource/ZEngine.png" width="400" alt="Z Engine logo"> </a> </p>

Z Engine is a tiny game engine.

Recent Updates (February 2026)

• Enhanced Profiling: Memory profiling for C#, Lua, and native code with detailed UI
• Scripting Support: Improved Lua and JavaScript/TypeScript integration via Puerts
• Editor Tools: New console window and better resource management
• Serialization: Complete binary serialization system with TypeTree reflection
• Build Improvements: Precompiled headers for faster compilation

See CHANGELOG.md for detailed version history.

Key Features

Core Engine

• Multi-platform Support: Windows, Linux, and macOS
• Vulkan Renderer: Modern graphics API with validation layers
• Physics: Integrated Jolt Physics engine
• Asset Pipeline: Complete asset management and bundle system

Scripting

• Lua Integration: Full Lua scripting support with profiling
• Puerts Support: JavaScript/TypeScript scripting via Puerts
• C# Scripting: Managed scripting with memory profiling

Editor

• Visual Editor: ImGui-based editor interface
• Console Window: Built-in console for debugging
• Project Management: Asset browser and hierarchy viewer
• Timeline Editor: Animation and sequencing tools
• Inspector: Property editing and component management

Developer Tools

• Profiling: Memory and performance profilers for all scripting languages
• Serialization: Binary and JSON serialization with reflection
• Virtual File System: Flexible file system abstraction
• Hot Reload: Asset and script hot reloading support

Continuous build status

| Build Type | Status | | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | Build Windows | | | Build Linux | | | Build macOS | |

Prerequisites

To build Z, you must first install the following tools.

Windows 10/11

• Visual Studio 2022 (or more recent)
• CMake 3.19 (or more recent)
• Git 2.1 (or more recent)

macOS >= 10.15 (x86_64)

• Xcode 12.3 (or more recent)
• CMake 3.19 (or more recent)
• Git 2.1 (or more recent)

Ubuntu 20.04

• apt install the following packages

sudo apt install libxrandr-dev
sudo apt install libxrender-dev
sudo apt install libxinerama-dev
sudo apt install libxcursor-dev
sudo apt install libxi-dev
sudo apt install libglvnd-dev
sudo apt install libvulkan-dev
sudo apt install cmake
sudo apt install clang
sudo apt install libc++-dev
sudo apt install libglew-dev
sudo apt install libglfw3-dev
sudo apt install vulkan-validationlayers
sudo apt install mesa-vulkan-drivers

• NVIDIA driver (The AMD and Intel driver is open-source, and thus is installed automatically by mesa-vulkan-drivers)

Build ZEngine

Build on Windows

You may execute the build_windows.bat. This batch file will generate the projects, and build the Release config of ZEngine automatically. After successful build, you can find the ZEditor.exe at the bin directory.

Or you can use the following command to generate the Visual Studio project firstly, then open the solution in the build directory and build it manually.

cmake -S . -B build

Build on macOS

The following build instructions only tested on specific hardware of x86_64, and do not support M1 chips. For M1 compatible, we will release later.

To compile Z Engine, you must have the most recent version of Xcode installed. Then run 'cmake' from the project's root directory, to generate a project of Xcode.

cmake -S . -B build -G "Xcode"

and you can build the project with

cmake --build build --config Release

Or you can execute the build_macos.sh to build the binaries.

Build on Ubuntu 20.04

You can execute the build_linux.sh to build the binaries.

Documentation

For documentation, please refer to the Wiki section.

Extra

Vulkan Validation Layer: Validation Error

We have noticed some developers on Windows encounted ZEditor.exe could run normally but reported an exception Vulkan Validation Layer: Validation Error when debugging. You can solve this problem by installing Vulkan SDK (official newest version will do).

Generate Compilation Database

You can build compile_commands.json with the following commands when Unix Makefiles generaters are avaliable. compile_commands.json is the file required by clangd language server, which is a backend for cpp lsp-mode in Emacs.

For Windows:

cmake -DCMAKE_TRY_COMPILE_TARGET_TYPE="STATIC_LIBRARY" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S . -B compile_db_temp -G "Unix Makefiles"
copy compile_db_temp\compile_commands.json .

Using Physics Debug Renderer

Currently Physics Debug Renderer is only available on Windows. You can use the following command to generate the solution with the debugger project.

cmake -S . -B build -DENABLE_PHYSICS_DEBUG_RENDERER=ON

Note:

1. Please clean the build directory before regenerating the solution. We've encountered building problems in regenerating directly with previous CMakeCache.
2. Physics Debug Renderer will run when you start ZEditor. We've synced the camera position between both scenes. But the initial camera mode in Physics Debug Renderer is wrong. Scrolling down the mouse wheel once will change the camera of Physics Debug Renderer to the correct mode.

Coding Style Guide

📖 详细文档: 完整的命名规范请参考 CODING_STYLE.md

C++ Naming Conventions

Namespaces

• Use uppercase initials, keep names short
• Example: namespace Z

Classes

• Use PascalCase (capitalize first letter of each word)
• Use nouns or noun phrases
• Example: class MemoryManager, class RuntimeGlobalContext

Functions

• Use camelCase (first word lowercase, capitalize first letter of subsequent words)
• Begin with verbs or verb phrases
• Example: initialize(), createObject(), destroyObject()

Member Variables

• Prefix with m_ followed by snake_case
• Example: m_window, m_is_quit, m_average_duration

Static Members

• Prefix with s_ followed by snake_case
• Example: s_fps_alpha

Global Variables

• Prefix with g_ followed by snake_case
• Example: g_runtime_global_context, g_is_editor_mode

Constants

• Use all uppercase with underscores
• Example: MAX_BUFFER_SIZE, DEFAULT_WINDOW_WIDTH

Enums

• Enum type names use PascalCase
• Enum values use lowercase (preferred) or UPPER_CASE
• Example:

enum class LogLevel {
    debug,
    info,
    warn,
    error,
    fatal
};

Parameters and Local Variables

• Use snake_case
• Be descriptive but concise
• Example: float delta_time, int frame_count, WindowCreateInfo create_info

Interface Classes

• Prefix with 'I' followed by PascalCase
• Example: class IRenderer, class ISystem

File Names

• Use lowercase with underscores
• Headers use .h extension
• Source files use .cpp extension
• Example: memory_manager.h, render_system.cpp

Macros

• Use all uppercase with underscores
• Add project prefix for project-specific macros
• Example: Z_ASSERT, Z_ENABLE_LOGGING

Template Parameters

• Use simple capital letters or meaningful PascalCase names
• Example:

template<typename T>
template<typename KeyType, typename ValueType>

Boolean Variables

• Prefix with is, has, can, should, etc.
• Example: isVisible, hasChildren, canUpdate

Private Methods

• Follow normal function naming rules
• Optionally use underscore suffix for private
• Example: calculateBounds_, updateInternal_

General Principles

1. Maintain consistency throughout the project
2. New code should follow existing conventions
3. Refactor inconsistent naming during major updates
4. Prioritize clarity and readability over brevity