ノードのユーザ定義プロパティとメソッド

このトピックで説明する関数は、3ds Max ユーザインタフェースの [オブジェクトプロパティ](Object Properties )ダイアログボックスの[ユーザ定義](User Defined)パネルにあるシーンオブジェクトのユーザプロパティへのアクセスを提供します。

個々のキーを付けたプロパティを設定および取得するための MAXScript メソッドが 2 セットあります。また、プロパティテキストを単独の長い文字列として扱うことができるメソッドが 2 つあります。 [オブジェクトプロパティ](Object Properties)ダイアログボックスのユーザ定義プロパティは、コンテンツ全体を表す単一の文字列として評価されるか、または次の形式のキー/プロパティペアとして評価されます。

<key1> = <property1><key2> = <property2>...

キーは識別子です(名前または文字列値ですが、名前は推奨しません。以下のノードを参照)。プロパティには値を指定できます。古いメソッドの場合は、数字、ブール演算、またはテキスト文字列を指定できます。新しいメソッドでは、(val==execute(val as string)) が true となる任意の値を使用できます。

注: setUserProp()/getUserProp() メソッドは、予測可能な結果を常に生成するとは限りません。3ds Max 2019.1 Update を使用してユーザプロパティを取得/設定する場合は、setUserPropVal()/getUserPropVal() メソッドを使用することをお勧めします。

注: キーは、大文字と小文字が区別されます。名前値が使用されている場合は、この値が、名前値を定義するために本来使用されていた文字列に変換されます。この文字列は、指定した名前値自体と大文字/小文字が異なる可能性がありますこのため、これらのメソッドのいずれかのキーとして名前値を使用しないことをお勧めします。

<node> メソッドは次のようになります。

getUserPropVal <node> <key_string> [asString:<bool>] [decodeCRLF:<bool>]

3ds Max 2019.1 Update の新機能: ノードのユーザプロパティを取得します。プロパティのキーは <key_string> に対応します。プロパティ値の文字列は、asString が指定されていない場合は、MaxScript 値として評価されます。指定されている場合は、false として評価されます。値の文字列の評価に成功した場合は、この値が返されます。それ以外の場合は、値の文字列が文字列値として返されます。asString が true として指定されている場合、プロパティ値の文字列は常に文字列値として返されます。

3ds Max 2019.2 Update の新機能: ノードパラメータを rootNode または外部参照ルートノード(.tree プロパティ)として指定し、このルートノードのユーザ定義プロパティを取得することができます。

文字列の最初の文字と最後の文字が引用符である場合は、文字列を返すときに文字列からこれらの引用符が削除されます。decodeCRLF が指定されていない場合、または true として指定されている場合は、文字列値を返すときに、プロパティ値の文字列内の改行復帰または改行の 16 進表現は改行復帰文字または改行文字に変換されます。それ以外の場合は、変換されません。つまり、「\xd\xa」は「\r\n」に変換されます。

プロパティキーが存在しない場合は、undefined 値が返されます。プロパティキーが存在しても、値が存在しない場合は、「emptyVal」の値が返されます。

注: getUserPropVal() を使用して、[オブジェクトプロパティ](Object Properties)ダイアログボックスに書き込まれたプロパティ、または setUserProp() を使用して書き込まれたプロパティを取得すると、予期しない結果になることがあります。例:setUserProp "p1" "xxx"; v=getUserPropVal "p1". この場合、v は引用符で囲まれていないため、値表現(グローバル変数名)であると見なされ、変数名の内容が返されます。したがって、通常は「未定義」となります。これは、基本的には v=execute "xxx" と同じです。

setUserPropVal <node> <key_string> <value>  [quoteString:<bool>]

3ds Max 2019.1 Update の新機能: ノードのユーザプロパティを設定します。プロパティキーは <key_string> に対応します。プロパティ値は <value> に対応します。 (val == execute (val as string)) となる任意の値タイプを使用できます。<value> が文字列で、quoteStrings が指定されていない場合、または true として指定されている場合は、プロパティ値の文字列が引用符で囲まれます。それ以外の場合は、引用符で囲まれません。<value> 値が文字列で、encodeCRLF が指定されていない場合、または true として指定されている場合は、プロパティ値の文字列内の改行復帰文字または改行文字が 16 進表現に変換されます。それ以外の場合は、変換されません。つまり、「\r\n」は「\xd\xa」に変換されます。「emptyVal」の値が使用されている場合、キーは書き込まれますが、値は書き込まれません。

3ds Max 2019.2 Update の新機能: ノードパラメータを rootNode または外部参照ルートノード(.tree プロパティ)として指定し、このルートノードのユーザ定義プロパティを設定することができます。

getUserProp <node> <key_string>

ノードのユーザプロパティを取得します。プロパティキーは <key_string> に対応します。キーが存在しない場合は、undefined 値が返されます。MAXScript はプロパティ値を数値に変換しようとします。変換に失敗した場合はブール値に変換し、それにも失敗した場合は、値をテキスト文字列として返します。このため、場合によっては正しく変換されないことがあります。たとえば、プロパティ値が「1m」に設定されていた場合、getUserProp() は時間値として 1800f を返します。「1m」は 1 分を表す時間リテラルとして解釈されるためです。このため、getUserPropVal() を代わりに使用する必要があります。

setUserProp <node> <key_string> <value>

ノードに対して、指定したキーのユーザプロパティを指定した値の文字列表現に設定します。

3ds Max 2019.2 Update の新機能: ノードパラメータを rootNode または外部参照ルートノード(.tree プロパティ)として指定し、このルートノードのユーザ定義プロパティバッファを設定することができます。

<bool>doesUserPropExist <node> <key_string>

3ds Max 2019.1 Update の新機能: 指定したユーザプロパティがノード上に存在する場合は、true を返します。

3ds Max 2019.2 Update の新機能: ノードパラメータを rootNode または外部参照ルートノード(.tree プロパティ)として指定し、このルートノードのユーザ定義プロパティを検索することができます。

<bool>deleteUserProp <node> <key_string>

3ds Max 2019.1 Update の新機能: ノード上の指定したユーザプロパティを削除します。プロパティが存在する場合は、true を返します。

3ds Max 2019.2 Update の新機能: ノードパラメータを rootNode または外部参照ルートノード(.tree プロパティ)として指定し、このルートノードのユーザ定義プロパティを削除することができます。

getUserPropBuffer <node>

ユーザプロパティバッファ全体をすべてのユーザプロパティ設定を含む文字列として取得します。これは、[3ds Max オブジェクトプロパティ](Object Properties)ダイアログボックスの[ユーザ定義プロパティ](User Defined Properties)ボックスの内容と同じです。

setUserPropBuffer <node> <string>

ユーザ定義プロパティバッファを指定した文字列に設定します。

注:

複数行のユーザ定義プロパティバッファ文字列に改行を含めるには、改行復帰と改行の組み合わせ ¥r¥n を使用する必要があります。制御文字のリストについては、「文字列リテラル」を参照してください。

次の 2 つのコードフラグメントでは、シーン内のオブジェクトのユーザ定義プロパティが保存およびロードされます。

最初のコードフラグメントは、ファイルを作成し、すべてのオブジェクトに対してオブジェクト名とユーザ定義プロパティのバッファ文字列を出力します。オブジェクト名は、(readValue() を介して)シーンオブジェクトへの直接参照として返される形で入力されます。また、ユーザ定義プロパティの文字列は、print()を使用して出力され、対応するreadValue() によって 1 つの(長い)文字列リテラルとして読み込むために引用符で囲まれます。

例:

-- create file and for all objects,
-- dump object name and user props
f = createFile "foo.dat"
for o in objects do
(
format "$%\n" o.name to:f -- output name in a pathname form
print (getUserPropBuffer o) to:f -- output buffer as a string literal
)
close f

2 つ目のコード例は、最初のコード例で作成したファイルに読み込み、ユーザプロパティを現在のシーン内にある同じ名前のオブジェクトに適用します。readValue() は、パス名($<name>)を読み込むことができ、指定されたシーンオブジェクトを返します。シーンに指定されたオブジェクトがない場合は、undefined を返します。readValue() 関数も 1 回の実行で複数の行を含む文字列リテラルを読み込めます。

例

-- open file and read in object names and
-- user properties to set
f = openFile "foo.dat"
while not eof f do
(
o = readValue f-- read object
if o != undefined then-- if present, read and set user prop string
setUserPropBuffer o (readValue f)
)
close f

まず xrefs.getXRefFile() を使用して外部参照を取得し、次に .tree プロパティを使用して外部参照ルートノードを取得することにより、外部参照のユーザプロパティバッファにアクセスすることができます。

例

-- Properties on an xref scene
i = 1  -- index value
z = xrefs.getXRefFile i
getUserPropBuffer (z.tree)