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

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

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

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

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

<node> メソッドは、次のとおりです。

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

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

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

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

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

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

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

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

getUserProp <node> <key_string>     

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

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

setUserProp <node> <key_string> <value>   

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

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

<boolean>doesUserPropExist <node> <key_string>

指定したユーザ プロパティがノード上に存在する場合は、true を返します。3ds Max 2019.1 Update 以降で使用可能です。

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

<boolean>deleteUserProp <node> <key_string>

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

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

getUserPropBuffer <node>

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

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

setUserPropBuffer <node> <string>

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

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

複数行のユーザ定義プロパティ バッファ文字列に改行を含めるには、改行復帰と改行の組み合わせ \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)