Easy3D v0.1.0

Documentation

Easy3D is a small C++23 helper library for CNA, an XNA 4.0-style runtime. It is a companion library that lives next to CNA — not on top of it, and not in front of it. It provides a handful of boring, practical helpers (cameras, billboard/cube batching, a texture atlas, debug drawing) so that small 3D projects can be written against CNA without re-inventing the same glue code every time.

Easy3D's first concrete purpose is to support Galaxy Eggbert, a planned 3D remake of Mobile Eggbert / Speedy Blupi, without dragging in a full engine or a heavy 3D abstraction layer.

What Easy3D is

A small helper library for CNA.
A collection of minimal, testable utility classes.
Used beside CNA: a game uses CNA directly and uses Easy3D where it helps.
Free to accept and return CNA / XNA-style types (Vector3, Matrix, …) wherever that is convenient.

What Easy3D is not

It is not a replacement for CNA — CNA remains the runtime.
It does not hide CNA. CNA types stay fully visible in Easy3D APIs.
It is not a general game engine and must not grow into one.
It has no entity/component framework, physics, navigation, networking, editor, asset database, resource cache, model importer, or plugin system.

See Design Principles for the reasoning behind these boundaries.

The big picture

Galaxy Eggbert (game) — drives the game loop, devices, input via CNA directly

↓ uses

Easy3D — cameras, billboard/cube batching, texture atlas, debug draw

↓ depends on

CNA — XNA 4.0-style runtime (Microsoft::Xna::Framework)

Easy3D depends on CNA; nothing in CNA depends on Easy3D. A game depends on both and is free to call CNA directly whenever Easy3D does not help. Details in Architecture.

Helpers at a glance

Camera3D

A minimal free-look perspective camera producing CNA view/projection matrices.

OrbitCamera

Turntable camera: yaw/pitch/distance orbit around a target point.

FollowCamera

Frame-rate-independent smoothed follow camera (target + offset + smoothing).

TextureAtlas

Named sub-rectangles of one texture, spritesheet grids, normalized UV lookup.

BillboardBatch

Queues camera-facing quads (sprites in 3D space) for later drawing.

CubeBatch

Queues axis-aligned cubes / tiles for later drawing (block terrain).

CubeMesh

Turns queued cubes into CPU-side vertex/index arrays — no GPU work.

DebugDraw

Queues debug lines and boxes for development overlays.

Version

Compile-time and run-time version information.

A taste of the API

The point of Easy3D is the shape of its API: the game still drives CNA directly (game loop, GraphicsDevice, input, …). Easy3D only helps with cameras, batching, atlases, and debug drawing — and CNA Matrix values come straight back out.

// The game still uses CNA directly for the Game loop, devices, input, etc.
// Easy3D only helps with cameras, billboard/cube drawing, atlases, debug draw.
#include <Easy3D/Easy3D.hpp>

using Vector3 = Easy3D::Camera3D::Vector3;   // = Microsoft::Xna::Framework::Vector3

Easy3D::Camera3D camera;
camera.SetPosition(Vector3(0.0f, 3.0f, 8.0f));
camera.SetTarget(Vector3::Zero);

const auto view       = camera.GetViewMatrix();        // Microsoft::Xna::Framework::Matrix
const auto projection = camera.GetProjectionMatrix();

// A small, CNA-free texture atlas (e.g. Blupi sprite frames).
Easy3D::TextureAtlas atlas(256, 256);
atlas.Add("blupi_idle_0", Easy3D::AtlasRect{0, 0, 32, 48});
const Easy3D::UvRect uv = atlas.GetUv("blupi_idle_0");

// Queue a billboard (camera-facing quad) that samples that atlas region.
Easy3D::BillboardBatch billboards;
billboards.Begin();
billboards.Add(Vector3(1.0f, 0.5f, 0.0f), {1.0f, 1.5f}, uv);
billboards.End();

Current status

Cameras exist and work: Camera3D, OrbitCamera, FollowCamera.
TextureAtlas supports named rects, grid spritesheet insertion (AddGrid), and a non-throwing lookup (GetUvOrDefault).
BillboardBatch, CubeBatch, and DebugDraw store queued data (BillboardItem / CubeItem / DebugLine + DebugBox) for later use.
CubeMesh turns queued cubes into plain CPU-side vertex/index arrays (Roadmap Phase 3).
Rendering (issuing actual CNA draw calls) is intentionally not implemented yet — see the Roadmap.

Easy3D grows only as far as Galaxy Eggbert actually needs it. If a feature is not needed soon, it is not built. This is a deliberate, documented policy — not an accident of youth.

Where to go next

Getting Started — clone, build, and run the tests in a couple of minutes.
Building & CMake — the three CNA linkage modes and all CMake options.
Architecture — how Easy3D relates to CNA and why linking matters.
Minimal Example — a walkthrough of the bundled example program.
Recipes — practical patterns: sprite billboards, cube terrain, camera rigs.