Procedural Mesh Generation

Generate game-ready 3D meshes with proper UVs and normals for Nethercore ZX.

Prerequisites

Blender 3.0+ must be installed and in PATH:

blender --version

Run mesh generation via: blender --background --python .studio/generate.py -- --only meshes

Spec-Based Workflow

Write one mesh spec per file under .studio/specs/meshes/:

# .studio/specs/meshes/barrel.spec.py
MESH = {
    "mesh": {
        "name": "barrel",
        "primitive": "cylinder",
        "params": {"radius": 0.45, "depth": 1.1, "vertices": 24},
        "modifiers": [{"type": "bevel", "width": 0.02, "segments": 2}],
        "uv": {"mode": "smart_project", "angle_limit": 66.0},
        "export": {"tangents": True},
    }
}

Generate with:

blender --background --python .studio/generate.py -- --only meshes

Workflow Selection

Hard Surface Quick Reference

Core Primitives:

• bpy.ops.mesh.primitive_cube_add() - Crates, boxes
• bpy.ops.mesh.primitive_cylinder_add() - Barrels, pillars
• bpy.ops.mesh.primitive_uv_sphere_add() - Spheres, domes
• bpy.ops.mesh.primitive_cone_add() - Spikes, cones
• bpy.ops.mesh.primitive_torus_add() - Rings, wheels

Key Modifiers: MIRROR, BEVEL, SOLIDIFY, ARRAY, BOOLEAN, DECIMATE

See references/bpy-modifiers.md for detailed modifier patterns.

Console Constraints

Texture resolution: Power-of-2 only (64, 128, 256, 512)

Required Post-Processing

Every mesh MUST have before export:

1. UV unwrap - smart_project or cube_project
2. Normals - shade_smooth + use_auto_smooth
3. Cleanup - remove_doubles, delete_loose
4. Triangulate - quads_convert_to_tris
5. Export - GLB with export_normals=True

See references/bpy-post-processing.md for implementation.

File Organization

One mesh spec per file:

.studio/specs/meshes/
├── barrel.spec.py
└── crate.spec.py

generated/meshes/
├── barrel.glb
└── crate.glb

nether.toml Integration

[build]
script = "blender --background --python .studio/generate.py -- --only meshes && cargo build -p game --target wasm32-unknown-unknown --release"

[[assets.meshes]]
id = "barrel"
path = "../generated/meshes/barrel.glb"

Tangent Export (for Normal Maps)

If using normal maps, enable tangents:

mesh.calc_tangents()  # Requires UVs
bpy.ops.export_scene.gltf(
    filepath="output.glb",
    export_tangents=True
)

See references/bpy-tangent-export.md for complete workflow.

Quality Checklist

• Triangle count within budget
• UVs unwrapped (no overlapping)
• Normals consistent (no inverted faces)
• No loose geometry
• Triangulated
• Correct scale (1 unit = 1 meter)
• Origin at logical point
• Tangents if using normal maps