AsterEngine

A modern, ECS-based 3D game engine built with C++ and Metal for macOS

Features • Architecture • Getting Started • Building • Usage • Documentation

📸 Screenshots

AsterEditor - Full-featured game editor with hierarchy, inspector, and project panels

Real-time 3D scene rendering with transform gizmos and debug visualization

✨ Features

Core Engine

Pure ECS Architecture - Entity Component System for data-driven game development
Metal Rendering Backend - High-performance graphics via Apple's Metal API
Real-time 3D Rendering - Modern rendering pipeline with PBR material support
Scene Management - Complete scene serialization and deserialization system
Asset Management - Automatic asset discovery and import system
Transform Hierarchy - Parent-child entity relationships with world-space transformations
Camera System - Free-look camera with WASD movement and mouse controls

Editor Features

Visual Editor - Native macOS editor built with AppKit
Hierarchy Panel - Tree view of scene entities with drag-and-drop support
Inspector Panel - Component-based property editing
Project Panel - Asset browser with import functionality
Transform Gizmos - Interactive 3D manipulation of entities
Debug Overlay - Real-time performance metrics and statistics
Welcome Window - Project management (create, open, recent projects)

Asset Pipeline

Mesh Import - Universal 3D model loader supporting:
- OBJ format (with Assimp)
- FBX, GLTF, COLLADA (extensible)
Texture Import - Image loading via STB Image
Procedural Primitives - Built-in mesh generation:
- Cube, Sphere, Plane
- Cylinder, Cone, Torus, Capsule

Component System

Transform - Position, rotation, scale with hierarchical support
Mesh - Geometry reference (primitive or imported)
Material - PBR properties (albedo, metallic, roughness)
MeshRenderer - Visibility and rendering control
Name - Entity naming for editor display

🏗️ Architecture

Overview

AsterEngine follows a modular, layered architecture designed for maintainability and extensibility:

┌─────────────────────────────────────────────────────────┐
│                     Applications                         │
│  ┌────────────────┐              ┌──────────────────┐  │
│  │  AsterEditor   │              │   Game Runtime   │  │
│  │   (AppKit UI)  │              │  (Custom Client) │  │
│  └────────────────┘              └──────────────────┘  │
└──────────────────────┬───────────────────┬──────────────┘
                       │                   │
┌──────────────────────┴───────────────────┴──────────────┐
│                   Engine Runtime                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  ECS Core (Registry, Components, Systems)        │  │
│  ├──────────────────────────────────────────────────┤  │
│  │  Scene Management & Serialization                │  │
│  ├──────────────────────────────────────────────────┤  │
│  │  Asset Manager (Meshes, Textures, Materials)     │  │
│  ├──────────────────────────────────────────────────┤  │
│  │  Rendering System (Camera, Debug Draw, Gizmos)   │  │
│  ├──────────────────────────────────────────────────┤  │
│  │  Editor Bridge (C API for UI interop)            │  │
│  └──────────────────────────────────────────────────┘  │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────┴─────────────────────────────┐
│              Rendering Hardware Interface (RHI)          │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Abstract Interface (Device, Pipeline, Buffer)   │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Metal Backend (DeviceMetal, BufferMetal, etc.)  │  │
│  └──────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Entity Component System (ECS)

The engine uses a sparse-set based ECS for optimal performance:

// Entities are lightweight IDs
using EntityId = uint32_t;

// Components are pure data (no logic)
struct Transform {
    Vec3 position, rotationEuler, scale;
    Mat4 worldMatrix;
    EntityId parent;
};

// Systems operate on component combinations
for (EntityId entity : registry.GetEntitiesWith<MeshRenderer>()) {
    const Transform* transform = registry.Get<Transform>(entity);
    const Mesh* mesh = registry.Get<Mesh>(entity);
    const Material* material = registry.Get<Material>(entity);
    // Render entity...
}

Key Benefits:

O(1) component lookup
Cache-friendly iteration
Data-driven design
Easy to extend with new components

Rendering Pipeline

┌──────────────────────────────────────────────────────────┐
│ 1. Scene Query: Get entities with MeshRenderer component │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────┐
│ 2. Component Gather: Collect Transform, Mesh, Material   │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────┐
│ 3. Resource Binding: Load meshes/textures on-demand      │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────┐
│ 4. Metal Draw Calls: Indexed rendering with instancing   │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────┐
│ 5. Debug Overlay: Gizmos, grid, statistics               │
└──────────────────────────────────────────────────────────┘

RHI Abstraction

The Rendering Hardware Interface (RHI) provides a clean abstraction over graphics APIs:

namespace aster::rhi {
    struct Device;      // GPU device management
    struct Swapchain;   // Present surface
    struct Pipeline;    // Shader program + state
    struct Buffer;      // GPU buffer (vertex/index/uniform)
    struct Texture;     // 2D/3D textures
    struct CommandList; // Command recording
}

Current Implementation: Metal (macOS)
Future Targets: Vulkan (cross-platform), DirectX 12 (Windows)

Project Structure

AsterEngine/
├── src/
│   ├── engine/
│   │   ├── ecs/              # Entity Component System
│   │   │   ├── Entity.h      # Entity ID type definitions
│   │   │   ├── Registry.h    # Component storage & queries
│   │   │   └── Components.h  # Component definitions
│   │   ├── scene/            # Scene management
│   │   │   ├── Scene.h       # Scene container
│   │   │   └── SceneSerializer.h  # Save/load scenes
│   │   ├── runtime/          # Core engine systems
│   │   │   ├── Engine.h      # Main engine class
│   │   │   ├── Camera.h      # Camera controller
│   │   │   ├── AssetManager.h    # Asset loading
│   │   │   ├── MeshLoader.h      # Mesh import (OBJ, etc.)
│   │   │   └── PrimitiveAssets.h # Procedural meshes
│   │   ├── render/           # Rendering utilities
│   │   │   ├── DebugDraw.h   # Debug line rendering
│   │   │   └── GizmoAxis.h   # Transform gizmos
│   │   ├── rhi/              # Graphics abstraction
│   │   │   └── Pipeline.h    # RHI interface
│   │   ├── editor/           # Editor-engine bridge
│   │   │   └── EditorBridge.h    # C API for UI
│   │   └── platform_macos/   # Platform layer
│   │       └── AppHost.mm    # Window & event handling
│   ├── rhi/
│   │   └── metal/            # Metal implementation
│   │       ├── DeviceMetal.mm
│   │       ├── CommandListMetal.mm
│   │       └── ...
│   ├── apps/
│   │   └── editor/           # Editor application
│   │       ├── EditorApp.mm  # Editor entry point
│   │       └── ui/           # UI panels (AppKit)
│   └── main.cpp              # Game runtime entry
├── third_party/              # External dependencies
│   ├── stb_image.h           # Image loading
│   └── assimp/               # 3D model import
├── resources/                # App resources
├── docs/                     # Documentation
└── CMakeLists.txt            # Build configuration

🚀 Getting Started

Prerequisites

macOS 11.0+ (Big Sur or later)
Xcode 13+ with Command Line Tools
CMake 4.0+
Homebrew (for dependencies)

Dependencies

Install required libraries via Homebrew:

brew install cmake assimp

Quick Start

Clone the repository:

git clone https://github.com/N3ur0sis/AsterEngine.git
cd AsterEngine

Create build directory:
```
mkdir build && cd build
```
Configure with CMake:
```
cmake ..
```
Build the project:
```
cmake --build .
```
Run the editor:
```
open AsterEditor.app
```

🔨 Building

Build Targets

The project produces three targets:

AsterEditor - Full-featured game editor
AsterEngine - Minimal game runtime
engine_runtime / engine_rhi_metal - Static libraries

Build Configuration

# Debug build (default)
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build .

# Release build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

CMake Options

set(CMAKE_CXX_STANDARD 23)           # C++23 features
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Build Outputs

build/
├── AsterEditor.app/        # Editor application bundle
├── AsterEngine.app/        # Game runtime bundle
├── libengine_runtime.a     # Core engine library
└── libengine_rhi_metal.a   # Metal rendering backend

📖 Usage

Creating a New Project

Launch AsterEditor.app
Click "Create New Project"
Choose a name and location

The editor creates:

MyProject/
├── Assets/
│   └── Meshes/
├── Scenes/
│   └── SampleScene.json
└── MyProject.aproj

Importing Assets

Method 1: Drag & Drop

Drag .obj, .fbx, or image files into the Project Panel

Method 2: Import Menu

Right-click in Project Panel → "Import Asset..."
Select files to import

Scene Editing

Creating Entities:

Right-click in Hierarchy → "Create Empty" or "Create Primitive"
Entities are created with Transform component by default

Adding Components:

Select an entity
Click "Add Component" in Inspector
Choose: Mesh, Material, or MeshRenderer

Transform Manipulation:

W - Translate gizmo
E - Rotate gizmo
R - Scale gizmo

Camera Controls:

Right-click + drag - Look around
WASD - Move camera
Q/E - Move up/down
Scroll - Adjust speed

Scripting (C++ API)

Create a custom game client:

#include "runtime/AppHost.h"
#include "runtime/Engine.h"

class MyGame : public AppClient {
    aster::Engine engine;
    
    void OnStartup() override {
        // Initialize engine
        engine.Initialize(surface, 1920, 1080);
        engine.LoadScene("Assets/Scenes/MainScene.json");
        
        // Create entities programmatically
        aster::Scene* scene = engine.GetScene();
        auto entity = scene->CreateEntity("Player");
        scene->AddComponent(entity, aster::Mesh{aster::PrimitiveMeshType::Sphere});
        scene->AddComponent(entity, aster::MeshRenderer{});
    }
    
    void OnUpdate(double dt) override {
        engine.Update(dt);
    }
    
    void OnRender() override {
        engine.Render();
    }
};

int main() {
    MyGame game;
    AppConfig cfg{"My Game", 1920, 1080};
    return RunApp(game, cfg);
}

📚 Documentation

Core Concepts

Component System Architecture - ECS design and patterns
Mesh Import System - Asset pipeline details

API Reference

Engine Core

class Engine {
    bool Initialize(const PlatformSurface& surface, int w, int h);
    void Update(double dt);
    void Render();
    
    Scene* GetScene();
    Camera* GetCamera();
    AssetManager* GetAssetManager();
    
    void NewScene(const std::string& name = "New Scene");
    bool LoadScene(const std::filesystem::path& path);
    bool SaveScene(const std::filesystem::path& path);
};

Scene Management

class Scene {
    EntityId CreateEntity(const char* name = nullptr);
    void DestroyEntity(EntityId entity);
    
    template<typename T>
    T& AddComponent(EntityId entity, T&& component);
    
    template<typename T>
    T* GetComponent(EntityId entity);
    
    Registry& GetRegistry();
};

ECS Registry

class Registry {
    EntityId CreateEntity();
    void DestroyEntity(EntityId entity);
    
    template<typename T>
    T& Add(EntityId entity, T&& component);
    
    template<typename T>
    T* Get(EntityId entity);
    
    template<typename T>
    bool Has(EntityId entity);
    
    template<typename... Components>
    std::vector<EntityId> GetEntitiesWith();
};

🎯 Roadmap

Current Features ✅

✅ ECS architecture with sparse-set storage
✅ Metal rendering backend
✅ Scene serialization (JSON)
✅ OBJ mesh import via Assimp
✅ Native macOS editor
✅ Transform gizmos
✅ Project management
✅ Asset browser and import

In Progress 🚧

🚧 PBR material system
🚧 Texture import and management
🚧 FBX/GLTF model support

Planned 📋

📋 Physics system (RigidBody, Collider components)
📋 Lighting system (Point, Directional, Spot lights)
📋 Shadow mapping
📋 Post-processing stack
📋 Audio system (3D spatial audio)
📋 Animation system
📋 Particle system
📋 Scripting (Lua/Python integration)
📋 Vulkan backend (Windows/Linux support)
📋 Scene runtime (playmode)
📋 Build pipeline (game export)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

Follow the existing code style (C++23, modern practices)
Keep components as data-only (no logic)
Use the ECS pattern for new features
Add documentation for public APIs
Test on macOS before submitting

Areas for Contribution

Rendering: Implement PBR shading, shadows, post-processing
Physics: Integrate a physics library (Bullet, Jolt)
Animation: Skeletal animation system
Tools: Additional editor panels and tools
Platform: Vulkan/DirectX backends
Documentation: Tutorials, examples, API docs

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Third-Party Libraries

Assimp - Open Asset Import Library
STB - Single-file public domain libraries
Apple Metal - High-performance graphics API

Inspiration

Unity - ECS workflow and editor design
Unreal Engine - Asset management patterns
Godot - Scene system architecture

Made with ❤️ using C++23 and Metal

Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
docs/images		docs/images
resources		resources
src		src
third_party		third_party
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation