アシスタント向けブリーフ

AR Clip のプロジェクトについて AI モデルに手伝いを頼む前に、このページを渡してください。チャットに貼り付けるか、このページのアドレスをモデルに渡します。

AR Clip で学習したモデルはありません。このページがないと、モデルは知っているほかのエンジンから知識を借りてきて、正しそうに見えて実は間違っている答えを返します。

機械が読める形式のコンテキストを探す AI ツールは、/llms.txt で自動的に見つけます。ドキュメント全体を 1 ファイルにまとめたものは /llms-full.txt にあります。

プロジェクトの組み立て方

プロジェクトの中のものは、すべてエンティティです。エンティティは、名前とコンポーネントの集まりです。エンティティが何であるかは、コンポーネントで決まります。クラスも、選択するオブジェクトの種類もありません。

Project
└── Space          共有の背景、ライティング、グリッド、単位
    └── Scene      Anchor を持つエンティティ（Anchor はシーンを表示させるトリガー）
        └── Entity
            └── Entity      エンティティは入れ子にできる

次の 2 つの関係を混同しないでください。

構成 — エンティティはコンポーネントを持ちます。同じ種類のものは 1 つまでです。コンポーネントは子ではありません。
包含 — エンティティはほかのエンティティを含みます。親を動かすと、子も動きます。

シーンは、Anchor を持ち、Transform を持たないエンティティです。スペース全体のロジックは、Script か Patch を持ち、親を持たないエンティティです。

コンポーネントを動かすコードを書く必要はありません。あなたの仕事は、どのコンポーネントを置き、どんな値を持たせるかを決めることです。

動きをつける 4 つの方法

レイヤー	置き場所	用途
イベント	Events コンポーネント	トリガーとステップの並び。インタラクションの大半
パッチ	パッチのグラフまたはリソース	値と条件を使うロジックを、ビジュアルで組む
スクリプト	スクリプトのリソース	本当にコードが必要なもの
UI	UI カード	2D インターフェースのすべて

4 つとも、同じコンポーネントを変更します。2 つの方法で同じトリガーを処理すると、2 回発生します。 生成された答えで非常によくあるバグです。

名前

トリガーはケバブケースです：on-click、on-launch、on-collide。
ステップはスネークケースです：play_animation、set_visibility、scene_transit_action。
キーとマウスのトリガーは、スクリプトでは名前が変わります。 イベントでは分岐付きの on-key と on-mouse を使います。スクリプトでは on-keydown / on-keyup と on-mousedown / on-mouseup / on-click を受け取ります。
名前は完全に一致させる必要があります。つづりを間違えてもエラーは出ません。ただ一致しないだけです。
エディタには「Show / hide object」のような読みやすいラベルが表示されます。コードでは上の ID を使います。

名前は推測せず、調べる

MCP で接続している場合、次の呼び出しで、実際に何があるかを正確に確認できます。

呼び出し	返すもの
`list_component_schemas`	すべてのコンポーネントとそのフィールド
`list_event_types`	すべてのトリガーとステップ、そのパラメーター
`list_patch_nodes`	すべてのパッチノードと、そのポート
`describe_*_api`	分野ごとの説明文

コンポーネント、トリガー、ステップ、ノードの名前を含むものを書く前に、これらを呼び出してください。正しそうに聞こえる名前をでっち上げるのが、このプラットフォームでいちばん多いミスです。

MCP がない場合は、リファレンスを使ってください。コンポーネント · トリガー · ステップ · パッチノード · シェーダーノード

正しそうに見えるミス

入れ子の値の一部だけを書くと、全体が置き換わる

update({ position: { y: 2 } }) は x と z を 0 にします。必ず元の値を展開してください。

t.update({ position: { ...t.$data.position, y: 2 } });

マテリアルはスロットのリスト

color はスロットの中にあるので、material.update({ color }) は何もしません。

material.update({
  materials: [{ ...material.$data.materials[0], color: '#ff0000' }],
});

$data に直接代入しない

動いているように見えますが、変更は失われます。データを書き込むのは update() と updateAt() だけです。

動的な物理ボディのトランスフォームを設定しても何も起きない

位置は物理演算が管理していて、次のステップで上書きします。置くには ctx.physics.teleport を、動かすには applyImpulse / applyForce を使ってください。

取り込んだモデルには当たり判定の形状がない

GLB は、コライダーを与えるまで実体がありません。動的なものは、ワールドをすり抜けて落ちていきます。

モデルがよく引っかかるルールは、ほかにもあります。

回転は、スクリプトではラジアン、人が見る場所ではすべて度です（エディタ、パッチノードのポート、MCP のツール）。
ctx.tick では dt を掛けてください。 そうしないと、動きの速さがデバイスのフレームレートに左右されます。
スクリプトでは、コンポーネントのクラスを @was/engine からインポートしてください。 TransformComponent、MetaComponent などです。グローバルなのは init と defineProps だけです。
「アニメーション終了」のイベントは、どのしくみにもありません。時間は自分で計ってください。
スクリプトには DOM も、fetch も、タイマーも、描画ライブラリもありません。 ctx.tick、ctx.audio、ctx.store を使い、インターフェースには UI カードを使ってください。
エディタはロジックを実行しません。 スクリプト、パッチ、物理演算、タイマーが動くのは、プレビューか公開したプロジェクトの中だけです。ユーザーに「スクリプトはエディタで動くはず」と言ってはいけません。
ステートがアクティブな間は、そのオブジェクトへの編集はステートに保存されます。オブジェクトには保存されません。
タイムラインは、タイムライン用のツールで変更してください。 タイムラインのコンポーネントを直接編集すると、アニメーションが再生されないことがあります。
1 つのオブジェクトには、アニメーションの方法を 1 つだけ。 タイムラインは、トランジションを上書きします。

書き直さずに組み込みのステップを使う

ctx.step(name, params, { targets }) は、エディタにあるどのステップでも実行できます。アニメーション、ステートの切り替え、シーンの遷移、トランジションなどです。同じものを手で書く前に、ステップのリファレンスを確認してください。

動くと言う前にパッチをチェックする

コードとして表示して、結果を読んでください。問題のあるグラフは、データの循環か壊れた JavaScript を報告します。MCP では preview_patch_code を使います。

単位

量	データ上	人に見えるもの
位置	メートル	プロジェクトの単位
回転	ラジアン	度
アニメーションの時間	秒	秒（ステートの切り替えではミリ秒）
不透明度	0〜1	キーフレームと不透明度のステップでは 0〜100
フォントサイズ	ピクセル、1000 px = 1 m	ピクセル
クリップのフレーム	30 fps	フレーム

ユーザーへの答え方

どのレイヤーを使いたいかを聞きます。 同じ質問でも、「コードなしで」と「スクリプトで」では答えがまったく違います。
うまくいくいちばんシンプルなレイヤーを選びます。 パッチよりイベント、スクリプトよりパッチです。
どこをクリックするかを伝えます。 エディタで作業している人には、概念よりパネルの名前のほうが大事です。
プレビューするよう伝えます。 「動かない」という報告の大半は、エディタがロジックを実行しないことが原因です。
名前をでっち上げません。 自信がなければそう伝え、リファレンスを案内します。

プロジェクトの組み立て方​

動きをつける 4 つの方法​

名前​

名前は推測せず、調べる​

正しそうに見えるミス​

書き直さずに組み込みのステップを使う​

動くと言う前にパッチをチェックする​

単位​

ユーザーへの答え方​