Processor

Input Processor は、値を受け取り、その値を処理した結果を返します。受け取る値と結果の値は、同じ型でなければなりません。例えば、clamp Processor を使用すると、コントロールの値を一定の範囲に固定できます。

ノート: 受け取った入力値を別の型に変換するには、合成 Binding を参照してください。

Processor の使用

Processor は、Binding、Action、または Control にインストールできます。

各 Processor は、固有の名前を使用して 登録 されます。既存の Processor を置き換えるには、既存の名前で独自の Processor を登録します。

Processor には、ブーリアン、整数、または浮動小数点数のパラメーターを指定できます。Binding などのデータ内で Processor を指定する場合は、関数呼び出しのような文字列として記述します。

    // "scale" として登録された Processor を参照し、その "factor"
        // パラメーター (浮動小数点値) の値を 2.5 に設定します。

        "scale(factor=2.5)"

        // 複数の Processor を連結できます。これらは、左から
        // 右へと処理されます。
        //
        // 例:  最初に値の符号を反転し、次に [0..10] の値を [0..1] に正規化します。

        "invert,normalize(min=0,max=10)"

Binding への Processor の適用

Action の Binding を作成するときに、Binding に Processor を加えることができます。バインド先のコントロールの値は、これらの Processor によって処理された後で Action の値に適用されます。例えば、コントロールの Vector2 値を Y 軸に沿って反転してから、アプリケーションの入力ロジックを駆動する Action に渡す必要があるとします。これを実現するには、Binding に Invert Vector2 Processor を加えます。

Input Action アセット を使用している場合は、Input Action エディターで Binding に任意の Processor を設定できます。Processor を加える Binding を選択すると、ウィンドウの右ペインに、その Binding のプロパティが表示されます。Processors フォールドアウトの Add (+) アイコンを選択して、現在のコントロールタイプで使用できるすべての Processor のリストを開きます。次に、いずれかの Processor タイプを選択して、そのタイプの Processor インスタンスを加えます。これで、Processor が Processors の折りたたみを開いた部分に表示されます。Processor にパラメーターがある場合は、Processors を開いた部分で編集できます。

Binding の Processor

Processor を削除するには、その横にある Remove (-) アイコンをクリックします。上下の矢印を使用して、Processor の順序を変更することもできます。これは、システムで値が処理される順序に影響します。

コードで Binding を作成する場合は、以下のように Processor を指定できます。

var action = new InputAction();
action.AddBinding("<Gamepad>/leftStick")
    .WithProcessor("invertVector2(invertX=false)");

Action への Processor の適用

Action 上の Processor は、Binding 上の Processor と同様に動作しますが、特定の Binding のコントロールだけでなく、Action にバインドされているすべてのコントロールに適用されます。Binding と Action の両方に Processor がある場合は、Binding 上の Processor が最初に処理されます。

Input Action アセット 内の Action には、Binding の場合と 同じ方法 で Processor を加えて編集できます。編集する Action を選択し、ウィンドウの右ペインで 1 つ以上の Processor を設定します。

コードで Action を作成する場合は、以下のように Processor を指定できます。

var action = new InputAction(processors: "invertVector2(invertX=false)");

Control への Processor の適用

InputControl には、任意の数の Processor を直接設定できます。この Processor が、Control から読み取られた値を処理します。Control の ReadValue を呼び出すと、その値は Control 上のすべての Processor によって処理されてから返されます。Processor をバイパスするには、Control の ReadUnprocessedValue を使用できます。

Control の レイアウト に Processor が指定されている場合は、Input System によって、デバイスの作成時に Control に Processor が設定されます。Control が作成された後で、既存の Control に Processor を加えることはできません。したがって、Control に Processor を加えることができるのは、カスタムデバイスを作成 するときだけです。Input System が標準でサポートしているデバイスの Control には、いくつかの便利な Processor が既に含まれています。例えば、ゲームパッドのスティックには Stick Deadzone Processor が設定されています。

Input System で InputControlAttribute を使用して 状態構造体 から生成されたレイアウトを使用している場合は、以下のように属性の processors プロパティを設定することで、適用する Processor を指定できます。

public struct MyDeviceState : IInputStateTypeInfo
{
    public FourCC format => return new FourCC('M', 'Y', 'D', 'V');

    // この Control は、静止位置が安定しないため、
    // Control に軸デッドゾーンを設定して、0.2 未満の
    // 値を無視します。
    [InputControl(layout = "Axis", processors = "AxisDeadzone(min=0.2)")]
    public short axis;
}

JSON からレイアウトを作成 する場合は、以下のように Control に Processor を指定できます。

{
    "name" : "MyDevice",
    "extend" : "Gamepad", // または他の Device
    "controls" : [
        {
            "name" : "axis",
            "layout" : "Axis",
            "offset" : 4,
            "format" : "FLT",
            "processors" : "AxisDeadzone(min=0.2)"
        }
    ]
}

定義済みの Processor

Input System パッケージには、開発者が使用できる一連の便利な Processor が含まれています。

Clamp (固定)

名前 Clamp
オペランドの型 float
パラメーター float min
float max

入力値を [min..max] の範囲に固定します。

Invert (反転)

名前 Invert
オペランドの型 float

Control の値の符号を反転します (つまり、値に -1 を乗算します)。

Invert Vector 2 (Vector2 の反転)

名前 InvertVector2
オペランドの型 Vector2
パラメーター bool invertX
bool invertY

Control の値の符号を反転します (つまり、値に -1 を乗算します)。invertX が true の場合はベクトルの x 軸を反転し、invertY が true の場合は y 軸を反転します。

Invert Vector 3 (Vector3 の反転)

名前 Invert Vector 3
オペランドの型 Vector3
パラメーター bool invertX
bool invertY
bool invertZ

Control の値の符号を反転します (つまり、値に -1 を乗算します)。invertX が true の場合はベクトルの x 軸を、invertY が true の場合は y 軸を、invertZ が true の場合は z 軸を反転します。

Normalize (正規化)

名前 Normalize
オペランドの型 float
パラメーター float min
float max
float zero

範囲が [min..max] の入力値を正規化します。min が >= 0 の場合は、符号なしの正規化形式 [0..1] になり、min < 0 の場合は、符号ありの正規化形式 [-1..1] になります。

Normalize Vector 2 (Vector2 の正規化)

名前 NormalizeVector2
オペランドの型 Vector2

入力ベクトルを単位長 (1) に正規化します。Vector2.normalized を呼び出すことと同じです。

Normalize Vector 3 (Vector3 の正規化)

名前 NormalizeVector3
オペランドの型 Vector3

入力ベクトルを単位長 (1) に正規化します。Vector3.normalized を呼び出すことと同じです。

Scale (スケール)

名前 Scale
オペランドの型 float
パラメーター float factor

すべての入力値に factor を乗算します。

Scale Vector 2 (Vector2 のスケール)

名前 ScaleVector2
オペランドの型 Vector2
パラメーター float x
float y

すべての入力値に対して、X 軸に沿って x を、Y 軸に沿って y を乗算します。

Scale Vector 3 (Vector3 のスケール)

名前 ScaleVector3
オペランドの型 Vector3
パラメーター float x
float y
float x

すべての入力値に対して、X 軸に沿って x を、Y 軸に沿って y を、Z 軸に沿って z を乗算します。

Axis Deadzone (軸デッドゾーン)

名前 AxisDeadzone
オペランドの型 float
パラメーター float min
float max

Axis Deadzone Processor は、Control の値を調整して、絶対値が min より小さい値はすべて 0 に、絶対値が max より大きい値はすべて 1 または -1 にします。多くの Control には、厳密な静止点がありません (つまり、Control が中央にあっても、常に厳密に 0 が報告されるわけではありません)。デッドゾーン Processor の min 値を使用すると、このような Control から、意図しない入力が読み取られるのを防ぐことができます。また、Control によっては、軸を最大限に移動したときに報告される最大値が一貫しないことがあります。デッドゾーン Processor の max 値を使用すると、このような場合に常に一定の最大値を取得できます。

Stick Deadzone (スティックデッドゾーン)

名前 StickDeadzone
オペランドの型 Vector2
パラメーター float min
float max

Stick Deadzone Processor は、スティックなどの Vector2 Control の値を調整して、作動量が min より小さい入力ベクトルをすべて (0,0) にし、作動量が max より大きい入力ベクトルをすべて長さ 1 に正規化します。多くの Control には、厳密な静止点がありません (つまり、Control が中央にあっても、常に厳密に 0,0 が報告されるわけではありません)。デッドゾーン Processor の min 値を使用すると、このような Control から、意図しない入力が読み取られるのを防ぐことができます。また、Control によっては、軸を最大限に移動したときに報告される最大値が一貫しないことがあります。デッドゾーン Processor の max 値を使用すると、このような場合に常に一定の最大値を取得できます。

カスタム Processor の作成

カスタム Processor を作成してプロジェクトで使用することもできます。カスタム Processor は、UI とコードの両方で、ビルトインの Processor と同じ方法で使用できます。InputProcessor<TValue> から派生するクラスを作成し、Process メソッドを実装します。

重要: Processor は ステートレス でなければなりません。つまり、処理中の入力に応じて変化するローカルの状態を Processor に格納することはできません。これは、Processor が、Input System によって保持される 入力状態 の一部ではないためです。

public class MyValueShiftProcessor : InputProcessor<float>
{
    [Tooltip("Number to add to incoming values.")]
    public float valueShift = 0;

    public override float Process(float value, InputControl control)
    {
        return value + valueShift;
    }
}

次に、作成した Processor を Input System に登録する必要があります。初期化コードで InputSystem.RegisterProcessor を呼び出します。これは、以下のように Processor クラス内でローカルで呼び出すことができます。

# if UNITY_EDITOR
[InitializeOnLoad]
# endif
public class MyValueShiftProcessor : InputProcessor<float>
{
    #if UNITY_EDITOR
    static MyValueShiftProcessor()
    {
        Initialize();
    }
    #endif

    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
    static void Initialize()
    {
        InputSystem.RegisterProcessor<MyValueShiftProcessor>();
    }

    //...
}

これで、新しい Processor が Input Action Asset エディターウィンドウ で使用可能になります。以下のように、コードで Processor を指定することもできます。

var action = new InputAction(processors: "myvalueshift(valueShift=2.3)");

Processor を編集するための UI をカスタマイズする場合は、カスタム InputParameterEditor クラスを作成します。

// InputParameterEditor には、登録の必要はありません。
// システムにより、
// <..> 型パラメーターに基づいて自動的にサブクラスが検出されます。
# if UNITY_EDITOR
public class MyValueShiftProcessorEditor : InputParameterEditor<MyValueShiftProcessor>
{
    private GUIContent m_SliderLabel = new GUIContent("Shift By");

    public override void OnEnable()
    {
        // ここに初期化コードを記述します。編集中の
        // MyValueShiftProcessor のインスタンスを参照するには、
        // "target" を使用します。
    }

    public override void OnGUI()
    {
        // ここで EditorGUILayout を使用してカスタム UI を定義します。
        target.valueShift = EditorGUILayout.Slider(m_SliderLabel,
            target.valueShift, 0, 10);
    }
}
# endif