概要
CSV4Unityは、UnityのTextAssetやCSV文字列からデータを読み取り、行・列・セルの単位で参照するためのC#ライブラリです。CSVの解析だけでなく、列の指定、型変換、検証、Editorでの確認までを扱います。
前身となる仕組みは急擬山で流用し、その後ライブラリとして独立させて開発を続けています。猫を題材にしたゲーム、MeteorCore Legion、MeteorCore Bladeなどでも、ゲーム内のデータを表形式で扱うために使用しています。
制作の目的
シナリオなどの表形式データを、Unityから安全に参照・変換・検証できるようにするために制作しました。行のコマンドによって同じ列の意味が変わるデータも扱えることを重視しています。
担当したこと
C#ライブラリの設計・実装
セルの参照・型変換と条件付きのデータ検証
Unity Editor向けの確認・検証機能
工夫した点
同じ列でも、行によって意味が変わる
ゲームのシナリオCSVでは、同じ引数の列でも、行のコマンドによって背景名、待機時間、真偽値など、入れる値が変わることがあります。CSV全体を一つのクラスへ変換する方式だけでは扱いづらい、このようなデータを対象にしています。
必要なセルを、必要なタイミングで明示的に型変換する構成にしています。列はEnumで指定できるため、列名の文字列をコードのあちこちに直接書かずに参照できます。
読み込み・参照・検証を分ける
コアでは、元のCSV文字列とセル範囲を保持するCsvDocument、CSVパーサー、型付きのCsvTable、型変換、明示的に作成する検索用Indexなどへ役割を分けています。RuntimeにUnity Editorへの依存を持ち込まないことも設計上の方針です。
解析はRFC 4180形式の引用符やセル内改行に対応します。単純なカンマ区切りとして分割するだけでは扱えない、文章や引用符を含むデータも読み込めるようにしています。
データの間違いを制作中に見つける
Enumに付けた属性を使って、必須値や型などの制約を定義できます。行の条件に応じた検証も用意し、コマンドごとに必要な引数が異なるCSVに対応しています。
Editor側には、手動検証、文字コードの確認とUTF-8変換、読み取り専用Viewerを用意しました。CSVを書き出してからゲームを動かすまでの間に、データを確認するための機能です。
継続していること
現在も1.0未満の再設計を進めており、APIは変更される可能性があります。利用するときは、タグかコミットを固定する形にしています。実際のゲーム制作で使いながら、CSVを読み込む処理と、データを確認する作業の両方を整えています。
開発の経緯
前身を作り始めたのは、2024年4月頃にノベルゲームを制作しようとしたときです。そのノベルゲームシステムを、2025年のゲームジャム作品「急擬山」で流用しました。
作品の中で使っていた仕組みを、モジュールとして独立したライブラリにできたら面白いのではないかと考えたことが、CSV4Unityの開発につながっています。最初から汎用ライブラリを目指したのではなく、実際のゲーム制作で使ったコードから発展した道具です。