tmhsdigital/blender-developer-tools

engine-export-presets

Export presets for Unity, Godot and Unreal.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/tmhsdigital/blender-developer-tools --skill engine-export-presets

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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
같은 저장소의 Skills

더 많은 Skills

모든 Skills
tmhsdigital
커뮤니티

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.

1시간 설치 수
1
GitHub Stars
20
업데이트
11월 3일
tmhsdigital
커뮤니티

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.

1시간 설치 수
1
GitHub Stars
20
업데이트
11월 3일
tmhsdigital
커뮤니티

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.

1시간 설치 수
1
GitHub Stars
20
업데이트
11월 3일