> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Diversion と Unity のベストプラクティス

> シームレスなバージョン管理のために、Unity で Diversion を効果的に使用する方法を学びます

Unity は Diversion とシームレスに連携し、従来の VCS システムの複雑さなしにゲームプロジェクト向けの強力なバージョン管理を提供します。[Diversion Unity プラグイン](/ja/unity/unity-plugin) を使用して統合された体験を得ることも、デスクトップアプリと CLI を使って作業することもできます。

## はじめに

### 前提条件

Diversion を Unity と組み合わせて使用する前に、以下を用意してください:

* Diversion をインストールし、サインインしていること（[クイックスタート](/ja/quickstart) を参照）
* Unity Hub と Unity Editor がインストールされていること
* Unity プロジェクトが作成済み、またはインポートできる状態であること

### 初期セットアップ

<Steps>
  <Step title="Unity のバージョン管理設定を構成する">
    Unity プロジェクトを開き、`Edit > Project Settings` に移動します:

    * **Version Control Mode** を `Visible Meta Files` に設定
    * **Asset Serialization Mode** を `Force Text` に設定

    <img alt="Unity プロジェクト設定" style={{width: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} src="https://mintcdn.com/diversion-2/BSIgOl9TnNu74UsW/images/unity-project-settings-vcs-meta.jpg?fit=max&auto=format&n=BSIgOl9TnNu74UsW&q=85&s=b390f0b5b4166d3db4694e60b97075fb" width="1396" height="744" data-path="images/unity-project-settings-vcs-meta.jpg" />

    <img alt="Unity プロジェクト設定" style={{width: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} src="https://mintcdn.com/diversion-2/BSIgOl9TnNu74UsW/images/unity-project-settings-vcs-force-text.jpg?fit=max&auto=format&n=BSIgOl9TnNu74UsW&q=85&s=7a6b2cc6a3ca4af3acf6768ead06aeca" width="1402" height="915" data-path="images/unity-project-settings-vcs-force-text.jpg" />

    これらの設定により、Unity のメタファイルが Diversion から見えるようになり、アセットがテキスト形式で保存されて競合の解決が容易になります。
  </Step>

  <Step title=".dvignore の構成を確認する">
    <Card title="注意" icon="info-circle" iconType="duotone" color="#0b8a42">
      Diversion は Unity プロジェクトを初期化する際に、Unity 固有のパターンを含む `.dvignore` ファイルを自動的に作成します。通常は変更する必要はありません。
    </Card>

    Unity プロジェクト用のデフォルトの `.dvignore` には、次のような一般的なパターンが含まれます:

    ```ini theme={null}
    # Unity generated folders
    .utmp/
    /[Ll]ibrary/
    /[Tt]emp/
    /[Oo]bj/
    /[Bb]uild/
    /[Bb]uilds/
    /[Ll]ogs/
    /[Uu]ser[Ss]ettings/
    /[Mm]emoryCaptures/
    /[Rr]ecordings/

    # Autogenerated Jetbrains Rider plugin
    /[Aa]ssets/Plugins/Editor/JetBrains*
    *.DotSettings.user

    # Visual Studio cache
    .vs/

    # Gradle cache directory
    .gradle/

    # Autogenerated VS/MD/Consulo solution and project files
    ExportedObj/
    .consulo/
    *.csproj
    *.unityproj
    *.sln
    *.suo
    *.tmp
    *.user
    *.userprefs
    *.pidb
    *.booproj
    *.svd
    *.pdb
    *.mdb
    *.opendb
    *.VC.db

    # Unity3D generated meta files
    *.pidb.meta
    *.pdb.meta
    *.mdb.meta

    # Unity3D crash reports
    sysinfo.txt
    mono_crash.*

    # Builds
    *.apk
    *.aab
    *.unitypackage
    *.unitypackage.meta
    *.app

    # Crashlytics generated
    crashlytics-build.properties

    # Addressables
    /ServerData/
    /[Aa]ssets/[Aa]ddressable[Aa]ssets[Dd]ata/*/*.bin*
    /[Aa]ssets/AddressableAssetsData/link.xml*
    /[Aa]ssets/Addressables_Temp*
    /[Aa]ssets/[Ss]treamingAssets/aa.meta
    /[Aa]ssets/[Ss]treamingAssets/aa/*

    # Visual Scripting generated files
    /[Aa]ssets/Unity.VisualScripting.Generated/

    # Test scenes (Unity Test Framework)
    /[Aa]ssets/[Ii]nit[Tt]est[Ss]cene*.unity*
    ```

    必要に応じてプロジェクト固有のパターンを追加できますが、デフォルトでほとんどの Unity のユースケースをカバーしています。
  </Step>

  <Step title="Diversion リポジトリを初期化する">
    Diversion デスクトップアプリを開き、Unity プロジェクトフォルダーから新しいリポジトリを作成するか、CLI で初期化します:

    ```bash theme={null}
    cd /path/to/your/unity/project
    dv init
    ```

    Diversion は Unity プロジェクトの構造を自動的に認識し、適切な `.dvignore` パターンを含めて必要なファイルの追跡を開始します。

    <Note>
      リポジトリ作成の詳細な手順については、[クイックスタートガイド](/ja/quickstart) または [Diversion を使い始める](/ja/basic/start-using-diversion) を参照してください。
    </Note>
  </Step>

  <Step title="最初のコミットを行う">
    初期化後、Unity プロジェクトをコミットします:

    ```bash theme={null}
    dv commit -m "Initial Unity project setup"
    ```

    覚えておいてください: Diversion では、このコマンド 1 つですべてを処理します。add、commit、push を個別に実行する必要はありません！

    <Note>
      コミットや Diversion の自動同期ワークフローについては、[変更をどう扱うか](/ja/basic/what-to-do-with-your-changes) で詳しく解説しています。
    </Note>
  </Step>
</Steps>

## Unity と Diversion の必須ワークフロー

### メタファイルの管理

<Card title="重要なルール" icon="exclamation" iconType="duotone" color="#ca8b04">
  メタファイルは、必ず対応するアセットと一緒にコミットしてください。メタファイルが欠落すると、アセットの参照が壊れ、チームでエラーが発生します。
</Card>

Unity はすべてのアセットに対して `.meta` ファイルを生成し、次のような重要な情報を保持します:

* **GUID**（グローバルに一意な識別子）: アセット参照に使用
* インポート設定と構成
* プラットフォーム固有の設定

**ベストプラクティス:**

* 新しいアセットを追加する際は、アセットとその `.meta` ファイルの両方を一緒にコミットしてください
* スクリプト参照の欠落や壊れたプレハブが見られる場合は、メタファイルが正しく同期されているか確認してください
* Unity 以外でメタファイルを手動で編集・削除しないでください

### ファイル操作

<Card title="重要" icon="triangle-exclamation" iconType="duotone" color="#ca8b04">
  ファイルシステム操作（移動、名前変更、複製、削除）は必ず Unity Editor で行い、OS のファイルエクスプローラーからは行わないでください。
</Card>

Unity がファイルを移動または名前変更するとき、次の処理を行います:

* すべての内部参照を自動的に更新
* メタファイル内の GUID 接続を維持
* プロジェクトの整合性を保つ

**正しいワークフロー:**

1. Unity Editor を開く
2. Project ウィンドウでアセットの名前変更・移動・削除を行う
3. プロジェクトを保存する（`Ctrl+S` または `Cmd+S`）
4. Diversion で変更をコミットする

## シーン管理と競合防止

### Diversion の競合防止機能を活用する

Git とは異なり、Diversion は競合が発生する前に積極的に防止します:

<Steps>
  <Step title="潜在的な競合を確認する">
    シーンを編集する前に、Diversion デスクトップアプリを開いて、ファイルツリーに **感嘆符アイコン**（!）がないか確認してください。これは、他の誰かが同じファイルを現在編集中の場合に警告してくれます。

    <img alt="潜在的な競合警告" style={{width: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} src="https://mintcdn.com/diversion-2/tgHOXPild1lTdU_m/images/branching-and-merging-merge-warning-icon.png?fit=max&auto=format&n=tgHOXPild1lTdU_m&q=85&s=b7ff43301f112a97f209df9ac40005d7" width="468" height="92" data-path="images/branching-and-merging-merge-warning-icon.png" />
  </Step>

  <Step title="チームと連絡を取る">
    潜在的な競合の警告が表示された場合は、変更を加える前にチームメイトと調整してください。Diversion のリアルタイム通知により、互いの作業を妨げるのを避けやすくなります。
  </Step>
</Steps>

### シーン整理のベストプラクティス

<Accordion title="マルチシーンアーキテクチャを活用する">
  大規模なレベルを、加算的にロードされる複数の小さなシーンに分割します:

  ```csharp theme={null}
  // Load scenes additively at runtime
  SceneManager.LoadSceneAsync("Environment", LoadSceneMode.Additive);
  SceneManager.LoadSceneAsync("Lighting", LoadSceneMode.Additive);
  SceneManager.LoadSceneAsync("Gameplay", LoadSceneMode.Additive);
  ```

  利点:

  * 複数のチームメンバーが異なる側面で同時に作業できる
  * シーンが小さい = 競合が少ない
  * 選択的なロードによりパフォーマンスが向上
</Accordion>

<Accordion title="プレハブの活用を最大化する">
  再利用可能なゲームオブジェクトをプレハブに変換します:

  * 同じオブジェクトの異なる構成には **プレハブバリアント** を使用
  * 複雑な階層には **ネストされたプレハブ** を活用
  * プレハブモードを使ってプレハブを分離した状態で編集

  これによりシーンファイルの変更が減り、競合が発生した場合でも解決が容易になります。
</Accordion>

## 日々のワークフローのベストプラクティス

### 1. 一日を正しく始める

Diversion デスクトップアプリを開いて、次のことを行います:

* 前回のセッションから未コミットの変更がないか確認する
* 編集予定のファイルに感嘆符（!）が付いていないか（潜在的な競合）を確認する
* コミット履歴でチームの最近のコミットを確認する

```bash theme={null}
# または CLI でワークスペースの状態を確認する
dv status
```

### 2. 頻繁にコミットする

Diversion の即時同期により、頻繁なコミットは全員に利益をもたらします:

* **新しい機能を作成した後**: 新しいスクリプト、プレハブ、マテリアル
* **シーンの変更後**: レベルデザインの更新やライティングの調整
* **タスクを切り替える前**: 作業を整理し、追跡可能に保つ
* **一日の終わり**: 未コミットの変更を翌日に持ち越さない

### 3. 意味のあるコミットメッセージを書く

良い例:

* "Add player jump mechanic with double-jump support"
* "Update level 3 lighting and post-processing"
* "Fix enemy AI pathfinding in narrow corridors"

避けるべき例:

* "Updated stuff"
* "Bug fix"
* "WIP"

### 4. 大きなアセットを扱う

Diversion は大きなファイルを得意としているため、次のことが可能です:

* **より高品質なアセットを使用**: 圧縮版と一緒に非圧縮のソースファイルも保持
* **複数のテクスチャ解像度を保存**: ファイルサイズを気にせず 4K/8K のテクスチャを維持
* **非圧縮の音声を含める**: WAV/FLAC のマスターと、異なるプラットフォーム向けの圧縮フォーマットを両方保存
* **包括的なアトラスを作成**: VCS の制約なしに、より大きく効率的なテクスチャアトラスを構築
* **バイナリファイルを自由にバージョン管理**: PSD、FBX などの大きなアセットもコードと同じくらい効率的に扱える

## チームでのコラボレーション

### ブランチ戦略

<Steps>
  <Step title="大きな変更にはフィーチャーブランチを使う">
    大きな機能や実験のためにブランチを作成します:

    ```bash theme={null}
    dv branch create feature/new-inventory-system
    ```

    Diversion のブランチは、プロジェクトサイズに関わらず即時かつ軽量です。
  </Step>

  <Step title="分離して作業する">
    メインブランチに影響を与えずに変更を加えます。Diversion の自動同期により、ブランチは常に最新の状態に保たれます。
  </Step>

  <Step title="準備ができたらレビューしてマージする">
    機能が完成しテストを終えたら、Diversion 組み込みのレビュー機能を使用して、マージ前にチームメイトからフィードバックを得ましょう。

    Diversion デスクトップアプリを開いてレビューを作成し、承認されたらブランチをマージします。

    <Note>
      コードレビューとレビューワークフローについては、[レビューのドキュメント](/ja/basic/reviews) で詳しく解説しています。
    </Note>
  </Step>
</Steps>

## よくある問題と解決策

### スクリプト参照の欠落

**問題**: "The associated script cannot be loaded"

**解決策**:

1. スクリプトの `.meta` ファイルがコミットされているか確認する
2. メタファイル内の GUID がプレハブの参照と一致するか確認する
3. 欠落している場合は、元の作成者にメタファイルをコミットしてもらう

### プレハブの接続が壊れる

**問題**: プレハブが切断されているか、欠落していると表示される

**解決策**:

1. Unity 以外でプレハブファイルを変更しない
2. すべてのプレハブ編集はプレハブモードで行う
3. 壊れた場合はプレハブを元に戻し、Unity から変更を再適用する

### シーンの競合

**問題**: 2 人が同じシーンを編集した

**解決策**:

1. Diversion の潜在的競合警告を活用して事前に回避する
2. 発生した場合は連携して手動で変更をマージする
3. シーンをより小さなサブシーンに分割することを検討する

## ベストプラクティスのまとめ

<Card title="やるべきこと" icon="check" iconType="duotone" color="#0b8a42">
  * メタファイルをアセットと一緒にコミットする
  * すべてのファイル操作を Unity Editor で行う
  * シーンを編集する前に潜在的な競合を確認する
  * 明確なメッセージで頻繁にコミットする
  * プレハブとマルチシーンアーキテクチャを使用する
  * テキストシリアライズのためにプロジェクト設定を構成する
</Card>

<Card title="やってはいけないこと" icon="xmark" iconType="duotone" color="#ca2020">
  * メタファイルを手動で削除・編集しない
  * Unity Editor 以外でファイルを移動しない
  * 同じシーンで同時に作業することを避ける
  * Library や Temp フォルダーをコミットしない
  * アセットの GUID を変更しない
  * 競合警告を無視しない
</Card>

## トラブルシューティング

問題が発生した場合は、次の点を確認してください:

1. Unity プロジェクトの設定（Visible Meta Files、Force Text シリアライズ）
2. `.dvignore` ファイルが正しく構成されているか
3. すべてのチームメンバーが同じ Unity バージョンを使っているか
4. メタファイルが追跡・コミットされているか

さらにサポートが必要な場合は、[Diversion Discord](https://discord.gg/diversion?utm_source=docs\&utm_medium=unity-best-practices) または [support@diversion.dev](mailto:support@diversion.dev) までお問い合わせください。