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

SS6Player for Unity（以降「SS6PU」）のアニメーション制御用クラス（Script_SpriteStudio6_Root）のセル・セルマップ管理関係の機能群のスクリプトリファレンスです。

SS6PUの「Ver.1.x系」と「Ver.2.0以降」とでは、マテリアルの管理仕様が根本的に変わっています。
そのため、本項目で解説される関数についても「前提」が変わっているものがありますので、注意してください。

  • Ver.1.x系
    インポート時に静的データとして（使用する）マテリアルを生成し、それをテーブル（TableMaterial）の形で運用しています。
    そのため、特にセルマップに対応するテクスチャを変更する場合、TableMaterialに設定されているマテリアル群のテクスチャを直接変更するなどの方法で実装する前提にありました。
  • Ver.2.0以降
    インポート時にはマテリアルを作成せず、実行時に使用しているマテリアルを作成し・SS6PUの内部にある「マテリアルキャッシュ」に貯蔵して・全アニメーションオブジェクトで共用します。
    そのため、セルマップに対応するテクスチャとマテリアルとの直結性がかなり薄れ、局所（ローカル）マテリアルキャッシュとTextureSetCellMap関数を併用するような前提に仕様が変わっています。

この差異については、細かいですが大きな前提の変更になっているので、注意していただけますようお願いいたします。

セルマップに対応したテクスチャの変更 （Ver.2.0以降）

関数（動的）

UnityEngine.Texture TextureSetCellMap(
        int indexCellMap,
        UnityEngine.Texture texture,
        bool flagReplaceMaterialCache
    )

引数

  • indexCellMap : 変更するセルマップ番号
  • texture : 設定するテクスチャ
  • flagReplaceMaterialCache : 既存のキャッシュの内容も置き換えるか？

返値

変更前に設定されていたテクスチャ
null ... 失敗（エラー）

解説

アニメーションに割り当たっているセルマップに対応するテクスチャを変更します。
本関数を使用するためには、事前にCacheBootUpMaterial関数を使用して、再生アニメーション用の局所（ローカル）マテリアルキャッシュを作成してください。
局所マテリアルキャッシュが作成されていない場合、本関数はエラーを返します。
また、大域（プロジェクトデータ全域）のセルマップ対応テクスチャを変更することはできません。

indexCellMapは、IndexGetCellMap関数などを使用して取得してください。

textureは、変更する（変更後の）テクスチャになります。
nullを指定すると、変更されていたテクスチャを元の状態（大域マテリアルキャッシュに定義されているものを使用する）に戻します。

flagReplaceMaterialCacheは、trueを設定すると「現在マテリアルキャッシュに既存している標準シェーダを使用しているマテリアル」のシェーダを全て置き換えます（ただし対象のキャッシュ範囲は局所マテリアルキャッシュの中に限られます）。
falseを設定すると「既存のマテリアルキャッシュ内のマテリアルはそのままで、本関数以降で新規作成される標準シェーダを使用したマテリアル」に対して設定したシェーダを使用します。

セルマップテーブルの取得

関数（動的）

Library_SpriteStudio6.Data.CellMap[] TableGetCellMap(
        bool flagInUse=true
    )

引数

  • flagInUse : 現在使用中のセルマップテーブルか？

返値

セルマップテーブルへの参照
null ... 失敗（エラー）

解説

アニメーションに割り当たっているセルマップテーブル（セルマップ情報の配列）を取得します。

flagInUseの設定は下記の仕様です。

  • false : アニメーションデータに元々設定してあるセルマップテーブルを取得します。
    TableSetCellMap関数などを使用して変更した使用中のセルマップテーブルではなく、変更前のアニメーションデータに設定されているセルマップテーブルが対象です。
  • true : 現在使用中のセルマップマップテーブルを取得します。
    TableSetCellMap関数などを使用して変更した使用中のセルマップテーブルが対象です。

※アニメーションオブジェクトが実体化してから、特段セルマップテーブルを変更していない場合でも、trueとfalseでは異なるセルマップテーブルへの参照を返します（アニメーションオブジェクトが実体化した際に、セルマップテーブルはシャローコピーされます）。

様々な都合上、TableCellMapメンバ変数をアプリケーションから直接取得することができますが（internalスコープになっています）、それは行わずに本関数を使用して取得するようにしてください。

セルマップテーブルの設定

関数（動的）

bool TableSetCellMap(
        Library_SpriteStudio6.Data.CellMap[] tableCellMap
    )

引数

  • tableCellMap : 変更するセルマップテーブル
    null ... アニメーションデータで設定されている元テーブルに戻す

返値

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

解説

アニメーションの再生に使用するセルマップテーブル（セルマップ情報の配列）を変更します。

変更後のセルマップテーブルは下記の要件を満たす必要があります（本関数は必要要件を満たしているかをチェックしませんので注意してください）。

  • アニメーションデータから使用されているセルマップ数を不足なく満たしていること。
    アニメーションデータ内に記録してある参照セルは、セルが格納されているセルマップを番号（インデックス）で保持しています（セルマップは名前情報も保持していますが、あくまでアプリケーション作成時などに名前からの逆引きを必要とした場合の運用にとどまっています）。
    そのため、セルマップテーブルがアニメーションデータから参照されている番号を満たす数を保持していなかったり、セルマップの役割などの順序が変わっていたりする場合には、期待通りの結果を得られませんので注意してください。
  • アニメーションデータから使用されているセル数を不足なく満たしていること。
    セルマップと同様に、セルマップに格納されているセルについても、番号（インデックス）で管理されています。
    そのため、各セルマップがアニメーションデータから参照されているセル番号を満たす数を保持していなかったり、セルの役割などの順序が変わっていたりする場合には、期待通りの結果を得られませんので注意してください。

様々な都合上、TableCellMapメンバ変数をアプリケーションから直接設定することができますが（internalスコープになっています）、それは行わずに本関数を使用して設定するようにしてください（アニメーションの再生が誤動作する場合があります）。

セルマップ数の取得

関数（動的）

int CountGetCellMap(
        bool flagInUse=true
    )

引数

  • flagInUse : 現在使用中のセルマップテーブルか？

返値

セルマップテーブルに内包されているセルマップ数
-1 ... 失敗（エラー）

解説

アニメーションに割り当たっているセルマップテーブル（セルマップ情報の配列）に内包されているセルマップ数（セルマップテーブルの配列長）を取得します。

flagInUseの設定はTableGetCellMap関数のflagInUseと同じ仕様です。

セルマップ番号の取得

関数（動的）

int IndexGetCellMap(
        string name,
        bool flagInUse=true
    )

引数

  • name : セルマップ名
  • flagInUse : 現在使用中のセルマップテーブルか？

返値

指定セルマップ名のセルマップ番号
-1 ... 発見できず（エラー）

解説

アニメーションに割り当たっているセルマップテーブル（セルマップ情報の配列）に内包されているセルマップから、指定の名称を持ったセルマップの番号（インデックス）を取得します。

flagInUseの設定はTableGetCellMap関数のflagInUseと同じ仕様です。

セルマップの取得

関数（動的）

Library_SpriteStudio6.Data.CellMap CellMapGet(
        int indexCellMap,
        bool flagInUse=true
    )

引数

  • indexCellMap : セルマップの番号
  • flagInUse : 現在使用中のセルマップテーブルか？

返値

指定セルマップ情報への参照
null ... 失敗（エラー）

解説

アニメーションに割り当たっているセルマップテーブル（セルマップ情報の配列）に内包されているセルマップから、指定番号のセルマップ情報への参照を取得します。
セルマップに含まれるセルの情報を取得するには、本関数で取得したセルマップ情報（Library_SpriteStudio6.Data.CellMapクラス）の関数などを使用します。

indexCellMapは、IndexGetCellMap関数などを使用して取得してください。

flagInUseの設定はTableGetCellMap関数のflagInUseと同じ仕様です。

セルマップの設定

関数（動的）

bool CellMapSet(
        int indexCellMap,
        Library_SpriteStudio6.Data.CellMap cellMap
    )

引数

  • indexCellMap : セルマップの番号
  • cellMap : 変更後のセルマップ

返値

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

解説

アニメーションオブジェクトが現在使用しているセルマップテーブル（セルマップ情報の配列）内の指定番号のセルマップ情報への参照を変更します。
本関数を使用して、アニメーションが持っている大元のセルマップ情報を変更することはできません（あくまで、そのアニメーションオブジェクト単体の使用中のセルマップテーブルの内容だけを書き換えることができます）。

indexCellMapは、IndexGetCellMap関数などを使用して変更対象のセルマップ番号を取得してください。

cellMapで指定される変更後のセルマップは、TableSetCellMap関数のセルマップ情報と同様に、アニメーションデータから参照されるセル数・セルの格納順序などを最低限満たす必要があります。

セルマップテーブルの複製（簡易）

関数（動的）

Library_SpriteStudio6.Data.CellMap[] TableCopyCellMapShallow(
        int indexStart=0,
        int indexEnd=-1,
        bool flagInUse=true
    )

引数

  • indexStart : 複製を開始するセルマップの番号
  • indexEnd : 複製を終了するセルマップの番号
  • flagInUse : 現在使用中のセルマップテーブルか？

返値

複製されたセルマップテーブル
null ... 失敗（エラー）

解説

アニメーションオブジェクトのセルマップテーブルをシャローコピーします。
※セルマップテーブルと・そのテーブルに書かれているセルマップ群のみが別の実体を持ち、各セルマップの持つセル情報群は参照元のセルマップ群が参照しているセル情報と同じ参照先です。

アニメーションオブジェクトのセルマップテーブルのindexStart～indexEndの連続した範囲を取り出したセルマップテーブルを作成します。
複製先のセルマップテーブルのセルマップテーブルの先頭（0番目）に、複製元のindexStart番目のセルマップがきます（セルマップテーブルを限定範囲で切り出した時は、複製後のセルマップテーブルは前に詰まります）。

indexStartは省略時は0（セルマップテーブルの先頭）です。

indexEndに-1を指定するとセルマップの終端を意味し省略時は-1です。

flagInUseの設定はTableGetCellMap関数のflagInUseと同じ仕様です。

セルマップテーブルの複製（完全）

関数（動的）

Library_SpriteStudio6.Data.CellMap[] TableCopyCellMapDeep(
        int indexStart=0,
        int indexEnd=-1,
        bool flagInUse=true
    )

引数

  • indexStart : 複製を開始するセルマップの番号
  • indexEnd : 複製を終了するセルマップの番号
  • flagInUse : 現在使用中のセルマップテーブルか？

返値

複製されたセルマップテーブル
null ... 失敗（エラー）

解説

アニメーションオブジェクトのセルマップテーブルをディープコピーします。
※元のセルマップテーブルが参照している先のセルマップやセル情報も別の実体が作成されます。

それ以外については、TableCopyCellMapShallow関数と同じです。

パーツの参照セルの変更

関数（動的）

bool CellChangeParts(
        int idParts,
        int indexCellMap,
        int indexCell,
        Library_SpriteStudio6.KindIgnoreAttribute ignoreAttribute
    )

引数

  • idParts : パーツID
  • indexCellMap : 変更後のセルが格納されているセルマップ番号
  • indexCell : 変更後のセルのセルマップ内番号
  • ignoreAttribute : 変更したセルの有効期間
    • NON : アニメーションデータでセル変更されるまで有効
    • NOW_ANIMATION : 再生アニメーションを変更するまで有効
    • PERMANENT : アニメーションオブジェクト生存期間中有効

返値

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

解説

動的セル変更機能です。
再生中のアニメーションで参照しているセルを変更します。
この機能を使用することで、アニメーションで表示しているセルを差し替えることができます（データ自体に影響を与えません。つまり指定したアニメーションオブジェクトで再生しているセルだけが差し替わります）。

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

セルマップ番号はIndexGetCellMap関数などで取得してください。
セル番号は、取得したセルマップ番号からCellMapGet関数で取得したセルマップ情報のIndexGetCell関数などを使用して取得してください。

ignoreAttributeで指定する変更したセルの有効期間は、厳密には「アニメーションデータで設定されている参照セルのキーデータを、どのように無視するか」です。

  • NON （無視しない）
    再生中のアニメーションで次に参照セルのデータが出現した時に、本関数での設定はアニメーションデータの参照セルで上書きされます。
    ※MonoBehaviour.Updateのタイミングで本関数を使用した場合、SS6PUのアニメーションの更新処理はLateUpdateのタイミングで実行されるため、同じフレーム位置で本関数での変更とアニメーションでの更新が起こった場合、アニメーションデータの参照セルが優先されます（後発優先です）。
  • NOW_ANIMATION （現在のアニメーション中は無視する）
    AnimationPlay関数などで再生しているアニメーションを変更するまで、本関数でのセルの変更設定が適用されます（アニメーションデータでの参照セルのキーデータを無視します）。
    ※「アニメーション合成」機能を使用している場合、パーツIDが参照しているアニメーションを再生しているトラックに新しいAnimationPlay関数が適用されるまでの間となります。
  • PERMANENT （常に無視する）
    AnimationPlay関数などで再生しているアニメーションが変更されても、本関数でのセルの変更設定が継続して適用されます。

また、本関数でセル変更を設定した後で再度本関数を使用した場合に、ignoreAttributeは後で実行された本関数の設定が適用されます（例えば、先にPERMANENTでセル変更を設定した後、いずれかのタイミングでNOW_ANIMATIONでセル変更を設定した場合、NOW_ANIMATIONの有効期間設定に変更されます）。

本関数を「メッシュ」パーツに指定しても、参照しているセルを変更することができます。
ただし、「メッシュセルに定義されている頂点や分割情報」や「パーツに設定されているウェイトなどの情報」（これらを総じて「メッシュバインド情報」と呼称します）は変更されず・古いメッシュセルの値を引き継ぎます。
つまり、図柄が変わるだけになりますので注意してください（変更前後のセルの大きさが異なっている場合には変更前のセルの大きさが優先される他・デフォーム機能などのメッシュセルの頂点に依存するデータも本関数では変更できません）。

セルマップテーブルの複製（簡易）

関数（静的）

Class: Cell
Library_SpriteStudio6.Data.CellMap[] TableCopyMapShallow(
        Library_SpriteStudio6.Data.CellMap[] tableCellMap
    )

引数

  • tableCellMap : 複製元のセルマップテーブル

返値

複製後のセルマップテーブル
null ... 失敗（エラー）

解説

指定されたセルマップテーブルのシャローコピーを作成します。
※セルマップテーブルと・そのテーブルに書かれているセルマップ群のみが別の実体を持ち、各セルマップの持つセル情報群は参照元のセルマップ群が参照しているセル情報と同じ参照先です。

Library_SpriteStudio6.Utility.Cell.TableCopyMapShallow関数のエリアスです。

セルマップテーブルの複製（完全）

関数（静的）

Class: Cell
Library_SpriteStudio6.Data.CellMap[] TableCopyMapDeep(
        Library_SpriteStudio6.Data.CellMap[] tableCellMap
    )

引数

  • tableCellMap : 複製元のセルマップテーブル

返値

複製後のセルマップテーブル
null ... 失敗（エラー）

解説

指定されたセルマップテーブルのディープコピーを作成します。
※元のセルマップテーブルが参照している先のセルマップやセル情報も別の実体が作成されます。

Library_SpriteStudio6.Utility.Cell.TableCopyMapDeep関数のエリアスです。

セルマップの複製（簡易）

関数（静的）

Class: Cell
Library_SpriteStudio6.Data.CellMap MapCopyShallow(
        Library_SpriteStudio6.Data.CellMap cellMap
    )

引数

  • cellMap : 複製元のセルマップ

返値

複製後のセルマップ
null ... 失敗（エラー）

解説

指定されたセルマップのシャローコピーを作成します。
※セルマップのみが別の実体を持ち、セルマップが持っているセル情報群は参照元のセルマップが参照しているものと同じ参照先です。

Library_SpriteStudio6.Utility.Cell.MapCopyShallow関数のエリアスです。

セルマップの複製（完全）

関数（静的）

Class: Cell
Library_SpriteStudio6.Data.CellMap MapCopyDeep(
        Library_SpriteStudio6.Data.CellMap cellMap
    )

引数

  • cellMap : 複製元のセルマップ

返値

複製後のセルマップ
null ... 失敗（エラー）

解説

指定されたセルマップのディープコピーを作成します。
※セルマップが持っているセル情報群も全て別の実体を持ちます。

Library_SpriteStudio6.Utility.Cell.MapCopyDeep関数のエリアスです。

セルの複製（簡易）

関数（静的）

Class: Cell
1. bool CopyShallow(
        ref Library_SpriteStudio6.Data.CellMap.Cell cellOutput,
        ref Library_SpriteStudio6.Data.CellMap.Cell cell
    )
2. bool CopyShallow(
        Library_SpriteStudio6.Data.CellMap cellMapOutput,
        int indexCellOutput,
        ref Library_SpriteStudio6.Data.CellMap.Cell cell
    )
3. bool CopyShallow(
        Library_SpriteStudio6.Data.CellMap cellMapOutput,
        int indexCellOutput,
        Library_SpriteStudio6.Data.CellMap cellMap,
        int indexCell,
        int countCell
    )

引数

  • cellOutput : 複製先のセル
  • cell : 複製元のセル
  • cellMapOutput : 複製先のセルマップ
  • indexCellOutput : 複製先のセル番号
  • cell : 複製元のセル
  • cellMapOutput : 複製先のセルマップ
  • indexCellOutput : 複製先の開始セル番号
  • cellMap : 複製元のセルマップ
  • indexCell : 複製元の開始セル番号
  • countCell : 複製元の開始セル番号

返値

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

解説

複製元のセル情報を複製先にシャローコピーします。
※複製先の持っている各情報は複製元と同じ実体を参照しています。

1.は単体セルの複製で、cellOutputにcellの内容を複製します。

2.は単体セルの複製ですが、出力先がセルマップ内のセルになります。
cellMapOutputで指定されるセルマップのindexCellOutput番目（0オリジン）のセルに、cellの内容を複製します。

3.は複数セルの複製で、入出力ともセルマップ内のセルになります。
cellMapOutputで指定されるセルマップのindexCellOutput番目（0オリジン）から始まるセル群に、cellMapで指定されるセルマップのindexCell番目（0オリジン）から始まるセル群を、countCell個コピーします。

いずれも、Library_SpriteStudio6.Utility.Cell.CopyShallow関数のエリアスです。

セルの複製（完全）

関数（静的）

Class: Cell
1. bool CopyDeep(
        ref Library_SpriteStudio6.Data.CellMap.Cell cellOutput,
        ref Library_SpriteStudio6.Data.CellMap.Cell cell
    )
2. bool CopyDeep(
        Library_SpriteStudio6.Data.CellMap cellMapOutput,
        int indexCellOutput,
        ref Library_SpriteStudio6.Data.CellMap.Cell cell
    )
3. bool CopyDeep(
        Library_SpriteStudio6.Data.CellMap cellMapOutput,
        int indexCellOutput,
        Library_SpriteStudio6.Data.CellMap cellMap,
        int indexCell,
        int countCell
    )

引数

  • cellOutput : 複製先のセル
  • cell : 複製元のセル
  • cellMapOutput : 複製先のセルマップ
  • indexCellOutput : 複製先のセル番号
  • cell : 複製元のセル
  • cellMapOutput : 複製先のセルマップ
  • indexCellOutput : 複製先の開始セル番号
  • cellMap : 複製元のセルマップ
  • indexCell : 複製元の開始セル番号
  • countCell : 複製元の開始セル番号

返値

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

解説

複製元のセル情報を複製先にディープコピーします。
※複製先の持っている各情報は複製元とは異なる実体を参照しています。

それ以外については、CopyShallow関数と同じです。

いずれも、Library_SpriteStudio6.Utility.Cell.CopyDeep関数のエリアスです。