3D Asset Pipeline

ReGame keeps dropped model files as typed project assets first. The editor only prepares engine-native .mesh, Material .data assets, textures, and hidden template cache files when you drag or assign a placeable asset.

Asset Types

• .obj files are Mesh assets. Dragging one into a 3D viewport creates one GameObject with Transform3D, MeshSource, and MeshRenderer.
• .gltf, .glb, and .fbx files are 3D Model assets. JSON .gltf and binary .glb are placeable and reimportable in the current slice; .fbx is indexed but still planned for placement import.
• image files are Texture assets.
• .mtl files are source material-library files. Material .data files are ReGame-native Material DataAssets.

The first supported source formats for placement are static glTF 2.0 .gltf/.glb and Wavefront OBJ .obj.

Supported model data:

• scenes and nodes
• node translation, rotation, and scale
• triangle mesh primitives
• positions, normals, UVs, and vertex colors
• indices
• material slot mapping per primitive
• base-color material factor
• base-color texture
• sampler filter and wrap
• per-node static collision through the extras.regameStaticCollision boolean

OBJ support is intentionally static and conservative:

• v, vt, vn, and f geometry
• triangle, quad, and n-gon faces, triangulated into ReGame mesh surfaces
• positive and negative OBJ indices
• .mtl material libraries
• Kd, d, Tr, and map_Kd for diffuse color, alpha, and albedo texture
• one ReGame material slot per usemtl

Deferred data:

• FBX, .blend, .dae, .3ds, .stl, and other model formats
• skeletal animation
• skinning
• morph targets
• cameras and lights from model files
• advanced PBR maps
• collision inference when neither the import setting nor a node extra requests it

Prepared Runtime Files

When you use tree.gltf, ReGame writes runtime cache resources to a hidden project cache:

file://.regame/model-cache/tree-gltf-<source-hash>/
  tree-gltf-<source-hash>.modelimport
  tree.template
  meshes/*.mesh
  materials/*.data
  textures/*

The hidden template cache contains normal ECS GameObjects. Mesh nodes use:

• Transform3D
• MeshSource
• MeshRenderer

Mesh nodes that request static collision also use StaticBody3D and an Area3D mesh shape that references the same imported Mesh DataAsset.

That means placed models use the same scene, inspector, material, renderer, and runtime path as hand-built 3D objects.

The .modelimport file records the source model, importer version, effective import options, and generated resource paths. ReGame uses it as the stable cache record so using the same model again can reuse the same settings and update the same generated outputs.

How To Use

Put a .gltf file and its external buffers/textures, a self-contained .glb, or an .obj file plus its .mtl/textures somewhere under file://assets, then use it from an asset surface:

• drag .obj into a 3D viewport to create a single mesh GameObject
• drag .gltf or .glb into a 3D viewport to create a template instance from the model
• create or load a GridSet3D data asset, add .obj or .gltf entries to it, assign it to a GridLayer3D, then paint cells
• drag a folder or source file from Finder into the FileSystem tree to copy it into the project without creating scene objects

Source double-clicks select the asset; they do not generate templates or scene objects.

Coordinate Systems And Orientation

ReGame imports glTF node transforms into ReGame's Y-up 3D coordinate system. Blender uses Z as its up axis, so Blender positions and rotations are converted during export. Do not copy raw Blender transform numbers into a ReGame Transform3D.

.gltf and .glb use the same glTF coordinate rules. GLB is the binary container form; it does not use a different axis convention.

See Coordinate Systems for Imported 3D Models for the axis mapping, model-facing convention, modular-kit workflow, and alignment troubleshooting.

Static Collision

Static collision is opt-in for directly imported glTF models. Enable Generate Collision in the model import settings to add static mesh collision to every imported mesh node. For selective collision, set the boolean regameStaticCollision extra on individual glTF nodes:

{
  "name": "Sidewalk",
  "mesh": 0,
  "extras": {
    "regameStaticCollision": true
  }
}

The per-node flag adds StaticBody3D and Area3D only to the marked mesh node. An unmarked sibling remains render-only unless the global Generate Collision setting is enabled. The collision shape uses the same mesh resource as MeshSource, in the node's local coordinate space, and follows the imported Transform3D hierarchy.

In Blender, add a Boolean custom property named regameStaticCollision to an immovable mesh object and enable custom-property export for glTF. Reimporting the source model rebuilds collision from that source property.

Use static mesh collision for immovable floors, walls, curbs, ramps, and environment shells. Movable props, characters, doors, and other runtime-driven objects need an appropriate dynamic or kinematic body instead. Highly detailed render meshes also produce highly detailed collision; use a lower-detail authored mesh node when the full render topology is unnecessary for contact accuracy. The generated components use the same runtime path on desktop, Android, and iOS.

GridSet3D And GridLayer3D

GridSet3D is the reusable paint set for modular 3D worlds. It is a .data resource that stores palette entries such as source asset path, display name, stable entry id, default transform hints, and collision mode. A GridLayer3D component references a GridSet and stores only compact cell data: grid position, palette entry id, palette index, and rotation.

This keeps painted 3D worlds from turning into hundreds of child GameObjects in the scene tree. The editor can still prepare hidden runtime mesh/model cache files when a GridSet entry is assigned, but those cache paths are not the source of truth.

The first GridSet3D collision modes are:

• none for visual-only entries
• cell_box for a clean grid-cell box
• bounds_box for an asset-bounds box
• mesh for mesh/model collision where the asset provides or can prepare that collision
• custom for explicit authored collision shapes stored on the GridSet entry

For cell_box and bounds_box, each palette entry can store an editable collision center and size. cell_box starts from the layer cell size and aligns to the asset's visual bounds when possible, which keeps floor pieces from getting half their collision buried below the painted surface. bounds_box starts from the mesh bounds. custom stores one or more explicit shapes such as box shapes, which is useful when a detailed visual mesh needs a clean walkable deck, ramp, or blocking volume. Use the Physics tab in Grid Painter 3D when a specific tile needs a shorter hazard box, a flatter walkable surface, or a collision box moved away from visual spikes.

GridLayer3D also has Chunk Size. This groups adjacent painted cell boxes into larger debug blocks, split at chunk boundaries, so collision visualization stays readable on wide platforms instead of drawing a separate box around every painted cell. The serialized cell data stays compact; chunking is an editor/runtime preparation detail, not child GameObjects in the scene tree.

Meshes, materials, and hidden template cache output are required for this first static-model slice. Animation and skinning are imported for supported glTF files where present. Collision remains opt-in through the model-wide import setting, extras.regameStaticCollision, explicit collider components, or GridLayer3D collision mode.

Auto-Scale Small Models is an authoring convenience. Some real glTF assets arrive at a tiny unit scale compared with ReGame's default cube/grid scale. When this option is enabled, ReGame leaves the imported mesh data intact and applies a scale on the generated template root when the source model is below the Small Model Threshold. Target Display Size controls the largest visible extent after that helper scale is applied. Disable it when you want the exact source-authored scale.

Existing model import settings are reused when present. Generated .modelimport files live under the hidden file://.regame/model-cache folder and are not part of normal asset browsing.

In the current slice, .gltf and .glb files can be placed and reimported as 3D Model assets. .fbx is visible in asset surfaces but placement import still reports a planned-next message. Use JSON .gltf plus its .bin and texture files, a self-contained binary .glb, or static .obj plus .mtl and texture files.

OBJ is good for many static props and environment pieces found on free model sites. It does not carry skeletal animation like glTF/FBX can, and its material data is much simpler, so use it as a static-mesh import path rather than a full character/animation format.

Many OBJ packages from model sites include .mtl files with texture paths from the artist's original machine, such as E:\Work\Project\textures\wall.tga. ReGame treats those as authoring references, not trusted project paths. During import it normalizes backslashes, tries the local relative path, then searches the dropped model folder by texture filename. If the texture is still missing, the mesh and material still import, the material falls back to its diffuse color, and the Output panel logs a warning. Extract bundled texture archives such as .zip or .rar beside the model, then reimport to let ReGame reconnect those texture filenames.

Why Import Instead Of Runtime-Loading glTF?

Model formats are authoring formats. They can contain meshes, materials, images, hierarchy, animation, skinning, and metadata in many combinations.

ReGame converts them into a predictable set of runtime resources:

• .mesh for geometry
• Material .data assets for surface appearance
• texture files for image data
• .template for ECS composition

This keeps runtime loading smaller, faster, and easier to validate across desktop, Android, and iOS.