3D Models from Blender
Prepare static, skinned, and animated 3D models in Blender 4.x or convert FBX and OBJ assets into glTF 2.0 (.glb/.gltf) matching NSGo's 3D conventions, verified against two committed round-trip sample models.
NSGo's 3D rendering layer is Stage 2 of the overview (nsgo#1059). The conventions and glTF 2.0 asset contract on this page let you author, convert, and validate 3D assets ahead of time so they load cleanly without re-exporting.
NSGo 3D conventions
NSGo adopts the standard glTF 2.0 coordinate system and physical units across every 3D package:
| Property | Convention | Notes |
|---|---|---|
| Handedness | Right-handed | Matches glTF 2.0 and OpenGL/Metal/Vulkan view math |
| Axes | +X right, +Y up, -Z forward |
Characters and vehicles face -Z in local space |
| Units | Meters (1.0 = 1 m) |
Human character ≈ 1.7–1.8 units tall; physics and lighting assume meters |
| Front-face winding | Counter-clockwise (CCW) | Outward normals satisfy (v1 - v0) × (v2 - v0) · n > 0 |
| Texture UVs | Origin (0, 0) at top-left |
Standard glTF 2.0 UV layout; Blender's glTF exporter flips V automatically |
| PBR workflow | Metallic-Roughness | Principled BSDF base color, metallic, roughness, normal, occlusion, emissive |
| Runtime format | Binary glTF 2.0 (.glb) |
Single self-contained file with aligned binary buffers; use .gltf for JSON inspection |
| Skinning limit | 4 bone influences per vertex | One JOINTS_0 / WEIGHTS_0 VEC4 attribute per vertex, normalized to sum to 1.0 |
Project layout for 3D assets
Keep runtime .glb files inside resources/ so nsgo build bundles them on all six targets and your game loads them via "asset:...". Keep heavy authoring files (.blend, .fbx, .obj, .psd) outside resources/ (for example in art/) so they never inflate release packages:
mygame/
├─ art/ # authoring sources, not shipped in builds
│ ├─ crate.blend
│ └─ robot_arm.blend
├─ resources/ # packaged with every target ("asset:...")
│ └─ models/
│ ├─ crate.glb
│ └─ robot_arm.glb
└─ nsgo.yaml
See Building and Shipping for using mobile.exclude_resources when desktop and mobile builds ship different LODs or texture sizes.
Blender 4.x export checklist
Blender uses a right-handed Z-up viewport (+X right, +Y into screen, +Z up). When you export with +Y Up enabled, Blender's glTF 2.0 exporter rotates the scene -90° around X so Blender's +Z becomes +Y and Blender's -Y (Front View, Numpad 1) becomes -Z forward in glTF.
Before exporting (every asset)
- Set metric units: in Scene Properties → Units, set Unit System to
Metricand Unit Scale to1.0. Verify the object's dimensions in meters in the N sidebar (Item → Dimensions). - Face
-Yin Blender: orient characters, weapons, and vehicles so their front faces-Y(looking toward you in Front Orthographic View, Numpad1). After+Y Upexport, they face-Zforward. - Place the pivot cleanly: put static props and characters with their base or feet resting at
(0, 0, 0)so spawning aty = 0places them flush on the floor. - Apply transforms: select the mesh (and armature for rigged assets) and press
Ctrl+A → Rotation & Scale(plusLocationfor origin-anchored props). Never export with negative scale (-1), which flips triangle winding inside out. - Check face orientation: enable Viewport Overlays → Face Orientation. Every visible outside surface must be blue. If any faces appear red, enter Edit Mode, select all (
A), and runMesh → Normals → Recalculate Outside(Shift+N). - Use
Principled BSDF: wire textures intoBase Color,Metallic,Roughness,Normal(via aNormal Mapnode), andEmission. Bake procedural Blender shader nodes (Noise, Voronoi, ColorRamp) to image textures before exporting; procedural Blender nodes do not exist in glTF.
Static meshes (.glb)
Open File → Export → glTF 2.0 (.glb/.gltf) and verify these settings:
- Format:
glTF Binary (.glb). - Include: enable
Selected Objects(orActive Collection) so cameras, lights, and guide empties stay out of the asset. - Transform: check
+Y Up. - Data → Mesh:
- Check
Apply Modifiers(bakes Subdivision, Mirror, Bevel, and Weighted Normal modifiers). - Check
UVsandNormals. - Check
Tangentsif the material uses a normal map (avoids tangent-space mismatches across renderers). - Uncheck
Vertex Colorsunless your shader reads them.
- Check
- Data → Material:
Materials: Export, images asAutomatic(PNG/JPEG) orWebPwhere supported. - Data → Compression: leave Draco mesh compression unchecked by default so the
.glbloads directly in pure-Go glTF readers without a C++/Wasm Draco decoder.
Skinned meshes and animations
Rigged characters and props need a few extra checks so GPU skinning and animation blending work cleanly:
- Single Armature root with unit scale: apply
Scale = (1, 1, 1)to both the Armature and the skinned Mesh before exporting. Keep the Armature modifier on the mesh (do not apply the Armature modifier). - Enforce the 4-bone influence limit:
- Select the mesh, switch to Weight Paint mode, and run
Weights → Limit Totalwith Limit =4. - Immediately run
Weights → Normalize All(with Lock Active unchecked) so every vertex's weights sum strictly to1.0. - In the glTF exporter under Data → Skinning, check
Skinningand leaveInclude All Bone Influencesunchecked so onlyJOINTS_0andWEIGHTS_0(4 joints per vertex) are emitted.
- Select the mesh, switch to Weight Paint mode, and run
- Export multiple clips via Actions / NLA:
- Give each clip a clean Action name (
Idle,Walk,Jump,Wave). - Push each Action down to an NLA strip in the Non-Linear Animation editor so Blender preserves every clip in the file.
- In the exporter under Animation, set Animation Mode to
Actions(orNLA Tracks), checkAlways Sample Animationsif the rig uses IK, Copy Rotation, or drivers, and set Sampling Rate to30or60fps (matching your fixed step). - Enable
Optimize Animation Sizeto drop redundant flat channels while keeping keyframe curves accurate.
- Give each clip a clean Action name (
- Root motion vs in-place locomotion:
- Structure your rig with a ground-level
Rootbone at(0, 0, 0)parentingHips/Pelvis. - For in-place clips (where Go code moves the entity transform), keep
Rootstationary at(0, 0, 0)and strip horizontalX/Zdrift fromHips. - For root-motion clips (such as dodge rolls or lunge attacks), author horizontal translation and yaw rotation exclusively on the
Rootbone. Runtime playback can then sample per-step root deltas and hand them to your movement controller without double-applying displacement.
- Structure your rig with a ground-level
- Clip events (
extras.events):- NSGo reads per-clip event markers from
animations[i].extras.events, an array of{ "time": <seconds>, "name": "<event>" }objects:"extras": { "events": [ { "time": 0.0, "name": "wave_start" }, { "time": 0.5, "name": "wave_apex" }, { "time": 1.0, "name": "wave_end" } ] } - In Blender, add Pose Markers to an Action in the Dope Sheet → Action Editor (
Mto add a marker,Ctrl+Mto rename it), then copy them ontoaction["events"]before exporting withInclude → Custom Propertiesenabled:
- NSGo reads per-clip event markers from
import bpy
fps = bpy.context.scene.render.fps / bpy.context.scene.render.fps_base
for action in bpy.data.actions:
if not action.pose_markers:
continue
start = action.frame_range[0]
events = [
{"time": round((m.frame - start) / fps, 6), "name": m.name}
for m in sorted(action.pose_markers, key=lambda item: item.frame)
]
action["events"] = events
Converting FBX and OBJ from other tools
Assets from Maya, 3ds Max, ZBrush, Mixamo, or third-party marketplaces frequently arrive as .fbx or .obj, often in centimeters (100× too large) or Z-up orientation. Convert them to .glb during asset preparation instead of parsing FBX or OBJ at runtime.
Headless Blender CLI conversion
You can batch-convert .fbx and .obj files reproducibly in CI or a local script using Blender's headless CLI (blender --background). Save the following helper as tools/convert_to_glb.py:
import os
import sys
import bpy
argv = sys.argv[sys.argv.index("--") + 1 :]
src_path, dst_path = argv[0], argv[1]
scale_factor = float(argv[2]) if len(argv) > 2 else 1.0 # pass 0.01 for cm -> m
bpy.ops.wm.read_factory_settings(use_empty=True)
ext = os.path.splitext(src_path)[1].lower()
if ext == ".fbx":
bpy.ops.import_scene.fbx(
filepath=src_path,
use_anim=True,
ignore_leaf_bones=True,
automatic_bone_orientation=True,
)
elif ext == ".obj":
bpy.ops.wm.obj_import(
filepath=src_path,
forward_axis="NEGATIVE_Z",
up_axis="Y",
)
else:
raise SystemExit(f"unsupported input format: {ext}")
# Apply centimeter -> meter scale when source tools authored in cm (Maya, Unreal, Mixamo).
if scale_factor != 1.0:
bpy.ops.object.select_all(action="SELECT")
for obj in bpy.context.selected_objects:
if obj.parent is None:
obj.scale = tuple(s * scale_factor for s in obj.scale)
bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)
# Normalize skinning weights to 4 bone influences per vertex on any skinned mesh.
for obj in bpy.data.objects:
if obj.type == "MESH" and obj.vertex_groups:
bpy.context.view_layer.objects.active = obj
bpy.ops.object.mode_set(mode="WEIGHT_PAINT")
bpy.ops.object.vertex_group_limit_total(limit=4)
bpy.ops.object.vertex_group_normalize_all(lock_active=False)
bpy.ops.object.mode_set(mode="OBJECT")
bpy.ops.export_scene.gltf(
filepath=dst_path,
export_format="GLB",
export_yup=True,
export_apply=True,
export_texcoords=True,
export_normals=True,
export_tangents=True,
export_skins=True,
export_all_influences=False,
export_animations=True,
export_force_sampling=True,
export_extras=True,
export_draco_mesh_compression_enable=False,
)
Run it from the command line:
# Convert an OBJ prop authored in meters
blender --background --python tools/convert_to_glb.py -- art/barrel.obj resources/models/barrel.glb
# Convert a Maya / Mixamo FBX authored in centimeters (0.01x -> meters)
blender --background --python tools/convert_to_glb.py -- art/character.fbx resources/models/character.glb 0.01
Handling common source-tool quirks
- Maya / 3ds Max / Unreal FBX (
cm→m): Blender's FBX importer respects the FBXUnitScaleFactorheader when present, but many marketplace exports leaveUnitScaleFactor = 1while modeling180units tall. Always verify bounding-box height in meters after conversion and pass0.01when needed. - Z-up OBJ files (CAD tools, older 3ds Max exports): pass
up_axis="Z"tobpy.ops.wm.obj_import(...)so Blender rotates the mesh upright before exporting withexport_yup=True. - Mixamo multi-clip FBX downloads: download the character mesh once (
With Skin), then download additional animationsWithout Skin, import their Armature actions into the same.blendfile, push each Action to the NLA stack, and export a single.glbcontaining all clips. - Standalone inspection & optimization: after exporting, you can inspect node trees, accessor bounds, and texture sizes with
gltf-transform inspect model.glbor validate strict spec compliance with the Khronosgltf_validator.
Round-trip sample models
The repository commits two minimal, deterministic glTF 2.0 sample models under docs/assets/3d-sample/ generated and round-trip verified in Go by packages/game/internal/samplegltf/.
1. Static binary crate (crate.glb)
File: docs/assets/3d-sample/crate.glb (1,920 bytes, GLB 2.0)
- Geometry:
1 m × 1 m × 1 mcube with pivot at bottom center (X ∈ [-0.5, 0.5],Y ∈ [0, 1],Z ∈ [-0.5, 0.5]), right-handed+Yup,-Zforward. - Mesh data: 24 vertices (4 per face for crisp hard normals), 12 triangles (36
UNSIGNED_SHORTindices), strict CCW outward winding,POSITION(with exactmin/max), unitNORMAL, and per-faceTEXCOORD_0. - Material:
CrateMaterialusingpbrMetallicRoughness(baseColorFactor: [0.72, 0.52, 0.32, 1],metallicFactor: 0.05,roughnessFactor: 0.78,doubleSided: false). - Container layout: 12-byte GLB header (
glTFmagic0x46546C67, version2, 4-byte-aligned total length), space-paddedJSONchunk (0x4E4F534A), and zero-paddedBINchunk (0x004E4942).
2. Skinned & animated 2-bone arm (robot_arm.gltf)
File: docs/assets/3d-sample/robot_arm.gltf (embedded base64 buffer, human-readable JSON)
- Hierarchy:
ArmRoot (node 0) ├─ ArmMesh (node 1: mesh 0, skin 0) └─ UpperArm (node 2: skeleton root at 0, 0, 0) └─ Forearm (node 3: translation 0, 0.5, 0) - Geometry & skinning:
0.25 m × 1.0 m × 0.25 msegmented arm (X ∈ [-0.125, 0.125],Y ∈ [0, 1],Z ∈ [-0.125, 0.125]), 32 vertices, 20 triangles (60 indices). The shared elbow ring aty = 0.5blends smoothly across both joints (JOINTS_0 = [0, 1, 0, 0],WEIGHTS_0 = [0.5, 0.5, 0, 0]), while base and tip rings bind1.0toUpperArmandForearmrespectively. - Skin (
ArmSkin):joints: [2, 3],skeleton: 2, andinverseBindMatricescontaining identityIforUpperArmand translationT(0, -0.5, 0)forForearm, satisfyingworldBind × IBM = I. - Animation (
Wave): 1.0-second clip (times = [0, 0.5, 1]) with twoLINEARquaternion rotation channels (UpperArm+15° Z,Forearm+60° Z) and threeextras.eventsmarkers (wave_startat0.0 s,wave_apexat0.5 s,wave_endat1.0 s).
Running the round-trip verifier
The Go test suite in packages/game/internal/samplegltf/samplegltf_test.go unpacks both committed assets and verifies:
- GLB magic, version
2, 4-byte alignment, JSON/BIN chunk bounds, and zero-byte BIN padding - Embedded data URI base64 decoding and exact buffer byte lengths
- Accessor alignment,
POSITIONmin/maxbounds, unit normals, and CCW outward triangle winding on every triangle - 4-bone
JOINTS_0/WEIGHTS_0bounds and per-vertex weight sums equal to1.0 - Exact
worldBind × inverseBindMatrix == Identityfor every joint inskins - Strictly increasing animation timestamps, unit rotation quaternions, and in-range
extras.events - Byte-for-byte reproducibility against the deterministic Go generator
Run the tests from packages/game/:
go tool nsgo test ./internal/samplegltf
If you edit the generator, regenerate both committed sample files and re-verify in one command:
go test ./internal/samplegltf -update
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Model is 100× too large or tiny | Source authored in centimeters or unapplied Object Scale | Set Blender units to Metric (1.0), apply Ctrl+A → Scale, or convert FBX with 0.01 scale |
| Model lies on its back or faces away from the camera | +Y Up disabled on export, or model built facing +Y instead of -Y |
Rotate model so front faces -Y in Blender, apply Ctrl+A → Rotation, and enable +Y Up |
| Inside-out or missing faces | Inverted normals or negative scale (-1) flipped triangle winding |
Apply Ctrl+A → Scale, check Face Orientation overlay, and run Shift+N (Recalculate Outside) |
| Skinned mesh explodes or stretches weirdly | Unapplied Armature/Mesh scale, >4 bone weights, or unnormalized weights | Apply scale to mesh and armature, run Limit Total (4) + Normalize All, uncheck Include All Bone Influences |
| Only one animation exports (or none) | Actions are not pushed to NLA tracks, or IK constraints are unbaked | Push every Action to an NLA strip, set Animation Mode to Actions, and check Always Sample Animations |
| Material looks flat white, black, or loses textures | Blender-only procedural nodes or unpacked external image paths | Bake procedural nodes into PBR maps wired to Principled BSDF and export as .glb |
| Character snaps back to origin when a walk cycle loops | Root motion baked into a clip meant to loop in place | Zero horizontal translation on Root/Hips for in-place loops, or consume root deltas in gameplay code |
extras.events missing from exported glTF |
Custom properties omitted or stored on the Object instead of the Action | Write action["events"] on each Blender Action and enable Include → Custom Properties on export |