一般イベント コールバック機能

MAXScript では、3ds Max でサポートされているすべての通知イベント(プレ/ポスト シーン ファイルを開く、新規、リセット、シーン ファイルの保存、プレ/ポスト レンダリング、選択の変更など)に対し、コールバック スクリプトを登録することができます。

1 つの通知イベントに対し、任意の数のコールバック スクリプトを指定できます。

コールバック スクリプトは、ID の付いたセットとしてまとめることができ、個々に、または ID を付けたセット全体を削除することができます。

また、コールバック スクリプトは persistent として指定できるため、現在開いているファイルとともに保存およびロードすることができます。

コールバックの追加

コールバックを追加するには、以下の構文を使用します。

callbacks.addScript <callback_type_name> (<function> | <script_string> | <script_stringstream> | fileName:<filename_string>) [id:<name>] [persistent:<boolean>]         

このメソッドは、新規のコールバック スクリプトを登録するのに使用します。最初の引数で、このスクリプトが関連付けられている通知イベントのタイプが指定されている必要があります。以下に有効な callback_type_name 値を示します。

スクリプトは、MAXScript 関数として提供されます。任意のタイプの関数(グローバル関数、構造体メソッド、プラグイン メソッド)を指定できます。どのパラメータも取らない関数、またはすべてのパラメータに既定値がある関数のみが、コールバックとして登録されます。パラメータを取る関数を追加しようとすると、addScript() の呼び出しは失敗します。コールバックとして渡された関数は保持できないため、persisted:true を指定して呼び出そうとすると失敗します。

スクリプトは、実行するスクリプトのテキストを直接含む String 値または StringStream 値として、または fileName: キーワード引数として指定することもできます。キーワード引数の場合は、イベント通知コールバックが発生するたびに、指定されたファイルがロードおよび実行されます。

3ds Max 2024.2 Update の新機能: fileName:キーワード引数を Python スクリプトに設定することができます。

オプションの id: パラメータを使用して、単独またはグループのコールバックに固有の名前でタグを付け、グループ内のすべてのコールバックをその他のコールバック(他のスクリプト ツールで登録したコールバックなど)に干渉することなく削除できます。

オプションの persistent: パラメータを使用して、スクリプトを現在開いているシーン ファイルに保存するか、ファイルの開閉操作に関係なく、常に実行できるグローバル コールバック スクリプトとして使用するかどうかを指定できます。true 値の場合、スクリプトは現在のファイルに保存され、このファイルを開くたびにコールバック用にロードおよび登録されます。persistent コールバック スクリプトは、新規のファイルをロードしたりリセットを実行すると常に削除されるため、あるファイルの persistent スクリプトが他のファイルに間違ってコピーされることはありません。このパラメータの既定値は false です。つまり、このスクリプトはグローバル スクリプトであり、persistent ではありません。関数ベースのコールバックは保持できないため、persistent:true を指定して渡すと失敗します。

例:

callbacks.addScript #preRender "setUpRenderGeom()" id:#jbwRender

レンダリングを実行する直前に呼び出される新規のコールバック スクリプトを登録します。このスクリプトにより関数が呼び出されます(この関数はあらかじめ設定されている必要があります)。スクリプトには固有の ID が割り当てられ、削除時の選択が可能になります。

-- in 3ds Max 2021 and higher
fn myCallback = print "hello"
callbacks.addScript #nodeCreated myCallback id:#myCallbacks

これにより、ノードが作成されるたびに呼び出される新しいコールバックが登録されます。コールバックは、以前に定義された関数です。

-- in 3ds Max 2024.2 Update and higher
script_name = @"C:\My Documents\scripts\my_python_script.py"
callbacks.addScript #nodeCreated filename:script_name id:#myCallbacks

これは前の例と似ていますが、コールバックが Python スクリプトである点が異なります。

コールバックの削除

callbacks.removeScripts [<callback_type_name>] [id:<name>]      

このメソッドは、1 つまたは複数のコールバック スクリプトを登録解除および削除します。

コールバック イベント タイプの名前を指定すると、そのイベント タイプに対するすべてのコールバック スクリプトが削除されます。

id: を指定するだけで、その ID を持つすべてのイベント内のコールバック スクリプトが削除されます。

上記の両方を指定すると、指定したイベント タイプと ID に制限して削除することができます。

コールバックの検査

callbacks.show [<callback_type_name>] [id:<name>] [to:<stream>] \
  [asArray: <boolean>] 

このメソッドは、[リスナー] (Listener)ウインドウに現在のコールバック スクリプトまたは関数をリストするか、オプションのストリームに出力します。リストされたコールバックには、ID、永続的な設定、およびシーン ファイルからロードされているかどうかが示されます。コールバックが文字列、stringStream、またはファイル内で定義されている場合、定義されているスクリプトまたはファイル名もリストされます。コールバックが関数として定義されている場合、定義されている構造体やプラグインを含む関数名がリストされます。

3ds Max 2009 以降 でオプションのコールバック タイプ名引数を指定した場合、そのタイプのコールバックだけが表示されます。

オプション キーワード引数 id: を指定した場合、その ID を持つコールバックだけが表示されます。

タイプ名と ID の両方を指定した場合、指定された ID を持つそのタイプのコールバックだけが表示されます。

3ds Max 2018.4 以降で使用可能: オプションのキーワード引数 to: を指定すると、メソッドからの出力は指定されたストリームに送信されます。

コールバック定義がシーン ファイルからロードされている場合は、SceneFileEmbedded:true としてリストされ、埋め込まれたスクリプトと見なされます。[セーフ シーン スクリプトの実行](Safe Scene Script Execution)機能が有効になっている場合、これらのタイプのコールバックは検査され、潜在的な危険性のあるコマンドは実行されません。3ds Max 2021.3 Update 以降で使用可能です。オプションのキーワード引数 asArray: が指定されている場合、出力は各コールバックの要素が含まれている配列として返されます。3ds Max 2019.3 Update 以降で使用可能です。各要素は、コールバックに関する情報を次の順序で持つ配列です。

(callback type, callback ID, persistent, is filename, script name, scene file embedded)

例

-- show callbacks of type #filePreOpen
callbacks.show #filePreOpen
-- output:
filePreOpen:
  id:#PhysXPlugin, persistent:false, SceneFileEmbedded:false, script:"px_filePreOpen()"
  id:#ALC_SecurityTool, persistent:false, SceneFileEmbedded:false, script:"::ALC_SecurityTool.scenePreOpen()"
  id:#ALC2_SecurityTool, persistent:false, SceneFileEmbedded:false, script:"::ALC2_SecurityTool.scenePreOpen()"
  id:#CRP_SecurityTool, persistent:false, SceneFileEmbedded:false, script:"::CRP_SecurityTool.m_in_file_open = true;::CRP_SecurityTool.register_post_load_check()"
  id:#ADSL_SecurityTool, persistent:false, SceneFileEmbedded:false, script:"::ADSL_SecurityTool.m_in_file_open = true;::ADSL_SecurityTool.register_post_load_check()"
OK

-- the same thing, but as an array:
callbacks.show #filePreOpen asArray:true
-- output:
#(#(#filePreOpen, #PhysXPlugin, false, false, "px_filePreOpen()", false), #(#filePreOpen, #ALC_SecurityTool, false, false, "::ALC_SecurityTool.scenePreOpen()", false), #(#filePreOpen, #ALC2_SecurityTool, false, false, "::ALC2_SecurityTool.scenePreOpen()", false), #(#filePreOpen, #CRP_SecurityTool, false, false, "::CRP_SecurityTool.m_in_file_open = true;::CRP_SecurityTool.register_post_load_check()", false), #(#filePreOpen, #ADSL_SecurityTool, false, false, "::ADSL_SecurityTool.m_in_file_open = true;::ADSL_SecurityTool.register_post_load_check()", false))


-- function defined in a struct:
callbacks.show #nodeCreated
-- output:
nodeCreated:
  id:#myCallbacks, persistent:false, SceneFileEmbedded:false, script:"myStruct.myCallback()"

callbacks.broadcastCallback <callback_type_name> 

このメソッドは、特定のイベントのシミュレーション方法とそのイベントを実行するためのすべてのコールバック スクリプトを提供します。

3ds Max 内では、#preRenderFrame および #postRenderFrame コールバックはレンダラーによってだけ呼び出すことができます。このメソッドを使用してこれらのコールバックを呼び出すことはできません。

コールバックに関する補足情報

callbacks.notificationParam() 

このメソッドは、コールバックに追加の情報を提供するためにコールバック スクリプト内で呼び出すことができます。このメソッドによって返される値は、コールバックのタイプに応じて異なります。コールバックの追加情報がない場合は、'undefined' という値が返されます。

例:

--Remove any existing callbacks with this ID.
callbacks.removeScripts id:#MXSHelp
--Add a new callback script which will call
--callbacks.notificationParam() before selected nodes are deleted
--and thus will print the deleted objects to the Listener:
callbacks.addScript #selectedNodesPreDelete" print (callbacks.notificationParam())" id:#MXSHelp

コールバック イベント名と notificationParam の戻り値

これらは、サポートされているすべてのコールバック イベント名と、通常返される callbacks.notificationParam() の値です。ブロードキャストが生成された方法によっては、ここに示した値の代わりに 'undefined' が返される場合があります。

廃止されたコールバック関数

MAXScript では、シーンを開くコールバックまたはシーン保存コールバックを追加する 2 つの関数が引き続き公開されていますが、廃止/非推奨になっているため、使用しないでください。

• setOpenSceneScript() は callbacks.addScript() と #filePreOpen に置き換えられました。
• setSaveSceneScript() は callbacks.addScript() と #filePreSave に置き換えられました。