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

SS6Player for Unity（以降「SS6PU」）のスクリプト機能群を解説します。

※サンプルについて

当GitHubのsampledevelopブランチには、主な再生機能を使用したサンプルがありますので、用法はそちらも参照いただけますようお願い致します。

機能概略

SS6PUのプレーヤーは下記のような機能区分（再生オブジェクト）を持っています。

アニメーション（Script_SpriteStudio6_Root）

「アニメーション」は、「SpriteStudio6上でのアニメーション（ssae）に相当するデータの再生」を行うものです（あくまで「ssaeに相当する」データですので、ssaeデータ自体を再生するわけではありません）。

  • アニメーション再生・再生トラック
    アニメーションの再生や停止・一時停止などを行うことができます。
    再生トラックは、アニメーションの再生管理に使用され、1トラックで1つのアニメーションの再生を管理します。
    通常の再生は1つの再生トラックで事足りますが、複数の再生トラックを使用することで「アニメーション合成」や「トラックトランジション」などの機能を使用して複雑で多様なアニメーションの表現が可能です。

  • アニメーション合成（複数アニメーションの同時適用）
    複数の再生トラックを使用している場合、アニメーションの各パーツに対して「どのトラックの再生アニメーションを適用するか」を設定することが可能です。
    この機能を使用することで、同じアニメーションデータ（元データはssae）に含まれている複数のアニメーションを合成して再生することが可能です。
    例えば、「上半身では武器毎のアニメーション」「下半身でダッシュや歩きなどの移動アニメーション」をそれぞれ別々に管理しながら、合成したアニメーションとして出力するなどが可能になります。

  • トラックトランジション（アニメーションのフェード）
    複数の再生トラックを使用している場合、1つのトラックに対して別の1つのトラックのアニメーションへ指定時間でブレンドしながら遷移をさせることが可能です（2つのアニメーション描画結果のフェードではありません）。
    例えば、「歩き」から「走り」のアニメーションの「つなぎのアニメーション」を作ることなく・スムーズに遷移させることが可能です。
    この機能は、「アニメーション合成」と併用が可能で、かつブレンドされる2つのトラックはそれぞれ再生中でも一時停止中でも構いません。
    ただし、ブレンドが可能なのは（SpriteStudio6上のアトリビュートで）「X/Y/Z座標」「X/Y/Z軸回転」「X/Yスケール（ローカルスケールは含みません）」のみですので、他のアトリビュート（例えば「参照セル」や「頂点変形」など）については、ブレンドの対象になりません。

  • 各種コールバック
    デリゲート関数を登録することでコールバックを受け取ることができ、様々な同期処理に使用することが可能です。

    • アニメーション全体の再生終了
    • 各再生トラックの再生終了
    • ユーザーデータの検知
    • 当たり判定の接触
    • タイムラインとの同期

  • 動的セル・セルマップ変更
    再生しているアニメーションのパーツが使用している参照セルをリアルタイムで変更可能です。
    また、ランタイム上で作成したり・他のアニメーションが持っているセルマップ（セルの集合で、1つのssceファイルと等価です）をアニメーションに割り当てることも可能です（SpriteStudio6で例えると、ssaeで使用しているssceそのものを差し替えるような機能です）。

  • 動的インスタンス・エフェクト変更
    再生しているアニメーションのインスタンスパーツやエフェクトパーツが管理しているソースアニメーション（呼び出しているアニメーションオブジェクト）を変更することが可能です。

  • 動的パーツカラー変更（追加カラー）
    再生しているアニメーションの全ての「スプライト」「メッシュ」パーツの色合成を変更することが可能です（アトリビュート「パーツカラー」と同じ効果をリアルタイムで全ての「スプライト」「メッシュ」パーツに適用する機能です）。
    だたし現時点仕様では、インスタンスアニメーションやエフェクトなどの子アニメーションへは適用されませんので、注意してください。

各機能用スクリプトの解説目次はこちらです。

エフェクト（Script_SpriteStudio6_RootEffect）

「エフェクト」は、「SpriteStudio6上でのエフェクト（ssee）に相当するデータの再生」を行うものです（あくまで「sseeに相当する」データですので、sseeデータ自体を再生するわけではありません）。

  • エフェクト再生
    本来SpriteStudio6のエフェクト機能は、常にアニメーションオブジェクト（SpriteStudio6のssae）に従属するものですが、SS6PUでは単独でエフェクトを再生することも可能です。
    エフェクトの再生や停止・一時停止などを行うことができます。

  • 各種コールバック
    デリゲート関数を登録することでコールバックを受け取ることができ、様々な同期処理に使用することが可能です。

    • エフェクトの再生終了
    • タイムラインとの同期

  • 動的セル・セルマップ変更
    再生しているエフェクトが使用している参照セルをリアルタイムで変更可能です。
    また、ランタイム上で作成したり・他のアニメーションが持っているセルマップ（セルの集合で、1つのssceファイルと等価です）をアニメーションに割り当てることも可能です（SpriteStudio6で例えると、sseeで使用しているssceそのものを差し替えるような機能です）。

  • 動的パーツカラー変更（追加カラー）（※実装予定機能）
    再生しているエフェクトの全てのセルパーツの色合成を変更することが可能です。
    ※本機能は、現在未搭載です。

各機能用スクリプトの解説目次はこちらです。

付記

SpriteStudio6の「エフェクト」は、「パーティクルを模した」制御構造を持つ「アニメーション」オブジェクトです。
通常のアニメーションが「タイムライン上でのキーフレームで作成・動作するアニメーション」であることに対して、エフェクトは「数式とそのパラメータで作成・動作するアニメーション」である……という位置づけです（ランダム性をはらむパラメータもありますが、原則的に固定結果のアニメーションを作り出し・再現性を重要視している性質であるのが、その証左となります）。
ですので（作成方法などが似てはいますが）、一般的に言われる「（粒子を表現するための）パーティクル」機能ではありませんし、加えてUnityのパーティクルシステムなどの代用的な位置づけの機能でもありません。
その点について、あらかじめご認識をお願いいたします。

シーケンス（Script_SpriteStudio6_Sequence） （Ver.2.0以降）

「シーケンス」は、「SpriteStudio6上でのシーケンス（ssqe・β提供機能）に相当するデータの再生」を行うものです（あくまで「ssqeに相当する」データですので、ssqeデータ自体を再生するわけではありません）。

  • シーケンス再生
    シーケンスの再生や停止・一時停止などを行うことができます。

  • 各種コールバック
    デリゲート関数を登録することでコールバックを受け取ることができ、様々な同期処理に使用することが可能です。

    • シーケンスの再生終了
    • ステップ（シーケンス中の各描画命令）のデコード
    • タイムラインとの同期

  • 動的パーツカラー変更（追加カラー）（※実装予定機能）
    再生しているエフェクトの全てのセルパーツの色合成を変更することが可能です。
    ※本機能は、現在未搭載です。

各機能用スクリプトの解説目次はこちらです。

複製描画（Script_SpriteStudio6_Replicate） （Ver.2.0以降）

「複製描画（レプリケイト）」は、「Unity上で、現在再生中のシーン上にあるSS6PUのアニメーション・エフェクト・シーケンスを再度描画する」ことを行うものです（SpriteStudio6の提供機能の再生ではなく、Unity上で再生する上でのユーティリティ機能の1つです）。

  • 複製描画
    再生中に複製元のアニメーションなどを切り替えたりすることも可能です。

  • 各種コールバック
    デリゲート関数を登録することでコールバックを受け取ることができ、様々な同期処理に使用することが可能です。

    • タイムラインとの同期

各機能用スクリプトの解説目次はこちらです。

スクリプト詳細解説

以下に、使用可能な機能群を大体の目的別に分類してあります。
※各関数の項目でリンクされていない項目は順次作成中です。

英語版の関数リファレンスは、下記のソースコード中の各public関数などにDoxygen形式で解説があります（当Wikiで記載が追い付いていないものについても、ソースコード中の英語版の記載は存在しています）。

  • アニメーション制御
    • Assets/SpriteStudio/Script/Script_SpriteStudio6_Root.cs
    • Assets/SpriteStudio/Script/Root内のC#ソースファイル群
  • エフェクト制御
    • Assets/SpriteStudio/Script/Script_SpriteStudio6_RootEffect.cs
    • Assets/SpriteStudio/Script/RootEffect内のC#ソースファイル群
  • シーケンス制御
    • Assets/SpriteStudio/Script/Script_SpriteStudio6_Sequence.cs
  • 複製描画制御
    • Assets/SpriteStudio/Script/Script_SpriteStudio6_Replicate.cs

アニメーション制御（Script_SpriteStudio6_Root）

各メンバ種別でのアクセスは下記になります。

  • 「動的」メンバ : 「本クラスの実体.～」
    本クラスの実体は、主にScript_SpriteStudio6_Root.Parts.RootGet関数等を使用して取得します。
  • 「静的」メンバ : 「Script_SpriteStudio6_Root.～」
    本クラスに直接アクセスします。

※原則、「動的」メンバは単体のアニメーションオブジェクトを対象としており、「静的」メンバはシーケンスオブジェクトに依存しないユーティリティ的な機能を提供しています。

公開機能

エフェクト制御（Script_SpriteStudio6_RootEffect）

各メンバ種別でのアクセスは下記になります。

  • 「動的」メンバ : 「本クラスの実体.～」
  • 「静的」メンバ : 「Script_SpriteStudio6_RootEffect.～」
    本クラスに直接アクセスします。

※原則、「動的」メンバは単体のエフェクトアニメーションオブジェクトを対象としており、「静的」メンバはエフェクトアニメーションオブジェクトに依存しないユーティリティ的な機能を提供しています。

公開機能

シーケンス制御（Script_SpriteStudio6_Sequence）

本クラスの実体は、主にScript_SpriteStudio6_Sequence.SequenceGet関数等を使用して取得します。

  • 「静的」メンバ : 「Script_SpriteStudio6_Sequence.～」
    本クラスに直接アクセスします。

※原則、「動的」メンバは単体のシーケンスオブジェクトを対象としており、「静的」メンバはシーケンスオブジェクトに依存しないユーティリティ的な機能を提供しています。

公開機能

各メンバ種別でのアクセスは下記になります。

  • 「動的」メンバ : 「本クラスの実体.～」
    本クラスの実体は、主にScript_SpriteStudio6_Root.Parts.RootGet関数等を使用して取得します。
  • 「静的」メンバ : 「Script_SpriteStudio6_Root.～」
    本クラスに直接アクセスします。

※原則、「動的」メンバは単体のアニメーションオブジェクトを対象としており、「静的」メンバはアニメーションオブジェクトに依存しないユーティリティ的な機能を提供しています。

公開機能

複製描画制御（Script_SpriteStudio6_Replicate）

各メンバ種別でのアクセスは下記になります。

  • 「動的」メンバ : 「本クラスの実体.～」
  • 「静的」メンバ : 「Script_SpriteStudio6_RootEffect.～」
    本クラスに直接アクセスします。

※原則、「動的」メンバは単体のエフェクトアニメーションオブジェクトを対象としており、「静的」メンバはエフェクトアニメーションオブジェクトに依存しないユーティリティ的な機能を提供しています。

公開機能

動的カラーパラメータ（Library_SpriteStudio6.Control.AdditionalColor）

動的パーツカラーを使用する際に、その設定を行うためのクラスです。

各メンバ種別でのアクセスは下記になります。

  • 「動的」メンバ : 「本クラスの実体.～」
    アニメーション(Script_SpriteStudio6_Root)またはエフェクト(Script_SpriteStudio6_RootEffect)のAdditionalColorCreate関数を使用して実体を作成します。
  • 「静的」メンバ : 「Library_SpriteStudio6.Control.AdditionalColor.～」

※原則、「動的」メンバは単体の追加カラーパラメータを対象としており、「静的」メンバは固定値などを提供しています。

公開機能

ユーザーデータ（Library_SpriteStudio6.Data.Animation.Attribute.UserData）

アニメーションオブジェクトからコールバックで取得できるユーザーデータの構造体です。
※コールバック以外でも静的アニメーションデータのセットアップアニメーション情報中にあるユーザーデータも、本構造体で内容を取得することが可能です。

各メンバ種別でのアクセスは下記になります。

  • 「動的」メンバ : 「本クラスの実体.～」
    実体は、ユーザーデータのコールバック受領（デリゲート）関数に引数で渡されるか・静的アニメーションデータ内セットアップアニメーション情報のユーザーデータになります。
  • 「静的」メンバ : 「Library_SpriteStudio6.Data.Animation.Attribute.UserData.～」

※原則、本構造体の実体は読取専用です。
※原則、本構造体内の各情報は、先に「Is～」プロパティで存在を確認してから、各値を取得するのが正しい用法です。

公開機能

  • [ユーザーデータ構造体]
    • 動的メンバ
      • IsNumber : ユーザーデータが「数値」情報を持っているか？
      • IsRectangle : ユーザーデータが「矩形」情報を持っているか？
      • IsCoordinate : ユーザーデータが「座標」情報を持っているか？
      • IsText : ユーザーデータが「文字列」情報を持っているか？
      • Number : 「数値」情報を符号なしで取得
      • NumberInt : 「数値」情報の値
      • Rectangle : 「矩形」情報の値
      • Coordinate : 「座標」情報の値
      • Text : 「文字列」情報の値

ライブラリ部（Library_SpriteStudio6）

本クラスは共通機能などを提供しているクラスで、実体を持ちません。 ただし、一部の機能はアニメーション制御やエフェクト制御からそれぞれ実体を取得するものがあります（主に動的メンバを持っているもの）。

  • 「動的」メンバ : 「各クラスの実体.～」
  • 「静的」メンバ : 「Library_SpriteStudio6.～」

※特に静的メンバについては、直接使用する機会はさほど多くはないと思われますが、SS6PUの実装で使用している機能群の内、アニメーションなどのより深い情報を扱ったり・アプリケーションの実装にも使えるかもしれないものを公開しています。

公開機能

  • セルマップ・セル関係
  • パーツ制御関係
  • ユーティリティ:アセット関係
  • ユーティリティ:補間計算関係
  • ユーティリティ:シェーダ関係
  • ユーティリティ:マテリアル関係
  • ユーティリティ:セルデータ関係
  • ユーティリティ:数学関係
  • ユーティリティ:乱数関係
    • メルセンヌ・ツイスタ
    • Xorshift-32

静的アニメーションデータ（Script_SpriteStudio6_DataAnimation）

各メンバ種別でのアクセスは下記になります。

公開機能

静的エフェクトデータ（Script_SpriteStudio6_DataEffect）

各メンバ種別でのアクセスは下記になります。

  • 「動的」メンバ : 「本クラスの実体.～」
    本クラスの実体はエフェクト制御(Script_SpriteStudio6_RootEffect)の実体内DataEffectメンバ変数で取得します。
    ※原則、DataEffectメンバは書き換えないでください（誤動作します）。
  • 「静的」メンバ : 「Script_SpriteStudio6_DataEffect.～」

※本クラスを直接アクセスする機会は少ないと思われますが、所持している一部情報群にはアプリケーションを開発する上で有益なものがありますので、それに絞って機能公開しています。
本クラスにアクセスする場合、細心の注意を払ってください。
特に、本クラスはアニメーションのマスタデータかつScriptableObjectなこともあり、アプリケーションから書き換えたり・公開機能以外を使用したりしないでください。

公開機能

（動作仕様）アニメーション内部処理の順序

アニメーションの処理は、MonoBehaviour.LateUpdateのタイミングで行われます。
時に（特に複数のコールバックを連動させるような場合）、処理の順序の認識が必要になる場合があります。
下記に内部処理の順序を記載します。
原則、上から下への順列で行われますが、パーツ・トラックの処理は、「パーツ・トラック毎のインデックス順列のループ」で処理されます。
また、 描画（本描画前描画も含む）は、描画対象パーツのみ処理されます（非表示や描画対象外のパーツなどは処理の対象から外れています。ただしインスタンスパーツとエフェクトパーツは子オブジェクトの更新が絡むため、常時処理対象になっています）。

  1. 経過時間処理（最親アニメーションのみ）
  2. 再生トラック更新処理（再生フレームの確定）
    • トラックの再生終了検知（終了検知コールバック処理のリクエスト）
  3. 各パーツ更新処理
  4. 描画対象マスクの本描画前描画（PreDraw）
  5. 描画対象パーツ・マスクの描画（Draw）
    • 従属アニメーション（子アニメーション・子エフェクト）のLateUpdate呼出
  6. 合成メッシュ作成（最親アニメーションのみ・描画の確定）
    • 合成メッシュのMeshFilterへの設定
    • 合成メッシュ用マテリアル群のMeshRendererへの設定
  7. 各トラック再生終了最終判定
    1. トラックトランジション用 FunctionPlayEndTrack コールバック発生
    2. トラック再生終了用 FunctionPlayEndTrack コールバック発生
  8. 再生終了最終判定

※補足:
「FunctionCollider～」「FunctionCollision～」のコールバックは、Unityの接触判定プロセスの処理タイミングで発生します。

  • 「FunctionCollider～」は「MonoBehaviour.OnTrigger～」
  • 「FunctionCollision～」は「MonoBehaviour.OnCollision～」

のタイミングです。