KSPリファレンスマニュアル 20 - ビルトイン変数と定数(Built-in Variables and Constants)

KSPリファレンスマニュアル 20 - ビルトイン変数と定数(Built-in Variables and Constants)


一般

$CURRENT_SCRIPT_SLOT

この変数は、現在のスクリプトのスクリプトスロットを返します(0から始まるため、最初のスクリプトスロットは0です)。

%GROUPS_SELECTED[<group-idx>]

この変数配列の各インデックスは、同じインデックスを持つグループを指します。

グループが編集対象として選択されている場合、対応する配列のセルには1が、そうでない場合は0が格納されます。

$NI_ASYNC_EXIT_STATUS

この変数は、on async_completeコールバックをトリガーしたコマンドが処理を正常に完了した場合に1を返します。コマンドが処理を完了できなかった場合、たとえばファイルが見つからなかった場合は0を返します。

$NI_ASYNC_ID

この変数は、on async_completeコールバックをトリガーしたコマンドのIDを返します。

$NI_BUS_OFFSET

この定数は、エンジンパラメーターコマンドの<generic>の部分で使用し、Instrumentのバスレベルを指定します。指定したいバスのインデックスを加算します。たとえば$NI_BUS_OFFSET + 2はInstrumentバス3を指します。

$NUM_GROUPS

この変数は、Instrument内のグループの総数を返します。

$NUM_OUTPUT_CHANNELS

この変数は、対象となるKontakt Multiの出力チャンネルの総数を返します。Auxチャンネルは含まれません。

$NUM_ZONES

この変数は、Instrument内のZoneの総数を返します。

$PLAYED_VOICES_INST

この変数は、現在のInstrumentで再生されているボイスの数を返します。

$PLAYED_VOICES_TOTAL

この変数は、すべてのInstrumentで再生されているボイスの数を返します。

$REF_GROUP_IDX

この変数は、Kontaktのインストゥルメント編集ビューで現在表示されているグループのグループインデックスを返します。

パス変数

以下のパス変数を使用できます:

$GET_FOLDER_LIBRARY_DIR

Kontakt Playerでエンコードされたライブラリーに属するパッチで使用した場合:ライブラリーフォルダー。

エンコードされていないパッチで使用した場合:次の場所にあるUser Contentフォルダー。

macOS:/Users/<UserName>/Documents/Native Instruments/User Content/

Windows:C:\Users\<UserName>\Documents\Native Instruments\User Content\

$GET_FOLDER_FACTORY_DIR

Kontaktのファクトリーデータフォルダーです。主にファクトリーのIRサンプルの読み込みに使用します。

注意:これはKontakt Factory Libraryフォルダーではありません。

$GET_FOLDER_PATCH_DIR

パッチが保存されているフォルダーです。

パッチがまだ保存されていない場合は、空の文字列が返されます。

$GET_FOLDER_RC_DIR

Resource Containerが保存されているフォルダーです。ライブラリー構造の中にある他のファイル(たとえばNKAファイルやMIDIファイル)を参照するときは、一般にこのパスを使用することが推奨されます。Resource Containerへのパスは、Kontakt Playerでエンコードされたライブラリーでも、エンコードされていないパッチでも同じだからです。

Instrumentに Resource Container が設定されていない場合は、空の文字列が返されます。

Time Machine Pro 変数

Time Machine Proの2つのボイスリミット(StandardとHigh Quality)にユーザーがアクセスするための定数です。set_voice_limit()get_voice_limit()と組み合わせて使用します。

$NI_VL_TMPRO_STANDARD

$NI_VL_TMRPO_HQ


イベントとMIDI

$ALL_GROUPS

この定数は、disallow_group()allow_group()set_event_par_arr()の各関数で使用したときに、Instrument内のすべてのグループを対象とします。

$ALL_EVENTS

この定数は、イベントID番号を扱う関数において、すべてのイベントを対象とします。

MIDIイベントIDを必要とするMIDIオブジェクトコマンドでも動作します。

$MARK_1 ... $MARK_28

これらの定数を使ってビットマスクを作成し、イベントを任意にグループ化できます。by_marks() , set_event_mark(), get_event_mark(), delete_event_mark(), mf_set_mark() および mf_get_mark() の各コマンドと組み合わせて使用することを想定しています。

%CC[<controller-number>]

この変数配列には、指定したMIDI CC(コンティニュアスコントローラー)メッセージの現在の値が格納されます。

$CC_NUM

この変数には、on controllerコールバックをトリガーしたコントローラーのMIDI CC(コンティニュアスコントローラー)番号が格納されます。

%CC_TOUCHED[<controller-number>]

この変数配列は、MIDI CCの値が変化するたびに自動的に更新されます。指定したMIDI CCの値が変化した場合は1、そうでない場合は0になります。

$EVENT_ID

この変数には、on noteまたはon releaseコールバックをトリガーしたイベントの固有ID番号が格納されます。

$CURRENT_EVENT

この変数には、現在選択されているMIDIイベント、つまりポジションマーカーの位置にあるMIDIイベントの固有ID番号が格納されます。

$EVENT_NOTE

この変数には、on noteまたはon releaseコールバックをトリガーしたイベントのノートナンバーが格納されます。

$EVENT_VELOCITY

この変数には、on noteコールバックをトリガーしたノートのベロシティが格納されます。

イベントパラメーター定数

set_event_par()get_event_par()で使用するイベントパラメーターです:

  • $EVENT_PAR_0 ... $EVENT_PAR_3

  • $EVENT_PAR_VOLUME

  • $EVENT_PAR_PAN

  • $EVENT_PAR_TUNE

  • $EVENT_PAR_NOTE

  • $EVENT_PAR_VELOCITY

  • $EVENT_PAR_MIDI_CHANNEL

set_event_par_arr()get_event_par_arr()で使用するイベントパラメーターです:

  • $EVENT_PAR_ALLOW_GROUP

  • $EVENT_PAR_CUSTOM

  • $EVENT_PAR_MOD_VALUE_ID

  • $EVENT_PAR_MOD_VALUE_EX_ID

get_event_par()でのみ使用するイベントパラメーターです:

  • $EVENT_PAR_SOURCE(イベントが外部から発生した場合は-1、それ以外はスロット番号0 ... 4)

  • $EVENT_PAR_PLAY_POS(Zone内の再生カーソルの絶対位置をマイクロ秒で返します)

  • $EVENT_PAR_ZONE_ID(イベントのZone IDを返します。アクティブなイベントに対してのみ使用できます。Zoneが1つもトリガーされていない場合は-1を返します。イベントによって複数のZoneがトリガーされている場合は、最も大きいZone IDを返します。Zone IDを取得する前に、たとえばwait (1)と記述して、ボイスが動作していることを必ず確認してください)

  • $EVENT_PAR_OUTPUT_TYPEredirect_­output(­)に渡された出力タイプを返します。イベントの出力がリダイレクトされていない場合は$OUTPUT_TYPE_NOT_SPECIFIEDを返します。この定数はKontakt 8.4で導入されました)

  • $EVENT_PAR_OUTPUT_INDEXredirect_­output(­)に渡された出力インデックスを返します。イベントの出力がリダイレクトされていない場合は0を返します。この定数はKontakt 8.4で導入されました)

Multiスクリプトでのみset_event_par()get_event_par()で使用するイベントパラメーターです:

  • $EVENT_PAR_MIDI_COMMAND

  • $EVENT_PAR_MIDI_BYTE_1

  • $EVENT_PAR_MIDI_BYTE_2

mf_set_event_par()mf_get_event_par()で使用するイベントパラメーターです:

  • $EVENT_PAR_POS

  • $EVENT_PAR_NOTE_LENGTH

  • $EVENT_PAR_ID

  • $EVENT_PAR_TRACK_NR

%EVENT_PAR[<event-par>]

この変数配列には、$EVENT_PAR_0 ... $EVENT_PAR_3の値と、$EVENT_PAR_CUSTOMのインデックス4〜15の値が格納されます。これらは$EVENT_IDに対して有効です。

イベントステータス定数

event_status()コマンドが返す値です:

$EVENT_STATUS_INACTIVE

$EVENT_STATUS_NOTE_QUEUE

Multiスクリプトのみ:

$EVENT_STATUS_MIDI_QUEUE

%GROUPS_AFFECTED

この変数配列には、現在のMIDI Note OnイベントまたはNote Offイベントの影響を受けるグループのインデックスが格納されます。

配列のサイズはイベントが影響を与えるグループの数に応じて変化するため、正しい配列サイズを取得するにはnum_elements()コマンドを使用してください。

返されるインデックスはallow_group()disallow_group()のコマンドが適用される前のものなので、Instrumentのマッピングを解析するために使用できます。

$NOTE_HELD

この変数には、コールバックをトリガーしたキーがまだ押されている場合は1、そうでない場合は0が格納されます。

%POLY_AT[<note-number>]

この変数配列には、すべてのMIDIノートナンバーに対するMIDI Polyphonic Aftertouchの現在の値が格納されます。

$POLY_AT_NUM

この変数には、on poly_atコールバックをトリガーしたMIDI Polyphonic Aftertouchイベントのノートナンバーが格納されます。

$RPN_ADDRESS

この変数には、受信したRPNメッセージまたはNRPNメッセージのアドレスが格納されます(0 ... 16383)。

$RPN_VALUE

この変数には、受信したRPNメッセージまたはNRPNメッセージの値が格納されます(0 ... 16383)。

$VCC_MONO_AT

この定数は、モノアフタータッチ(MIDI Channel Pressureメッセージ)用のバーチャルコンティニュアスコントローラーを指定します。主にon controllerコールバックやset_controller()コマンドで使用します。

$VCC_PITCH_BEND

この定数は、MIDI Pitch Bendメッセージ用のバーチャルコンティニュアスコントローラーを指定します。主にon controllerコールバックやset_controller()コマンドで使用します。

$VNC_PITCH_BEND

この定数は、MIDI 2.0のPer-Note Pitch Bendメッセージ用のバーチャルノートコントローラーを指定します。主にon_note_controllerコールバックや、set_note_controller()コマンドで使用します。

%KEY_DOWN[<note-number>]

この変数配列には、すべてのキーの現在の状態が格納されます。キーが押されている場合は1、そうでない場合は0になります。

%KEY_DOWN_OCT[<note-number>]

この変数配列は、オクターブに関係なくいずれかのノートが押されている場合は1、そうでない場合は0になります。そのため、ノートナンバーは0(C)から11(B)の範囲の値にしてください。

フェードカーブ定数

これらの値はfade_in()fade_out()の引数として渡すことができます。

$NI_FADE_LINEAR

リニアなランプです。相関のある素材のクロスフェードに使用します。

$NI_FADE_EQUAL_POWER

イコールパワーカーブです。相関のない素材のクロスフェードに使用します。

$NI_FADE_S_CURVE

S字カーブ(開始と終了がなめらか)です。音楽的なフェードに使用します。

$NI_FADE_EXPONENTIAL

指数カーブ(ゆるやかに始まり、急速に終わります)。

$NI_FADE_LOGARITHMIC

対数カーブ(急速に始まり、ゆるやかに終わります)。


時間とトランスポート

日付と時刻の変数

これらの変数は、オペレーティングシステムで設定されている現在の日付と時刻を整数値として返します。

$NI_DATE_YEAR

$NI_DATE_MONTH(1 ... 12)

$NI_DATE_DAY(1 ... 31)

$NI_TIME_HOUR(0 ... 23)

$NI_TIME_MINUTE(0 ... 59)

$NI_TIME_SECOND(0 ... 59)

$DISTANCE_BAR_START

この変数は、現在のテンポを基準として、現在の小節の先頭からMIDI Note Onメッセージまでの時間をマイクロ秒で返します。

$DURATION_BAR

この変数は、現在のテンポを基準とした1小節の長さをマイクロ秒で返します。

クロックが動作しているときにのみ機能し、それ以外の場合は0を返します。

$SIGNATURE_NUM$SIGNATURE_DENOMを各種の$DURATION_定数と組み合わせて使用することでも、1小節の長さを取得できます。

$DURATION_QUARTER

この変数は、現在のテンポを基準とした4分音符の長さをマイクロ秒で返します。次の変数も使用できます:

$DURATION_EIGHTH

$DURATION_SIXTEENTH

$DURATION_QUARTER_TRIPLET

$DURATION_EIGHTH_TRIPLET

$DURATION_SIXTEENTH_TRIPLET

$ENGINE_UPTIME

この変数は、Kontaktがインスタンス化されてから経過した時間をミリ秒(マイクロ秒ではありません)で返します。エンジンのアップタイムはサンプルレートから算出されるため、オフラインバウンスでも同期が保たれ、音楽的な用途(たとえばアルペジエーターやシーケンサーの構築)にも使用できます。

$KSP_TIMER

この変数は、Kontaktがインスタンス化されてから経過した時間をマイクロ秒で返します。

reset_ksp_timerでリセットできます。

KSPタイマーはCPUクロックに基づいているため、Kontaktがリアルタイムで使用されているかどうかに関係なく一定の速さで進みます。そのため、音楽的な計算のためではなく、スクリプトの効率を検証する目的で使用してください。

$NI_SONG_POSITION

この変数は、ホストの現在のソングポジションを960 PPQ(1拍あたりのパルス数)で返します。

$NI_TRANSPORT_RUNNING

この変数には、ホストのトランスポートが動作している場合は1、そうでない場合は0が格納されます。

$SIGNATURE_NUM

この変数には、現在の拍子記号の分子が格納されます。たとえば4/4の4です。

$SIGNATURE_DENOM

この変数には、現在の拍子記号の分母が格納されます。たとえば4/4の4です。

テンポユニット定数

これらの定数は、$ENGINE_PAR_DL_TIME_UNITのようなエンジンパラメーター変数を使って、時間に関するコントロール(Delay Time、Envelope Attackなど)のユニットパラメーターを制御するために使用します。

$NI_SYNC_UNIT_ABS(テンポに同期しません)

$NI_SYNC_UNIT_WHOLE

$NI_SYNC_UNIT_WHOLE_TRIPLET

$NI_SYNC_UNIT_HALF

$NI_SYNC_UNIT_HALF_TRIPLET

$NI_SYNC_UNIT_QUARTER

$NI_SYNC_UNIT_QUARTER_TRIPLET

$NI_SYNC_UNIT_8TH

$NI_SYNC_UNIT_8TH_TRIPLET

$NI_SYNC_UNIT_16TH

$NI_SYNC_UNIT_16TH_TRIPLET

$NI_SYNC_UNIT_32ND

$NI_SYNC_UNIT_32ND_TRIPLET

$NI_SYNC_UNIT_64TH

$NI_SYNC_UNIT_64TH_TRIPLET

$NI_SYNC_UNIT_256TH

$NI_SYNC_UNIT_ZONE(一部のSourceモジュールのサンプラーモードにおけるSpeedパラメーターにのみ適用されます)

%NOTE_DURATION[<note-number>]

この変数配列には、各キーについてノートが始まってからの経過時間がマイクロ秒で格納されます。主にon releaseコールバックでのみ意味を持ちます。

$NI_BAR_START_POSITION

この変数は、ホストプロジェクトの先頭から現在の小節の開始位置までをティック(960 PPQ)で返します。

注意:AAXプラグインフォーマットはこの情報を提供しないため、ProToolsではこの変数は-1を返します。


コールバックとUI

$NI_CALLBACK_ID

この変数は、コールバックのID番号を返します。すべてのコールバックは固有のID番号を持ち、その番号はユーザー定義関数の中でも変わりません。

$NI_CALLBACK_TYPE

これらの定数は、特定のコールバックIDのコールバックタイプを返します。特定のユーザー定義関数をトリガーしたコールバックタイプを取得するときに便利です。次の定数を使用できます:

$NI_CB_TYPE_ASYNC_COMPLETE

$NI_CB_TYPE_CONTROLLER

$NI_CB_TYPE_INIT

$NI_CB_TYPE_LISTENER

$NI_CB_TYPE_NOTE

$NI_CB_TYPE_NOTE_CONTROLLER

$NI_CB_TYPE_NRPN

$NI_CB_TYPE_PERSISTENCE_CHANGED

$NI_CB_TYPE_PGS

$NI_CB_TYPE_POLY_AT

$NI_CB_TYPE_RELEASE

$NI_CB_TYPE_RPN

$NI_CB_TYPE_UI_CONTROL

$NI_CB_TYPE_UI_CONTROLS

$NI_CB_TYPE_UI_UPDATE

Multiスクリプトのみ:

$NI_CB_TYPE_MIDI_IN

ノブユニットマーク定数

これらの定数はset_knob_unit()または$CONTROL_PAR_UNITと組み合わせて使用します。

$KNOB_UNIT_NONE

$KNOB_UNIT_DB

$KNOB_UNIT_HZ

$KNOB_UNIT_PERCENT

$KNOB_UNIT_MS

$KNOB_UNIT_ST

$KNOB_UNIT_OCT

$NI_UI_ID

この変数は、on ui_controlまたはon ui_controlsコールバックをトリガーしたUIウィジェットのIDを返します。

$NI_SIGNAL_TIMER_BEAT

$NI_SIGNAL_TIMER_MS

$NI_SIGNAL_TRANSP_START

$NI_SIGNAL_TRANSP_STOP

これらの定数はset_listener()またはchange_listener_par()と組み合わせて使用し、どのシグナルがon listenerコールバックをトリガーするかを設定します。

$NI_SIGNAL_TYPE

この変数はon listenerコールバックの中で、どのシグナルタイプがトリガーしたかを判別するために使用できます。

$NI_KONTAKT_IS_HEADLESS

この変数は、KontaktのGUIが利用できない、または読み込めない場合に1を返します。現在のところ、これはKontaktをMaschine+で使用している場合にのみ起こります。Kontaktを通常のホストで使用している場合は、GUIが表示されていなくても0を返します。

$NI_KONTAKT_IS_STANDALONE

この変数は、Kontaktがスタンドアローンで動作している場合は1を、ホストにプラグインとして読み込まれている場合は0を返します。


数学に関する定数

~NI_MATH_PI

この定数は円周率πの値を返します(およそ3.14159…)。

~NI_MATH_E

この定数はネイピア数eの値を返します(およそ2.71828…)。


参照元情報:Built-in Variables and Constants
https://docs.native-instruments.com/online-guides/ksp-manual/en/built-in-variables-and-constants