SDL3CPlusPlus/docs/SCENE_FRAMEWORK.md

Scene Framework

A reusable Lua framework for 3D scene construction in SDL3CPlusPlus.

Overview

scene_framework.lua provides commonly-used utilities for building 3D scenes:

• Mesh Generation: Planes, cubes, and primitives
• Object Builders: Standardized scene object creation with metadata
• Config Utilities: Type-safe configuration resolution
• Material Registry: Centralized material/shader management

Usage

local scene_framework = require("scene_framework")

-- Generate a tessellated floor
local vertices, indices = scene_framework.generate_plane_mesh(20, 20, 20, {1.0, 1.0, 1.0})

-- Create a static cube object
local cube = scene_framework.create_static_cube(
    {0, 5, 0},          -- position
    {2, 2, 2},          -- scale
    {1.0, 0.5, 0.2},    -- color
    "solid",            -- shader_key
    "my_cube"           -- object_type
)

-- Config resolution with fallbacks
local speed = scene_framework.resolve_number(config.move_speed, 5.0)
local position = scene_framework.resolve_vec3(config.spawn_point, {0, 0, 0})

API Reference

Mesh Generation

generate_plane_mesh(width, depth, subdivisions, color)

Generates a tessellated plane with normals pointing up (+Y).

• Returns: vertices, indices (0-based indices)
• Example: 20x20 subdivisions = 441 vertices, 800 triangles

generate_cube_mesh(double_sided)

Generates a unit cube (-0.5 to 0.5) with proper normals per face.

• Single-sided: 24 vertices, 36 indices
• Double-sided: 24 vertices, 72 indices

apply_color_to_vertices(vertices, color)

Copies vertex array and applies new color to all vertices.

flip_normals(vertices)

Inverts normals in-place (useful for ceilings, inside-out geometry).

Object Builders

create_static_object(vertices, indices, position, scale, shader_key, object_type)

Creates a static scene object with no animation.

create_static_cube(position, scale, color, shader_key, object_type, cube_mesh)

Convenience builder for colored cube objects.

create_dynamic_object(vertices, indices, compute_fn, shader_key, object_type)

Creates animated object with compute_fn(time) -> matrix callback.

Config Utilities

• resolve_number(value, fallback) - Safe number extraction
• resolve_boolean(value, fallback) - Safe boolean extraction
• resolve_string(value, fallback) - Safe string extraction
• resolve_table(value, fallback) - Safe table extraction
• resolve_vec3(value, fallback) - Safe {x,y,z} extraction

Transform Utilities

build_static_model_matrix(position, scale)

Builds transformation matrix from position {x,y,z} and scale {sx,sy,sz}.

Material Registry

local registry = scene_framework.MaterialRegistry.new(config)

if registry:has("floor") then
    local material = registry:get("floor")
    local shader_key = registry:get_key("floor")  -- Returns key or default
end

Testing

Run the test suite:

cd scripts && lua test_scene_framework.lua

65 tests covering:

• Config resolution edge cases
• Mesh generation correctness
• Object builder metadata
• Material registry lookups

Integration

See cube_logic.lua for real-world usage:

local scene_framework = require("scene_framework")

-- Delegate to framework
local function generate_plane_mesh(width, depth, subdivisions, color)
    local vertices, indices_zero = scene_framework.generate_plane_mesh(width, depth, subdivisions, color)
    -- Convert 0-based to 1-based indices for Lua
    local indices = {}
    for i = 1, #indices_zero do
        indices[i] = indices_zero[i] + 1
    end
    return vertices, indices
end

Benefits

• DRY: Fix mesh generation bugs once, benefit everywhere
• Consistency: All scenes use same object structure with object_type
• Testability: Framework tested independently in Lua
• Discoverability: New scenes see available primitives via documentation
• Type Safety: Config resolution prevents nil dereferences

Future Enhancements

Potential additions:

• generate_sphere_mesh() for skyboxes, particles
• generate_cylinder_mesh() for columns, barrels
• Physics object helpers with mass/friction
• Texture coordinate generation utilities