tmhsdigital/blender-developer-tools

engine-export-presets

Export presets for Unity, Godot and Unreal.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/tmhsdigital/blender-developer-tools --skill engine-export-presets

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Engine Export Presets

Trigger

Use this skill when the user:

  • Needs a Unity, Godot, or Unreal export from Blender Python
  • Mentions Y-up, Z-up, centimeter scale, export_yup, axis_forward, or axis_up
  • Is about to pass FBX axis kwargs to bpy.ops.export_scene.gltf
  • Wants a headless preset the later ai-asset-pipeline-template can call

This skill is the export layer. It composes ai-mesh-cleanup (apply transforms, units), depsgraph-and-evaluated-data (export_apply ships evaluated mesh), and the unapplied-scale-gltf witness (export_apply does not bake object scale). It does not generate meshes.

The core misunderstanding

glTF and FBX do not share axis RNA. bpy.ops.export_scene.gltf has export_yup (boolean, "+Y Up"). It does not have axis_forward or axis_up. bpy.ops.export_scene.fbx has axis_forward and axis_up (axis enums) and global_scale. It does not have export_yup. Passing the other exporter's kwargs is a TypeError or a silent no-op depending on how the call is built.

That split is the contract. Verified on current RNA:

  • glTF: https://docs.blender.org/api/current/bpy.ops.exportscene.html#bpy.ops.exportscene.gltf (export_yup, no axis enums)
  • FBX: https://docs.blender.org/api/current/bpy.ops.exportscene.html#bpy.ops.exportscene.fbx (axis_forward, axis_up, global_scale)

Shared prelude

Before any preset: meters in the scene (scale_length == 1.0), identity object scale via transform_apply through temp_override, export_apply=True / use_mesh_modifiers=True so modifiers ship. See ai-mesh-cleanup and unapplied-scale-gltf.

python
def apply_selected_mesh_transforms():
    # One operator call for the whole selection. transform_apply reads
    # selected_editable_objects, so that is the key to override. It refuses
    # shared (glTF-instanced) mesh data, so copy it per object first, and
    # unparent keeping the world placement, or a rotated root stays on the node.
    meshes = [o for o in bpy.context.selected_objects if o.type == "MESH"]
    if not meshes:
        return
    for o in meshes:
        if o.data.users > 1:
            o.data = o.data.copy()
        if o.parent is not None:
            world = o.matrix_world.copy()
            o.parent = None
            o.matrix_world = world
    with bpy.context.temp_override(
        object=meshes[0], active_object=meshes[0], selected_editable_objects=meshes
    ):
        bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)

The two guards are for ordinary imports. Instanced glTF nodes come back as several objects sharing one Mesh, and transform_apply then raises Cannot apply to a multi user (4.5.11 and 5.2.1). A mesh under a rotated root has an identity matrix_basis. Applying it leaves the root's rotation in matrix_world, and use_selection=True writes that rotation onto the exported node. Copying the data means instances no longer share one mesh. That is the cost of baking transforms into vertices.

use_selection=True on every preset. Draco is opt-in on glTF; do not copy gltf_draco_export.py wholesale.

glTF is the same for every engine

The glTF 2.0 spec fixes the coordinate system: +Y up, right-handed, units in meters. Unity, Godot and Unreal all import glTF against that spec, so the correct glTF export is the same call for all three: export_yup=True, meters, transforms applied. The engines differ in what they do on import (Unreal converts meters to centimeters itself; Godot reads node-name import hints), not in the file you should write.

Unity (Y-up, meters, glTF)

python
bpy.ops.export_scene.gltf(
    filepath=path,
    export_format="GLB",
    use_selection=True,
    export_yup=True,
    export_apply=True,
    export_draco_mesh_compression_enable=draco,
    export_animations=False,
)

export_yup=True bakes (x, y, z) -> (x, z, -y) into POSITION with no node rotation. Witness: `examples/gltf-export-roundtrip/` and `examples/export-preset-axis/`.

Snippet: `snippets/export_preset_unity.py`.

Godot (Y-up glTF, meters)

Godot is right-handed and Y-up, and its importer reads glTF as the spec says. The export is the Unity call: export_yup=True, meters, .glb. What is Godot-specific happens on import, through node-name suffixes the importer reads as hints: a mesh named Crate-convcolonly becomes a convex collision shape with no visible mesh, -colonly a trimesh collision shape, -col / -convcol add collision to a visible mesh, and -rigid makes a rigid body. Name the collider object accordingly before export instead of changing axes. See Godot's node type customization docs.

export_yup=False is wrong for Godot, as for every glTF consumer: it writes Blender's Z-up POSITION into a file the importer reads as Y-up, so the model arrives rotated -90° about X (lying on its back). `examples/export-preset-axis/` measures exactly that.

Snippet: `snippets/export_preset_godot.py`.

Unreal (centimeters)

Unreal works in centimeters, but do not bake 100x into a glTF. glTF units are meters by spec, and Unreal's glTF importer (Interchange) applies its own meters-to-centimeters conversion (import_scale, default 100). A 1 m crate exported with a 100x bake imports 100 m wide. Export Unreal glTF exactly like Unity: export_yup=True, meters.

FBX is where Unreal needs explicit axis and scale kwargs. It keeps the meter mesh and scales on the way out:

python
bpy.ops.export_scene.fbx(
    filepath=path,
    use_selection=True,
    axis_forward="-Z",
    axis_up="Y",
    global_scale=100.0,
    apply_unit_scale=False,
    use_mesh_modifiers=True,
    bake_anim=False,
)

Do not pass export_yup to FBX. Do not pass axis_forward to glTF.

Snippet: `snippets/export_preset_unreal.py`.

Common AI mistakes

  1. `export_scene.gltf(..., axis_forward="-Z", axis_up="Y")`. Those names are FBX. Rule use-correct-axis-rna-per-exporter.
  2. `export_scene.fbx(..., export_yup=True)`. Same rule, other direction.
  3. Skipping `transform_apply`. export_apply is modifiers, not object scale. `examples/unapplied-scale-gltf/`.
  4. `export_yup=False` for any engine. glTF is Y-up by spec; a Z-up file imports lying on its back in Unity, Godot and Unreal alike. `examples/export-preset-axis/` re-imports both and measures the -90° tilt.
  5. Baking 100x into an Unreal glTF. glTF is meters by spec and Unreal's glTF importer already scales by 100 on import, so a baked file lands 100x too large. The 100x belongs on the FBX path (global_scale).
  6. Changing axes to express engine differences. Engine-specific behaviour for glTF lives in import settings and node names (Godot -convcolonly, -rigid), not in export_yup.

Version correctness

Probed on 4.5 LTS, 5.1, and 5.2: export_yup on glTF and axis_forward / axis_up / global_scale on FBX are present on all three. No version branch for the axis kwargs. Guard by requiring those names in operator RNA so a future rename fails loudly, as `examples/gltf-export-roundtrip/` does.

Always pass export_format on glTF and make the filepath suffix match it. The operator does not infer the format from the suffix: export_scene.gltf(filepath="x.gltf") with no export_format writes a binary x.glb, so the requested path never exists (measured on 4.5.11 and 5.2.1). Use export_format="GLB" with .glb, or "GLTF_SEPARATE" with .gltf.

Related

<!-- examples:begin (generated by scripts/buildexamplesindex.py from examples/skills.json; do not edit) -->

Runnable examples

Each example runs headless, asserts the contract, and exits non-zero when it breaks. Run one with blender --background --python <script> --; pass a falsifier flag to watch the check fail.

  • `export-preset-axis`: A radio mast exported once with the engine glTF preset (export_yup=True, shared by Unity, Godot and Unreal) and once naively Z-up, then re-imported: the Z-up file lies on its back Falsify: --same-axis (exit 9).
  • `gltf-export-roundtrip`: A sci-fi supply crate exported to glTF and re-imported, verifying the round-trip against the depsgraph-evaluated mesh within float tolerances. Falsify: --no-yup (exit 9).
  • `gltf-skin-roundtrip`: A rigged mech scorpion exported to glTF with skins and re-imported, verifying the skinning contract the geometry round-trip left uncovered. Falsify: --no-skins (exit 5).
  • `unapplied-scale-gltf`: Synthesizes unapplied non-uniform object scale on a unit cube, then asserts the glTF exporter contract. Falsify: --identity (exit 3).

Snippets

Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.

<!-- examples:end -->

References

  • bpy.ops.export_scene.gltf: https://docs.blender.org/api/current/bpy.ops.exportscene.html#bpy.ops.exportscene.gltf
  • bpy.ops.export_scene.fbx: https://docs.blender.org/api/current/bpy.ops.exportscene.html#bpy.ops.exportscene.fbx
  • glTF 5.1: https://docs.blender.org/api/5.1/bpy.ops.exportscene.html#bpy.ops.exportscene.gltf
  • FBX 5.1: https://docs.blender.org/api/5.1/bpy.ops.exportscene.html#bpy.ops.exportscene.fbx
from this repository

More skills

All skills
tmhsdigital
Community

bake-high-to-low

Cage-bake high-poly surface detail onto a low-poly target as a tangent-space normal map with bpy.ops.object.bake (Cycles, selected-to-active, active Image Texture node, UV layer, saverender). Use when the user wants a normal map from a dense mesh onto a game-resolution or decimated LOD, mentions cageextrusion or useselectedtoactive, or gets a bake that returns CANCELLED, comes out black or flat, or fails with 'No active UV layer found'. Targets 5.2 LTS with 4.5 LTS fallback.

1h installs
1
GitHub stars
20
Updated
Nov 3
tmhsdigital
Community

bl-info-migration

Migrate a legacy blinfo add-on to the Extensions Platform in three steps, with a before/after diff and the dual-format pattern. Use when the user has a blinfo dictionary in init.py, asks whether blinfo is deprecated or still supported, wants to publish to extensions.blender.org or ship an extension .zip, or sees warnings about legacy add-ons at install time. Targets 5.2 LTS; manifests work from 4.2.

1h installs
1
GitHub stars
20
Updated
Nov 3
tmhsdigital
Community

drivers-and-app-handlers

Drive properties from expressions with the Driver API (driveradd, drivernamespace for custom Python functions) and react to events with bpy.app.handlers (loadpost, savepre, framechangepost, depsgraphupdatepost, exitpre in 5.1+). Use when the user wants one property to follow another, runs code on load, save, frame change or exit, or has a driver failing with NameError or the Python security block, including drivers that die after reopening a file.

1h installs
1
GitHub stars
20
Updated
Nov 3