Common Organization of Controls Kit Manual (日本語)

基本的な使い方

合理的かつ簡単に使用できるように設計されたライブラリであり素晴らしい柔軟性および機能を維持します。

準備

あなたが最初に行う必要のあることは、明白であり、ライブラリを require します。その後、 cock.new を使用して制御オブジェクトを新規作成します。任意でデータを即時に埋めることもできますし、または後で行っても構いません。その後、インスタンスに対するシリアル化を介して、任意で保存された設定を読み込みます。その後に (その前にではない) cock.reloadJoysticks によりジョイスティックを再読込することができ、それは本質的に以前使用されたジョイスティックを検出してそれに対する設定を行います。制御の読み込みを行っていない場合は、 cock.setControls によりジョイスティックの方式およびマウスの値へ、標準の制御が割り当てられます(生成時に行っていなかった場合)。

制御データ形式

cock.new および cock.setControls 関数は保全される必要のある特定形式のデータを受理します。それは以下のように定義されています:

{ default1 = {
  up = { primary = { "keyboard", "up" }, secondary = { "mouse axis", "y", "negative", "positive cutoff" },
  down = { primary = { "keyboard", "down" }, secondary = { "mouse axis", "y", "positive", "positive cutoff" } },
 default2 = { ... }
}

制御 "up" および "down" を後でアクセスするために、2つの選択肢 ("primary" および "secondary") を使用して、あるキーボードのみの制御および別のものとしてマウスのみ、および "default1" 制御一式を伸張します。定義済みの標準を cock.setDefault を使用することができます。例えば、制御を標準へ復旧、または利用者編集による制御ではない場合に設定します。

値の取得

これをするのは本当に簡単です:単に制御クラス "current" または "previous" 定義した制御のテーブルにある子供の名前でアクセスします。

if control.current.up > 0 then 
    player.y = player.y - 100 * dt 
elseif control.current.down > 0 then 
    player.y = player.y + 100 * dt 
end

これらの変数 (マウスの軸を除く)は -1 から 1 (0 から 1 では "cutoff" および "whole" 方式) までの範囲の十進数値を内包しており、アナログ制御に対してどちらかを使用することができます。マウス軸の割り当て変数は綺麗な任意値で格納を行い、未定義範囲では、マウス計数および支距のみ影響を受けます。

さらに通常の入力コールバックと同様にライブラリのコールバックを使用できます:

function cock.controlpressed ( id, key, val )
    if key == "up" then
        player.accel = 1
    end
end

標準では、ライブラリ・コールバックはすべて無効であり、従ってそれらを使用するには cock.setCallbacks を介して有効にする必要があります。

さらにライブラリには効率的なゲッターおよびセッターがありますが、それらの使用は強く思いとどまってください。

制御の更新

単に更新関数 (cock.updateAll) を "love.update" コールバックへ置くだけです。それは関数の最初に置くことをお勧めします。 "love.keypressed" といった、その他のコールバックへ置くことはそれらを扱う LOVE 方法に対して全て正当ありますが不要です。

利用者に対して操作の編集を可能にする

ライブラリ "入力捕獲" 方式を仮定する特別な関数があり (cock.setCapture)、指定されたキーへの自動割り当ておよび利用者から入ってくる全ての入力の取り込みを行います。入力取り込み方式時に、入力コールバックおよび更新関数を施錠して、マウスの動作を無視するかどうか指定しても構いません。この方式は cock.cancelCapture を使用することで中断することができます。入力取り込み方式では、マウスの動作取り込みが有効になった場合は、ライブラリはマウスを中央に移動した後にいった入力が取り込まれた場合は位置を中心へ戻しますが、非表示にしないので、利用者による実装可能なマウス・カーソルでは、それは無意味なため、従って取り込みの間にカーソルが非表示であるか確められるか、そうでなければ画面中央へ瞬間移動するか戻されます。この場合は、通常時に cock.bind と一緒に controlcaptured コールバックを終わりに使用したいと思うかもしれません。

cock.bind 関数を使用することでデバイスとキーを手動で割り当てることができます。

"アクション当たりの任意の割り当て" は cock.getEmptyOption を経由して未使用の選択肢を検索することで実装することができます。次の未使用の選択肢を返し、入力を捕らえるために、選択肢の名前は無関係であるため、単にキーを割り当てることで任意の選択肢を解放することができます。関数が空の選択肢の検出に失敗した場合は、存在しない選択肢へ割り当てるのではなく cock.addOption により新規作成する必要があります。これはライブラリの内部構造に依ります。

注意: なにか入力が供給されるまで、入力取り込み方式では、ライブラリはラッパー用途にて一時的に入力コールバックおよび更新関数の置換を行うため、同様(このライブラリ本体にでさえ)に別のライブラリ/モジュールと干渉する可能性があるため、注意して使用してください。これは無限再帰を引き起こしてしまい、スタック・オーバーフローのエラーを青画面に表示して即時異常終了の原因となるため入力取り込み中に別の入力取り込みに横取りされないことを確認してください。経験法則として一度に一つのコールバックのみを置換する権限を付与するか、入れ子の置換を許可することではありますが、置換と交差しないようにしてください。それは別のコードにある別のスレッドでは行われませんが、両方とも施錠を有効にすることで主スレッドで安全な取り込みが行われることを保証します。これをコードで一切行っていない場合は、ロックを有効にする必要はないかもしれません。

高度な機能

このライブラリは強健な設計思想にて作成されていますが、それが常に便利というわけではないため、プログラマの要望により実装された少し便利で高度な機能に対応しています。

マウスの支距および拡大・縮小係数

操作表から値を取得する単純性については、あなたに対してこの二つの算術操作を扱います。それは支距離から実際のマウス位置を減算して (cock.setMouseOffset)、軸ごとに、結果として拡大・縮小係数 (cock.setMouseFactor) を乗算します。これはマウスの中心地点およびマウスの感度を設定を容易な事項を作成します。

デルタおよび反転方式、カットオフ方式

これらの方式は入力読み取りの挙動を変更します。反転方式は入力の否定を行い(軸の反転およびキーに対して "押す" および "離す" 状態の入れ替え)、デルタ方式は実際の値ではなく値の変化を報告します。反転に対する用途は明白であり、デルタ方式はキー押し下げ・キー押し上げおよび軸状の入力デバイスの速力のみ報告できます。

詳細な解釈: Common Organization of Controls Kit Modes

ジョイスティックのハット方式

ジョイスティックのハットに対する標準方式は LÖVE の標準ジョイスティックのハットと同じく "8-方向"の対角線の入力であり、それ以外の亜種は "4-方向" です。この機能は水平または垂直バイアス、均一に半径方向のバイアスの軸を作成するために使用することができます。軸を4方向へ "分割" することができ、それは各方向の値の報告を行い、方向のパッドではなく4つのキーのように D-パッド を効果的に扱います。

詳細な解釈: Common Organization of Controls Kit Hat modes

cock.setJoystickHatMode により必要なときに瞬時に方式を変更することができます。

無反応領域

cock.setJoystickDeadzone により軸毎に無反応領域を定義することができます。この関数はかなり直接的に動作します。関連する小さな実装詳細について知りたいと思うかもしれません。まず最初に値から閾値を減算してから "shrinked" に該当する軸の結果として別の数値により増幅を行い、通常の 1 のように閾値の地点から終点までではなく、 0 から閾値および同様のものへ飛び越します。

ジョイスティックのハットにおける再マッピング

ジョイスティックのハットを扱うある方法として、 cock.remapJoystickHat にて仮想ジョイスティックのハットへジョイスティックのあるボタンを割り当てたいと思う場合があります。これを行うには、単純に対応関数を使用して使用するジョイスティックの4つのボタンを正確に渡します。その後、ジョイスティックは指定されハットが"再割り当て"されて、さらに通常のジョイスティックのハットのように動作します。一度再割り当てを開始すると、即座に"再割り当てされた"方式へ切り替わり、さらに不完全な再割り当ては不完全な操作性の結果となることに注意してください。

設定の表示

リテラルから数値への変換およびその反対、割り当てられた制御を返すためのもの、未使用の選択肢の検出といったようなものを、ライブラリにて少数のフィードバック関数提供しています。これについての詳細はデモにて見つけることができます。

関数の索引

cock.addJoystick (日本語)ジョイスティックを新規追加します。
cock.addOption (日本語)新しい入力オプションを作成します。
cock.bind (日本語)入力のバインド指定をします。
cock.cancelCapture (日本語)入力捕獲の取り消しを行います。
cock.convertAxis (日本語)軸を変換します。
cock.convertDelta (日本語)デルタを変換します。
cock.convertDevice (日本語)デバイスを変換します。
cock.convertInverse (日本語)反転を変換します。
cock.convertJoystick (日本語)ジョイステックを変換します。
cock.convertJoystickHat (日本語)ジョイステックハットを変換します。
cock.convertJoystickHatMode (日本語)ハット方式を変換します。
cock.convertKey (日本語)キーを変換します。
cock.delete (日本語)オブジェクトを削除します。
cock.deleteJoystick (日本語)ジョイスティックを削除します。
cock.deleteOption (日本語)入力オプションを削除します。
cock.explodeCapturedData (日本語)longdata の変換。
cock.find (日本語)オブジェクトを検索します。
cock.getBinded (日本語)制御バインディングを返します。
cock.getCapture (日本語)入力捕獲方式の状態を返します。
cock.getEmptyOption (日本語)未使用の入力オプションを検索します。
cock.getJoystickDeadzone (日本語)無反応領域の取得をします。
cock.getJoystickHatMode (日本語)ハット方式を取得します。
cock.getJoysticksList (日本語)ジョイステックの一覧。
cock.getMouseFactor (日本語)マウス係数を取得します。
cock.getMouseOffset (日本語)マウス支距を取得します。
cock.new (日本語)オブジェクトの新規作成。
cock.reloadJoysticks (日本語)ジョイステックの再読み込み。
cock.remapJoystickHat (日本語)ボタンをハットへ割り当てます。
cock.setCallbacks (日本語)コールバックを有効または無効にします。
cock.setCapture (日本語)利用者編集による制御。
cock.setControls (日本語)コントロール・レイアウトを作成します。
cock.setDefault (日本語)標準値へ復旧します。
cock.setDefaultXBox360 (日本語)(故障中) XBox360 レイアウトを作成します。
cock.setJoystickDeadzone (日本語)無反応領域を設定します。
cock.setJoystickHatMode (日本語)ハット方式を設定します。
cock.setMouseFactor (日本語)マウス係数を設定します。
cock.setMouseOffset (日本語)マウスの支距を設定します。
cock.unbind (日本語)マップをアンバインドします。
cock.update (日本語)オブジェクトを更新します。
cock.updateAll (日本語)全てのオブジェクトを更新します。

関連

そのほかの言語