blender-scene-setup

シーンの設定と整理

実行モデルと検証手順については、blender-core を参照してください。

手順

1. scripts/scene_audit.py を実行します（自分が所有するファイルに限り、--fix purge scale paths を追加します）。単位、未適用または負のスケール、デフォルト名、シーンルート内のオブジェクト、欠落画像、孤立データ、原点から大きく離れたオブジェクトが報告されます。
2. 単位を設定します。メートル法、単位スケール 1.0、長さはメートルにします。Unreal／Roblox 用でも 1.0 のままにしてください。変換はエクスポーターが処理します（blender-export-pipelines を参照）。
3. コレクションのレイアウトを作成します（以下を参照）。すべてのオブジェクトを名前付きコレクションに入れ、シーンルートには置かないでください。
4. 以下の規則に従って、すべてに名前を付けます。複製または結合するたびに名前を変更し、.001 サフィックスが残らないようにしてください。
5. 原点を設定します。小道具は底面の中央（Z=0 で地面に接する位置）、キャラクターは足の間のワールド原点、ドアやヒンジはピボットに配置します。
6. メッシュの回転とスケールを適用します（Ctrl+A）。アセットを原点でエクスポートする場合を除き、位置はそのままにします。
7. 監査を再実行します。issues が空、または残った各問題が意図的で、説明されていれば完了です。

コレクションのレイアウト（.blend ごとにアセット 1 つ、またはアセットごとにコレクション 1 つ）

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)

Collection Exporters（4.2 以降）を使って、コレクションごとに一度エクスポートを定義し、1 回の呼び出しで再エクスポートします。

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() は、すべてのコレクションエクスポーターを再実行します。

命名規則（Unreal スタイル。すべてのエンジンで使用できます）

種類	パターン	例
静的メッシュ	SM_<Name>[_LOD#]	SM_Crate_LOD1
スケルタルメッシュ／リグ	SK_<Name> / RIG_<Name>（アーマチュアオブジェクトは Armature または root）	SK_Hero
マテリアル	M_<Name> / インスタンス MI_<Name>	M_Wood_Oak
テクスチャ	T_<Name>_<Suffix>：_BC ベースカラー、_N 法線、_ORM（R=AO G=Rough B=Metal）、_E 発光、_M マスク	T_Crate_ORM
コリジョン	UE UCX_<Mesh>_##、Godot サフィックス -col／-colonly／-convcolonly	UCX_SM_Crate_00
ボーン／左右	サフィックス .L／.R（Blender のミラーツールがこれに依存します）	upper_arm.L
アクション	<Rig>_<Clip>	Hero_Run
ASCII のみを使い、スペースは使わず、プロジェクト全体で PascalCase または snake_case のいずれかに統一してください。

実寸の目安（メートル）

ドア 2.0–2.1 × 0.9 · 天井 2.4–2.7 · テーブル 0.75 · 椅子の座面 0.45 · カウンター 0.9 · 階段の蹴上げ 0.18／踏み面 0.28 · 成人 1.7–1.8（目の高さ 1.6）· 車 4.5 × 1.8 × 1.5。Roblox：1 stud ≈ 0.28 m、デフォルトのキャラクターの高さは約 5 studs です。スケールが間違っていると、物理演算、ライティングの減衰、DOF、テクセル密度に問題が生じるため、まず ob.dimensions を確認してください。

リンク、アペンド、オーバーライド

• アペンド（libraries.load(link=False)）はローカルコピーを作成します。一度限りの再利用に使います。
• リンク（link=True）は読み取り専用で、ソースから更新され、パイプラインで使用されます。リンクしたコレクションを編集するには、ライブラリオーバーライドを追加します：ob.override_hierarchy_create(scene, view_layer, do_fully_editable=False)。変更できるのはオーバーライド可能なプロパティ（トランスフォーム、ポーズ、オーバーライド可能としてマークされた項目）のみです。
• ライブラリパスは相対パス（//）にします。壊れたパスがないか bpy.data.libraries を確認してください。

アセットライブラリ

• マークします：ob.asset_mark(); ob.asset_generate_preview()。メタデータは ob.asset_data に格納します（author、description、license、tags.new("wood")、catalog_id）。
• カタログはライブラリのルートにある blender_assets.cats.txt に保存します。カタログごとに 1 行で、形式は UUID:Path/Sub:Simple Name です。
• ライブラリは prefs.filepaths.asset_libraries.new(name=..., directory=...) で登録します。5.2 以降では、use_remote_url と remote_url を使ってリモートライブラリを登録できます。5.2 では、active_asset_library のインデックスは 2 つずれています（「All」、「Essentials」）。
• ライブラリごとのインポート方法：LINK、APPEND、APPEND_REUSE（デフォルト。すでにアペンドされたデータを再利用します）。

データ整理のルール

• リリース前に孤立データを削除します（bpy.data.orphans_purge(do_recursive=True)）。フェイクユーザーは意図がある場合にのみ使用します。
• 画像パスは相対パスにする（file.make_paths_relative）か、単一ファイルでの納品用にパックします（file.pack_all）。
• オブジェクトごとの未適用スケールがあるメッシュデータを複数ユーザーで共有した状態で納品しないでください。インスタンスは問題ありませんが、エクスポート前にスケールを適用します。
• ヘルパーはhide_render=Trueに設定し、エクスポート対象のコレクションからも除外します。ビューポートで非表示にするだけでは不十分です。
• 納品するファイルのシーンは1つだけアクティブにします。シーンが複数あるとエクスポーターで混乱が生じます（use_active_scene）。