Architecture

Easy3D / Guide / Architecture

Easy3D is a companion library, not an engine. It sits beside CNA: a game still creates and drives its CNA Game, devices, graphics device, and input directly. Easy3D only removes repetitive glue — cameras, billboard/cube batching, a texture atlas, debug drawing.

The big picture

Galaxy Eggbert
  -> uses CNA directly
  -> uses Easy3D helpers
  -> may use Mobile Eggbert as existing reference/library/data source

Easy3D
  -> depends on CNA
  -> does not hide CNA
  -> contains helper classes only

CNA
  -> XNA 4.0-style runtime and future CNA/NOXNA extensions

Dependency direction

galaxy-eggbert ──depends on──> easy-3d ──depends on──> cna
        │                                               ▲
        └───────────────── also depends on ─────────────┘
                       (uses CNA directly too)

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.

Principles

Easy3D APIs may expose CNA types

It is normal and encouraged for Easy3D functions to take or return Microsoft::Xna::Framework::Vector3, Matrix, and friends. Easy3D must not invent parallel math types that hide CNA, and must not wrap CNA objects just to rename them. The one deliberate exception: TextureAtlas uses two small Easy3D-local PODs (AtlasRect, UvRect) because pixel/UV rectangles are not CNA concepts — this also keeps it CNA-free and unit-testable on its own.

The intended design — CNA stays in charge

// A bad design (Easy3D hiding everything):
Easy3D::Game game;
game.RunEverything();   // NO — this is not what Easy3D is for

// The intended design (CNA stays in charge, Easy3D just helps):
Easy3D::Camera3D     camera;
Easy3D::OrbitCamera  orbit;
Easy3D::TextureAtlas atlas;

Eggbert-specific rules stay out of Easy3D

Anything that only makes sense for Galaxy Eggbert / Mobile Eggbert — tile meanings, Blupi animation tables, level formats, gameplay rules — belongs in those projects, never in Easy3D. Likewise, Mobile Eggbert is an existing, working reference and is not refactored just because Galaxy Eggbert (or Easy3D) would find it convenient.

How Easy3D consumes CNA

CNA's public headers are under ../cna/include (namespace Microsoft::Xna::Framework).
CNA's CMake library target is named CNA — a STATIC library built with C++23. It links SHARP_RUNTIME, a graphics backend target, and (privately) SDL3 / ffmpeg.
CNA math types such as Vector3 and Matrix are declared in headers but defined in CNA's compiled .cpp files. Therefore:
- The easy3d static library compiles against CNA headers alone.
- Code that actually executes CNA math (e.g. Camera3D::GetViewMatrix()) must link the CNA library at final link time.
Easy3D's CMake resolves CNA linkage three ways — parent-provided target, standalone -DEASY3D_LINK_CNA=ON, or headers-only. When CNA is linked, EASY3D_HAS_CNA_LINK is defined. Full details on Building & CMake.
Easy3D does not depend on sharp-runtime directly, even though CNA does (it comes in transitively when CNA is linked).

Sibling repository layout

.../openeggbert/
  ├── cna/            <- required: the CNA runtime (headers under cna/include)
  ├── sharp-runtime/  <- optional: used by CNA; Easy3D does NOT depend on it (yet)
  └── easy-3d/        <- the Easy3D repository

Anatomy of the library

The public API is thirteen headers under include/Easy3D/. Eleven of them are pulled in by the umbrella header Easy3D.hpp; BillboardMesh.hpp and BillboardMeshRenderer.hpp are deliberately not — include those two directly.

Header	Provides	CNA at runtime?	In umbrella?
`Easy3D/Version.hpp`	Version macros, constants, `VersionString()`	No	Yes
`Easy3D/Camera3D.hpp`	`Camera3D`	Yes (matrices)	Yes
`Easy3D/OrbitCamera.hpp`	`OrbitCamera`	Yes	Yes
`Easy3D/FollowCamera.hpp`	`FollowCamera`	Yes	Yes
`Easy3D/TextureAtlas.hpp`	`TextureAtlas`, `AtlasRect`, `UvRect`	No (CNA-free)	Yes
`Easy3D/BillboardBatch.hpp`	`BillboardBatch`, `BillboardItem`	Stores CNA types	Yes
`Easy3D/BillboardMesh.hpp`	`BillboardVertex`, `AppendBillboardMesh`, `BuildBillboardMesh`	Yes (Vector3 math)	No
`Easy3D/BillboardMeshRenderer.hpp`	`BillboardMeshRenderer`	Yes (GPU draw)	No
`Easy3D/CubeBatch.hpp`	`CubeBatch`, `CubeItem`	Stores CNA types	Yes
`Easy3D/CubeMesh.hpp`	`CubeVertex`, `AppendCubeMesh`/`BuildCubeMesh`, `DirectionalCubeItem`, `PlateItem`, `TripleCrossItem`, `PyramidTipItem`	Yes (Vector3 math)	Yes
`Easy3D/CubeMeshRenderer.hpp`	`CubeMeshRenderer`	Yes (GPU draw)	Yes
`Easy3D/DebugDraw.hpp`	`DebugDraw`, `DebugLine`, `DebugBox`	Stores CNA types	Yes

The data-first pipeline

Easy3D is being built in deliberate phases (see the Roadmap). The batching classes are data recorders, not renderers:

1. Queue data — BillboardBatch / CubeBatch / DebugDraw store plain items (done)

↓

2. Build CPU-side geometry — BuildCubeMesh() / BuildBillboardMesh() → std::vector of vertices/indices (done for cubes & billboards; debug lines/boxes remain)

↓

3. CNA renderer adapters — CubeMeshRenderer / BillboardMeshRenderer upload buffers, issue real CNA draw calls (done for cubes & billboards; debug lines/boxes remain)

This kept every step testable without a GPU until it actually needed one, and deferred the concrete CNA draw-path decision to the phase that actually needed it. Debug line/box drawing is the one shape that hasn't made it through this pipeline yet.

What Easy3D is deliberately NOT

No ECS, no generic engine object hierarchy, no Lua, no physics, no navigation, no networking, no editor, no asset database, no resource cache, no model importer, no plugin system, no PBR renderer. If one of these starts to appear, it is a sign Easy3D is drifting toward being an engine — stop and reconsider. See Design Principles.