Nebula Dreamcast Engine

Nebula Dreamcast Engine is an open-source 3D game engine purpose-built for the Sega Dreamcast. Build your scenes in the project editor, write your gameplay scripts in plain C, and package directly to CDI disc images that boot on real hardware.

Highlights

• Dreamcast-first runtime path with rapid package/rebuild loops
• Editor-driven content workflow (scenes, meshes, textures, materials)
• Deterministic asset staging names for reliable disc lookup
• Runtime safety fallbacks to avoid hard crashes on missing texture refs

Current Status

Active development / prototyping, with a working Dreamcast package flow and hardware-focused iteration.

Dependencies

Windows Editor / Tooling

• Visual Studio 2022 + Native Tools x64
  • Required for MSVC/cl.exe build flows.
  • Install "Desktop development with C++" workload.
• CMake + CMake GUI
  • Used to configure/generate Visual Studio solution files.
• Git
  • Source sync and branch workflows.

Dreamcast Build Toolchain

• DreamSDK (KallistiOS toolchain)
  • Provides Dreamcast compile/link/package tools (e.g. sh-elf-gcc, kos-cc, mkisofs, CDI tooling).
  • Required for building nebula_dreamcast.elf and packaging CDI output.
  • WARNING: DreamSDK must be fully installed with KOS toolchain, or the Dreamcast CDI build will fail.

Quick checks

where cl
cmake --version
where sh-elf-gcc
where kos-cc

Dreamcast Runtime Notes

• Runtime staged data is packaged under:
  • build_dreamcast/cd_root/data/materials
  • build_dreamcast/cd_root/data/meshes
  • build_dreamcast/cd_root/data/scenes
  • build_dreamcast/cd_root/data/textures
  • build_dreamcast/cd_root/data/animations
  • build_dreamcast/cd_root/data/vmu
• Scene/mesh/texture/animation staging uses short deterministic names:
  • Scenes: Sxxxxx.*
  • Meshes: Mxxxxx.*
  • Textures: Txxxxx.*
  • Animations: Axxxxx.*
• Missing scene texture refs can fall back safely at runtime.
• Missing/unloadable textures use fallback white texture instead of hard exit.
• Material refs are staged to data/materials for packaging parity.

Repository Layout

• src/ - engine source (directory guide)
  • camera/ - camera math and viewport utilities
  • editor/ - editor application, shared state, preferences
  • io/ - file format loaders and exporters
  • math/ - math primitives and utility functions
  • navmesh/ - navigation mesh building
  • nodes/ - scene node type definitions
  • platform/dreamcast/ - Dreamcast codegen and KOS bindings
  • runtime/ - play-mode physics, collision, script bridge
  • scene/ - scene serialization and management
  • ui/ - ImGui editor panels
  • viewport/ - 3D viewport rendering and gizmos
  • vmu/ - VMU icon tool
• assets/ - project assets
• thirdparty/ - vendored dependencies (GLFW, ImGui, Recast/Detour)
• build_dreamcast/ - generated Dreamcast runtime/package output (project-local)
• docs/ - engine documentation

Documentation

See docs/README.md for the full documentation index and learning path.

• Quickstart Tutorial — build, create a project, write a script, run on Dreamcast
• Source Directory Structure — module layout and dependency flow
• Scripting — C gameplay scripts and NB_RT_* API reference
• Dreamcast Binding API v2 — all NB_RT_*, NB_DC_*, NB_KOS_* runtime APIs
• Dreamcast Export — codegen, packaging, disc layout
• Dreamcast Header Reference — platform header files and types
• Script Formatting & Syntax — how to write C gameplay scripts
• Multi-Script Runtime — running multiple gameplay scripts simultaneously
• Editor Play Mode — compilation, DLL caching, progress bar, hot reload, scene switching
• Asset Pipeline — texture, material, mesh, and animation formats and export
• Dependencies & Paths — toolchain setup and path requirements

File Formats

• .nebproj - project file
• .nebscene - scene file
• .nebmesh - mesh format
• .nebtex - texture format
• .nebmat - material reference file
• .nebslots - StaticMesh material-slot manifest
• .nebanim - vertex animation clip format

Compile (Windows Editor) — CMake GUI + Visual Studio

Prerequisites

• Visual Studio 2022 (Desktop development with C++)
• CMake (and CMake GUI)
• Git

CMake GUI configure/generate

1. Open CMake GUI.
2. Set:
   • Where is the source code: <repo>/ (this folder)
   • Where to build the binaries: <repo>/build
3. Click Configure.
4. Choose generator:
   • Visual Studio 17 2022
   • Platform: x64
5. Let configure finish (fix any missing dependency prompts if shown).
6. Click Generate.
7. Click Open Project (opens the generated .sln in Visual Studio).

Compile in Visual Studio

1. Set NebulaEditor as the startup project (Solution Explorer → right-click NebulaEditor → Set as Startup Project).
2. Set configuration to Debug or Release.
3. Set platform to x64.
4. Build:
   • Build → Build Solution (Ctrl+Shift+B)
5. Run from Visual Studio (or run built exe from build/...).

Command-line alternative (optional)

cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

Build / Package (Dreamcast)

General flow:

1. Open project in editor
2. Export/package Dreamcast build
3. Run _nebula_build_dreamcast.bat in build_dreamcast
4. Test nebula_dreamcast.cdi (emulator/hardware)
5. Iterate

Quick analysis of what _nebula_build_dreamcast.bat runs:

• Cleans prior ELF output (rm -f nebula_dreamcast.elf)
• Compiles C sources to objects (main.c, bindings/input files, and script .c files)
• Links objects into nebula_dreamcast.elf with kos-cc
• Builds disc image data (mkisofs)
• Generates final CDI image for emulator/hardware testing (cdi4dc)

Exact environment/toolchain setup may vary by local DreamSDK/KOS install.

Preferences Path Hooks (Toolchain Fallbacks)

If default toolchain detection fails on your machine, set custom paths in:

• File -> Preferences

Fields:

• DreamSDK
  • Path to your DreamSDK root (example: C:\DreamSDK)
  • Used by Dreamcast build packaging scripts when generating/running _nebula_build_dreamcast.bat
• MSVC
  • Path to either:
    • a Visual Studio root folder (example: C:\Program Files\Microsoft Visual Studio), or
    • a direct vcvars batch file path (vcvarsall.bat / vcvars64.bat)
  • Used by script runtime compile fallback when cl.exe is not already in PATH

Nebula validates these paths in Preferences and shows status (OK/missing). Save preferences to persist them in editor_prefs.ini.

Roadmap Direction

• Keep editor/runtime parity tight
• Harden scene/material-slot serialization consistency
• Continue exporter/import cleanup for geometry stability
• Preserve pragmatic runtime behavior over feature bloat

Learning Path

New to the engine? See the Learning Path for a recommended reading order.

License

TODO: add license