スクリプトリファレンス（[Root]その他） - SpriteStudio/SS6PlayerForUnity GitHub Wiki

SS6Player for Unity（以降「SS6PU」）のアニメーション制御用クラス（Script_SpriteStudio6_Root）の専属の部位を持たない機能群のスクリプトリファレンスです。

初期化完了状態を取得

関数（動的）

bool StatustGetValid()

引数

返値

true ... 初期化正常終了
false ... 初期化未了 / 初期化異常終了

解説

アニメーションオブジェクトが「Start」関数の処理を正常に終了しているかを取得します。

同種のプロパティに「StatusIsValid」がありますが、このプロパティは使用しないでください（内部処理用なので、仕様が予告なく変更されることがあります）。

初期化完了状態を取得

関数（動的）

bool StatustGetValid()

引数

返値

true ... 初期化正常終了
false ... 初期化未了 / 初期化異常終了

解説

アニメーションオブジェクトが「Start」関数の処理を正常に終了しているかを取得します。

Transformリフレッシュの抑止

関数（動的）

bool RefreshCancelTransform(
        int idParts
        bool flagPosition,
        bool flagRotation,
        bool flagScaling
    )

引数

idParts : パーツID
flagPosition : Positionのリフレッシュの抑制状態
flagRotation : Rotationのリフレッシュの抑制状態
flagScaling : Scaleのリフレッシュの抑制状態

返値

true ... 成功
false ... 失敗（エラー）

解説

非常に特殊な役割の関数です。
アニメーション変更時に、指定パーツの持つGameObjectのTransformの再初期化の抑制を設定します。

SS6PUには「SpriteStudio6のデータ上で、（再生するアニメーションデータ及びSetupアニメーションで）X/Y/Z座標・X/Y/Z軸回転・スケールX/Yのいずれも操作していないパーツは、そのパーツが対応しているGameObjectのTransformを操作しない」という、（他プラットフォームのSS6プレーヤと比較すると特殊ですが、SS5PUの頃から続いて採用されている）仕様があります。
※この仕様は、特定のパーツをスクリプト（プログラム）から直接操作する……ということを実現するためにあります。

正確には、各アトリビュートは下記のTransformの要素に対応しており、それぞれのアトリビュートを使用していない場合には対応するTransformの成分はSS6PUからは変更されない……となります。

X/Y/Z座標 : Transform.localPosition
X/Y/Z軸回転 : Transform.localEulerAngles
スケールX/Y : Transform.localScale

ただし、アニメーションを変更した時には（再生の安定性を維持するために）各パーツのGameObjectの値がリフレッシュされます（これも仕様です）。

アプリケーションの実装の都合によっては、このリフレッシュが邪魔になる場合があります（例えば、アニメーションの変更を問わず、特定パーツのTransform.localScaleをスクリプトから制御したままにしたい場合など）。
そういう場合に、本関数を使用して、アニメーション変更時のTransformのリフレッシュを抑制します。

flagPosition・flagRotation・flagScalingにはそれぞれ下記の指定を行います。

true : アニメーション変更時でも、値のリフレッシュを行わない（値を保持します）。
false : アニメーション変更時は、値のリフレッシュを行う。

インスタンスの取得

関数（動的）

Script_SpriteStudio6_Root InstanceGet(
        int idParts
    )

引数

idParts : パーツID

返値

インスタンスパーツのアニメーション制御クラス
null ... インスタンスがない / 失敗（エラー）

解説

指定したパーツの持つインスタンスアニメーションのアニメーション管理クラス（Script_SpriteStudio6_Root）の実体を取得します。

パーツIDは、IDGetParts関数で取得してください。

本関数が失敗時以外で（正常終了値として）nullを返す場合には、下記があります。

指定したパーツがインスタンスパーツでない。
※一応よくある誤指定なのでエラーではないとして記載してありますが……これは明確に指定ミスです。
指定したパーツがインスタンスアニメーションの実体を持っていない。
※SpriteStudio6上で存在しないアニメーションをインスタンスとして呼び出していたり・Unity上で何らかの理由でインスタンスアニメーションオブジェクトを消去していたりしないかをチェックしてください。

インスタンスの変更

関数（動的）

bool InstanceChange(
        int idParts,
        GameObject source
    )

引数

idParts : パーツID
source : 生成元のアニメーションオブジェクト

返値

true ... 成功
false ... 失敗（エラー）

解説

動的インスタンス変更機能です。
指定したパーツの持つインスタンスアニメーションを、他のアニメーションオブジェクトに変更します。

パーツIDは、IDGetParts関数で取得してください。
指定したパーツがインスタンスパーツない場合、本関数はエラーを返します。

sourceは大抵の場合Prefabなどになるはずで、必ずScript_SpriteStudio6_Rootを持っていること（SpriteStudio6で作成・SS6Playerモードでインポートされたアニメーションオブジェクトであること）が必須です。
sourceにnullを与えると、元のインスタンス（アニメーションオブジェクトのデータをインポートした時に持っているインスタンスアニメーション）に戻します（インスタンスを割り当てない状態にはできないので注意してください）。
sourceで与えられたGameObject（Prefab）はinstantiate（複製か展開）され、指定パーツの子アニメーションとして登録され・制御下に置かれます。
本関数実行以前に指定パーツの制御下にあったインスタンスアニメーションオブジェクトはDestroy（消去）されます。

本関数を使用する上で、最低限、下記に注意する必要があります。

本関数は一時的にある程度の大きさのマネージドメモリ（いわゆるヒープ）を使用し・CPU処理に高負荷をかけます。
※「古いインスタンスアニメーションを消去」「新しいインスタンスアニメーションを作成」「親アニメーションのメッシュ合成用バッファを再構築する」（さらにUnityの処理内でシーンのGameObjectの再構築処理が入る）という処理が実行されるためです。
新しく設定されたインスタンスアニメーションオブジェクトの内容によっては、期待した結果にならない場合があります。
新しく設定されたインスタンスアニメーションオブジェクトの再生アニメーションはインデックス指定で0に設定されます。
新しく設定するインスタンスアニメーションがループ（循環）構造になっていないかに注意してください。
※SpriteStudio6上では設定できない「親アニメーションをインスタンスとして呼び出しているアニメーション」などを指定して、アニメーションの参照構造が無限ループなどに陥るような構造を指定した場合の結果は「不定」であり、大半の場合誤動作やハングアップなどを招きます。
新しく設定されたインスタンスアニメーションと親のアニメーションとの間でフレームレート（FPS）が異なっている場合でも、親のアニメーションのフレームレートに強制的にあわせられます。
インスタンスパーツが持っているアニメーションデータの再生情報で正しく再生されるためには、新しく設定したアニメーションオブジェクトは元のインスタンスアニメーションと最低限互換の実装である必要があります（この場合の互換は「同じ数のアニメーションが、同じ順序で並んでいる」「アニメーションで指定している再生フレーム区間が正しく搭載されている」という意味です）。

インスタンスの再生アニメーションの変更

関数（動的）

1. bool AnimationChangeInstance(
        int idParts,
        string nameAnimation,
        Library_SpriteStudio6.KindIgnoreAttribute ignoreAttribute,
        bool flagStartImmediate = false,
        int timesPlay = 1,
        float rateTime = 1.0f,
        Library_SpriteStudio6.KindStylePlay style = Library_SpriteStudio6.KindStylePlay.NORMAL,
        string labelRangeStart = null,
        int frameRangeOffsetStart = 0,
        string labelRangeEnd = null,
        int frameRangeOffsetEnd = 0
    )
2. bool AnimationChangeInstance(
        int idParts,
        int indexAnimation,
        Library_SpriteStudio6.KindIgnoreAttribute ignoreAttribute,
        bool flagStartImmediate = false,
        int timesPlay = 1,
        float rateTime = 1.0f,
        Library_SpriteStudio6.KindStylePlay style = Library_SpriteStudio6.KindStylePlay.NORMAL,
        string labelRangeStart = null,
        int frameRangeOffsetStart = 0,
        string labelRangeEnd = null,
        int frameRangeOffsetEnd = 0
    )

引数

idParts : パーツID
nameAnimation : 設定するアニメーションの名前
ignoreAttribute : 変更したアニメーションの有効期間
flagStartImmediate : 即時にアニメーションを開始するか？
timesPlay : 再生回数
rateTime : 再生速度
style : 再生スタイル
labelRangeStart : 再生区間先頭ラベル
frameRangeOffsetStart : 再生区間先頭オフセット
labelRangeEnd : 再生区間終端ラベル
frameRangeOffsetEnd : 再生区間終端オフセット

idParts : パーツID
indexAnimation : 設定するアニメーションの番号
ignoreAttribute : 変更したアニメーションの有効期間
flagStartImmediate : 即時にアニメーションを開始するか？
timesPlay : 再生回数
rateTime : 再生速度
style : 再生スタイル
labelRangeStart : 再生区間先頭ラベル
frameRangeOffsetStart : 再生区間先頭オフセット
labelRangeEnd : 再生区間終端ラベル
frameRangeOffsetEnd : 再生区間終端オフセット

返値

true ... 成功
false ... 失敗（エラー）

解説

インスタンスの動的アニメーション変更機能です。
指定したパーツの持つインスタンスアニメーションが再生しているアニメーションを変更します。

パーツIDは、IDGetParts関数で取得してください。

1.と2.の違いは、アニメーションの指定が名前（文字列）であるかインデックス（番号）であるかの違いです。
インデックスで指定した方が、文字列での検索を行わない分ほんの少しだけ高速です（その場合、事前に新しいインスタンスアニメーションのIndexGetAnimation関数などでアニメーションのインデックスを取得しておいてください）。
※単体で使用する分には使い分ける意味はほとんどありませんが、同じ処理ループ中で行ったりする場合や同じ変更指定を複数回行ったりする場合などに、あらかじめインデックスをキャッシュ（保持）しておくことで負荷を減らせます。

ignoreAttributeの仕様については、CellChangeParts関数の同名引数と同じです。
※ただし、対象のアトリビュートが「参照セル」と「インスタンス」の違いがあることはご了承ください。

flagStartImmediateは下記の挙動をします。

true : アニメーションを本関数実行直後から開始します。
この指定の場合、SpriteStudio6上のインスタンスの指定で「独立動作」のチェックをした時と同じ動作になります。
false : アニメーションの再生開始を待ちます。
この指定の場合、指定パーツの「インスタンス」キーデータが次に登場した時に指定アニメーションの再生を開始します。

timesPlay・rateTime・style・labelRangeStart・frameRangeOffsetStart・labelRangeEnd・frameRangeOffsetEndについては、AnimationPlay関数のものと同じ仕様です（いずれもSpriteStudio6の「インスタンス」アトリビュートで設定できる内容です）。
ただし、「同じトラックで直前に再生した時の設定のまま」という指定は存在しない（使用できない）ので注意してください。
唯一の例外は、アニメーションの有効期間（ignoreAttribute）だけを変える場合で、その場合にはアニメーションの指定をなし（「nameAnimation=nullもしくは空文字列」か「indexAnimation=-1」）にすることで可能になります。

動的カラーパラメータ作成

関数（動的）

Library_SpriteStudio6.Control.AdditionalColor AdditionalColorCreate()

引数

返値

動的カラーパラメータの実体への参照 null ... 失敗（エラー）

解説

動的パーツカラーを制御するための、「動的カラーパラメータ」の実体を作成します。
動的カラーパラメータの実体は、動的カラー変更を使用する最初に作成し・動的パーツカラー変更を行わなくなった時に（AdditionalColorRelease関数で）実体を廃棄します。
※つまり、動的パーツカラーを使用している間は一度作成した実体を使い続けます。

本関数で作成した動的パーツカラーは（Ver.1.1.0現在では）子アニメーション（インスタンス・エフェクト）には影響しません。
※本仕様はVer.1.1.0以降のできる限り早いタイミングで変更予定です（引数が追加になる予定です）。

取得したLibrary_SpriteStudio6.Control.AdditionalColorクラスの機能を使って動的パーツカラーを制御します。

動的パーツカラーを使用した場合、アニメーションオブジェクトの持つ全てのパーツに対して指定したパーツカラーがかかり・アニメーションデータ中に設定されているパーツカラーデータは（動的パーツカラーを「未使用」に設定しない限り）無視されます。

本関数は、すでに割り当たった動的カラーパラメータがある場合、実体の再生成を行いません（先着優先です）。
実体を再生成する場合、一度AdditionalColorReleaseで現在割り当たっている動的カラーパラメータの実体を削除してから本関数を使用してください。

動的カラーパラメータ解放

関数（動的）

void AdditionalColorRelease()

引数

返値

解説

AdditionalColorCreate関数で作成した「動的カラーパラメータ」を廃棄します。
本関数を使用した時点で、動的パーツカラーの使用をやめてアニメーションデータの指定に従います。

本関数はVer.1.1.0以降のできる限り早いタイミングで仕様変更予定です（引数が追加になる予定です）。

動的パーツカラーの使用が終わった時点で、本関数を使用して動的カラーパラメータを廃棄しないと、動的カラーパラメータがメモリリークする可能性が高いので注意してください。

静的アニメーションデータ（Read-Only）

変数（動的）

Script_SpriteStudio6_DataAnimation DataAnimation

値

アニメーションオブジェクトのアニメーションデータのマスタ（Read-Only）

解説

SS6PUのアニメーションオブジェクトがアニメーションを再生する上で参照しているアニメーションデータのマスタデータになります。
本変数は、絶対に変更しないでください（読取専用です。また、みだりに変更すると誤動作します）。

本変数の参照先である静的アニメーションデータは、SpriteStudio6上で「同じプロジェクトの同じアニメーション（ssae）」である複数のオブジェクト間で共有されていますので、（参照先の）内容を変更することも行わないでください。
※他のアニメーションオブジェクトに影響が出る上、Script_SpriteStudio6_DataAnimationクラスはScriptableObjectの派生クラスですので、最悪プロジェクト全体に影響が波及しますので、アクセスには細心の注意を払ってください。

本変数から取得した静的アニメーションデータは、Script_SpriteStudio6_DataAnimationクラスの公開機能関数を使って、内部に格納されている情報を取得することができます。静的アニメーションデータに直接アクセスする機会は少ないと思われますが、所持している一部情報群にはアプリケーションを開発する上で有益なものがありますので、（Script_SpriteStudio6_DataAnimationクラスは）それに絞って機能公開しています。

強制非表示指定

変数（動的）

bool FlagHideForce

値

true ... 強制的に非表示にする
false ... 強制非表示を解除する（データに従う）

解説

アニメーションの再生状態や（アニメーションデータ上での）各パーツの非表示状態とは関係なく、アニメーション全体を非表示にする設定です。

ただし、非表示（本値をtrue）に設定しても、再生状態の管理やアニメーション状況の更新などは実行されます（最終的な描画が行われないだけです）。

平面化描画指定

変数（動的）

bool FlagPlanarization

値

true ... 平面化描画を行う
false ... 平面化描画を行わない（データに従う）

解説

SpriteStudio6上で、下記のような場合に「アニメーションが厚みを持つ」場合があります。

パーツソート基準に「Z座標」を指定していたりする都合でZ座標を使用している。
X/Y軸回転を使用している。

上記の際には、各パーツの描画はZ軸方向にも座標が移動したり・表示しているセルなどが各軸に対して傾いたりします。
それらを「アニメーションが厚みを持つ」と呼称しています。

本来、SS6PUはそういったデータに対しても「厚みを持ったまま処理を行う」ことをします。
ただ一部の状況（特に大掛かりな画面演出を作成したり……などの時です）で、その厚みが実装の邪魔になる場合があります。
その多くは、カメラのNear/Farクリップにアニメーションの各パーツがひっかかってしまい、描画が欠けたりする症状として出現します。

そういったアニメーションオブジェクトの本変数をtrueに設定することによって、（描画に限って）厚みを消して「厚さ0」のアニメーションオブジェクトとして描画します。

本変数は、Script_SpriteStudio6_Rootが取得できるタイミングであれば（実際にアニメーションの初期化が完全に終了していない状態でも）指定して構いません（また、アニメーションの動作途中で値を変更することも可能です）。
※ただし、アニメーションオブジェクトからの各種コールバックの受領関数内での変更は推奨しません（動作が不安定になり、前後の処理フレームでの動作が不定になる場合があります）。

ただし、下記の場合「厚さ0になったアニメーションオブジェクトが空間内で回転するので、（結果、軸と平行にならずに）Near/Farクリップなどに引っかかる」状況が起こりますので、注意してください。

アニメーションオブジェクトの親のGameObjectなど（例えば制御パーツやその上位GameObject）がX/Y軸回転している場合。
SpriteStudio6上のrootパーツ（に相当するUnity上のGameObject）でX/Y軸回転やZ座標などが設定されている場合。
※rootパーツについてはアニメーション全体を制御するためのパーツなので扱いが特殊となり、上記の親が回転している場合と同じ挙動をします。
その他カメラがアニメーションオブジェクトに正対していない場合。

また、加えて下記の注意点もあります。

X/Y回転やZ座標が指定されているパーツが当たり判定を持っている場合、その当たり判定については平面化しません（最終的なZ座標が表示とずれる他、当たり判定の厚みも生きています）。
※あくまで平面化するのは描画だけです。
パーツソート基準が「Z座標」を使用している場合、ソートに使用されるZ座標と描画に使用されるZ座標は混同されません（平面化したからといって、パーツ毎の描画優先順序はかわりません）。
同じZ値に他のアニメーションや他アセットでの描画オブジェクトを設置した場合には、パーツなどの間にそれらのオブジェクトが挟み込まれる現象がでる場合があります（Zファイトの一種とお考えください）。

本件は、こちら（Issue内）にも類似解説がございます。

衝突判定と非表示状態との強制連動指定

変数（動的）

bool FlagColliderInterlockHideForce

値

true ... 強制的に非表示と連動する
false ... 非表示と連動しない（常に衝突判定を行う）

解説

アニメーションのパーツに設置されているコライダかコリジョン（当たり判定）の効果を「そのパーツの非表示状態」と同期させるための設定です。
trueに設定すると、パーツが非表示状態になるとコライダも効果しません。

パーツの非表示状態は、「そのパーツ単体の非表示指定」ではなく・親パーツから継承した結果としての「最終的な・実効状態としての非表示」であることに注意してください。

大きな注意点として、特に物理接触（コライダ）を使用している際に、接触状態などは考慮しないで効果・非効果を切り替えるため、実行時の状況によっては意図しない動作などが起こる場合があります。
※空間内の接触判定が突然消失したり・出現したりすることによって、前後の状態を無視した予想がつかない変化が起こる可能性が低くありません。

描画順強制指定

変数（動的）

int OrderInLayer

値

Unityの上での描画順序指定

解説

SS6PUのアニメーションオブジェクトが持つMeshRenderer.sortingOrderに本値が設定されます。
デフォルト値は0です。
設定値の詳細な仕様などは、Unityのスクリプトマニュアルの「Renderer.sortingOrder」を参照ください。

主に、下記のような場合の解決策のひとつになります。

（特にuGUIなどの）UnityのSprite等との描画優先度を制御したい場合。
Unityの動的（メッシュ）バッチングなどでZファイトに類する動作が起こった場合の回避（複数のアニメーションオブジェクトがカメラからの深度が全く同じだった場合に、動的バッチングが描画優先度を邪魔する場合があります）。

本変数は、Script_SpriteStudio6_Rootが取得できるタイミングであれば（実際にアニメーションの初期化が完全に終了していない状態でも）指定して構いません（また、アニメーションの動作途中で値を変更することも可能です）。
※SS6PUの内部処理で、MeshRendererなどの初期化が終了して動作可能な状態になった時から・毎更新処理で設定が行われます。
※ただし、アニメーションオブジェクトからの各種コールバックの受領関数内での変更は推奨しません（動作が不安定になり、前後の処理フレームでの動作が不定になる場合があります）。

本件は、こちら（Issue内）にも類似・追加解説がございます。