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, Physics, Config, Resource, AnimationState, InstancedMesh, ParticleEmitter, CharacterController, etc.), and drives the lifecycle — init(), update(dt), draw().
Vulkan	Rendering. Draws meshes and UI: loads SPIR-V shaders, manages vertex/index buffers, PBR materials with shadow mapping, GPU instancing via SSBO, skeletal skinning via bone matrix SSBO, records draw calls from Wren, and provides a Nuklear Vulkan backend so the full GUI 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/Doppler for spatial sound.
Jolt	Physics. Full physics integration: rigid bodies (static/kinematic/dynamic) with multiple shapes, constraints (fixed/hinge/slider/cone/6DOF), character controller, contact event callbacks, raycasts, and complete Wren API for forces, impulses, velocities, and simulation control.

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.

Roadmap

Current capabilities and planned milestones: what’s in place, what’s still coming, and longer-term direction.

What’s in place

• RenderingVulkan, PBR (Cook–Torrance), base color + UV, triplanar fallback, shadow mapping (up to 4 maps, configurable resolution/bias), debug view modes
• SceneScene graph, nodes, transforms, cameras, lights (point/sun/spot/hemi/area); findNodeById, tag/collision-layer system
• ContentBlender 5 .blend loader: meshes, materials, UVs, animations, armatures, physics bodies, particles, blend instantiation
• ScriptingWren API: Scene, Mesh, Camera, Light, Input, Raycast, Physics, Resource, AnimationState, InstancedMesh, ParticleEmitter, CharacterController, Gui, etc.
• InputSDL3: keyboard, mouse, 4 gamepads, touch; “just pressed” state
• AudioOpenAL: 3D positional audio, HRTF, Doppler, seek/tell, source clone, WAV/MP3/OGG/FLAC
• PhysicsJolt: static/dynamic/kinematic bodies, box/sphere/capsule/mesh shapes, constraints (hinge, slider, cone, 6DOF), contact events, full Wren API (forces, impulses, velocities, raycast, pause)
• Character ControllerCapsule-based CharacterVirtual (Jolt): ground detection, step, jump, state machine (idle/walk/run/jump/fall/swim/crouch), configurable speeds
• AnimationKeyframe/FCurve from Blender: AnimationState, blend layers, crossfade, events (Blender markers), drivers, skeletal (bone hierarchy, skinning matrices)
• ParticlesTier 2 Jolt physics particles: body pool, emission rate, burst, play/stop/pause; rendered via instanced mesh
• Instanced MeshGPU instancing via SSBO: up to 65K instances per draw, per-instance position/transform/scale, dynamic updates, visibility toggle
• GUIFull Nuklear API: themes, fonts, layouts (dynamic/static/template/space), sliders, knobs, combos, trees, popups, menus, charts, color picker, custom drawing
• Configgame.toml, class-based scripts (e.g. Radio, GameCamera), hot reload
• LightingMultiple lights (point/sun/spot/area) with shadow casting; Graphics.setLights + shadow mapping controls

---

Short-Term: Indie-level (small–medium 3D)

• Material texturesNormal map, roughness/metallic texture maps — PBR structure in place; texture samplers not yet wired to Wren.
• ScriptingCoroutines or async for “wait then…” so Wren can drive animation, timed events, and AI without blocking.
• AudioOptional reverb zones (OpenAL EFX extension); environmental audio effects.
• Save/loadSerialize scene or game state (e.g. toml + Wren API) for checkpoints/settings.
• Frustum cullingSkip meshes outside camera frustum (scene graph + bounds).
• Basic LODOptional: swap mesh by distance (single LOD fine for many indies).
• Rendering robustnessBack-face culling, depth pre-pass, alpha/double-sided handling.

---

Long-Term: AA-level (larger scope, higher fidelity)

• Lighting pipelineMany lights (deferred or clustered forward), CSM, point cubemap shadows, contact shadows.
• Global illuminationLight probes, SSAO, simple reflection (probes or SSR).
• Post-processingBloom, tone mapping, DoF, motion blur, color grading.
• Asset pipelineMore formats (FBX/glTF), texture compression (ASTC/BC), clear “cook” step for release.
• Level streamingLoad/unload scene chunks by region; async asset loading.
• Occlusion cullingPVS or GPU occlusion to skip hidden objects.
• LOD systemMultiple LODs per model, selection by distance/screen size, optional impostors.
• Animation+Blend trees, IK, runtime retargeting.
• Physics+Ragdolls, vehicles, trigger volumes.
• TerrainHeightmap or splat terrain, texture splatting, optional foliage.
• UI scaleScale Nuklear to complex HUD/menus; layout, themes, localization.
• Profiling / toolsFrame profiler, scene inspector, Blender-centric workflow tools.

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.
Vaultis	A companion desktop asset manager for game developers (macOS/Windows/Linux). Discovers Unity Asset Store packages (.unitypackage, .zip, .tar), imports them into a local vault, provides 3D model and audio previews, and exports assets to engine projects (Unity, Unreal, Godot, or custom — suitable for Plume3D). See vaultis.wyldmagic.gg for more.

Getting started

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

1. Get the binaries — Email hello@wyldmagic.gg or see Get Plume3D; extract and run from your app folder.
2. Get the Blender addon — Email hello@wyldmagic.gg to request the addon zip; 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, Physics, CharacterController, InstancedMesh, ParticleEmitter, Animation, Math.
• Examples — Run and learn from the example apps (aspect ratio, audio, GUI, mesh, blend loading, 3D radio, etc.).
• Licensing — License terms for the Plume3D engine, this documentation site, and third-party components.