FAQ

Easy3D / Examples / FAQ

Does Easy3D actually draw anything yet?

Yes, for two of the three shapes. Easy3D was built in deliberate phases: the batching classes (Phase 2) store plain data, vertex builders (Phase 3) turn that data into CPU-side geometry, and renderer adapters (Phase 4) issue actual CNA draw calls. Cubes and billboards have made it all the way through: CubeMeshRenderer and BillboardMeshRenderer upload real GPU buffers and call GraphicsDevice::DrawIndexedPrimitives, verified end-to-end against a real windowed Galaxy Eggbert binary. Debug lines/boxes have not — DebugDraw still only queues plain data, with no vertex builder or renderer adapter yet (no concrete consumer has needed one). The phased approach kept every step testable without a GPU and deferred the concrete CNA draw-path decision (BasicEffect + raw VertexBuffer/IndexBuffer, not SpriteBatch) to the phase that actually needed it. See the Roadmap.

My cube/billboard faces are invisible (or I only see the inside of the level). What's wrong?

Almost certainly a winding-convention mismatch, if you're building geometry by hand alongside Easy3D's. Every shape in CubeMesh and BillboardMesh is wound so its first triangle's cross(v1-v0, v2-v0) points into the solid — the opposite of the OpenGL-textbook "counter-clockwise from outside" rule. This matches CNA's real culling behavior: under the default RasterizerState::CullCounterClockwise, the surviving triangles are the ones that look visually clockwise on screen. Easy3D got this wrong in an earlier version (faces were invisible from outside, and scenes only "looked right" by showing the mirrored interiors of opposite faces) — see CubeMesh's winding section for the full story before you "fix" it back to the textbook convention.

Why are CNA types exposed in the API instead of wrapped?

Because Easy3D is a companion, not an abstraction layer. Hiding CNA behind Easy3D types would make Easy3D a middleman for everything — exactly the engine-shaped drift the project guards against. Easy3D functions take and return Microsoft::Xna::Framework::Vector3, Matrix, and friends directly, so the values plug straight into the CNA code your game already writes. The reasoning is spelled out in Design Principles.

I get linker errors like undefined reference to Vector3::Vector3(float, float, float). What's wrong?

You are executing CNA math without linking the CNA library. CNA's math types are declared in headers but defined in CNA's compiled .cpp files, so the code compiles and then fails at link time. Fixes:

Full details on Building & CMake.

Do I need to build all of CNA (SDL3, ffmpeg, …) just to use Easy3D?

No — that's the point of the default build. It compiles the easy3d library against CNA's headers only and runs the CNA-free tests. You only pay for the full CNA build when your executable actually runs CNA math (cameras, batch item construction), which for a real game is true anyway.

I included <Easy3D/Easy3D.hpp> but BillboardMesh/BillboardMeshRenderer aren't found. Why?

Those two headers are deliberately left out of the umbrella header — include <Easy3D/BillboardMesh.hpp> and <Easy3D/BillboardMeshRenderer.hpp> directly. Every other public header (including CubeMesh.hpp and CubeMeshRenderer.hpp) is in the umbrella; see the header table on Architecture for the full list.

Is TextureAtlas really usable without CNA?

Yes — completely. TextureAtlas deliberately uses its own small PODs (AtlasRect, UvRect) and never touches CNA types. It builds, runs, and is unit-tested in the default headers-only build.

Will Easy3D get Lua scripting?

Not currently. Lua is intentionally out of scope for this version. If it is ever approved, it would be an optional, separate module (working name easy3d-lua) — and no Lua code lands before that explicit approval. See the Roadmap, Phase 6.

Will Easy3D load 3D models?

No — Easy3D stays billboard / cube / tile only for the first Galaxy Eggbert versions. A model importer is one of the recorded hard limits; whether Easy3D should ever load models is at most a future discussion. See Design Principles.

What are Galaxy Eggbert, Mobile Eggbert, and Blupi?

Speedy Blupi (a.k.a. Speedy Eggbert) is a classic 2D platformer; Mobile Eggbert is an existing remake of it in the same project family. Galaxy Eggbert is a planned 3D remake — and Easy3D's first concrete consumer. The plan: Blupi rendered as a billboard from existing Mobile Eggbert sprite frames, levels as cube/tile terrain. All Eggbert-specific logic (tile meanings, animation tables, gameplay) lives in the game, never in Easy3D.

How does Easy3D relate to Simple3D / Nova-3D / MeshCraft?

They are earlier, larger 3D abstraction attempts in the same project family. Easy3D is explicitly not them and must not grow back into them — no ECS, no engine object hierarchy, no model pipeline. They serve as conceptual lessons only; their code is never copied into Easy3D.

Why is FollowCamera's smoothing defined against 1/60 s?

The smoothing value means "fraction of the remaining gap closed per 1/60 s of elapsed time" — a fixed reference that makes the value frame-rate independent (30, 60, and 144 fps all behave the same). The 60 is kept for continuity with tuning done when the project's game loop targeted 60 fps and is part of the value's contract. The math is on the FollowCamera page.

What license is Easy3D under?

Easy3D is licensed under the MIT License. CNA itself is licensed under the Microsoft Public License (Ms-PL); Easy3D only uses CNA's public headers — it does not copy CNA source.

Can I contribute a feature?

Keep it small, boring, and testable — and check the Roadmap and Design Principles first. Features on the hard-limit list (ECS, physics, model import, Lua, …) need explicit approval from the project owner before any code. If a helper only makes sense for Galaxy Eggbert or Mobile Eggbert, it belongs in that project instead. When you add behavior that can be tested without linking all of CNA, add a small test (see Testing), and keep the default build green.