> ## Documentation Index
> Fetch the complete documentation index at: https://docs.makkii.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# 仮想オフセットを設定する

> Physics Sensor の基準点から見た任意の点（仮想オフセット/フレーム）を追加・設定する方法

Physics Frame Codegen は、Physics Sensor 自体が計測する点（ビークル上のセンサー設置位置）とは別に、そこから相対的にずれた任意の点を「仮想オフセット」（内部的には「フレーム」と呼びます）として何個でも定義できます。ローター先端、カメラ、武装位置など、Physics Sensor を物理的に置いていない場所の位置・速度・向きを計算したい場合に使います。

## オフセットカードを追加する

中央カラムの「＋ 仮想オフセットを追加」をクリックすると、新しいカードが追加されます。カードのヘッダーで名前を入力できます。名前は生成される Lua コードの変数名の一部に使われるため、`[A-Za-z0-9_]` 以外の文字は自動的に `_` に置き換えられ、先頭の数字などは取り除かれます（例: `rotor-A` → `rotor_A`）。同じ名前のカードが複数あっても動作しますが、生成コードでは2個目以降に `_2` のような連番が付き、中央カラム上部のバッジに `名前重複: <名前>` と表示されます。

カード右上のボタンで、カードの複製（オフセット・出力設定をまるごとコピー）や削除もできます。

## オフセットを入力する

各カードの「Offsets」で、Physics Sensor の基準点からの相対位置と相対回転を入力します。

| フィールド        | 内容        | 単位   |
| ------------ | --------- | ---- |
| X / Right    | 右方向への平行移動 | メートル |
| Y / Up       | 上方向への平行移動 | メートル |
| Z / Forward  | 前方向への平行移動 | メートル |
| Pitch \[deg] | X軸周りの回転   | 度    |
| Yaw \[deg]   | Y軸周りの回転   | 度    |
| Roll \[deg]  | Z軸周りの回転   | 度    |

<Note>
  静的オフセットの角度（Pitch/Yaw/Roll）は、右上の「動的角度単位」設定に関わらず常に度数法です。度数法/ラジアンの切り替えは、後述する動的オフセットの実行時引数にのみ影響します。
</Note>

## 静的オフセットと動的オフセット

カードヘッダーの「動的」チェックボックスで、そのオフセットが Physics Sensor に対して固定されているか、tick ごとに変化するかを切り替えます。

<Tabs>
  <Tab title="静的オフセット（既定）">
    オフセット値はカードに入力した固定値としてコードに直接埋め込まれます。回転角度もあらかじめ数値として計算されるため、Pitch/Yaw/Roll がすべて0の場合は回転行列自体が生成されず、コード量を抑えられます。ローターの取り付け位置のように、ビークルに対して常に同じ位置・向きにある点に向いています。
  </Tab>

  <Tab title="動的オフセット">
    位置・姿勢が実行時に変わる点（旋回するタレット、可動アームの先端など）に使います。動的オフセットに設定したカードは、生成される関数の引数として渡す必要があります。値は次の6要素配列です。

    ```lua theme={null}
    {right, up, forward, pitch, yaw, roll}
    ```

    角度（pitch/yaw/roll）の単位は、右上の「動的角度単位 (Dynamic Unit)」設定（`rad` または `deg`）に従います。生成コード量を抑えたい場合は `rad` を選ぶと、度数法からラジアンへの変換コードが生成されません。

    <Warning>
      毎tick渡すオフセット値は、その tick で観測したい仮想位置・仮想向きとして扱われます。前 tick からのオフセットの変化量は速度・加速度の計算には加算されません（オフセット自体を動かしても、それによる追加の速度は生成コードに反映されません）。
    </Warning>
  </Tab>
</Tabs>

## 関数の引数

生成される関数の引数は、動的オフセットに設定したカードだけが、定義した順番で並びます。静的オフセットのみの構成では引数のない関数になります。

```lua theme={null}
physConvert()                              -- 動的オフセットなし
physConvert(rotor_offset, camera_offset)   -- rotor, camera の順で動的オフセットを設定した場合
```

Lua には名前付き引数がないため、呼び出し側は定義順を意識して6要素配列を渡す必要があります。

出力する物理量の選び方は、[出力リファレンス](/physics-codegen/reference/outputs) を参照してください。


## Related topics

- [使い始め方](/physics-codegen/quickstart.md)
- [Physics Frame Codegen](/physics-codegen/index.md)
- [出力リファレンス](/physics-codegen/reference/outputs.md)
- [設定リファレンス](/physics-codegen/reference/settings.md)
- [HTTP API リファレンス](/physics-codegen/reference/api.md)