スクリプト プラグイン句
プラグイン本体内のさまざまなオプション句は、スクリプト ユーティリティ句およびスクリプト ツール句に似ています。
さらにスクリプト プラグイン固有の句である <parameters> があり、シーンの保存やトラック ビューの表示ができるプラグインのパラメータを定義できます。
スクリプト プラグインを定義する <plugin_body> は、次に示す一連のプラグイン句で構成されます。
<plugin_body> ::= { <plugin_clause> }+プラグイン句はスクリプト プラグインのコンポーネントを定義し、次の 5 つの基本事項のいずれかです。
ローカル変数、関数、または構造体の定義: そのスコープがプラグインである変数、関数、および構造体です。 これらのローカルは、プラグインのインスタンスが存在する限り存在します。ローカルの可視性、および外部コードからのスクリプト プラグイン ローカルへのアクセスの詳細は、「ロールアウト コード内のローカル、関数、構造体、ユーザ インタフェース項目の可視性」および「外部コードからロールアウトのローカルおよび他の項目へのアクセス」を参照してください。
パラメータ ブロック: プラグインのパラメータ セットを定義します。パラメータ セットはプラグイン ローカル変数のようなものですが、直接アニメート化したり、シーン ファイルに保存したり、シーン ファイルから復元したりできます。各パラメータをプラグイン ロールアウト内の適切なユーザ インタフェース要素に関連付けることもできます。このように関連付けられている場合、パラメータは該当するスピナーやチェックボックスなどに「関連付け」られます。一方が変更されると両方が自動的に更新されるため、ユーザ インタフェース イベント ハンドラを作成する必要はありません。これらのパラメータは、別の 3ds Max プラグインに表示される可視パラメータに対応します。
マウス ツール: 3ds Max のビューポートでのマウス クリックに従って一連のアクションを実行するために使用します。詳細は、「スクリプト化されたマウス ツール」を参照してください。
ロールアウト: スクリプト プラグイン用に表示できます。既存のプラグインを拡張するスクリプト プラグイン用に、これらのロールアウトを既存のプラグインのロールアウトへ追加または置換して表示できます。ロールアウト定義については、「ユーティリティ句」を参照してください。
イベント ハンドラ: 特定のイベントに関連付けられた特殊な関数です。イベント ハンドラは、ユーザがスクリプト プラグインのインスタンスを作成したとき、または 3ds Max によってスクリプト プラグインが呼び出されたときに実行する必要のある処理を指定します。これらのアクションによって名前付きイベントが生成され、このイベントに指定したオプションのイベント ハンドラがアクションの発生時に呼び出されます。
<plugin_clause> は、次のように定義されます。
<plugin_clause> ::= <local_variable_decl> |
<local_function_decl> |
<local_struct_decl> |
<parameters> |
<tools> |
<rollouts> |
<event_handler>
トピック ナビゲーション
- ローカル
- すべてのスクリプト プラグインに 4 つのアクセス可能なローカル変数があります。
- パラメータ
- パラメータ イベント ハンドラ
- ツール
- ロールアウトおよび関連するイベント ハンドラ
- イベント ハンドラ
ローカル
<local_variable_decl>、<local_function_decl>、<local_struct_decl> は、MAXScript 内のローカル変数、関数、構造体の定義とまったく同義です。
<local_variable_decl> ::= local <decl> { , <decl> }
<decl> ::= <name> [ = <expr> ] -- optional initial value
<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>
<local_struct_decl> ::= struct <name> ( <member> { , <member> } )
<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )グローバル変数をプラグイン句として宣言することはできません。ただし、イベント ハンドラのスクリプト内では宣言できます。変数名がグローバル変数を確実に参照するようにする必要がある場合は、スクリプトでプラグインを定義する直前に変数名をグローバルとして宣言します。
スクリプトを作成するときは、ローカル変数およびグローバル変数を明示的に宣言することをお勧めします。暗示的な宣言は簡易的に提供されるものであり、通常、リスナーでインタラクティブに作業する場合や短いスクリプトを作成する場合に使用します。長いスクリプトを作成する場合は、変数を明示的に宣言するとエラーを軽減し、コードが読みやすくなります。また、特にグローバル変数が必要な場合を除き、すべての変数をローカルとして宣言することをお勧めします。この理由については、「変数のスコープ」を参照してください。
プラグイン ローカルはプラグイン オブジェクトに所属しており、スクリプト プラグインの各新規インスタンスには独自のローカル記憶領域があります。プラグイン関数やハンドラのプラグイン ローカルへの参照時には、現在アクティブなオブジェクトのローカル記憶領域にアクセスします。たとえば、コマンド パネルで現在開かれているオブジェクトです。プラグイン ローカル記録領域は、シーンの保存およびロードにおいて永続的ではありません(<parameters> とは異なります)。MAXScript 内の別の場所と同様に、ローカルに初期値を指定できます。ローカルは、保存されたスクリプト プラグイン オブジェクトが、開いているシーン ファイルの一部として再度読み込まれるときに再度初期化されます。また、ローカルをプラグイン内に指定し、create イベント ハンドラ内で手動で初期化を実行することもできます。
プラグイン ローカルは、オブジェクト上の通常のプロパティとしてプラグイン以外のスクリプト コードにアクセスできます。ただし、同じ名前が付いている場合は、パラメータやその他の共通オブジェクトのプロパティによって非表示になっている場合があることに注意してください。スクリプト プラグイン オブジェクトのプロパティにアクセスすると、MAXScript ではまず共通のプロパティ内(ノード上の .pos、.scale、.parent など)が検索され、次にパラメータ内、ローカル内で一致するプロパティ名が検索されます。
すべてのスクリプト プラグインに 4 つのアクセス可能なローカル変数があります。
versionオブジェクトの現在のバージョンが整数値として生成されます。
thisスクリプト プラグインのインスタンスが生成されます。
delegateextends: プラグインで拡張しているプラグインのインスタンスが生成されます。
loading3ds Max**6 以降**では、プラグイン インスタンスがロード処理中であれば true を返します。
version ローカル変数には、スクリプト プラグインの定義で指定されたバージョン番号が含まれています。この変数の詳細については、「スクリプト プラグインの更新」を参照してください。
this ローカル変数には、スクリプト プラグインの現在のインスタンスと対応する MAXScript 値が常に含まれています。 この変数によって、プラグイン コード内の新規オブジェクトのパラメータに確実にアクセスする(同じ名前のローカルまたはグローバルがある場合)ことができ、この変数を他の変数に格納する場合にプラグインを参照できます。
delegate ローカル変数には、拡張されたプラグインのインスタンスに対応する MAXScript 値が含まれています。拡張されたプラグインのインスタンスにおける共通のプロパティまたは subAnim プロパティにアクセスするには、delegate ローカル変数を使用する必要があります。
例
delegate.width = thisWidthプラグイン関数またはハンドラの内部で、拡張されるプラグインのインスタンスに
.widthプロパティを設定します。シーン オブジェクトを作成するスクリプト プラグインの代理ローカル変数にノード自体は含まれていませんが、そのノードの BaseObject は含まれています。そのため、作成されたオブジェクトのノード レベルのプロパティにアクセスすることはできません。これに対する例外はノードの変換であり、nodeTMというローカル変数を使用してスクリプト プラグインに公開されます。この変数については、適切なスクリプト プラグイン タイプのトピックを参照してください。
extends: パラメータがプラグインに指定されていない場合、delegate は undefined を返します。
スクリプト ユーティリティおよびロールアウトで可能なように、ローカル変数以外にもローカル関数およびローカル構造体を定義できます。
パラメータ
スクリプト プラグインでは、複数のパラメータ ブロックを定義できます。
パラメータ ブロックの形式は次のとおりです。
parameters <name> [type:#class] [rollout:<name>] (
{ <param_defs> }+
{ <event_handler> }
)パラメータ ブロックは、プラグインのパラメータ セットを定義します。パラメータ セットはプラグイン ローカル変数のようなものですが、直接アニメート化したり、シーン ファイルに保存したり、シーン ファイルから復元したりできます。 各パラメータをプラグイン ロールアウト内の適切なユーザ インタフェース要素に関連付けることもできます。このように関連付けられている場合、パラメータは該当するスピナーやチェックボックスなどに「関連付け」られます。一方が変更されると両方が自動的に更新されるため、ユーザ インタフェース イベント ハンドラを作成する必要はありません。これらのパラメータは、別の 3ds Max プラグインに表示される可視パラメータに対応します。パラメータ ブロックのパラメータには 3ds Max の「元に戻す」機能が備わっていないため、パラメータ値への変更を元に戻すことはできません。
<name> は、パラメータ ブロックに指定され、そのパラメータ ブロックに永久的に関連付けられます。また、シーン ファイルからロードされているプラグイン オブジェクト内の正しいパラメータ ブロックに接続するために MAXScript で使用されます。これは、プラグインのスクリプトを修正し、別のファイル内の古い定義に対応するオブジェクトが存在する場合に重要になります。古いバージョンのオブジェクトが読み込まれると、MAXScript は現行のパラメータ ブロックの定義を参考にして、新しい定義に変換します。正しく変換するために、パラメータ ブロックの各パラメータにも永続的な名前が与えられます。したがって、他のファイル内にプラグインの既存オブジェクトがある場合は、パラメータ ブロック名をランダムに変更しないでください。変更すると、読み込みできなくなります。
オプションの type:<#class> は、パラメータ ブロック内のパラメータが「class」パラメータであることを示します。つまり、このプラグイン クラスの*すべての*オブジェクトには各パラメータのコピーが存在するため、すべてのオブジェクトがパラメータを共有することになります。既存のクラス パラメータの例には、標準ジオメトリ プリミティブの作成タイプおよびキー入力パラメータが挙げられます。
オプションの rollout:<name> は、プラグイン本体の別の場所にあるロールアウト定義を指定し、パラメータ ブロックのパラメータのユーザ インタフェース ロールアウトとして使用されます。内部パラメータ ブロックのメカニズムによる制限のため、各パラメータ ブロックが個別のロールアウトに関連付けられ、各ロールアウトが単一のパラメータ ブロックに関連付けられている必要があります。つまり、プラグインのユーザ インタフェースに含める各ロールアウトには、独自のパラメータ ブロックが個別に必要になります。
<param_defs> は、パラメータ ブロック内の各パラメータの定義です。
形式は次のとおりです。
<name> type:<#name> [localizedName:<string>] [nonLocalizedName:<string>] [tabSize:<integer>]
[tabSizeVariable:<boolean>] [default:<operand>] [animatable:<boolean>]
[subAnim:<boolean>] [ui:<ui_def>] [assettype:<asset_type>]
[invisibleInTV:<boolean>] [showAllInTV:<boolean>]
[readOnly:<boolean>] [readOnlyAsset:<boolean>] [enumAsAsset:<boolean>]
[useNodeOsValidity:<boolean>] [useNodeTmValidity:<boolean>]<name> は、パラメータ ブロック名と同じように、パラメータに永久的に関連付けされます。これを使用して、スクリプト プラグインのオブジェクトが読み込まれるときに正しいパラメータに接続し、スクリプトに特定の変更を加えても、古いバージョンのオブジェクトを読み込めるようにすることができます。パラメータ ブロック名の場合と同様に、取得したい古いバージョンのオブジェクトを含むシーン ファイルが存在する場合は、パラメータ名を変更したり、パラメータ名を再利用したりしないでください。
オプションの localizedName:<string> は 3ds Max がパラメータのローカライズされた名前を表示しようとする際に使用するローカライズされた文字列を指定します。このローカライズされた名前は、パラメータ タイプがアニメート可能、またはマテリアルやテクスチャマップを保持する場合はトラック ビュー、サブマテリアルやサブテクスチャの UI を表示する場合は[マテリアル エディタ](Material Editor)、スロット名を表示する場合は[スレート マテリアル エディタ](Slate Material Editor)などに表示されます。このローカライズされた名前は、MAXScript の getSubAnimName()、getSubAnimNames()、getSubMtlSlotName()、および getSubTexmapSlotName() メソッドから返されます。指定しない場合、パラメータの name プロパティが表示されます。
3ds Max 2021 以降 で使用可能です。
3ds Max 2022 の新機能: オプションの nonLocalizedName:<string> は、スクリプト内のパラメータにアクセスしようとする際に使用されるローカライズされていない(ENU)文字列を指定します。このオプションは、3ds Max が en-US ロケールで実行されている場合に、パラメータの name プロパティが localizedName オプションと異なる場合に指定する必要があります。ローカライズされていない名前は、MAXScript getSubAnimName()、getSubAnimNames()、getSubMtlSlotName() および getSubTexmapSlotName() メソッドを、localizedName/localizedNames オプションを false に設定して呼び出すと、それらのメソッドから返されます。指定しない場合、代わりにパラメータの name プロパティが表示されます。
type:<#name> パラメータが必要になります。これは、パラメータ タイプを定義します。引数には次のいずれかを使用できます。
#float |
アニメート可能 |
#integer |
アニメート可能 |
#index |
アニメート可能 |
#color |
アニメート可能 |
#rgb |
アニメート可能、#color のエイリアス |
#frgba |
アニメート可能、3ds Max 6 から使用可能 |
#point3 |
アニメート可能 |
#point4 |
アニメート可能、3ds Max 6 から使用可能 |
#boolean |
アニメート可能 |
#angle |
アニメート可能 |
#percent |
アニメート可能 |
#worldUnits |
アニメート可能 |
#matrix3 |
|
#string |
|
#filename |
|
#colorChannel |
アニメート可能 |
#time |
アニメート可能 |
#radiobtnIndex |
|
#material |
|
#texturemap |
|
#bitmap |
|
#node |
|
#maxObject |
|
#paramBlock2 |
3ds Max 2018 以降で使用可能 |
#point2 |
3ds Max 2018 以降で使用可能 |
または、上記基本タイプの配列である次のタイプのいずれかを使用できます。
#floatTab |
|
#intTab |
|
#indexTab |
|
#colorTab |
|
#rgbTab |
#colorTab の別名 |
#frgbaTab |
3ds Max 6 から使用可能 |
#point3Tab |
|
#point4Tab |
3ds Max 6 から使用可能 |
#boolTab |
|
#angleTab |
|
#percentTab |
|
#worldUnitsTab |
|
#matrix3Tab |
|
#stringTab |
|
#filenameTab |
|
#colorChannelTab |
|
#timeTab |
|
#radiobtnIndexTab |
|
#materialTab |
|
#texturemapTab |
|
#bitmapTab |
|
#nodeTab |
|
#maxObjectTab |
3ds Max 2010 以降では、パラメータのタイプが #filename である場合、パラメータをアセットとして処理するには、引数が次のいずれかの enum である assettype:<asset_type> を指定する必要があります。
#Other |
|
#Bitmap |
|
#XRef |
|
#Photometric |
|
#Animation |
|
#VideoPost |
|
#BatchRender |
|
#ExternalLink |
|
#RenderOutput |
|
#PreRenderScript |
|
#PostRenderScript |
|
#Sound |
|
#Container |
TYPE_INDEX、TYPE_INDEX_TAB、TYPE_MATRIX3、および TYPE_MATRIX3_TAB が、MAXScript でサポートされる PB2 データ タイプとして追加されました。TYPE_INDEX は基数が 0 のパラメータに使用されますが、MAXScript では、頂点インデックスの場合のように基数が 1 として公開されます。
上記のデータ タイプは、それぞれ #index、#indexTab、#matrix3、および #matrix3Tab タイプのスクリプト パラメータ ブロックでも使用できます。
例
height1 type:#index animatable:true default:1 ui:height1 height3 type:#indexTab tabSizeVariable:true m3a type:#matrix3 default:(matrix3 [1,0,0] [0,0,1] [0,-1,0] [53.1187,-6.50834e-007,14.8893]) m3b type:#matrix3tab tabSizeVariable:true
type:#index はアニメート可能で、#matrix3 はアニメート可能ではありません。
type:#index は、type:#int と同じように作用します。ただし、保存されているデータ値の基数が 0 であっても、MAXScript では基数が 1 とみなされる場合を除きます。このため、上記の例で定義されているように、アニメートされた height1 プロパティを使用するオブジェクトがある場合は
次のように表示されます。
$.height1 15 $.height1.controller.value 14.0
type:#integer パラメータは、パラメータ定義の UI: オプションを使って、dropDownList、ComboBox、ListBox ユーザ インタフェース コントロールに関連付けることができます。パラメータの値は、dropDownList 内で現在選択されている項目のうち、基数は 1 のインデックスに対応しています。
ListBox ユーザ インタフェース コントロールは、3ds Max 7 よりも前のリリースでは、整数パラメータの関連付けでサポートされていませんでした。
通常、このリストには名前や文字列を表示します。関連付けたパラメータの値は、表示させる名前または文字列のコード番号になります。スクリプトを使ってパラメータの値を設定すれば、そのオブジェクトの UI が現在開いている場合は、dropDownList 内の対応する項目が自動的に選択されます。
#worldUnits および #worldUnitsTab は、パラメータがワールド距離値を保持するように指定します。これは、システム単位の実数として内部的に保持されます。
例
parameters main rollout:params ( height type:#worldUnits ui:heightSpin )
ここでは、すべてのスピナー表示が現行のディスプレイ単位では自動的に表示されないことに注意してください。また、関連付けたロールアウト スピナーの定義に type:#worldUnits を指定する必要があります。
#node および #nodeTab は、ノードへの参照を保存するために使用されます。これらのパラメータに保存されたノードは、循環従属を作成することはできません。たとえば、スクリプト ヘルパーを作成してヘルパーをカメラのターゲットまたは親として設定する場合、カメラ ノードを #node または #nodeTab パラメータに保存することはできません。同様に、スクリプト モディファイヤまたはスクリプト マテリアルを作成してノードを #node または #nodeTab パラメータに保存する場合、モディファイヤやマテリアルをそのノードに適用することはできません。
#node および #nodeTab は次のフラグを取ることができます。これにより、ノードがアニメートされる場合にプラグインを再評価するかどうかが変わります。
useNodeTmValidity- スクリプト プラグインがノードの変換の有効性を考慮に入れるようにするには、true に設定します。useNodeOsValidity- スクリプト プラグインがノードのオブジェクト空間/ジオメトリのパイプラインの有効性を考慮に入れるようにするには、true に設定します。
xxTab パラメータのさまざまなタイプにより、対応するタイプを保持したまま値の配列を保存できます。配列の初期サイズは、tabSize: 指定子を使用して指定します。tabSizeVariable:true が指定された場合、配列のサイズより大きなインデックス値を代入すると配列のサイズが自動的に大きくなります。
例
parameters main rollout:params ( mapAmounts type:#floatTab tabSize:4 tabSizeVariable:true ui:(map1Amount, map2Amount, map3Amount, map4Amount) )
4 つの実数要素を含む配列パラメータを定義します(tabSize: パラメータによって定義される)。
UI 項目の数は tabSize と一致しなければなりません。 ユーザがスクリプトによってタブのサイズを増やした場合、新しい項目用の新しい UI 要素は作成されません。ユーザがこの数を UI 要素数を下回るまで減らすと、クラッシュしてしまいます。
個々のロールアウト要素を、配列パラメータ要素ごとに関連付けできます。これらのパラメータは、プラグイン ハンドラ コードでアクセスされた場合に配列として表示されます。
例
a = mapAmounts[i]
tabSizeVariable:true が指定されているため、以下を実行すると配列のサイズは自動的に 10 に増えます。
mapAmounts[10] = a
配列のサイズは、.count プロパティに値を設定して大きくしたり小さくしたりすることもできます。
基本タイプがある種の数値である配列パラメータ内の各要素(floatTab、intTab、percentTab など)は、animatable:false を指定しない限り、個別に、および自動的にアニメート可能になります。.controller プロパティを使って、個別のコントローラを取得し、割り当てることができます。
例
c = mapAmounts[i].controller
オプションのパラメータ default:<operand> は、パラメータの初期既定値を指定します。<operand> 式は、MAXScript によってパラメータの基本タイプに変換可能でなければなりません。
オプションのパラメータ animatable:<boolean> には、パラメータがアニメート可能であり、トラック ビュー内で表示可能どうかを指定します。アニメート可能として指定できるのは、上記のタイプ リスト内でアニメート可能と記された基本タイプのみです。既定は true です。
オプションのパラメータ subAnim:<boolean>は、#node、#material、#textureMap、#maxObject などの 3ds Max オブジェクト タイプに指定できます。true に設定すると、3ds Max オブジェクトは、トラック ビューでサブオブジェクト トラックとして表示されます。既定は false です。
オプションのパラメータ ui:<ui_def> を使用して、このパラメータにリンクされる、パラメータ ブロックの関連付けられたロールアウト内のユーザ インタフェース要素を指定します。ユーザ インタフェース要素にリンクすると、これらに対するユーザ操作は自動的に処理され、さらにアニメーションやスクリプトなどで発生するパラメータへの変更が自動的に更新されます。たとえば、次の例では、main という名前のパラメータ ブロックが params という名前のロールアウトに関連付けられています。 また、height および spread パラメータは、そのロールアウト内の height および spread という名前のスピナーに次のようにリンクされています。
例:
parameters main rollout:params ( key type:#node subAnim:true fill type:#node subAnim:true back type:#node subAnim:true height type:#float animatable:true default:10 ui:height spread type:#float animatable:true default:10 ui:spread on height set val do ( key.pos.z = val back.pos.z = val * 1.5 fill.pos.z = val * 0.5 ) ) rollout params "Light Parameters" ( spinner height "Height" spinner spread "Spread" )
これが完了するとパラメータとスピナーがリンクされるため、どちらか一方に変更が加えられると、その変更がただちにもう一方にも自動的に反映されます。さらに、パラメータがアニメート化される場合は、他の 3ds Max プラグインの場合と同様に、タイム スライダがパラメータのキーフレームに配置されると、スピナーによってキーフレームが赤く強調表示されます。特定のパラメータ タイプにリンクできるユーザ インタフェース項目の種類は、以下に示す適切な組み合わせに限られます。
| パラメータ タイプ | ロールアウト ユーザ インタフェース項目 |
|---|---|
#integer |
スピナー、スライダ、ラジオ ボタン、チェック ボックス、チェック ボタン |
#float |
スピナー、スライダ |
#time |
スピナー、スライダ |
#color |
カラー ピッカー |
#angle |
スピナー、スライダ |
#percent |
スピナー、スライダ |
#colorChannel |
スピナー、スライダ |
#boolean |
チェック ボックス、チェック ボタン |
#node |
選択ボタン |
#textureMap |
マップ ボタン |
#material |
マテリアル ボタン |
#worldUnits |
スピナー、スライダ |
オプションのパラメータ invisibleInTV:<boolean> が true に設定されている場合、トラック ビューのパラメータを非表示にします。これは、トラック ビューに通常表示されるサブアニメーションまたはアニメート可能なパラメータにのみ適用されます。既定値は false です。
オプションのパラメータ showAllInTV:<boolean> が true に設定されている場合、そしてトラック ビューに通常表示されるパラメータがサブアニメーションまたはアニメート可能で、そのパフォーマンスがタブ タイプ パラメータでもある場合、すべてのタブ要素がトラック ビューに表示されます。既定値は false です。
オプションのパラメータ readOnly:<boolean> が trueに設定されている場合は、MAXScript を使用してパラメータ値を設定できません。変更は、ユーザ インタフェースで行う必要があります。同様に、オプションの readOnlyAsset:<boolean> パラメータはアセット タイプのパラメータに適用されます。true に設定されている場合は、アセット トラッカーまたは MAXScript を使用してパラメータ値を設定できません。変更は、ユーザ インタフェースで行う必要があります。
アセット タイプのパラメータに対して、オプションのパラメータ enumAsAsset:<boolean> が true に設定されている場合は、シーンのアセットを列挙するときに、このパラメータで保持されているアセットが報告されるように指定されます。
例
t=teapot() bitmap_holder = attributes "bitmap_holder" ( parameters main ( thebitmap type:#filename assetType:#bitmap enumAsAsset:true ) ) custattributes.add t.baseobject bitmap_holder t.baseobject.thebitmap = "fir1.tga" function get_names name a = append a name files = #() enumerateFiles t.baseobject get_names files enumerateFiles t.baseobject get_names files #missing files --> #("fir1.tga")
パラメータ イベント ハンドラ
次のイベント ハンドラがパラメータに関連付けられています。これらのハンドラは、パラメータに値が割り当てられたとき、またはパラメータ値が取得されるときに呼び出されます。
ほとんどの場合、set は preSet で置き換えられます。以下を参照してください。
on <name> set <arg> do <expr>
on <name> preSet <arg1> do <expr>
on <name> postSet <arg1> do <expr>set ハンドラはブロック内のパラメータに指定することが可能で、パラメータが更新されるたびに、関連付けられたロールアウトのユーザ インタフェース項目を通して、または直接(特に MAXScript プロパティの割り当てなどの場合に)呼び出されます。変更ハンドラをコード化する場合は、パラメータの set ハンドラを指定する方法が、ロールアウト定義内のスピナーやチェックボックスなどの on <item> 変更ハンドラを指定する方法よりも一般的です。前述の例では、set ハンドラによって height パラメータ値が変更されたときにライトの位置が更新されます。
set ハンドラは、その他の従属システム オブジェクトや代理プロパティを設定する場合など、共通の従属操作を実行できるように、インスタンスを作成するときやロードするときにも呼び出されます。
set ハンドラは作成時やロード時に呼び出されません。3ds Max 2018 以降で使用可能: preSet および postSet ハンドラは、パラメータ値の状態を保証します。ほとんどの状況で、set ではなく preSet を使用する必要があります。パラメータ値は元の値になることが保証されますが、渡される <arg> は新しい値だからです。渡される <arg> 値を変更するには、<arg> を変更しないで、ハンドラから新しい値を返します。MAXScript はパラメータをこの戻り値に設定します。
渡される値を変更する必要がない場合、または元のパラメータ値について考慮しない場合は(UI 要素を更新している場合など)、postSet を使用します。
on <name> get <arg> do <expr>get ハンドラはブロック内のすべてのパラメータに指定可能であり、パラメータ値が取得されるたびに呼び出されます。これは、ユーザ インタフェースが更新を開始、またはスクリプトのパラメータにアクセスした場合に発生します。スクリプト(スクリプト プラグイン自体を含む)が再描画またはレンダリングの一部としてパラメータにアクセスし、ビューポートの再描画またはレンダリングが実行された場合にも発生します。これらのすべての場合で、アニメートされた値が 1 回以上取得されます。get ハンドラは、パラメータ ブロック(またはパラメータがアニメートされている場合は元になるコントローラ)に格納されている現在の値である単一の引数で呼び出されます。currentTime 変数には値が取得される時間が設定されるため、現在のスライダ タイムを設定する必要はありません。これは、いつでもパラメータの値を参照できるためです。get ハンドラを実装している場合は値を返す必要があり、その値は値の要求元へのパラメータ値として返されます。値を変更しないで、アクセスを監視するだけの場合は引数を返します。また、どのような値でも適切なタイプで計算して返すことができます。
on <name> set <arg1> [<arg2>] do <expr>
on <name> get <arg1> [<arg2>] do <expr>get および set ハンドラの両方でパラメータが tab タイプの場合、2 番目の引数をハンドラに対して指定できます。tab インデックスが、2 番目の引数に置かれます。
例:
plugin helper getsetHandlerTest name:"DummyEx" classID:#(1453456,5432110) category:"Scripted Primitives" extends:dummy ( parameters main rollout:params ( nodeTab type:#nodetab tabSizeVariable:true on nodeTab set val index do format "set nodeTab: % : %\n" val index on nodeTab get val index do (format "get nodeTab: % : %\n" val index;val) intTab type:#inttab tabSizeVariable:true on intTab set val index do format "set intTab: % : %\n" val index on intTab get val index do (format "get intTab: % : %\n" val index;val) point3Tab type:#point3tab tabSizeVariable:true on point3Tab set val index do format "set point3Tab: % : %\n" val index on point3Tab get val index do (format "get point3Tab: % : %\n" val index;val) intVal type:#integer on intVal set val do format "set intVal: %\n" val on intVal get val do (format "get intVal: %\n" val;val) ) rollout params "Parameters" ( ) ) ---------------------------------- --Test the Get and Set Handlers:-- ---------------------------------- x=getsetHandlerTest() --create an instance of the above Helper b=box() s=sphere() x.nodeTab[1] = b x.nodeTab[2] = s x.nodeTab[1] x.nodeTab[2] x.intTab[1] = 9 x.intTab[2] = 20 x.intTab[1] x.intTab[2] x.point3Tab[1] = [pi,pi,pi] x.point3Tab[2] = [e,e,e] x.point3Tab[1] x.point3Tab[2] x.intVal = 20 x.intVal with animate on at time 100 x.intVal = 120出力:
getsetHandlerTest set intVal: 0 $DummyEx:DummyEx01 @ [0.000000,0.000000,0.000000] $Box:Box01 @ [0.000000,0.000000,0.000000] $Sphere:Sphere01 @ [0.000000,0.000000,0.000000] set nodeTab: $Box:Box01 @ [0.000000,0.000000,0.000000] : 1 $Box:Box01 @ [0.000000,0.000000,0.000000] set nodeTab: $Sphere:Sphere01 @ [0.000000,0.000000,0.000000] : 2 $Sphere:Sphere01 @ [0.000000,0.000000,0.000000] get nodeTab: $Box:Box01 @ [0.000000,0.000000,0.000000] : 1 $Box:Box01 @ [0.000000,0.000000,0.000000] get nodeTab: $Sphere:Sphere01 @ [0.000000,0.000000,0.000000] : 2 $Sphere:Sphere01 @ [0.000000,0.000000,0.000000] set intTab: 9 : 1 9 set intTab: 20 : 2 20 get intTab: 9 : 1 9 get intTab: 20 : 2 20 set point3Tab: [3.14159,3.14159,3.14159] : 1 [3.14159,3.14159,3.14159] set point3Tab: [2.71828,2.71828,2.71828] : 2 [2.71828,2.71828,2.71828] get point3Tab: [3.14159,3.14159,3.14159] : 1 [3.14159,3.14159,3.14159] get point3Tab: [2.71828,2.71828,2.71828] : 2 [2.71828,2.71828,2.71828] set intVal: 20 20 get intVal: 20 20 set intVal: 120 120 OK
on <name> tabChanged <arg1> <arg2> <arg3> do <expr>tabChanged ハンドラは、ブロック内のすべてのタブ パラメータに指定可能であり、タブ自体で操作を実行すると呼び出されます。引数は次のようになります。
arg1: 変更のタイプ。次のうちのいずれかになります: # insert、# append、# delete、# refDeleted、# setCount、# sort。# refDeleted 以外はすべて非常に明確です。このタイプは、タブに保存された MAXWrapper が削除された場合に発生します。
arg2: 操作に関連付けられた tabIndex。適用されない場合の値は、0 になります。
arg3: 操作に関連付けられたカウント。適用されない場合の値は、-1 になります。
たとえば、既に 1 つのメンバを含んでいるタブに項目を追加する場合、引数 #append 2 1 によってこのハンドラに対する呼び出しを取得します。set ハンドラは呼び出されないので、このメッセージを set ハンドラと同じ方法で処理する必要があります。
ツール
プラグインでは、ローカル マウス ツールを定義できます。任意の数のローカル ツールを使用し、必要に応じて起動できますが、通常は、「create」という予約名の単独のツールを指定します。これは、[作成] (Create)パネルに作成されたオブジェクトの作成ツールとなり、スクリプト プラグイン オブジェクトを作成すると自動的に実行されます。ツールの定義については、「スクリプト化されたマウス ツール」を参照してください。
作成可能なシーン スクリプト プラグイン(非表示でないスクリプト プラグイン、テンポラリ、または拡張されたほかのプラグイン)には、create ツールが必要です。create ツールは、非テンポラリ拡張プラグインに表示された場合、代理の create ツールを変更します。アニメート状態は、create ツールの実行中にオフになります。
ローカル変数 WS73099cc142f487553098682e12ac2fc2bc7-722e には、create ツールからアクセスできます。この変数には、Matrix3 値が入っています。この値は、アクティブなグリッドの座標系にあります。この変数により、create ツールは現在作成中のノードの変換を設定できるようになります。また、オブジェクト作成はアクティブなグリッド座標系で管理されているため、create ツール内ではすべての場合に gridX 値を使用し、worldX 値は使用しないでください。
ロールアウトおよび関連するイベント ハンドラ
プラグインでは、ローカル ロールアウトを定義できます。これらは、スクリプト ユーティリティのローカル ロールアウトと構文が同じです。ただし、ユーティリティのローカル ロールアウトとは異なり、これらのロールアウトはコマンド パネルやマテリアル エディタなどのプラグイン タイプに適切であるように自動的に開かれます。
on <rollout> open イベント ハンドラを指定してこれらの値を取得します。ロールアウト定義については、「ユーティリティ句」を参照してください。on <rollout> reload do ...このイベント ハンドラは、スクリプト プラグイン内のロールアウト用に定義されます。このハンドラは、マテリアル エディタまたは[レンダリング効果](render effects)ダイアログ ボックスでプラグインのインスタンスが開いており、同じプラグイン クラスの別のインスタンスが選択された場合に常に、スクリプト マテリアルや環境やレンダリング効果において呼び出されます。この状況では、既存のロールアウトはいったん閉じられてもう一度開くのではなく、開いたままの状態で新しいインスタンスによって「ロード」されます。「reload」ハンドラは、新しいインスタンスがロールアウトにインストールされた後に呼び出され、「on <rollout> open do ...」ハンドラの代わりに使用してロールアウトを更新することができます。この場合、open ハンドラは呼び出されません。reload イベント ハンドラはスクリプト オブジェクトにカスタム アトリビュートが関連付けられている場合には呼び出されず、この場合、既存のロールアウトが閉じられ新しいロールアウトが開きます。
on <rollout> setTime <val> do ...このイベント ハンドラは、スクリプト マテリアルおよびテクスチャマップ内にあるロールアップ用に定義されます。このハンドラは、ロールアウトが表示されているときにタイム スライダが変更されると常に呼び出されます。<val> はスライダ タイムです。
イベント ハンドラ
マウス ツールでの場合と同様に、スクリプト プラグインはハンドラ関数を実行して、3ds Max の特定の操作に応答します。スクリプト プラグインのすべてのタイプでは、以下のイベント ハンドラがサポートされています。これらのイベント ハンドラを使用して、プラグイン ローカル変数を読み込んだり、プラグインの代理プロパティを初期化するなど、必要に応じて追加の初期化を実行できます。
on create do <expr>create イベント ハンドラは、スクリプト プラグインのインスタンスがシーン ファイルに作成されるたびに呼び出されます。アニメート状態は、create イベント ハンドラ式の実行中に暗黙的にオフになります。
on postCreate do <expr>スクリプト プラグインが作成されると、create ハンドラが呼び出され、すべての paramBlock に対する set ハンドラが呼び出され、次に、postCreate ハンドラが呼び出されます。3ds Max 6 およびそれ以降
on load do <expr>load イベント ハンドラは、スクリプト プラグインのインスタンスがシーン ファイルからロードされるたびに呼び出されます。アニメート状態は、load イベント ハンドラ式の実行中に暗黙的にオフになります。
on postLoad do <expr>スクリプト プラグインがロードされると、必要に応じて update ハンドラが呼び出され、load ハンドラが呼び出され、すべてのパラメータ ブロックの項目に関する set ハンドラが呼び出され、次に、postLoad ハンドラが呼び出されます。ほとんどの場合、パラメータ ブロックの項目の set ハンドラがロード中に呼び出されたときには、そこでは何のアクションも実行しないはずです。「loading」自動変数を使用して set ハンドラの条件処理が実行できます。
3ds Max 6 およびそれ以降 で使用可能です。
load または post load ハンドらでは MAX オブジェクトを削除しないことを推奨します。また、パラメータ ブロックの項目の set ハンドラをロード中に呼び出したときには、そこでも MAX オブジェクトを削除しないことを推奨します。 この呼び出しは、シーン ロードにおいて update ハンドラよりもずっと後に発生するので、オブジェクトを削除しても多くの場合失敗を引き起こすことはありません。しかし、保証はできません。
on update do <nodeVar>update イベント ハンドラは、スクリプト プラグインのインスタンスがシーン ファイルに表示されるたびに呼び出され、スクリプト プラグインの定義を変更します(つまり、スクリプト プラグインを定義し、プラグイン オブジェクトのインスタンスをシーンに作成してからスクリプト プラグインを定義するスクリプトを変更して実行すると、スクリプト プラグインの新しい定義内に定義された update イベント ハンドラが、シーン内のプラグイン オブジェクトの各インスタンスで呼び出されます)。詳細は、「スクリプト プラグインの更新」を参照してください。
MAX オブジェクトを update ハンドラ内で削除しないでください。 update ハンドラの呼び出し時にファイルがロードされることはなく、3ds Max が既に削除済みのオブジェクトのロードを完了させようとしたときにオブジェクトを削除すると、クラッシュしてしまう可能性があります。
on attachedToNode <nodeVar> do ...スクリプト プラグイン シーン オブジェクト(ジオメトリ、カメラ、ライト、ヘルパー、シェイプ)がシーン内のノードにバインドされる場合(作成モード中など)に、常に呼び出されます。現在のプラグイン インスタンスが付加されたノードが、最初の引数として与えられます。シーン ノード インスタンス化イベントでは、このハンドラは、基本オブジェクトがノードにインスタンス化されるときに毎回呼び出されるため、複数回呼び出されることがあります。大抵の場合、これは作成モードの最中に呼び出されるため、結果として、ハンドラ本体の他のノード作成などの動作が妨げられます。このような動作は、通常は「on create」ハンドラにあります。
on detachedFromNode <node> do ...これは、シーン オブジェクト スクリプト プラグインへのハンドラです。このハンドラは、プラグイン インスタンスを参照するノードがシーンで削除されるたびに呼び出されます。インスタンスが存在する場合は、基本オブジェクト インスタンスを参照する他のノードが存在する場合もあるので注意してください。
on deleted do...スクリプト プラグイン オブジェクトを最終的に削除したとき、常に呼び出されます。スクリプト化された基本オブジェクトを含むシーン ノードを削除したときなどは、すぐには呼び出されません。これは、ユーザによるノード削除のやり直しに備えて、オブジェクトがやり直しスタックに保持されるためです。ファイルの新規作成やリセットなどでやり直しスタックがクリアされると、削除が行われます。
on clone <original> do ...スクリプト プラグインのインスタンスのクローンが作成されたときに呼び出されます。このイベント ハンドラは、新しく作成されたスクリプト プラグイン インスタンスで呼び出され、渡される引数は、クローン作成されたプラグイン インスタンスになります。
例:
plugin material MyMaterial name:"MyMaterial" classID:#(0x69fedc0d, 0x7c79a4d2) extends:Standard replaceUI:true ( parameters hardwareShaders rollout:shaderRoll ( ) rollout shaderRoll "Hardware Shaders" width:328 height:189 ( label l1 "AA" ) on create do format "created: %\n"this on clone orig do format "cloned: % : % : % : %\n" this orig(this == orig) (delegate == orig.delegate) ) a=mymaterial() b=copy a結果
MyMaterial created: (null):MyMaterial MyMaterial:MyMaterial cloned: MyMaterial:MyMaterial : MyMaterial:MyMaterial : false : false MyMaterial:MyMaterial
特定のスクリプト プラグインのクラスでは、追加のイベント ハンドラを実装しています。特定のスクリプト プラグインのクラスについては、スクリプト プラグイン タイプで説明されています。
特定のイベント ハンドラ内でランタイム エラーが発生した場合、プラグインは定義し直されるまで無効になります。プラグインが無効になると、プラグイン イベント ハンドラはまったく呼び出されません。たとえば、map イベント ハンドラ式(SimpleMods 内)と buildMesh イベント ハンドラ式(SimpleObject 内)のエラーは頻繁に呼び出されるため、プラグインが無効になります。プラグイン イベント ハンドラをもう一度有効にするには、問題を解決し、プラグインの定義を評価し直す必要があります。