スクリプトリファレンス（Sequence） - SpriteStudio/SS6PlayerForUnity GitHub Wiki

SS6Player for Unity（以降「SS6PU」）のシーケンス制御用クラス（Script_SpriteStudio6_Sequence）の機能群のスクリプトリファレンスです。
シーケンス制御はVer.1.x系では実装されておりません（Ver.2.0以降）。

再生関連

静的プロジェクトデータ

変数（動的）

Script_SpriteStudio6_DataProject DataProject;

値

シーケンスオブジェクトで再生するシーケンスが格納されているプロジェクトデータ

解説

SS6PUのシーケンスオブジェクトがシーケンスを再生する上で参照しているアニメーションデータのマスタデータです。
本変数は、変更可能ですが、その先のプロジェクトデータについては変更しないようにしてください（プロジェクトデータ本体は読取専用です。また、みだりに変更すると誤動作します）。
ただし、シーケンスオブジェクトの再生中に本値を変更しないでください（必ず停止させてから行うようにしてください）。

シーケンスオブジェクトは本来シーン上に設置して、その際にインスペクタからプロジェクトデータが設定されているべきものですが、シーケンスオブジェクトをinstantiate等で動的に生成した場合などに後から設定しなくてはならない場合が生じます。
本値をインスペクタから設定していない状況によっては初期化不全が起こる場合がありますが（シーケンスオブジェクトの再生中などに変更した場合）、本値にプロジェクトデータを設定した後で（シーケンスオブジェクトの）「StartMain()」関数を呼び出すと初期化が正常に行われます。
※本手順については、後のバージョンアップでもう少し確実な手段（関数など）を設置する可能性があります。

シーケンスパック数の取得

関数（動的）

int CountGetPack()

引数

返値

シーケンスパック数
-1 ... 失敗（エラー）

解説

現在割り当たっているプロジェクトデータに格納されているシーケンスパック（SpriteStudio6のssqeファイルに相当）数を取得します。
本関数の実行前に、最低限DataProjectにプロジェクトデータが設定されている必要があります。

シーケンスパック番号の取得

関数（動的）

int IndexGetPack(string name)

引数

name : シーケンスパック名

返値

シーケンス番号 -1 ... 失敗（エラー）

解説

シーケンスパック名からシーケンスパック番号を取得します。
単一のシーケンスデータを扱い始める前に、必ずシーケンスパックをPackSet関数を使って確定させるために、この値が必要になります。
本関数の実行前に、最低限DataProjectにプロジェクトデータが設定されている必要があります。

プロジェクトデータのオブジェクトが同一である限り、シーケンスパック名とシーケンスパック番号は静的に一対になっています（元のデータが再インポートなどで変わらない限り、名前に対応したシーケンスパック番号が変わることはありません）。

nameはシーケンスパックの名前で、通常は（インポートしたsspjの中に含まれる）シーケンスパックファイル（ssqe）のファイルボディ名と同じです。

シーケンスパック番号は、「0 ～ CountGetPack-1」の値をとります。

シーケンスパックの設定

関数（動的）

bool PackSet(int index)

引数

index : シーケンスパック番号

返値

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

解説

再生するシーケンス（データ）が格納されているシーケンスパックを設定します。
本関数の実行前に、最低限DataProjectにプロジェクトデータが設定されている必要があります。

シーケンスデータの操作を開始する前に、必ず本関数でシーケンスパックを確定させる必要があります。

シーケンスパックの未使用化

関数（動的）

bool PackSetNoUse()

引数

返値

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

解説

現在使用しているシーケンスパックを「未設定」状態に設定します。

シーケンスオブジェクトを動作させないようにする場合（例えば他のプロジェクトデータに変更したり・シーケンスパックを変更したりする時の前段階など）に使用してください。

シーケンス数の取得

関数（動的）

int CountGetSequence()

引数

返値

現在のシーケンスパックに含まれるシーケンス（データ）数
-1 ... 失敗（エラー）

解説

（PackSet関数で）設定されているシーケンスパックに格納されているシーケンス（データ）数を取得します。
本関数の実行前には必ずPackSet関数が実行されている必要があります。

シーケンス番号の取得

関数（動的）

int IndexGetSequence(string name)

引数

返値

シーケンス（データ）番号
-1 ... 失敗（エラー）

解説

プロジェクトデータのオブジェクトが同一である限り、シーケンスパック内のシーケンス（データ）番号はシーケンス名と静的に一対になっています（元のデータが再インポートなどで変わらない限り、名前に対応したシーケンス番号が変わることはありません）。

nameはシーケンスの名前で、通常は（インポートしたsspjの中に含まれるssqeの中の）各シーケンスデータ名と同じです。

シーケンスパック番号は、「0 ～ CountGetSequence-1」の値をとります。

シーケンスの設定

関数（動的）

インデックス指定版

bool SequenceSet(int index)

データ直接指定版

bool SequenceSet(
        Library_SpriteStudio6.Data.Sequence.Type typeLoop,
        Library_SpriteStudio6.Data.Sequence.Data.Step[] dataStep
    )

引数

インデックス指定版
- index : シーケンスパック番号
データ直接指定版
- typeLoop : シーケンスの終端まで再生終了した場合の挙動
- dataStep : シーケンスの各ステップ（再生コマンド）の配列

返値

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

解説

再生するシーケンス（データ）を設定します。
本関数の実行前には必ずPackSet関数が実行されている必要があります。

シーケンスデータの再生を開始する前に、必ず本関数で再生するシーケンスを特定させておく必要があります。

インデックス指定版は、シーケンスパック中に格納されているデータを再生する際に使用します。
データ直接指定版は、プログラムなどで（シーケンスパックなどに含まれていない）シーケンスを作成し・それを再生したい時などに使用します。

ステップ数の取得

関数（動的）

public int CountGetStep()

引数

返値

シーケンス中に含まれるステップ数 -1 ... 失敗（エラー）

解説

現在設定されているシーケンス中のステップ（再生コマンド）数を取得します。

シーケンスの再生

関数（動的）

bool Play(
        int step=0,
        float rateTime=float.NaN
    )

引数

step : 再生開始するステップ番号
rateTime : 再生速度（1.0で等速）

返値

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

解説

現在設定されているシーケンスの再生を開始します。

stepは、再生を開始するステップを指定します。
本値は「0（最初）～CountGetStep-1」の間の値である必要があります。

rateTimeは、再生速度を等速との比率で設定します。
0.0以下の数（0.0及び負の数）を与えた場合、本値は1.0に矯正されます。
float.NaNを与えた場合、同じシーケンスオブジェクトで前回再生した時のrateTimeを引き継ぎます。

シーケンスの再生停止

関数（動的）

void Stop(
        bool flagJumpEndStep,
        bool flagJumpEndFrame
    )

引数

flagJumpEndStep : 最終ステップにジャンプするか？（現在非動作）
flagJumpEndFrame : 最終フレームにジャンプするか？

返値

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

解説

現在再生しているシーケンスを停止します。

flagJumpEndStepは、trueで最終ステップまでジャンプします。
falseで現在のステップのまま停止します。
※現在、本設定は非動作です。予約として確保されていますが、できるだけ早いタイミングで対応・更新したいと思います。

flagJumpEndFrameは、trueでステップの最後まで表示フレームをジャンプします。
falseで現在のフレーム位置で停止します。

シーケンスの再生の一時停止設定

関数（動的）

bool PauseSet(bool flagSwitch)

引数

flagSwitch : 一時停止状態

返値

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

解説

現在再生しているシーケンスの再生一時停止状態を設定します。

flagSwitchは、trueで一時停止・falseで一時停止解除（再生再開）となります。

ステップの強制設定

関数（動的）

bool StepSet(int step)

引数

step : 移動先のステップ番号

返値

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

解説

現在再生しているシーケンスの再生ステップを強制的に移動します。

stepは、移動するステップ番号を指定します。
本値は「0（最初）～CountGetStep-1」の間の値である必要があります。

再生カーソルの移動

関数（動的）

bool CursorSet(
        float time,
        bool flagIgnoreChangeAnimation=true
    )

引数

time : 移動する再生カーソル（経過時間）位置（1.0で1秒）
flagIgnoreChangeAnimation : アニメーション再生オブジェクトを更新するか？

返値

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

解説

現在再生しているシーケンスの再生カーソル（経過時間）を強制的に移動します。

timeは、シーケンス先頭からのカーソル位置で、1.0で1秒を表します。

flagIgnoreChangeAnimationは、trueで「カーソルを移動している間のステップ更新処理中に（再生指定によって起こる）アニメーション再生オブジェクトの変更を停止する（変更しない）」ことを意味します。
falseでステップ移動中もアニメーションオブジェクトの変更を行います。
シーケンスは、ステップの内容によって（必要が生じた時に）個別のステップを再生するためのアニメーションオブジェクト（Script_SpriteStudio6_Root）の実体を適したものに変更します。
その変更が、Unityのdestroyとinstantiate（GameObjectのシーンからの廃棄と実体化）を伴うためと、ステップ変更に伴うステップデコードのコールバックが働くことから、実行時の処理時間がかかる場合があります。
trueの設定は、その処理時間の軽減（と使用メモリの軽減）のために用意された設定で、最終的に再生対象となるステップに到達するまでアニメーションオブジェクトの変更を行いません。

コールバック

時間経過管理関数定義

プロパティ（動的）

Library_SpriteStudio6.CallBack.FunctionTimeElapseSequence FunctionTimeElapse

定義関数型

delegate float FunctionTimeElapseSequence(Script_SpriteStudio6_Sequence scriptSequence)

定義関数引数

scriptSequence : 呼出元のシーケンスオブジェクト

定義関数返値

経過時間（1.0fが1秒）

解説

シーケンスオブジェクト毎に（呼出元の）「前の処理サイクルから今回の処理サイクルまでにかかった時間」を決定する関数を定義することが可能です。
nullに設定すると、初期状態に戻し・その場合の経過時間は「UnityEngine.Time.deltaTime」と等価になります。

本コールバックは、MonoBehaviour.LateUpdateのタイミングで発生します。
ただし、本コールバックを発生するのは、シーケンスオブジェクトからだけで・シーケンスの従属下にある「実際のアニメーションオブジェクト（Script_SpriteStudio_Root）からはコールバックされません（そして、そのような実装を行わないようにしてください）。

主な用途として、アプリケーションやシーケンスオブジェクト毎で特殊な経過時間を処理する場合に、このプロパティを使用して定義した関数で個別に経過時間を制御することができます。

再生終了検知

変数（動的）

Library_SpriteStudio6.CallBack.FunctionPlayEndSequence FunctionPlayEnd

定義関数型

delegate bool FunctionPlayEndSequence(Script_SpriteStudio6_Sequence scriptSequence)

定義関数引数

scriptSequence : 呼出元のシーケンスオブジェクト

定義関数返値

true ... シーンに残る
false ... シーンから自身を抹消（Destroy）する（現在機能しません）

解説

シーケンスオブジェクト自体が再生終了した時に発行されるコールバックの受領関数（デリゲート）を定義します。
nullを設定するとコールバックは発行されません。

シーケンスの終了の条件は下記の条件が全て成立したタイミングになります。

再生ステップが末尾に到達し・ステップの再生が終了した
シーケンスが末尾ステップでループする設定になっていない

デリゲート関数からfalseを返すと、シーケンスオブジェクトを削除する仕様ですが、現在本挙動は実装されておりません（できるだけ早いタイミングで実装する予定です）。

コールバック

Timeline制御コールバック

変数（動的）

Library_SpriteStudio6.CallBack.FunctionTimelineSequence FunctionTimeline

定義関数型

delegate bool FunctionTimelineSequence(
        Script_SpriteStudio6_Sequence scriptSequence,
        KindSituationTimeline situation,
        float timeElapsed,
        double timeLocal
    )

定義関数引数

scriptSequence : 呼出元のシーケンスオブジェクト
situation : 呼び出されたシチュエーション
timeElapsed : 前回呼出からの経過時間（1.0が1秒）
timeLocal : タイムライン上で経過した時間（1.0が1秒・開始を0.0とした時の絶対経過時間）

定義関数返値

（なし）

解説

シーケンスオブジェクトがTimeline上で制御されている最中に、発生するコールバックの受領関数（デリゲート）を定義します。
このコールバックを使用して、シーケンスオブジェクト自体の制御なども行うことが可能です（ただし、あまり込み入った処理を行うことや・Playable Trackクリップとの混用については推奨しかねます。スクリプトからの複雑な制御を行う場合には、Playable Trackを使用した方がTimelineのワークフローに適していると思われます）。

situationによって呼び出された状況を把握することができます。

Library_SpriteStudio6.KindSituationTimeline.START
Timeline上で制御が始まった時に発生します。
この時のtimeElapsedとtimeLocalはfloat.NaNです。
Library_SpriteStudio6.KindSituationTimeline.END
Timeline上で制御が終了する時に発生します。
この時のtimeElapsedとtimeLocalはfloat.NaNです。
Library_SpriteStudio6.KindSituationTimeline.UPDATE
Timeline上で制御されている最中に毎処理ループで発生します。

ユーティリティ

シーケンスの再生時間の取得

関数（動的）

float TimeGetDurationSequence(
        string nameSequence,
        bool flagIgnoreRepeatTail=true
    )

引数

nameSequence : シーケンス名
flagIgnoreRepeatTail : シーケンスのループ設定を無視するか？

返値

シーケンスの再生時間（1.0で1秒）
float.PositiveInfinity ... 終了しない（末尾でループしている）
float.NaN ... 失敗（エラー）

解説

現在設定されているシーケンスパックの中に含まれるシーケンスの再生時間を取得します。
本関数の実行前に必ずPackSet関数が実行されている必要があります。

nameSequenceはシーケンス名で、IndexGetSequence関数のnameと同じ規則です。

flagIgnoreRepeatTailは、trueで「シーケンスの設定に関わらず・無視して、末尾でループしない場合の時間」を返します（1.0で1秒）。
falseで、実際の再生時間を返しますが、末尾でループする設定になっている場合、常に無限を返します（つまり、本関数が無限を返す場合にループしているシーケンスであると判定できます）。

ステップの再生時間の取得

関数（動的）

float TimeGetDurationStep(ref Library_SpriteStudio6.Data.Sequence.Data.Step dataStep)

引数

dataStep : ステップデータ

返値

ステップの再生時間（1.0で1秒）
float.PositiveInfinity ... 終了しない（末尾でループしている）
float.NaN ... 失敗（エラー）

解説

指定したステップの実行時間を求めます。
本関数の実行前に必ずPackSet関数が実行されている必要があります。

datraStepは個別のステップ（再生コマンド）の実体です。

シーケンス制御クラスの取得

関数（静的）

Script_SpriteStudio6_Sequence SequenceGet(
        GameObject gameObject,
        bool flagApplySelf=true
    )

引数

gameObject : 起点となるGameObject
flagApplySelf : gameObject自身を検査に含むか

返値

最初に発見されたScript_SpriteStudio6_Sequenceの参照
null ... 失敗（エラー） / 発見できなかった

解説

gameObjectを起点に子のGameObjectを走査して、最初に発見されたシーケンス制御（Script_SpriteStudio6_Sequence）を返します。

注意点としては、「最初に発見された」という点です。
子GameObject群の中に複数のScript_SpriteStudio6_Sequenceがあっても、走査ロジック上で最初に見つかったScript_SpriteStudio6_Sequenceのみを返します。
また、gameObjectの直下（直子）にあるGameObject群までは「最初に発見された＝最も浅い階層にある」ということが保証されますが、孫以上の階層になった場合、「最初に発見された＝最も浅い階層にある」ということが保証されなくなります。

flagApplySelfをfalseにすると、gameObject自身は走査対象に含まず、直子のGameObject群から走査を開始します。

その他機能群

強制非表示指定

変数（動的）

bool FlagHideForce

値

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

解説

アニメーションの同名の変数と同じ機能です。
シーケンスは各ステップの内容によってアニメーションを表示するための実体が交換（破棄・生成）が行われる動作ですが、本変数の設定は交換された実体にも都度反映されます。

平面化描画指定

変数（動的）

bool FlagPlanarization

値

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

解説

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

変数（動的）

bool FlagColliderInterlockHideForce

値

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