unity-uitoolkit

このモジュールのスキルを呼び出す前に： 名前や説明からパラメーターを推測してスキルを呼び出そうとしている場合は、いったん止めて、このファイルを読むか、GET /skills/recommend?includeSchema=true を使ってスキーマを取得してください。recommend/schema からパラメーターの定義をすでに入手している場合は、そのまま dryRun に進んでかまいません。

トリガー

• UI Toolkit を使用したランタイムまたはエディター UI の作成
• USS/UXML の記述
• UIDocument の接続
• UI のデータへのバインド
• ワールド空間 UI の構築
• UI Toolkit を使用したランタイムまたはエディター UI の作成、USS/UXML の記述、UIDocument の接続、UI のデータソースへのバインド、ワールド空間 UI の構築

Unity UI Toolkit スキル

このモジュールは Unity UI Toolkit 専用です。構造には UXML、スタイル設定には USS、シーンへのアタッチには UIDocument、ランタイムでのレンダリングには PanelSettings を使用します。

Unity 2022.3+ が必要です。このモジュールを ui_* の UGUI/Canvas スキルと混在させないでください。 ローカライズ：表示される UI テキストはユーザーの言語に合わせてください。中国語での会話では、中国語のラベル／プレースホルダー／ボタンテキストを使用します。USS クラス名と CSS 変数は英語のままにしてください。

動作モード

• Approval：照会系スキル（uitk_read_file / uitk_find_files / uitk_get_panel_settings / uitk_list_documents / uitk_inspect_uxml / uitk_list_uss_variables / uitk_inspect_document / uitk_runtime_binding_list / uitk_worldspace_panel_get / uitk_element_reference_get、ソースでは SkillMode.SemiAuto と指定）は直接実行されます。その他のファイル／シーン書き込み系（uitk_create_* / uitk_write_file / uitk_add_* / uitk_modify_element / uitk_runtime_binding_add / uitk_uxml_upgrade / uitk_worldspace_panel_create など、SkillMode.FullAuto と指定）はユーザーの grant が必要です。grant 後、サーバーが一度の処理で実行し、結果を返します。
• Auto / Bypass：禁止リストに阻止されていないスキルは直接実行されます。
• このモジュールにはDelete 系のスキルが含まれます：uitk_delete_file、uitk_remove_element、uitk_remove_uss_rule は SkillOperation.Delete として指定され、IsForbiddenInSemi によって静的にブロックされます。呼び出せるのは Bypass モード、または Allowlist に追加した場合のみです。
• このモジュールにはドメインリロードを伴うスキルも 2 つ含まれます：uitk_create_editor_window と uitk_create_runtime_ui は .cs ファイルを生成し、必ずドメインリロードを引き起こすため、MayTriggerReload = true と指定されています。IsForbiddenInSemi はこのフラグを直接読み取るため、これらも上記の Delete 系と同様に静的にブロックされます。つまり Approval と Auto ではどちらも MODE_FORBIDDEN を返し、「grant が必要」なわけではなく、grant を与えても実行できません。呼び出せるのは Bypass モード、または Allowlist に該当する場合のみです。この 2 つは、上記の「その他の書き込み系スキルにはユーザーの grant が必要」という最初の項目の例外です。
• 同じフラグにはもう 1 つの影響があります：?mode=transactional の一括処理にこの 2 つの手順が含まれている場合、実行前に 400 で拒否され、違反している steps[i] がエラーで示されます。ドメインリロードによってエディターの undo スタックがクリアされ、トランザクション一括処理のロールバックを保証できないため、サーバーは事後の失敗ではなく事前の拒否を選択します。トランザクション一括処理のワークフローでスクリプトを生成する場合は、この 2 つの手順を分けて個別に呼び出してください。
• アセットの再インポート動作：すべてのファイル書き込み／削除系スキルは、単一の USS/UXML アセットごとに AssetDatabase.ImportAsset(path) でインポートを個別にトリガーします。全プロジェクトをスキャンする AssetDatabase.Refresh() は呼び出しません。一括作成時も、順番に個別インポートします。ただし USS/UXML は ScriptedImporter 型であるため、インポート時にこのアセットに依存する PanelSettings/UIDocument の参照が再構築され、IMGUI インスペクターの更新とシーンビューの再描画が発生します。

しないでください（よくある誤り）：

• uitoolkit_create_button / uitoolkit_create_label は存在しません -> uitk_add_element を使用してください
• uitoolkit_set_style は存在しません -> uitk_add_uss_rule、uitk_remove_uss_rule、または uitk_modify_element を使用してください
• uitoolkit_create_canvas は存在しません -> UI Toolkit は Canvas ではなく UIDocument を使用します
• uitk_* と ui_* は別のシステムです。UI Toolkit の構造／スタイル設定に関する前提を UGUI のワークフローに持ち込まないでください
• USS は完全な CSS ではありません。display:grid、box-shadow、calc()、@media、::before、z-index、グラデーションはサポートされていません
• uitk_add_element / uitk_modify_element の binding-path は、旧式の SerializedObject エディターバインディングです。ランタイムのデータバインディングではありません -> その場合は uitk_runtime_binding_add を使用してください
• component_add で PanelRenderer を追加しないでください。ワールド空間用の設定が必要です -> uitk_worldspace_panel_create を使用してください

振り分け：

• UGUI の Canvas/Button/Text/Image には ui モジュールを使用してください
• XR のワールド空間 Canvas への変換には xr_setup_ui_canvas を使用してください
• 生成済みのスターターレイアウトには uitk_create_from_template を使用してください
• 既存の UXML をシーンオブジェクトにアタッチするには uitk_create_document または uitk_set_document を使用してください

スキル

ファイル関連スキル

スキル	用途	主なパラメーター
uitk_create_uss	USS ファイルを作成	savePath, content?
uitk_create_uxml	UXML ファイルを作成	savePath, content?, ussPath?
uitk_read_file	USS/UXML の内容を読み取る	filePath
uitk_write_file	USS/UXML の内容を上書き	filePath (末尾が .uss または .uxml である必要があります), content
uitk_delete_file	USS/UXML ファイルを削除	filePath
uitk_find_files	名前／パスでファイルを検索	type?, folder?, filter?, limit?
uitk_create_batch	1 回の呼び出しで 2 個以上のファイルを作成	items

uitk_write_file は汎用のファイル書き込みツールではありません。 filePath の末尾は .uss または .uxml（大文字と小文字は区別されません）である必要があります。これ以外の拡張子（拡張子がない場合も含む）は拒否され、SEMANTIC_INVALID、validValues: [".uss", ".uxml"]、および script_create を指す relatedSkills が返されます。チェックは対象ディレクトリの作成前に実行されるため、拒否された呼び出しによってファイルや不要なフォルダーが残ることはありません。.cs ファイルの書き込みにこのツールを使わないでください。スクリプトの書き込みによって発生するドメインの再読み込みを正しく宣言する script_create を使用してください。

シーン関連スキル

スキル	用途	主なパラメーター
uitk_create_document	UIDocument ゲームオブジェクトを作成	name, uxmlPath?, panelSettingsPath?, sortOrder?, parentName?/parentInstanceId?/parentPath?
uitk_set_document	UIDocument のアセットバインディングを変更	name/instanceId, uxmlPath?, panelSettingsPath?
uitk_create_panel_settings	PanelSettings アセットを作成	savePath, scaleMode, referenceResolutionX/Y, Unity 6 のワールド空間オプション
uitk_get_panel_settings	PanelSettings の値を読み取る	assetPath
uitk_set_panel_settings	PanelSettings を選択して更新	assetPath, 変更したフィールドのみ
uitk_list_documents	シーン内の UIDocument を一覧表示	なし
uitk_inspect_document	実行中の VisualElement ツリーを調査	name/instanceId/path, depth

バージョンによって使用可否が決まる PanelSettings パラメーター — 名前を指定して拒否され、無視されることはありません。 uitk_create_panel_settings と uitk_set_panel_settings の両方で、renderMode、forceGammaRendering、bindingLogLevel、colliderUpdateMode、colliderIsTrigger、vertexBudget は Unity 6.0 以降が必要で、textureSlotCount は Unity 6000.3 以降が必要です。古いエディターでこれらのパラメーターを渡すと、無視されるのではなく、該当パラメーター名を含む SEMANTIC_INVALID が返されます。そのため、送信した値は適用されるかエラーとして返されるかのどちらかで、黙って破棄されることはありません。どちらのスキルも、最初の書き込み前にすべての列挙値とアセットパスを解決するため、拒否された呼び出しでもアセットのバイト列は変更されません。後から部分適用を元に戻す必要はありません。

UXML 構造関連スキル

スキル	用途	主なパラメーター
uitk_add_element	子要素を追加	filePath, elementType, parentName?, elementName?, text?, classes?
uitk_remove_element	name で要素を削除	filePath, elementName
uitk_modify_element	属性／クラス／テキストを変更	filePath, elementName, text?, classes?, style?, newName?, bindingPath?, カスタム属性フィールド
uitk_clone_element	要素のサブツリーを複製	filePath, elementName, newName?
uitk_inspect_uxml	UXML の階層を解析	filePath, depth?

USS スタイル関連スキル

スキル	用途	主なパラメーター
uitk_add_uss_rule	セレクタールールを追加または置換	filePath, selector, properties
uitk_remove_uss_rule	セレクタールールを削除	filePath, selector
uitk_list_uss_variables	デザイントークン／var() の使用状況を調査	filePath

テンプレートと CodeGen スキル

スキル	用途	主なパラメーター
uitk_create_from_template	UXML+USS のペアを生成	template、savePath、name?
uitk_create_editor_window	EditorWindow スクリプトを生成	savePath、className、uxmlPath?、ussPath?、menuPath?
uitk_create_runtime_ui	ランタイム MonoBehaviour クエリのひな形を生成	savePath、className、elementQueries?

対応するスターターテンプレートには、menu、hud、dialog、settings、inventory、list、tab-view、toolbar、card、notification があります。

Unity 6 スキル（バージョンによる制限あり）

これらのスキルは、サポート対象のすべてのエディターに存在するとは限らない API を呼び出します。各スキルは最初に実行中のエディターを確認し、原因が分かりにくい形で失敗する代わりに、requiredUnityVersion と currentUnityVersion を含む構造化された SEMANTIC_INVALID エラーを返します。呼び出す前に最低バージョンを確認してください。

スキル	最低 Unity バージョン	用途	主なパラメーター
uitk_runtime_binding_add	6000.0	UXML 要素に <DataBinding> を追加／更新	filePath、elementName、property、bindingMode?、dataSource?、dataSourcePath?、extraAttributes?
uitk_runtime_binding_list	なし（読み取り専用）	UXML ファイルで宣言されたバインディングとデータソースを一覧表示	filePath
uitk_uxml_upgrade	6000.3（一部のビルドでは未対応 — 下記参照）	登録済みの UXML アップグレーダーをアセットに対して実行	filePath?、folder?、upgraderNames?、listOnly?、limit?
uitk_worldspace_panel_create	6000.2	ワールド空間の UI パネル GameObject を作成	name、uxmlPath?、panelSettingsPath?、sizeMode?、worldSpaceSizeX/Y?、pivot?、pivotReferenceSize?、setPanelRenderMode?
uitk_worldspace_panel_get	6000.2	ワールド空間パネルの設定を読み取り	name/instanceId/path
uitk_element_reference_get	なし（読み取り専用）	authoring-id の値とネストされた authoring-id パスを一覧表示	filePath、maxTemplateDepth?

ランタイムデータバインディング

uitk_runtime_binding_add はバインディングをUXML アセットに書き込むため、永続化されます — ランタイム専用のコード呼び出しではありません。Unity の UI Builder が生成するマークアップを出力します。

<engine:Label text="Label" data-source="ExampleObject.asset" data-source-path="simpleLabel">
    <Bindings>
        <engine:DataBinding property="text" binding-mode="ToTarget" />
    </Bindings>
</engine:Label>

• data-source / data-source-path は要素に、property / binding-mode は <DataBinding> に書き込まれます。
• bindingMode は TwoWay、ToSource、ToTarget、ToTargetOnce に対して検証されます。無効な値は書き込み前に拒否されます。誤った binding-mode があると、UXML アセット全体のインポートに失敗するためです。
• 同じ elementName + property に対して 2 回呼び出すと、その場で更新されます（応答の action は added または updated）。そのため、安全に再実行できます。
• extraAttributes には JSON オブジェクト（例：{"update-trigger":"OnSourceChanged"}）を指定します。これは <DataBinding> ノードにそのまま書き込まれます。これらはスキルによるスキーマ検証の対象外です — 属性名が誤っていると、アセットのインポートに失敗します。使用が確認できている属性に限って使用してください。
• C# オブジェクトへのデータソースのバインドには、ソースプロパティに [CreateProperty]（Unity.Properties）が必要です。このスキルが書き込むのはマークアップのみであり、データソースの型の作成や検証は行いません。

ワールド空間パネル

基盤となるコンポーネントはエディターのバージョンによって異なり、応答の component フィールドで使用されたコンポーネントを確認できます。

• Unity 6000.5+ — PanelRenderer コンポーネント（UnityEngine.UIElements.PanelRenderer。Renderer のサブクラス）。
• Unity 6000.2–6000.4 — ワールド空間プロパティを設定した UIDocument。

どちらの方法でも同じパラメーターを使用できます。sizeMode は Dynamic または Fixed です（Fixed は worldSpaceSizeX/Y を使用します）。pivot は Center、TopLeft、TopCenter、TopRight、LeftCenter、RightCenter、BottomLeft、BottomCenter、BottomRight を指定できます。pivotReferenceSize は BoundingBox または Layout を指定できます。サポートされていない値は無視されず、有効な値の一覧とともにエラーになります。

ワールド空間でレンダリングするには、リンクされた PanelSettings もワールド空間のレンダリングモードにする必要があります。setPanelRenderMode のデフォルトは true で、このアセットがワールド空間用に切り替えられます（変更前の状態が記録され、元に戻せます）。応答には panelRenderModeSetToWorldSpace が含まれます。アセットを変更しない場合は false に設定してください。

UXML のアップグレード

uitk_uxml_upgrade は UnityEditor.UIElements.UxmlUpgradeService を実行します。Unity のドキュメントでは、このサービスは 6000.3 以降とされていますが、すべての 6000.3 ビルドに含まれているわけではありません（6000.3.9f1 には含まれていません）。そのため、このスキルではリフレクションを使ってサービスをバインドし、エディターにサービスがない場合は通常の SEMANTIC_INVALID 拒否を返します。つまり、6000.3 以降であっても、この呼び出しが実行されるとは限りません。まず listOnly=true を指定して、ここでサービスが利用可能か、登録済みかつ有効なアップグレーダーを確認してください。アップグレーダーの構成は固定されておらず、サードパーティーパッケージが独自のアップグレーダーを登録することもあります。次に upgraderNames（カンマ区切り）を渡すと一部のアップグレーダーが実行され、省略すると有効なアップグレーダーがすべて実行されます。

応答では、アップグレーダーが実際にファイルを書き換えたかを判断できるよう、各アセットの .uxml テキストを変更前後で比較し、changed: true/false を報告します。

コアドメイン知識

USS と CSS の比較

パターン	USS でのサポート	対応方法
フレックスレイアウト	はい	flex-direction、flex-wrap、align-items、justify-content を使用します
border-radius、opacity、overflow:hidden	はい	安全に使用できます
トランスフォーム／トランジション	はい	translate、scale、rotate が動作します
CSS 変数	はい	:root のトークンを優先してください
display:grid／display:block／display:inline	いいえ	すべてフレックスです。折り返し行でグリッドを再現してください
box-shadow	いいえ	背景要素を入れ子にして再現してください
linear-gradient()／radial-gradient()	いいえ	画像テクスチャを使用してください
calc()／@media	いいえ	明示的な値と PanelSettings.scaleMode を使用してください
::before／::after	いいえ	実際の子 VisualElement を追加してください
z-index	いいえ	後にある兄弟要素が手前に描画されます

よく使う USS の回避策

必要なもの	USS で使える回避策
影	コンテンツの背後に追加の子 VisualElement を配置します
レスポンシブな拡大縮小	PanelSettings.scaleMode = ScaleWithScreenSize
グリッドカード	flex-direction: row ＋ flex-wrap: wrap ＋ 子要素の幅
円形アバター	幅と高さを同じにし、半径をサイズの半分に設定して overflow:hidden を指定します
疑似要素による装飾	絶対位置指定した子要素を追加します

使用頻度の高いパラメーター

スキル	まず必要になることが多いパラメーター
uitk_create_panel_settings	savePath、scaleMode、referenceResolutionX、referenceResolutionY
uitk_create_document	name、uxmlPath、panelSettingsPath、sortOrder?
uitk_add_element	filePath、elementType、parentName?、elementName?、text?、classes?
uitk_modify_element	filePath、elementName、変更した属性のみ
uitk_add_uss_rule	filePath、selector、properties

PanelSettings の選択肢

• ScaleWithScreenSize：ランタイムの HUD／メニュー UI のデフォルト
• ConstantPixelSize：厳密なピクセル対応が重要な場合に使用します
• ConstantPhysicalSize：まれなケースです。物理サイズが必要な UI に限って使用します

Unity 6000.2 以降でワールド空間（3D）UI を使用する場合は、先に PanelSettings を設定し、uitk_create_document ではなく uitk_worldspace_panel_create でシーンオブジェクトを作成してください。

ファイルと構造のルール

• <Style src="..."/> を通じて共有トークン／スタイルファイルを参照する UXML ルートを 1 つ使用してください。
• 相対スタイル参照を短く保てるよう、可能であれば USS を UXML の隣に配置してください。
• ファイルを自分で作成していない場合は、複雑な構造を編集する前に uitk_inspect_uxml を使用してください。
• ussPath を指定すると、uitk_create_uxml がスタイルシートを自動参照できます。

ワークフローに関する注意事項

1. 最初に USS／UXML を作成し、その後 uitk_create_document でアタッチしてください。
2. ランタイムでのレンダリングには、有効な PanelSettings アセットが必要です。
3. USS と UXML が同じフォルダーにある場合は、<Style src="MyStyle.uss" /> を優先してください。フォルダーをまたいで参照する場合に限り、完全なアセットパスを使用してください。
4. デザイントークン、コンポーネントのルール、レイアウトコンテナーの順に作成してください。
5. 段階的に編集する場合は、uitk_read_file → 編集 → uitk_write_file の順を推奨します。
6. 2 つ以上のファイルを作成する場合は、uitk_create_batch を使用してください。
7. Unity 6000.2 以降でワールド空間（3D）UI を使用する場合：PanelSettings を作成 → uitk_worldspace_panel_create（ワールド空間のレンダーモードが自動的に設定されます）。
8. ユーザーがすぐに使える初期画面を必要としている場合は uitk_create_from_template を使用し、既存ファイルを対象にした編集には uitk_add_element／uitk_add_uss_rule を使用してください。
9. ランタイムデータバインディングでは、まず UXML 要素を作成し、次にバインドするプロパティごとに uitk_runtime_binding_add を実行してください。uitk_runtime_binding_list で確認します。

最小限の例

import unity_skills

unity_skills.call_skill("uitk_create_panel_settings",
    savePath="Assets/UI/GamePanel.asset",
    scaleMode="ScaleWithScreenSize",
    referenceResolutionX=1920,
    referenceResolutionY=1080
)

unity_skills.call_skill("uitk_create_uss",
    savePath="Assets/UI/HUD.uss",
    content=":root { --accent: #E8632B; } .title { color: var(--accent); }"
)

unity_skills.call_skill("uitk_create_uxml",
    savePath="Assets/UI/HUD.uxml",
    content="<?xml version=\"1.0\" encoding=\"utf-8\"?><engine:UXML xmlns:engine=\"UnityEngine.UIElements\"><Style src=\"HUD.uss\" /><engine:Label class=\"title\" text=\"Start\" /></engine:UXML>"
)

unity_skills.call_skill("uitk_create_document",
    name="HUD",
    uxmlPath="Assets/UI/HUD.uxml",
    panelSettingsPath="Assets/UI/GamePanel.asset"
)

制限事項

このモジュールが意図的に対応していない機能を以下に示します。該当する機能を探して呼び出しを無駄にしないようにしてください。

利用不可	理由	代わりに行うこと
ファーストクラスのパラメーターとしてのバインディングコンバーター／update-trigger	型コンバーターと更新トリガーに使う UXML 属性名は、Unity の Scripting API やマニュアルに記載されていません。推測した名前を指定すると、アセットのインポート全体が失敗します	確認済みの属性を uitk_runtime_binding_add の extraAttributes に渡します
ランタイムバインディングを 1 つだけ削除すること	専用のスキルがありません	ワークフローの履歴からロールバックするか、uitk_write_file で要素を書き換えてください
アセット上に VisualElementReference／AuthoringIdPath を構築すること	これらは MonoBehaviour フィールドの Inspector で設定するランタイム型です。外部からシーンやプレハブに作成するエディター側 API はありません	uitk_element_reference_get で authoring-id のパスを確認し、Inspector または独自の C# で参照を割り当ててください
authoring-id の作成	このスキルは既存の authoring-id 属性を読み取りますが、新しい属性は割り当てません	UI Builder（Unity 6000.5 以降）で作成してください
Unity 6000.2 より前のワールド空間 UI	UIDocument がワールド空間プロパティを取得したのは 6000.2 であり、PanelRenderer が存在するのは 6000.5 以降のみです	UGUI のワールド空間 Canvas（ui モジュール）または xr_setup_ui_canvas を使用してください
Unity 6000.0 より前のランタイムデータバインディング	2022.3 には DataBinding／BindingMode がありません	エディター UI では binding-path の SerializedObject バインディングを使用してください

uitk_element_reference_get は、<Template src="..."> 宣言をたどって別の .uxml ファイルに進み、ネストされたパスを解決します（maxTemplateDepth の範囲内。デフォルトは 3 で、循環参照を防止します）。 解決できないテンプレートは、黙って除外されるのではなく unresolvedTemplates に報告されます。

正確なシグネチャ

正確な名前、パラメーター、デフォルト値、戻り値はこのファイルではなく、GET /skills/schema または unity_skills.get_skill_schema() で定義されています。 複雑な USS システム、レイアウトパターン、コンポーネントスタイル、または完全な例を生成する前に、USS_REFERENCE.md を読み込んでください。