mcpField
B
blender-scene-setup

blender-scene-setup

github.com/el4cteoCreative & media569103 installsUpdated 2w ago
Repository

About blender-scene-setup

A Blender scene setup and hygiene skill for artists preparing assets for reuse or export. It covers scene audits, organization, naming, scale, paths, asset libraries, and cleanup conventions.

Key features

  1. 01Audit scene issues and apply fixes
  2. 02Organize assets into named collections
  3. 03Set naming, scale, and origin conventions
  4. 04Manage linked and appended data
  5. 05Prepare asset libraries and clean files

Use cases

  1. 01Check a scene before asset delivery
  2. 02Standardize collections and object names
  3. 03Relocate or repair external file paths
  4. 04Register and maintain asset libraries

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/el4cteo/blender-skills --skill blender-scene-setup

After installing, type/blender-scene-setupin Claude Code to confirm it loaded.

Bundled filesscripts/_bpyx.pyscripts/scene_audit.py

Details

From the project README

Scene Setup & Hygiene

The execution model and verification steps are in blender-core.

Procedure

  1. Run scripts/scene_audit.py (add --fix purge scale paths only on files you own). It reports units, unapplied/negative scale, default names, objects in the scene root, missing images, orphans and far-off origins.
  2. Set units: Metric, Unit Scale 1.0, Length meters. Keep 1.0 even for Unreal/Roblox, because exporters handle the conversion (see blender-export-pipelines).
  3. Build the collection layout (below). Every object must be in a named collection, never the scene root.
  4. Name everything with the conventions below. Rename after every duplicate or join so no .001 suffixes remain.
  5. Set origins: props at the bottom-center (they sit on the ground at Z=0), characters at world origin between the feet, doors/hinges at the pivot.
  6. Apply rotation and scale on meshes (Ctrl+A). Keep location unless the asset should export at the origin.
  7. Re-run the audit. It's done when issues is empty or every remaining issue is intentional and explained.

Collection layout (one asset per .blend, or one collection per asset)

ASSET_Crate
├── Crate_high      # sculpt / subdiv source (exclude from export)
├── Crate_low       # game mesh(es) SM_Crate, SM_Crate_LOD1..
├── Crate_bake      # cages, bake helpers
├── Crate_collision # UCX_SM_Crate_00 (UE) / Crate-col (Godot)
└── Crate_ref       # reference images/blockout (hide_render)

Use Collection Exporters (4.2+) to define the export once per collection, then re-export with one call:

with bpy.context.temp_override(collection=col):
    bpy.ops.collection.exporter_add(name="IO_FH_gltf2")
ex = col.exporters[-1]; ex.export_properties.filepath = "//export/SM_Crate.glb"
with bpy.context.temp_override(collection=col):
    bpy.ops.collection.exporter_export(index=len(col.exporters) - 1)

bpy.ops.wm.collection_export_all() re-runs every collection exporter.

Naming conventions (Unreal-style, accepted by all engines)

TypePatternExample
Static meshSM_<Name>[_LOD#]SM_Crate_LOD1
Skeletal mesh / rigSK_<Name> / RIG_<Name> (armature object Armature or root)SK_Hero
MaterialM_<Name> / instance MI_<Name>M_Wood_Oak
TextureT_<Name>_<Suffix>: _BC base color, _N normal, _ORM (R=AO G=Rough B=Metal), _E emissive, _M maskT_Crate_ORM
CollisionUE UCX_<Mesh>_##, Godot suffix -col/-colonly/-convcolonlyUCX_SM_Crate_00
Bones/sides.L/.R suffix (Blender mirror tools depend on it)upper_arm.L
Actions<Rig>_<Clip>Hero_Run
Use ASCII only, no spaces, and PascalCase or snake_case consistently across the project.

Real-world scale reference (meters)

Door 2.0–2.1 × 0.9 · ceiling 2.4–2.7 · table 0.75 · chair seat 0.45 · counter 0.9 · stair rise 0.18 / tread 0.28 · adult human 1.7–1.8 (eyes 1.6) · car 4.5 × 1.8 × 1.5. Roblox: 1 stud ≈ 0.28 m; default character ≈ 5 studs tall. Wrong scale breaks physics, lighting falloff, DOF and texel density, so check ob.dimensions first.

Linking, appending, overrides

  • Append (libraries.load(link=False)) makes a local copy. Use it for one-off reuse.
  • Link (link=True) is read-only, updates from the source and is what pipelines use. To edit a linked collection, add a library override: ob.override_hierarchy_create(scene, view_layer, do_fully_editable=False). Only overridable properties (transforms, pose, and anything marked overridable) can change.
  • Keep library paths relative (//). Check bpy.data.libraries for broken paths.

Asset libraries

  • Mark: ob.asset_mark(); ob.asset_generate_preview(). Metadata goes in ob.asset_data (author, description, license, tags.new("wood"), catalog_id).
  • Catalogs live in blender_assets.cats.txt at the library root, one line per catalog: UUID:Path/Sub:Simple Name.
  • Register a library with prefs.filepaths.asset_libraries.new(name=..., directory=...). 5.2+: remote libraries via use_remote_url + remote_url. In 5.2 active_asset_library indices are offset by 2 ("All", "Essentials").
  • Import method per library: LINK, APPEND, APPEND_REUSE (default; reuses already-appended data).

Hygiene rules

  • Purge orphans before shipping (bpy.data.orphans_purge(do_recursive=True)). Use fake users only on purpose.
  • Image paths: relative (file.make_paths_relative), or pack for single-file delivery (file.pack_all).
  • Never ship multi-user mesh data that has an unapplied per-object scale. Instances are fine, but bake scale before export.
  • Hide helpers with hide_render=True and exclude them from export collections; viewport hiding alone isn't enough.
  • One active scene per file for delivery. Extra scenes confuse exporters (use_active_scene).

Comments

Markdown supported