mirror of
https://github.com/johndoe6345789/SDL3CPlusPlus.git
synced 2026-04-24 13:44:58 +00:00
136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```lua
|
|
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
|
|
|
|
```lua
|
|
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:
|
|
```bash
|
|
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:
|
|
```lua
|
|
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
|