Unityで外部CSVファイルを読み込む方法｜初心者向けにわかりやすく解説！

はじめに

Unityでゲームを作っていると、だんだんこんな悩みが出てきませんか？

• 敵やアイテムの数値をコードに直接書いていて、あとから調整するのが大変
• 同じような数値を何か所も直していてミスが怖い
• 「データ」と「処理」を分けたほうが良さそうだけど、やり方が分からない

そんなときに役立つのが、CSVファイルを使った外部データ管理です。

CSVを使えば、ゲーム内で使う数値や文章をコードに直書きせず、Excelやスプレッドシートで編集できます。 バランス調整やテキスト修正も、スクリプトを触らずに済むようになるので、開発効率が一気に上がります。

ただし、Unity初心者の方にとっては、

• CSVって何？
• どこに置けばいいの？
• C#でどうやって読み込むの？

と、分からないことだらけになりがちです。

この記事では、そんな初心者さん向けに、Unityで外部CSVファイルを読み込む基本的な方法を、できるだけ噛み砕いて解説していきます。

この記事を読むことで、次のことが分かるようになります。

• UnityでCSVを使うメリット
• CSVファイルの正しい準備方法
• TextAssetを使った安全な読み込み手順
• 初心者がハマりやすい注意点

「とりあえず動くところまでやってみたい」という方でも大丈夫です。 まずはシンプルな構成から、一緒にCSV読み込みを体験していきましょう 🙂

---

結論

Unityで外部CSVファイルを読み込むなら、初心者の方は「TextAsset＋Resourcesフォルダ」を使う方法から始めるのが一番安全です。

理由はシンプルで、

• 設定が少なく、すぐに動かせる
• エディタ上で完結するのでエラー原因を追いやすい
• C#の基礎的な文字列処理だけで実装できる

といったメリットがあるからです。

CSV読み込みというと難しく感じるかもしれませんが、基本の流れは次の3ステップだけです。

1. CSVファイルをTextAssetとして読み込む
2. 中身を1行ずつ取り出す
3. カンマ区切りで分解してデータとして使う

まずはこの基本を押さえるだけで、アイテムデータ・敵ステータス・メッセージ一覧など、さまざまなデータをコードから切り離して管理できるようになります。

逆に、

• 最初から複雑なCSVパーサーを使う
• StreamingAssetsや外部ファイル読み込みをいきなり使う

といったことをすると、初心者の方は混乱しやすくなります。

この記事では、「まずは動かす → 仕組みを理解する → 必要に応じて発展させる」という流れを大切にしながら解説していきます。

---

CSVを使うと何ができる？Unityでの活用例

UnityでCSVを使う一番のメリットは、ゲーム内のデータを「あとから安全に調整できる形」で管理できることです。

具体的には、次のような場面でCSVがよく使われます。

RPGのマスターデータ管理

RPGを作る場合、こんなデータが大量に出てきますよね。

• アイテム名・価格・効果量
• 敵キャラのHP・攻撃力・経験値
• スキルの消費MPや威力

これらをコードに直書きしてしまうと、数値調整のたびにスクリプトを修正する必要があり、とても大変です。

CSVで管理しておけば、表計算ソフトで数値を調整 → Unityを再生という流れで、テンポよくバランス調整ができます。

メッセージ・テキストの一覧管理

会話文や説明文をCSVで管理するケースも多いです。

• アイテム説明文
• チュートリアルの文章
• NPCのセリフ

文章をコードに書かずに済むので、誤字修正や文章調整がとても楽になります。

非エンジニアでも触れるデータ設計

CSVの大きな強みは、Unityを触れない人でも編集できる点です。

例えば、

• プランナーが数値を調整する
• 自分以外の人にデータ作業を任せる

といった場合でも、CSVならスプレッドシートを共有するだけで対応できます。

こうしたCSVのデータは、読み込んだあとに List や Dictionary に変換して使うのが基本になります。

---

CSVファイルの基本ルール（初心者が最初につまずく所）

UnityでCSVを読み込む前に、必ず押さえておきたいCSVファイルの基本ルールがあります。 ここを間違えると、スクリプトが正しくても「なぜか動かない…」という状態になりがちです。

CSVとは何か？

CSVは Comma Separated Values の略で、カンマ（,）区切りのテキストファイルです。

見た目は表計算ソフトそのものですが、実体はただのテキストなので、Unityでも簡単に読み込めます。

文字コードは必ずUTF-8で保存する

初心者が一番ハマりやすいのが、文字コードの問題です。

Unityの TextAsset は、UTF-8で保存されたCSV でないと、日本語が文字化けすることがあります。

• Excelで保存する場合は「UTF-8（コンマ区切り）」
• Googleスプレッドシートなら問題なし

「数字だけなのにエラーが出る」という場合も、実は文字コードが原因なことがあるので注意してください。

1行目は見出し（カラム名）にする

CSVの1行目には、データの意味が分かる見出しを書くのがおすすめです。

例えば、こんなイメージです。

id,name,price,power
1,ポーション,50,10
2,ハイポーション,200,50

こうしておくと、

• あとから見返しても内容が分かりやすい
• コード側との対応関係を把握しやすい

といったメリットがあります。

セル内のカンマと空白に注意

CSVでは、カンマが区切り文字として使われます。

そのため、文章中にカンマを含めたい場合は注意が必要です。 初心者のうちは、できるだけカンマを含まないデータ構成にしておくと安全です。

また、見えない空白が混ざるとエラーの原因になることもあります。 読み込み後に Trim() で空白を除去するクセをつけると安心です。

---

UnityでCSVを読み込む基本構成

ここからはいよいよ、Unity側でCSVを読み込む話に入っていきます。 ただし、いきなりコードを見る前に、全体の流れを一度イメージしておくことがとても大切です。

CSV読み込みは、やっていること自体はそこまで複雑ではありません。 基本は次の流れだけです。

1. CSVファイルをUnityプロジェクト内に配置する
2. CSVを TextAsset として読み込む
3. 文字列として中身を取り出す
4. 1行ずつ処理して、カンマで分割する
5. ゲーム内で使いやすい形（Listやクラス）に変換する

「CSVを読み込む」と聞くと難しそうに感じますが、実際にはテキストを読む処理をしているだけ、というイメージでOKです。

なぜTextAssetを使うの？

Unityには、テキストファイルをそのまま扱える TextAsset という仕組みがあります。

これを使うことで、

• 外部ライブラリなしでCSVを扱える
• エディタ上で完結する
• パス指定のミスが起きにくい

といったメリットがあります。

初心者は「Resources＋TextAsset」から始めよう

UnityにはCSVを読み込む方法がいくつかありますが、初心者の方にはResourcesフォルダを使う方法がおすすめです。

理由は、

• 設定が少ない
• 動作確認が簡単
• 「読み込めない原因」を特定しやすい

といった点にあります。

もちろん、プロジェクトが大きくなれば別の方法を選ぶこともありますが、最初はシンプルなやり方で理解するのが一番です。

---

【実践】Resources＋TextAssetでCSVを読み込む方法

ここからは、実際にUnityでCSVファイルを読み込む具体的な手順を見ていきます。 まずは「確実に動く」構成を体験することを優先しましょう。

① CSVファイルをResourcesフォルダに配置する

Unityで Resources.Load を使う場合、CSVファイルは必ず Resources フォルダ配下に置きます。

例えば、次のような構成です。

Assets
 └ Resources
    └ item_master.csv

このとき、ファイル名は拡張子を除いた名前で扱う点に注意してください。

② CSVをTextAssetとして読み込む

次に、C#スクリプト側でCSVを読み込みます。 Resources.Load を使うと、CSVは TextAsset として取得できます。

TextAsset csvFile = Resources.Load("item_master");

ここで csvFile.text を使うことで、CSVの中身を1つの文字列として扱えるようになります。

③ 1行ずつ読み込んで分割する

CSVはそのまま扱うのではなく、1行ずつ処理するのが基本です。

よく使われるのが StringReader です。

using System.IO;

StringReader reader = new StringReader(csvFile.text);
while (reader.Peek() != -1)
{
    string line = reader.ReadLine();
    string[] values = line.Split(',');
}

これで、1行分のデータが values 配列として取得できます。

④ データをListやクラスに格納する

実際のゲームでは、分割したデータをそのまま使うことは少なく、 Listやクラスに変換して管理するのが一般的です。

例えば、アイテムデータなら、

• CSV → クラスに変換
• クラスのListとして保持

という流れになります。

この「データをListやDictionaryに変換する考え方」はとても重要です。 詳しく知りたい場合は、こちらの記事も参考になります。

ここまでできれば、CSVを読み込んでゲーム内で使うところまではクリアです。

---

よくある失敗とエラー対策

CSV読み込みは仕組み自体はシンプルですが、初心者がつまずきやすいポイントがいくつかあります。 ここでは「動かない原因になりやすい所」を先回りして整理しておきます。

日本語が文字化けする

一番多いトラブルが、日本語の文字化けです。

原因のほとんどは、CSVの文字コードがUTF-8になっていないことです。

• Excel保存時に「CSV（UTF-8）」を選んでいない
• 古いExcelでShift-JISのまま保存している

TextAssetで読み込む場合は、UTF-8で保存することを必ず確認してください。

Resources.Loadでnullが返ってくる

次によくあるのが、Resources.Load が null を返すケースです。

この場合、ほぼ確実に次のどれかが原因です。

• Resourcesフォルダの場所が間違っている
• ファイル名に拡張子（.csv）を含めている
• 大文字・小文字が一致していない

特に初心者の方は、「ファイル名は拡張子なし」を忘れがちなので注意してください。

Splitで配列数が合わない

Split(',') を使っていると、

• 配列の要素数が想定と違う
• IndexOutOfRangeExceptionが出る

といったエラーが起きることがあります。

これは、

• 空行が含まれている
• 行の末尾に余計なカンマがある

といったケースが原因です。

対策としては、

• 空行はスキップする
• Trim()で余計な空白を除去する

といった処理を入れておくと安定します。

数値変換でエラーが出る

CSVの文字列を int.Parse や float.Parse で変換するときに、例外が出ることもあります。

これは、

• 空文字が入っている
• 全角数字が混ざっている

といった場合に起きやすいです。

初心者のうちは、

• CSVの中身をできるだけシンプルに保つ
• 変換前にログで値を確認する

この2点を意識するだけでも、かなりトラブルを減らせます。

---

CSVと他のデータ管理方法の比較

CSVはとても便利ですが、すべてのケースで最適とは限りません。 ここでは、Unityでよく使われる他のデータ管理方法と比較しながら、「どれを選べばいいか」の判断基準を整理します。

CSVとScriptableObjectの違い

ScriptableObjectは、Unityエディタ上でデータを管理できる仕組みです。

それぞれの特徴を簡単にまとめると、次のようになります。

• CSV：大量データ・表形式・外部編集に強い
• ScriptableObject：Unity完結・型安全・小〜中規模向き

アイテムが数個〜数十個程度であれば、ScriptableObjectの方が管理しやすい場合も多いです。

逆に、

• 数百行以上のマスターデータ
• あとからまとめて数値調整したい

といったケースでは、CSVの方が作業効率が高くなります。

CSVとJSONの違い

JSONは、構造化されたデータを扱うのに向いている形式です。

• 階層構造を持たせたい
• セーブデータとして使いたい

といった場合は、CSVよりJSONの方が適しています。

一方で、CSVは「表データ」に特化しているため、 マスターデータ管理の分かりやすさでは今でも強い選択肢です。

初心者向けのおすすめ判断基準

迷ったら、次の基準で考えると失敗しにくいです。

• 最初はCSVで仕組みを理解する
• 小規模ならScriptableObjectも検討する
• セーブ・ロードが絡むならJSONを使う

「最初から完璧な選択」をしなくても大丈夫です。 Unity開発では、途中で管理方法を切り替えることもよくあります。

---

【発展】CSV管理が大変になったらどうする？

CSVはとても便利ですが、プロジェクトが進んでくると、だんだんこんな悩みが出てくることがあります。

• データ量が増えて管理がつらくなってきた
• CSVを読み込んだあと、セーブ・ロードもしたくなった
• データ構造が複雑になってきて、コードがごちゃつく

こうなってきたら、CSVをそのまま頑張り続ける必要はありません。 Unityでは、データ管理や保存を楽にしてくれる便利なツールも用意されています。

セーブ・ロードまで含めて管理したい場合

CSVは「読み込み専用のマスターデータ」としては優秀ですが、 プレイ状況や設定値などを保存・復元する用途には向いていません。

そういった場合は、セーブ処理を丸ごと任せられるアセットを使うのが現実的です。

EASY SAVEは、

• セーブ・ロード処理をほぼ自動化できる
• 複雑なデータ構造でもそのまま保存できる
• 初心者でも扱いやすいAPI設計

といった特徴があり、CSVで読み込んだデータを保存したい場面でも活躍します。

「CSVでマスターデータを管理 → 実行中の状態をセーブする」 という役割分担にすると、設計がかなりスッキリします。

---

RPG制作でCSVを使うなら知っておきたい選択肢

RPG制作では、アイテム・敵・スキル・イベントなど、扱うデータ量が一気に増えます。 そのため、「CSVで全部管理するのが正解なのか？」と悩む方も多いです。

結論から言うと、CSVが向いている人と、ツールに任せた方が楽な人がいます。

CSV管理が向いている人

次のような人は、CSV管理と相性が良いです。

• UnityとC#の仕組みをしっかり理解したい
• データ構造を自分で設計したい
• 小〜中規模のRPGを作っている

CSVでマスターデータを管理すると、ゲーム内部の仕組みが見えやすくなり、 プログラミングの理解も一段深まります。

最初からツールを使った方が楽なケース

一方で、次のような場合は、最初から専用ツールを使うのも良い選択です。

• RPGの完成が目的で、仕組み作りに時間をかけたくない
• イベントや会話、バランス調整まで一括で管理したい
• Unity初心者で挫折したくない

RPG MAKER UNITEを使えば、

• データベース管理をGUIで完結できる
• RPG特有の仕組みを最初から用意できる
• 「作りながら学ぶ」より「完成させる」ことに集中できる

といったメリットがあります。

CSV管理はゴールではなく手段です。 自分の目的に合った方法を選ぶことが、結果的に一番の近道になります。

---

よくある誤解・注意点まとめ

最後に、UnityでCSVを使い始めたときに、初心者の方が勘違いしやすいポイントをまとめておきます。

CSVを使えば何でも解決する、と思ってしまう

CSVはとても便利ですが、万能ではありません。

• データ同士の強い関連性がある
• 階層構造が複雑

といった場合は、CSVよりもScriptableObjectやJSONの方が向いていることもあります。

「CSVで管理できるか？」ではなく、 「今扱っているデータの性質は何か？」を考えることが大切です。

最初から完璧な設計を目指してしまう

CSV管理を始めると、

• 将来の拡張
• きれいな設計
• 汎用的な仕組み

を意識しすぎて、手が止まってしまうことがあります。

でも、初心者のうちはまず動くものを作るのが一番大切です。

CSV読み込みも、

• 最初はSplitでOK
• 問題が出たら改善する

このくらいの感覚で問題ありません。

Resourcesフォルダはずっと使い続けるものだと思ってしまう

この記事では、初心者向けに Resources フォルダを使いましたが、 これはあくまで学習用・小規模向けの方法です。

プロジェクトが大きくなってきたら、

• Addressables
• StreamingAssets

といった別の選択肢に切り替えることもあります。

今は「仕組みを理解する段階」だと割り切って使うのが正解です。

---

まとめ

この記事では、Unityで外部CSVファイルを読み込む方法について、初心者の方向けに基礎から順番に解説してきました。

ポイントを振り返ると、次のとおりです。

• CSVを使うと、数値や文章をコードに直書きせず管理できる
• 初心者は「Resourcesフォルダ＋TextAsset」から始めるのが安全
• CSV読み込みの本質は「テキストを1行ずつ処理する」こと
• 文字コード（UTF-8）や空行など、基本ルールを守ることが重要

CSV管理は、Unity開発でよく使われるデータ駆動設計の入り口でもあります。 最初は少し面倒に感じるかもしれませんが、一度慣れると「もう直書きには戻れない」と感じるはずです。

また、プロジェクトが成長すれば、

• ScriptableObjectに移行する
• JSONやセーブ管理アセットを併用する
• RPG向けツールを活用する

といった選択肢も自然に見えてきます。

大切なのは、今の自分のレベルと目的に合った方法を選ぶことです。 この記事が、Unityでのデータ管理に一歩踏み出すきっかけになれば嬉しいです。

---

参考文献・参考リンク

• UnityでCSVファイルを読み込む方法（TextAsset編）
• UnityでCSVを扱うときに知っておきたい基礎知識
• CSVの読み込みでハマるあれこれ（文字コード・分割トラブル）
• UnityでCSVをパースする実装例まとめ
• Is there really no CSV reader in Unity?（Stack Overflow）
• Uni-CSV（Unity向けCSVパーサー GitHub）
• Unity CSV Tutorial – 基本的な読み込み解説（YouTube）
• UnityでCSVを使ったデータ管理の実例解説（YouTube）
• Unity CSV Parsing Tutorial（実践編・YouTube）

---

よくある質問（FAQ）