Welcome to Plume3D

Plume3D is a scriptable 3D game engine for building games and tools with a small, immediate-style API. You write game logic in Wren; the engine handles windowing, rendering, audio, and (optionally) physics via modular integrations. Design resolution and scale modes (stretch, letterbox, integer) give you control over aspect ratio and pixel-perfect scaling.

Integrations

The engine is built from a small core plus integrations that each handle a major subsystem. Scripts see a unified API; the host wires these together.

Integration	Purpose
Wren	Scripting. Runs your game: loads the main script, exposes the engine API as foreign classes (Engine, Logger, Mesh, Input, Window, Graphics, Audio, Scene, Node, Camera, Light, Raycast, Config, Resource, etc.), and drives the lifecycle — init(), update(dt), draw().
Vulkan	Rendering. Draws meshes and UI: loads SPIR-V shaders, manages vertex/index buffers, records draw calls from Wren, and provides a Nuklear Vulkan backend so the GUI (windows, buttons, labels, edit fields) is rendered with Vulkan.
OpenAL	Audio. 3D positional audio: creates sources from mounted files (WAV, MP3, OGG, FLAC), play/stop/pause, per-source volume/pitch/position/cone/attenuation, and global listener position/orientation for spatial sound.
Jolt	Physics. Optional physics: one system per scene, collision matrix from game.toml, create/destroy bodies from nodes, step simulation, and sync transforms back. Used for raycasts and physics queries when enabled.

Platform and I/O are abstracted: SDL3 is used on desktop for window and input; a console port would swap in another implementation behind the same abstractions.

Libraries

The engine uses these vendor libraries for shaders, file access, GUI, and config:

Library	Purpose
Slang	Shaders. Compiles .slang shader source to SPIR-V for Vulkan. Apps ship compiled .spv files; the engine can watch source and recompile on change when hot-reload is enabled.
PhysicsFS	Virtual filesystem. Mounts the game directory or a .zip/.p3d archive as the project root so all asset and script loading (shaders, Wren, audio, TOML, blends) goes through one path.
Nuklear	Immediate-mode GUI. Single-header UI toolkit for windows, layout, labels, buttons, and edit fields. The Vulkan integration provides a Nuklear backend so Wren’s Gui API draws with Vulkan.
TomlPlusPlus	TOML parsing. Reads game.toml and engine.toml for window, design size, scale mode, physics layers, collision matrix, and other config; used by the host and config_toml module.

Modules

Supporting modules (used by the host and integrations) provide:

Module	Purpose
app_package	Resolves the game path (directory, game.toml file, or .zip/.p3d archive) into a mount root for PhysicsFS so the engine can load assets and scripts from the project.
blend_load	Loads Blender .blend files (via Kaitai Struct): parses scene data, objects, cameras, lights, materials, textures, and mesh data so the engine can instantiate hierarchies and render them.
config_toml	Parses game.toml and engine.toml: window size, design resolution, scale mode, physics tag/collision layer names, and collision matrix.
audio_load	Decodes audio from memory (WAV, MP3, OGG/Vorbis, FLAC) into PCM for OpenAL. Used with PhysicsFS so all file access stays on the mounted project.
hotreload	Polling-based file change detection: watches config and script files by mtime so the engine can reload games and shaders during development without restarting.

Tools

Tool	Purpose
Blender addon	Lets you attach Wren class and config path references to objects and collections in Blender. The addon stores config path, script path, class name, Node Id, and tag/collision layers in the .blend; the engine loads config and scripts from the project and instantiates your classes. Save the .blend after configuring so the engine sees the metadata.

Getting started

New to Plume3D? The Getting Started guide walks you through:

1. Download the binaries — Downloads or Releases (platform archives); extract and run plume3d . from your app folder.
2. Download the Blender addon — Downloads or Blender addon; install in Blender to attach Wren scripts and config to objects and collections.
3. Write an initial app — Create a folder with game.toml and main.wren, implement the Game lifecycle (init, update, draw), and run it with plume3d ..

Next steps

• API Reference — Full Wren API: Engine, Logger, Mesh, Input, Window, Graphics, Gui, Audio, Config, Resource, Scene, Node, Camera, Light, Raycast, Animation, Math.
• Examples — Run and learn from the example apps (aspect ratio, audio, GUI, mesh, blend loading, 3D radio, etc.).
• Build the engine — Clone the Plume3D engine repo, run git submodule update --init --recursive, then cmake --workflow --preset default. Example apps live under apps/; run from an app directory with ./plume3d ..