unity-ui

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

トリガー

• UGUI 画面の構築
• Canvas 要素の追加
• UI レイアウトの配置
• UGUI 界面の構築、Canvas 要素の追加、UI レイアウトの配置

Unity UI スキル

Unity UGUI / Canvas のワークフローには、このモジュールを使用します。UI Toolkit とは別のモジュールです。

バッチ優先：UI 要素を 2+ 個作成する場合は、ui_create_batch を優先してください。

動作モード

• Approval：照会系の skill（ソースで SkillMode.SemiAuto と記載されている ui_find_all）はそのまま実行します。それ以外の作成／変更系（ui_create_* / ui_set_* / ui_add_* / ui_layout_children / ui_align_selected など、SkillMode.FullAuto と記載されているもの）はユーザーの許可が必要です。許可後、サーバーが一度の処理で実行し、結果を返します。
• Auto / Bypass：すべての skill をそのまま実行します。Auto は AI による自己評価を行い、Bypass はすべて許可します。
• このモジュールには、Delete / PlayMode / Reload / 高リスクの skill は含まれません。Bypass 専用のブロック対象もありません。UI ノードの削除には gameobject モジュールを使用してください。

禁止事項（よくある誤認）：

• ui_add_canvas は存在しません。ui_create_canvas を使用してください。
• ui_create_label は存在しません。ui_create_text を使用してください。
• ui_create_checkbox は存在しません。ui_create_toggle を使用してください。
• ui_set_color は存在しません。Image / Text に対して component_set_property を使用するか、利用可能な場合は専用の UI プロパティスキルを使用してください。
• UGUI（ui）と UI Toolkit（uitoolkit）を混同しないでください。

振り分け：

• UXML/USS/UIDocument には uitoolkit を使用してください。
• XR 対応のワールドスペース Canvas への変換には xr_setup_ui_canvas を使用してください。
• 作成後のテキスト更新には ui_set_text を使用してください。
• レイアウトと整列には ui_layout_children、ui_align_selected、ui_distribute_selected を使用してください。

スキル

作成スキル

Skill	用途	主なパラメーター
ui_create_canvas	Canvas を作成	name?、renderMode?
ui_create_panel	パネルコンテナーを作成	name?、parent?、r/g/b/a?
ui_create_button	ボタンを作成	name?、parent?、text?、width/height?
ui_create_text	テキストラベルを作成	name?、parent?、text?、fontSize?、r/g/b?
ui_create_image	画像を作成	name?、parent?、spritePath?、width/height?
ui_create_inputfield	入力フィールドを作成	name?、parent?、placeholder?、width/height?
ui_create_slider	スライダーを作成	name?、parent?、minValue?、maxValue?、value?
ui_create_toggle	トグルを作成	name?、parent?、label?、isOn?
ui_create_dropdown	ドロップダウンを作成	name?、parent?、options?、width/height?
ui_create_scrollview	ScrollRect 階層を作成	name?、parent?、width/height?、horizontal?、vertical?
ui_create_rawimage	RawImage を作成	name?、parent?、texturePath?、width/height?
ui_create_scrollbar	スクロールバーを作成	name?、parent?、direction?、value?、size?
ui_create_batch	複数の UI 要素を作成	items（JSON 文字列配列）

照会・レイアウトスキル

Skill	用途	主なパラメーター
ui_find_all	シーン内の UI 要素を検索	uiType?、limit?
ui_set_text	テキスト内容を更新	name、text
ui_set_rect	RectTransform のサイズ／オフセットを設定	対象、width、height、posX、posY、left/right/top/bottom?
ui_get_rect_transform	RectTransform の全データを読み取る	対象
ui_set_rect_transform	RectTransform の全データを設定	アンカー、ピボット、オフセット、ローカルトランスフォーム、width/height
ui_set_rect_transform_batch	複数の要素の RectTransform 全データを設定	items
ui_set_anchor	アンカープリセットを適用	対象、preset?、setPivot?
ui_layout_children	垂直／水平／グリッドレイアウト	対象、layoutType?、spacing?
ui_align_selected	現在の選択項目を整列	alignment?
ui_distribute_selected	現在の選択項目を均等配置	direction?

プロパティとエフェクトのスキル

スキル	用途	主なパラメーター
ui_set_image	画像タイプ／塗りつぶし／スプライト	target、type?、fillMethod?、fillAmount?、spritePath?
ui_add_layout_element	LayoutElement の制約を追加	target、幅／高さの優先値、柔軟値
ui_add_canvas_group	CanvasGroup を追加	target、alpha?、interactable?、blocksRaycasts?
ui_add_mask	Mask または RectMask2D を追加	target、maskType?、showMaskGraphic?
ui_add_outline	Shadow／Outline エフェクトを追加	target、effectType?、r/g/b/a?、distanceX/Y?
ui_configure_selectable	トランジション／ナビゲーション／色を設定	target、transition?、navigationMode?、色の値

使用頻度の高いデフォルト

Canvas と親子関係

• ui_create_canvas のデフォルトは ScreenSpaceOverlay です。
• ほとんどの作成スキルでは parent を指定できます。省略した場合、実装の状況に応じて、Unity はアクティブな Canvas またはシーンのルートの下に作成します。
• 再利用可能なメニューグループを作成する場合は、Canvas を一度作成してから Panel を作成し、すべての子コントロールをそのパネルの下に配置します。

よく使われる作成パラメーター

スキル	使用頻度の高いフィールド
ui_create_button	text、width、height
ui_create_text	text、fontSize、r/g/b
ui_create_image	spritePath、width、height
ui_create_slider	minValue、maxValue、value
ui_create_toggle	label、isOn
ui_create_dropdown	options
ui_create_scrollview	horizontal、vertical、movementType

重要：

• ほとんどの作成スキルでは、明示的な x/y の配置は指定できません。
• まず作成し、その後 ui_set_rect、ui_set_anchor、または ui_layout_children で配置／アンカーを設定します。

RectTransform の詳細編集

プリセットではなく Inspector レベルで RectTransform を設定する必要がある場合は、ui_set_rect_transform を使用します。

スキル	パラメーター
ui_get_rect_transform	name、instanceId、path
ui_set_rect_transform	target と anchorMinX/Y、anchorMaxX/Y、pivotX/Y、anchoredPosX/Y/Z、sizeDeltaX/Y、offsetMinX/Y、offsetMaxX/Y、localPosX/Y/Z、localRotX/Y/Z、localScaleX/Y/Z、width、height
ui_set_rect_transform_batch	同じターゲットごとのフィールドを含む items JSON 配列

ui_get_rect_transform

UI 要素の RectTransform データをすべて取得します。

パラメーター	型	必須	デフォルト	説明
name	string	No*	null	GameObject 名
instanceId	int	No*	0	GameObject インスタンス ID
path	string	No*	null	ヒエラルキーのパス

戻り値： { success, name, instanceId, path, anchorMin, anchorMax, pivot, anchoredPosition3D, sizeDelta, offsetMin, offsetMax, localPosition, localEulerAngles, localScale, rect }

ui_set_rect_transform

UI 要素の RectTransform データ全体を設定します。

Parameter	Type	Required	Default	Description
name	string	No*	null	GameObject 名
instanceId	int	No*	0	GameObject のインスタンス ID
path	string	No*	null	ヒエラルキーのパス
anchorMinX / anchorMinY	float	No	null	アンカーの最小値
anchorMaxX / anchorMaxY	float	No	null	アンカーの最大値
pivotX / pivotY	float	No	null	ピボット
anchoredPosX / anchoredPosY / anchoredPosZ	float	No	null	アンカー基準の 3D 位置
sizeDeltaX / sizeDeltaY	float	No	null	サイズの差分
offsetMinX / offsetMinY	float	No	null	オフセットの最小値
offsetMaxX / offsetMaxY	float	No	null	オフセットの最大値
localPosX / localPosY / localPosZ	float	No	null	ローカル位置
localRotX / localRotY / localRotZ	float	No	null	ローカルのオイラー角による回転
localScaleX / localScaleY / localScaleZ	float	No	null	ローカルスケール
width / height	float	No	null	現在のアンカーを基準にしたサイズ

戻り値： ui_get_rect_transform と同じ形式です。

ui_set_rect_transform_batch

複数の UI 要素の RectTransform データ全体を設定します。

Parameter	Type	Required	Default	Description
items	json string	Yes	-	各項目の対象と RectTransform フィールドを含む JSON 配列

戻り値： { success, totalItems, successCount, failCount, results }

レイアウトとアンカーのルール

• コントロールを標準的なレイアウト位置に移動するには、ui_set_anchor が最も手早い方法です。
• アンカー設定後にサイズやオフセットを正確に調整するには、ui_set_rect が適しています。
• 縦、横、またはグリッド形式のメニューを作成する場合、子要素を一つずつ手動で配置するより、ui_layout_children を使用してください。

本番環境でよく使用されるアンカープリセット：

• モーダル／メニューパネルには MiddleCenter
• HUD の隅には TopLeft または TopRight
• 全画面の背景には StretchAll

TextMeshPro に関する注意

テキスト作成時には TMP が自動検出されます：

• TMP が利用可能 -> TextMeshProUGUI
• TMP が利用できない -> レガシーの Text

後続のコンポーネント固有の編集で必要な場合は、作成されたコンポーネントを把握するためにレスポンスのペイロードを確認してください。

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

1. まず Canvas を作成します。
2. 関連するコントロールをパネルでグループ化します。
3. メニュー、HUD グループ、繰り返し使用するウィジェットには、ui_create_batch を優先してください。
4. 子要素を一つずつ手動で配置する前に、アンカーとレイアウトグループを使用します。
5. テキスト作成時には TextMeshPro が自動検出されます。レスポンスには TMP が使用されたかどうかが示されます。
6. ワールド空間のゲームプレイ UI では、まずここで Canvas を作成し、必要な場合にのみ XR 用に変換します。
7. ui_create_batch は主に一括作成用であり、正確な位置調整には適していません。作成後にレイアウトまたは矩形／アンカーを調整してください。
8. 現在の REST/API レイヤーでは、ui_create_batch.items は JSON 文字列のパラメーターであり、生の配列オブジェクトではありません。

最小限の例

import unity_skills
import json

unity_skills.call_skill("ui_create_canvas", name="MainMenu")
unity_skills.call_skill("ui_create_panel", name="MenuPanel", parent="MainMenu", a=0.7)
unity_skills.call_skill("ui_set_rect", name="MenuPanel", width=320, height=240)
unity_skills.call_skill("ui_create_batch", items=json.dumps([
    {"type": "Button", "name": "StartBtn", "parent": "MenuPanel", "text": "Start", "width": 220, "height": 44},
    {"type": "Button", "name": "OptionsBtn", "parent": "MenuPanel", "text": "Options", "width": 220, "height": 44},
    {"type": "Button", "name": "QuitBtn", "parent": "MenuPanel", "text": "Quit", "width": 220, "height": 44}
]))

unity_skills.call_skill("ui_set_anchor", name="MenuPanel", preset="MiddleCenter")
unity_skills.call_skill("ui_layout_children", name="MenuPanel", layoutType="Vertical", spacing=12)

正確なシグネチャ

正確な名前、パラメーター、デフォルト値、戻り値は、このファイルではなく GET /skills/schema または unity_skills.get_skill_schema() で定義されています。 要素の作成に関する詳細、プロパティの表、より大規模な UGUI の例については、UI_REFERENCE.md を読み込んでください。

よくあるエラー

トランスポートレベルのすべてのコード（COMPILING/RATE_LIMIT など）→ ../../references/protocol-error-codes.md

エラー	発生条件	修正方法
TARGET_NOT_FOUND	親の GameObject、UI 要素、RectTransform、Text/Image/Selectable コンポーネント、またはスプライトアセットが見つかりませんでした。	ui_find_all、gameobject_find、または scene_get_hierarchy を使用して要素を探し、asset_find でスプライトのパスを確認してください。
SEMANTIC_INVALID	不明なアンカープリセット、レイアウトタイプ、配置、または区切り文字を含む名前／パスなど、無効な値が指定されました。	エラーの内容から有効なプリセット／タイプ（例：MiddleCenter、Vertical、TopLeft）を選択して、再試行してください。
SKILL_ERROR	必要な数に満たない UI 要素しか選択されておらず、選択ベースの操作に失敗しました（例：Select at least 2 UI elements）。	配置／分布スキルを呼び出す前に、Hierarchy で必要な UI 要素を選択してください。