simple-3d

What is simple-3d?

simple-3d is a high-level C++ game framework built as a clean wrapper around an Urho3D engine fork. It exposes a minimal, game-first API without requiring you to understand any of the underlying engine's internal types, subsystems, or component model.

Urho3D types (Urho3D::Node, Urho3D::Scene, Urho3D::Application, etc.) are never visible in the public headers. They are hidden behind PIMPL classes. The only exception is the math library — Vector2, Vector3, Color, Quaternion and friends are re-exported as Simple3D:: type aliases because they are ABI-identical and there is no benefit to wrapping them further.

The result: you write entity->AddRigidBody(1.0f) and simple-3d handles the Urho3D::RigidBody component, GetOrCreateComponent, collision mask setup, and physics world registration behind the scenes.

Why simple-3d?

Key Features

Architecture at a glance

Every public class in simple-3d uses the PIMPL idiom: the .h file declares struct Impl; and stores it in a unique_ptr<Impl>. The .cpp file defines Impl and can include any Urho3D header it needs. This guarantees that rebuilding the engine never forces recompilation of game code.

Full architecture documentation →

Quick Start (C++)

One header, one subclass, four methods — that is everything required for a complete interactive game.

#include <Simple3D/Simple3D.h>
using namespace Simple3D;

class MyGame : public Game {
public:
    Entity* player;
    Camera* camera;

    void Start() override {
        // ── Scene ────────────────────────────────────────────
        auto ground = CreateEntity("Ground");
        ground->AddModel("Models/Ground.mdl");
        ground->AddRigidBody(0.0f);                      // 0 = static
        ground->AddBoxCollider(Vector3(100, 1, 100));

        // ── Player ───────────────────────────────────────────
        player = CreateEntity("Player");
        player->AddModel("Models/Character.mdl");
        player->AddAnimationController();
        player->AddRigidBody(70.0f);
        player->AddCapsuleCollider(0.4f, 1.75f);
        player->SetPosition(0, 2, 0);
        player->AddScript("Scripts/player.lua");

        // ── Lighting ─────────────────────────────────────────
        auto sun = CreateEntity("Sun");
        sun->AddDirectionalLight(Color(1.0f, 0.95f, 0.85f), 1.0f);
        sun->SetRotation(Quaternion(50, -30, 0));

        // ── Camera ───────────────────────────────────────────
        camera = CreateCamera();
        camera->Follow(player, 6.0f, 2.5f);
        camera->SetSmoothFollow(true, 7.0f);
        camera->SetCollisionEnabled(true);

        // ── Audio ────────────────────────────────────────────
        PlayMusic("Music/theme.ogg");
    }

    void Update(float dt) override {
        if (IsKeyDown(Key::Escape)) Quit();
    }
};

int main() {
    return CreateGame<MyGame>()->Run();
}

Build instructions →  ·  Full C++ API reference →

Lua Script Example

Attach scripts to individual entities. Each script has its own isolated Lua state with access to the owning entity, input, audio, and scene. Scripts are hot-reloadable at runtime.

-- Scripts/player.lua
-- Loaded via entity->AddScript("Scripts/player.lua") in C++

speed     = 6    -- m/s horizontal movement
jumpForce = 8    -- impulse on Space
local anim         -- AnimationController reference

function Start()
    entity = self.node   -- Simple3D convention: alias self.node
    anim   = entity:GetAnimationController()
end

function Update(dt)
    local move = Vector3(0, 0, 0)

    if Input:IsKeyDown("W") then move.z = move.z + 1 end
    if Input:IsKeyDown("S") then move.z = move.z - 1 end
    if Input:IsKeyDown("A") then move.x = move.x - 1 end
    if Input:IsKeyDown("D") then move.x = move.x + 1 end

    if move:Length() > 0 then
        entity:MoveRelative(move:Normalized() * speed * dt)
        anim:Play("run", 0, true, 0.2)
    else
        anim:Play("idle", 0, true, 0.2)
    end

    if Input:IsKeyPress("Space") and entity:IsOnGround() then
        entity:ApplyImpulse(Vector3(0, jumpForce, 0))
        PlaySound("Sounds/jump.wav")
    end
end

Full Lua API reference →  ·  More examples →

Module Status

Backends

The same simple-3d source works with two different engine backends. Switch with a single CMake variable; no changes to game code are needed.

cmake -S . -B build \
  -DSIMPLE3D_ENGINE=U3D \
  -DU3D_HOME=/path/to/u3d/build

cmake -S . -B build \
  -DSIMPLE3D_ENGINE=NOVA3D \
  -DNOVA3D_HOME=/path/to/nova3d/build

Comparison with Direct Urho3D Use

License

simple-3d is open source. See the LICENSE file in the repository for the full text. The underlying Urho3D fork (U3D) is distributed under the MIT license.