v1.0 から v1.1 への移行マニュアル - SpriteStudioArchive/SS5PlayerForUnity_v1_2_1 GitHub Wiki

仕様変更点概要

ドローコールの最適化能力が上がっております。
※「V1.0」までは、各アニメーションオブジェクト毎に最適化を行っていたため、最低でも、シーン中のアニメーションオブジェクト数の数だけドローコールがかかっていましたが、これを描画領域（View）毎の最適化に変更しました。
ですので、「同じマテリアル」を使用しているアニメーションオブジェクトを多数出した場合でも、ドローコールがかなり削減されております。
ただし、Unity4.x系の一部バージョン以降から、「何も表示しない状況でも、ドローコールが1つ発生する」場合があり、そういった環境下では、何らかのスプライトオブジェクトを表示した場合の、最低のドローコール数は「2」になります。
インスタンスパーツに対応しました。
アニメーション再生関数が「ラベル」や「往復（ピンポン）」再生などに対応しました。
　 ※それに伴い、再生関数への引数などが変更・追加になっています。
アセット（インポートしたPrefab）の容量を若干削減しました。
　 ※主に「ユーザーデータ」「使用セルデータ」等の格納冗長性を改良しました。　 ※ver.1.1.9以降からは、さらに冗長性を改良して、なるだけ最小限のデータ搭載状態になるように改良しました。
ユーザーデータのコールバックのためのデリゲート関数の引数が変更になっています。
　 ※これは、3で新規に対応した再生方式や、4での改良による影響です。
アニメーションオブジェクトの特定のパーツ（GameObject）毎に強制非表示の状態を設定できるようになりました。
インポート時にヒエラルキー上で指定されたフォルダの下に、「SSPJの名前」のフォルダを作成し・その下に従来のインポートデータを格納できるオプションをつけました。
V1.0までの「Script_LinkPrefab」のスクリプト名（クラス名）が変更になっています。
※「V1.0」までは「プレハブ in プレハブ」を実装するための汎用スクリプトでしたが、今回のバージョンアップで（利便性を上げるため）「SpriteStudio 5 Player for Unity」専用の挙動に変更されたためです。
パーツ毎のセルデータの情報を追加しました。
パーツのセルデータのマッピング座標値は、元のセルマップ内の「ピクセル単位での矩形」情報で持っていますが（この情報からスプライトサイズとマッピングUVの2種類のデータを算出する必要があるためです）、 V1.1からアニメーションのセル情報に「インポートした時に使用していたセルマップの大きさ」を格納するようにしました。
V1.0までは（セルマップの大きさを）ランタイムで使用しているマテリアルのテクスチャから取り出していましたが、この変更で「使用するマテリアルについているテクスチャの大きさの制限（従来は同じ大きさでなくてはなりませんでした）」が幾分か緩くなり、インポート時と異なるテクスチャサイズをマテリアルに割り当てても、パーツの正常な表示を行うことができるようになりました。

　ただ、大きさを変更する場合でも、

インポート時のテクスチャのピクセルサイズの「2のn乗倍」か「2のn乗分の1」にすることを推奨します（ミップマップなどと同様の倍率とお考え下さい）。
テクスチャを小さくした場合でも、スプライトの大きさは変わりませんので、テクスチャは「拡大して表示」されることになります。
大きさが変わった場合、セルマップ上に置かれた各セルの間のピクセルバウンダリが小さくなってしまうため、画面にゴミが出る可能性があります。　……以上の点にご注意下さい。

留意点概略

「V1.1」では、「V1.0」から、クラス名や関数引数の型などが変更になっている箇所が存在します。
そのため、単純に「V1.1」に入れ替えると、コンパイルエラーなどが数多く出るかと思われます。

これらは、主に「機能の実装状態が変更された」ものに多いのですが、
「V1.0」と同名のクラス名などを使用していると、（運用方法や仕様が変更されているにも関わらず）
コンパイルが通ってしまう場合があり、それらによってかえって追跡が難航するようなバグを誘発すると考えたため、
コンパイル時に洗い出せるように、クラス名などを変更いたしました。

移行時にお手を煩わせる形となってしまい、申し訳ございませんが、
そういった事情を考慮した結果ですので、何卒ご理解の程お願い致します。

V1.0から変更された各種名称・定義など

ドローコール最適化マネージャ（描画マネージャ）について

旧クラス名: Script_SpriteStudio_PartsRoot
新クラス名: Script_SpriteStudio_DrawManagerView

留意点:

A. ドローコールの最適化の単位が変更されています。

V1.0までは各アニメーションオブジェクトのルートパーツ（以降「PartsRoot」）
毎の最適化でしたが、ドローコールの軽減のため、「（Camera2Dの下などにある）
View」のGameObject毎での最適化を行うように変更いたしました。
また、それに伴い、3D空間用（主にPerspectiveカメラ用）の「View3D」という
Viewのプレハブが追加されています。

B. 設定の影響範囲が変更になっています。

Aでの記載の通り、各アニメーションオブジェクトから、Viewでの最適化に仕様が
変更になったため、設定の影響範囲が「各アニメーションオブジェクト」から、
「View下にある全てのアニメーションオブジェクトへの共通設定」に変更になって
います。
そのため、V1.0上で、アニメーションオブジェクト毎で描画レイヤーなどを変えて
いた場合、シーンの構造を変更する必要が出てきております。

そういった処理を行う場合、主に下記の3つが対応策として考えられます。
a. カメラの下に複数の（設定を変えた）Viewを作成し、それらの設定を変更した上
で、各アニメーションオブジェクトを（それぞれのViewに）再分類する。
b. Viewで設定を変更するのではなく、設定を変えた複数のカメラを作成し、
各アニメーションオブジェクトを（それぞれのカメラに）再分類する。
c. アニメーションオブジェクトで使用しているマテリアル群（Based-Material Table
に設定されているマテリアル）で使用しているシェーダーの設定を変更する。
（シェーダを別名でコピーして、シェーダ内のレイヤー設定を書き換えて、マテ
リアルに再設定する）。

ただ、c.の方法は様々な管理上煩雑になるため、想定外の動作を招きやすいという
欠点がございますので、「V1.0で作成したシーンの構成を変更することができない」
状態でのみ選択肢として考慮していただくことを推奨いたします。

C. 「Rate Z Effect」のパラメータが廃止になっています。

「V1.0」では、各アニメーションオブジェクトの(Transform.Positionの)Z値を
どのように全体の描画に反映するかの設定として、本パラメータが存在していまし
たが、「V1.1」からはPartsRootのTransform.PositionのZ値で自動的に描画順を
ソートする仕様に変更になったため、本パラメータは不要になり・削除されており
ます。

アニメーションオブジェクトの強制非表示状態の設定方法の変更について

V1.0では、PartsRootにMeshFilterとMeshRendererがついていたため、MeshRenderer
のEnable状態を変更することで、アニメーションオブジェクトの表示・非表示を変更
することができましたが、V1.1からはその方法が使えなくなっています。

その代替として、以前からご要望の多かった「特定のパーツ（GameObject）やその
子パーツ毎で表示状態を制御する」という関数を実装しました。

  対象クラス:  
   Script_SpriteStudio_PartsRoot 
   Script_SpriteStudio_PartsNULL  
   Script_SpriteStudio_PartsInstance  
   Script_SpriteStudio_Triangle2  
   Script_SpriteStudio_Triangle4  

  対応関数:  
	 public void HideSetForce(bool FlagSwitch,  
                               bool FlagSetChild=false,  
                               bool FlagSetInstance=false  
                  ) 
   引数: 
    FlagSwitch ... true == 非表示 / false == 表示  
    FlagSetChild ... true == 子パーツにも設定を反映する / false == そのパーツのみ  
             ※省略可能: 省略時: false  
    FlagSetInstance ... true == 呼び出されているインスタンスオブジェクトにも反映する  
              / false == 反映しない  
             ※省略可能: 省略時: false

注釈:
FlagSetInstanceについては、特殊な運用状況を想定して、インスタンス呼出のオブジェクトにも反映できるようにはなっていますが、インスタンスオブジェクトを非表示にする場合、Script_SpriteStudio_PartsInstanceのGameObject単体に本関数を使用するだけで、そのGameObjectから呼び出されているインスタンスオブジェクトが非表示になりますので、特段の事由がない限り、FlagSetInstanceはfalseのまま使用されることを推奨します。

同様に、アニメーションオブジェクト全体を非表示にしたい場合、
Script_SpriteStudio_PartsRootのHideSetForce(true, false, false);
で、実現できますので、FlagSetChildをtrueに設定する必要はありません。
このアニメーションオブジェクトが、インスタンスオブジェクトを呼び出している場合、インスタンスオブジェクトも自動的に非表示になります）

本関数は、FlagSetChild/FlagSetInstanceをtrueにした場合、指定したGameObject下の全子GameObjectに対して、
「Script_SpriteStudio_～」が存在しているかを走査する処理を行うため、
対象パーツ（GameObject）が多い場合、アプリケーションの実行速度が低下する恐れがあります。

ユーザーデータコールバックのデリゲート関数の仕様変更について

ユーザーデータコールバックのデリゲート関数の引数などが、V1.0から変更になっています。

  対象デリゲート関数型: 
   public delegate void FunctionCallBackUserData(
                             GameObject ObjectControl, 
                             string PartsName,
                             Library_SpriteStudio.AnimationData AnimationDataParts,
                             int AnimationNo,
                             int FrameNoDecode,
                             int FrameNoKeyData,
                             Library_SpriteStudio.KeyFrame.ValueUser.Data Data,
                             bool FlagWayBack
                     );

  引数:
    ObjectControl: コントロール用パーツのゲームオブジェクト
    PartsName: ユーザーデータが検知されたパーツ名
    AnimationDataParts: ユーザーデータが検知されたパーツのSpriteStudio
              アニメーション再生管理情報
    AnimationNo: ユーザーデータが検知された際のアニメーション番号
    FrameNo: ユーザーデータが検知された、再生時のフレーム数
    FrameNoKeyData: 検知されたユーザーデータが定義されている、パーツ内フレーム番号
    Data: 検知されたユーザーデータ
       ※この引数の関数型が変更になっています。
    FlagWayBack: 往復（ピンポン）再生時の行き道か帰り道か
           true == 帰り道
           false == 行き道
       ※この引数が追加になっています。

注釈: 本関数型は基本的にV1.0と変わりませんが、引数が追加・引数型が変更されています。

Dataの型は、V1.0では「Library_SpriteStudio.KeyFrame.ValueUser」型でしたが、今回の、ユーザーデータの格納状態の冗長性を解消するために、同クラスの実装構造が変更されたために、型が変更になっております。

FlagWayBackは、ピンポン再生では１回の再生が「指定区間の往復」になるため、コールバックされた時点が行きなのか帰りなのかが不明になりがちなため、追加されたフラグになります。
ピンポン再生以外の再生方法では、本値は常にfalseになります。

アニメーション再生関数の引数追加

  対象クラス: Script_SpriteStudio_PartsRoot
  対象関数
	public bool AnimationPlay(  int No = -1,
                                int TimesPlay = -1,
                                int FrameInitial = -1,
                                float RateTime = 0.0f,
                                PlayStyle KindStylePlay = PlayStyle.NO_CHANGE,
                                string LabelStart = "",
                                int FrameOffsetStart = int.MinValue,
                                string LabelEnd = "",
                                int FrameOffsetEnd = int.MaxValue
							)
  引数:
    No: 再生するアニメーション番号
      -1 == 現在設定（インスペクタ等での設定）を変更しない
    TimesPlay: 再生回数
      0 == 無限ループ
      1 == 1回再生
      2～ == 指定回数再生
      -1 == 現在設定（インスペクタ等での設定）を変更しない
    FrameInitial:
      再生時開始時のオフセットフレーム数
      -1 == 現在設定（インスペクタ等での設定）を変更しない
    RateTime:
      再生時速度倍率
      1.0fを等速とし、本値を経過時間に乗算します
      ※大きな値を設定すると早くアニメーションします。
      ※負数を与えると逆再生します。
      0.0f == 現在設定（インスペクタ等での設定）を変更しない
    KindStylePlay:（引数追加）
      再生スタイル
      (Script_SpriteStudio_PartsRoot.)PlayStyle.NORMAL == 一方向再生
      (Script_SpriteStudio_PartsRoot.)PlayStyle.PINGPONG == 往復再生
      (Script_SpriteStudio_PartsRoot.)PlayStyle.NO_CHANGE
              == 現在設定（インスペクタでの設定）を変更しない
    LabelStart: （引数追加）
      再生区間、開始位置ラベル名
      "" == 現在設定（インスペクタ等での設定）を変更しない
    FrameOffsetStart: （引数追加）
      再生区間、開始位置ラベル名からのオフセットフレーム数
      int.MinValue == 現在設定（インスペクタ等での設定）を変更しない
    LabelEnd: （引数追加）
      再生区間、終了位置ラベル名
      "" == 現在設定（インスペクタ等での設定）を変更しない
    FrameOffsetEnd: （引数追加）
      再生区間、終了位置ラベル名からのオフセットフレーム数
      int.MaxValue == 現在設定（インスペクタ等での設定）を変更しない

  注釈:
    アニメーションを再生開始します。
    LabelStartに"_start"を指定するとアニメーションの最初が該当位置になります。
    LabelEndに"_end"を指定するとアニメーションの最後が該当位置になります。
    この2つの名称は、SpriteStudioの予約文字列となっており、同名のラベルを
    ユーザー定義していた場合、インポータが警告を出し・ユーザー定義側のラベルを
    無視しますので、注意して下さい。

    「LabelStart + FrameOffsetStart」は再生方向に関わらず再生区間の先頭位置を、
    「LabelEnd + FrameOffsetEnd」は再生方向に関わらず再生区間の終了位置を
    示しますので、
    必ず「LabelStart + FrameOffsetStart」は「LabelEnd + FrameOffsetEnd」よりも
    小さな値（かつ負数でない値）である必要があります。
    また、「LabelEnd + FrameOffsetEnd」は、再生するアニメーションのフレーム数
    を超えていない必要があります。

    FrameInitialは、必ず「LabelStart + FrameOffsetStart」から「LabelEnd + 
    FrameOffsetEnd」の区間の中に入っている必要があります。

    本関数は、V1.0では省略不可能な引数がありましたが、V1.1からは全ての引数が
    省略可能になっています。
    ですので、「AnimationPlay();」と記載すると、インスペクタや直前再生時に指定
    した設定を保持したまま通常再生を行います。

Script_LinkPrefabクラスの廃止

  同クラス（スクリプト）の目的仕様が変更になったため、クラス名が変更になって
  おります。

  旧クラス名: Script_LinkPrefab
  新クラス名: Script_SpriteStudio_LinkPrefab

  この変更は、V1.0まではScript_LinkPrefabクラス（スクリプト）は、「プレハブ in
  プレハブ」を行うための汎用スクリプトでしたが、V1.0からは下記の理由からSS5PU
  専用のクラスに変更になりました。

  ・インスタンス呼出の際にも使用するために、機能を専用化した。
  ・V1.0まではインスペクタで「Auto Develop-Prefab」などを設定していても、
   エディタ上のプレイモードで自動展開されなかった仕様を変更しました。
   （プレイモードでも自動的にプレハブが展開されます）

アニメーション再生終了時コールバック関数の返値での挙動の違い

アニメーション再生終了時コールバック関数でfalseを返すと、該当するアニメーションオブジェクトを自動削除する仕様があります。
V1.0までは本関数でfalseを返すと「制御用オブジェクト」が存在するものとして、
PartsRootの一段階親から実体を削除していましたが、今回のバージョンアップで、
制御用オブジェクトがない場合については、PartsRoot以下を削除するように変更されています。

一部関数のinternal化

現実上、Unityではpublicとinternalの違いがほとんどありませんが、ユーザーが独自で使用することを禁止している関数
（独自で使用された場合の動作などについては保障いたしかねます）については、V1.1からinternalのスコープで定義してあります。
ただし、エディタ側（インポータやインスペクタ）から使用される関数については、publicのまま残っているものがあります。
ソース内の関数に使用説明がないものや、「Don't use this function.」との注釈があるものについては、publicスコープであっても使用しないで下さい。

その他注意点

再生フレームの外部からの検知について

これはV1.0にも共通する仕様となりますが、Unityの場合、実際のプラットフォーム上でのアプリケーションの実行フレームレートが可変であるため、 Script_SpriteStudio_PartsRootクラスの再生フレーム番号などを「何かしらの同期処理」などに使用すると、
「同じフレームが複数回再生」されたり「フレームがスキップしてしまう」ことが起き、
誤動作などの元になるため、アニメーションとの同期処理には、できる限り「ユーザーデータ」をデータに設定し、
そのコールバックを受け取る形で同期を行うことを推奨いたします。

SS5PUのユーザーデータコールバックは、LateUpdateの実行タイミングで発行されるため、
コールバック関数内では極力「次のUpdateで処理されるべき処理のためのパラメータ設定
（例えば効果音データの識別名の確定など）」にとどめ、それらの実際の処理は
次に回ってくるUpdateのタイミングで行うことを推奨いたします。

データの再インポートが必要になります。

V1.0とV1.1とでは大きく構造が異なったり・アニメーションデータの格納形式が変更に
なっている箇所がありますため、使用するデータの再インポートが必要になります。
V1.0のデータを再インポートせずにV1.1上で動作させると、想定していない誤動作を
する場合がありえますので、ご注意くださいますようお願い致します。

シーンセーブ時などに出るWarningについて

一部Unityのバージョン（主に4.3以降と思われます）で、エディタ上のプレイモードを
停止した後で、シーンをセーブしたりした場合などに、「CombineInstanceの配列にnull
が混じっている」という警告がコンソールに出る場合があります。
これは描画マネージャとアニメーションオブジェクトの処理が切り離された
ため、「プレイモードを終了したタイミング」によって、双方の動作状態の不整合などが
原因で出てしまう警告と思われます。
実際のアプリケーション動作上では問題がないと思われますので、現状、無視していただ
けますようお願い致します。

また、同種の要因から、テストモード終了後に画面のアニメーションオブジェクトの表示
が崩れる場合がありますが、これについてはシーンをセーブしたり・シーン中のアセット等
を選択しなおすと（Unityの内部処理である程度各GameObject間の同期が取り直されるため）、
正常な表示に戻ります。
一応、アプリケーションの動作状態に障害を起こすものではありませんが、今後のバージョン
アップで（可能であれば）解消しようと思っておりますので、ご理解の程お願い致します。

OPTPiX SpriteStudio上での2つの非表示方法の反映の違いについて

これはV1.0以前からの仕様ですが、インポート時の誤解などが少なくないと思われるため、
記載させて頂きます。

OPTPiX SpriteStudio上でパーツを不可視状態にする方法には2種類存在し、
(1) タイムライン上のアトリビュートの「非表示」を設定する。
(2) タイムラインのパーツ名の前にある「目のアイコン」をクリックして不可視にする。

この内、(2)はOPTPiX SpriteStudio上でのデータエディット時のサポート機能となって
いますので、インポート時には、この設定は無視されます。
アニメーションとして「表示しないパーツ」の場合には、(1)のタイムライン上に非表示
のアトリビュートを設定して下さいますようお願い致します。
（この挙動・制限は、バグではなく、仕様となっております）

スプライトパーツの子として別のアニメーションオブジェクトをつける場合の注意点

V1.1ではインスタンスオブジェクト呼出に対応しているため、スプライトパーツの子
として、別のアニメーションオブジェクトを接続する方法が2種類に増えました。

[1] Unityのシーン上で該当するパーツの子として、直接インポートしたプレハブを設置する
[2] インスタンスパーツ機能を使用する

どちらの方法も、大した違いがないように見受けられますが、仕様として下記の
決定的な違いがありますので、目的に合わせて使い分けるようにしてください。

[1]の方法では、2つのアニメーションオブジェクトは、常に親子関係の影響を受けて（親に子が）追従します。
また、それぞれ「独立したアニメーションオブジェクト」として（描画マネージャに）
処理されますので、「描画の順序」は「それぞれのオブジェクトのPartsRootのカメラ
からのZ座標（距離）」で決定されます。

一方[2]の方法では、呼び出されたインスタンスアニメーションは、呼出元のインスタ
ンスパーツの「優先度」アトリビュートの値で描画順序が（呼出元のアニメーション
に連動して）決定され、追従も呼出元のインスタンスパーツの「座標」「回転」「ス
ケール」の影響を受けます（インスタンスパーツが何かのパーツの子として付けられ
ていた場合、インスタンスパーツの親の「座標」「回転」「スケール」の値の影響
も受けますが、「優先度」は親パーツの影響は受けません）。

……以上の点にご注意くださいますようお願い致します。