マスターデータ等、Unityでテーブル形式のデータを扱う際はExcelを使うと便利なことがよくあります。その際は一般的にNPOIを利用して読み込みを行うのですが、データに合わせて毎回インポート処理を実装するのが手間でした。そこで、今回その仕組みを汎用化しプラグインにしてみました。
ちなみに、UnityでExcelを読み込むためのプラグインで有名なものに、テラシュールブログ・@tsubaki様（いつもお世話になっております）のUnity Excel Importer Makerがありますが、こちらはImporterを「Make」するためのプラグインです。本プラグインはImporter部分はリフレクションを用いて１つのまま、Excel内のデータを保持するScriptableObjectを作るという点で違いがあります。
2019/6/12: いくつか説明を加筆しました。
プラグインインポート
https://github.com/mikito/unity-excel-importer
こちらのリポジトリからソースコードをダウンロードし、Assets/ExcelImporter以下をプロジェクトに追加してください。
Excelファイルごとの事前準備
Excelファイルごとに、それに紐づく必要なクラスの定義・生成を一度だけ行う必要があります。
1. Entityクラスの定義
まずは、Excelからロードしたいデータ構造のクラスを手動で定義します。
本プラグインではこのデータ構造クラスをEntityクラスと呼んでいます。
クラスにはpublicなフィールドで型と名前を定義し、System.Serializableアトリビュートを付与します。
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
[System.Serializable] // アトリビュートを付与
public class MstItemEntity
{
public int id; // publicでエクセルでインポートしたい型と名前を定義
public string name;
public int price;
}
2. Excelファイルの作成と追加
次に、Excelファイルを作成します。
Excelファイルは1行目にEntityクラスのフィールド名と同じ名称を記述し、
そのフィールドの型に基づく値を2行目から入力します。
さらにシートの名前を適当な名称に変更します。
注:
Excelファイルの1行目の名称は、Entityクラスのフィールド名と紐づいているため、どちらかを変更した場合はもう片方を合わせる必要があります。ちなみに並び順には影響されません。
作成したExcelファイルをAssets以下のどこのディレクトリでも良いので、
Unityにインポートします。
この時１度だけワーニングが出ますが、無視して構いません。（v1.1で出力しないようになりました）
3. ExcelAssetスクリプトの生成
次にEntityクラスを保持するためのScriptableObjectクラスを生成します。
こちらは総じてExcelAssetクラスと呼んでいます。
Excelファイルを選択した状態でProjectビューのCreateメニューからExcelAssetScriptを実行すると、スクリプトファイルの保存先が聞かれるため、適当なディレクトリを選択します。
すると、Excelファイルと同名のテンプレートスクリプトが生成されます。
生成されたスクリプト内には、コメントアウトされた行があり、
Excelファイル内のシート数と名前が反映されています。
using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
[ExcelAsset]
public class MstItems : ScriptableObject
{
//public List<EntityType> Entities; // Replace 'EntityType' to an actual type that is serializable.
}
ちなみに、ExcelAssetスクリプトの生成はプラグインの機能を利用すると楽ですが、大した内容ではないので手動で定義しても問題ありません。（ExcelAssetアトリビュートが付いたScriptableObjectで、Excelファイルと同名である必要があります。）
4. ExcelAssetスクリプトの修正
上記で生成したスクリプトを修正します。
コメントアウトを外し、EntityTypeを先ほど定義した実際のTypeに置き換えます。
using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
[ExcelAsset]
public class MstItems : ScriptableObject // クラス名とExcelファイル名を合わせる
{
public List<MstItemEntity> Entities; // シート名とフィールド名を合わせる
}
注:
上記ExcelAssetスクリプトのフィールド名、「Entities」の部分はExcelファイル内のシート名と紐づいています。シート名を変更した場合はこちらの定義も変更する必要があります。
またクラス・スクリプトファイル名の「MstItems」はExcelファイル名と紐づいています。こちらも、Excelファイルの名称を変更した場合は追従して変更する必要があります。
自動更新とデータの利用
一度上記作業を終えた後は、
Excelファイルを更新する度に自動で対応するExcelAssetのScriptableObjectを生成・更新します。
初回設定時はExcelファイルに対してReimportを行うと即時処理が実行され良いでしょう。
このデータを利用するためには、
何かしらのMonoBehaviourクラスのSerializeFieldのフィールドからExcelAssetオブジェクトを参照してください。
その他
bool型の入力
Excelファイルのセルにて、FALSE、 TRUEの文字列を入力します（小文字で入力した場合、エクセルが自動的にbool値と判別して大文字に変換します）。
コメント行
行の先頭のセルにて最初の文字を#にするとその行をコメント行とみなします。
アセット生成パスの変更
ExcelAssetアトリビュートにAssetPathを指定すると、
Excelファイルと同じディレクトリに生成されるAssetファイルのパスを変更できます。
例えば、Resources以下に変更すれば、
Resources.Load使って参照を取るということも可能です。
using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
[ExcelAsset(AssetPath = "Resources/MasterData")]
public class MstItems : ScriptableObject
{
public List<MstItemEntity> Entities;
}
Enumの利用
Entityクラス内のフィールドの型にenumを指定し、Excelファイルのセル内にそのenumの要素名を文字列で入力すると、自動でenumに変換します。
このとき、Excelファイル内で「データの入力規則」の機能を使って
enum名のプルダウンを作ると便利です（以下の図はLibreOfficeのためUIが異なる場合があります）。
データ読み込みの終了位置
Excelファイルのシート内で、空の行もしくは空の列が出現した場合は、そこでデータの終了とみなしそこでセルの読み込みを打ち切ります。
以降のセルはコメントを残したり、計算式を記述するのに利用できます。
複数シートの対応
１つのExcelファイルで複数シートに対応したい場合は、ExcelAssetの定義にシートと同名の定義を追加します。
using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
[ExcelAsset]
public class MyExcelAsset : ScriptableObject
{
public List<Hoge> Sheet1; // シート名と変数名を合わせる
public List<Fuga> Sheet2;
public List<Piyo> Sheet3;
}
空のセルの挙動
セルを空にした場合は、Entityクラスで定義したフィールドの型のデフォルト値が入ります。