unity-csharp-scripting

Unity C# スクリプティングパターン

概要

Unity 開発向けの C# スクリプティングの基本リファレンスです。MonoBehaviour のライフサイクル、物理演算と衝突 API、アニメーションスクリプティング、オーディオ、ナビゲーション、一般的なデザインパターン、シリアル化、ECS/DOTS のコーディングパターンを扱います。

MonoBehaviour のライフサイクル

実行順序

Awake() -> OnEnable() -> Start() -> FixedUpdate() -> Update() -> LateUpdate() -> OnDisable() -> OnDestroy()

メソッド	呼び出されるタイミング	用途
Awake()	オブジェクトのインスタンス生成時に一度（Start より前）	初期化、参照のキャッシュ
OnEnable()	オブジェクトがアクティブになるたび	イベントの購読、状態のリセット
Start()	最初の Update の前に一度（すべての Awake の後）	オブジェクト間の初期化
FixedUpdate()	固定時間間隔（デフォルトは 0.02s）	物理演算、Rigidbody の移動
Update()	毎フレーム	入力、物理演算以外のロジック
LateUpdate()	すべての Update 呼び出しの後	カメラ追従、移動後の調整
OnDisable()	オブジェクトが非アクティブになるとき	イベントの購読解除、状態の保存
OnDestroy()	オブジェクトが破棄されるとき	最終的なクリーンアップ、リソースの解放

主なルール

• 無効なコンポーネントでも Awake は実行されます（ただし、無効な GameObject では実行されません）。
• スクリプト間の Awake/Start の実行順序に依存しないでください。[DefaultExecutionOrder(N)] または Script Execution Order 設定を使用してください。
• シリアライズされたフィールドをエディター上で検証するには OnValidate() を使用してください。

コルーチンと非同期処理

コルーチン

IEnumerator SpawnWaves(int count, float delay)
{
    for (int i = 0; i < count; i++)
    {
        SpawnEnemy();
        yield return new WaitForSeconds(delay);
    }
}
// Start: Coroutine handle = StartCoroutine(SpawnWaves(5, 1f));
// Stop: StopCoroutine(handle); or StopAllCoroutines();

Yield 命令	動作
yield return null	1 フレーム待機
yield return new WaitForSeconds(t)	t 秒待機（timeScale の影響を受けます）
yield return new WaitForSecondsRealtime(t)	スケールされない時間で待機
yield return new WaitForFixedUpdate()	次の FixedUpdate まで待機
yield return new WaitForEndOfFrame()	レンダリング後まで待機
yield return new WaitUntil(() => condition)	条件式が true になるまで待機
yield return StartCoroutine(other)	ネストしたコルーチンの完了まで待機

Async/Await（Unity 6 以降 / UniTask）

Unity 2023+/Unity 6 では Awaitable が組み込まれています。古いバージョンでは UniTask を使用してください。

async Awaitable LoadLevelAsync(string sceneName)
{
    await Awaitable.WaitForSecondsAsync(1f);
    var op = SceneManager.LoadSceneAsync(sceneName);
    while (!op.isDone)
    {
        progressBar.value = op.progress;
        await Awaitable.NextFrameAsync();
    }
}

イベントとデリゲート

イベントパターン（推奨）

// Publisher
public class Health : MonoBehaviour
{
    public event System.Action<float> OnDamaged;  // event keyword prevents external invocation
    public event System.Action OnDeath;

    public void TakeDamage(float amount)
    {
        currentHealth -= amount;
        OnDamaged?.Invoke(amount);
        if (currentHealth <= 0) OnDeath?.Invoke();
    }
}

// Subscriber
void OnEnable() => health.OnDamaged += HandleDamage;
void OnDisable() => health.OnDamaged -= HandleDamage;
void HandleDamage(float amount) => /* react */;

ScriptableObject イベントチャネル

直接参照を使わずにシステム間の依存を切り離します。ScriptableObject アセットとして GameEvent を作成し、発行側から呼び出し、GameEventListener MonoBehaviour を介して購読側からリッスンします。実装の詳細については references/design-patterns.md を参照してください。

物理演算 API クイックリファレンス

Rigidbody の移動（3D）

タスク	メソッド	使用場所
継続的な力	rb.AddForce(dir * force)	FixedUpdate
瞬間的な衝撃	rb.AddForce(dir * force, ForceMode.Impulse)	FixedUpdate
速度を直接設定	rb.linearVelocity = dir * speed	FixedUpdate
キネマティック移動	rb.MovePosition(target)	FixedUpdate
回転	rb.MoveRotation(targetRot)	FixedUpdate

注：Unity 6 では、Rigidbody.velocity は Rigidbody.linearVelocity に名称が変更されています。

レイキャスト

if (Physics.Raycast(origin, direction, out RaycastHit hit, maxDistance, layerMask))
{
    Debug.Log($"Hit {hit.collider.name} at {hit.point}");
}
// Use Physics.RaycastAll or Physics.RaycastNonAlloc for multiple hits
// 2D: Physics2D.Raycast, Physics2D.OverlapCircle, etc.

衝突とトリガーの違い

コールバック	要件	用途
OnCollisionEnter/Stay/Exit	両方に Collider があり、少なくとも一方に Rigidbody があり、isTrigger=false	物理的な衝突
OnTriggerEnter/Stay/Exit	一方の Collider で isTrigger=true になっており、少なくとも一方に Rigidbody がある	エリア、アイテム取得、検出

other.tag == "Enemy" の代わりに、常に CompareTag("Enemy") を使用してください（GC の割り当てを避けられます）。

アニメーションスクリプティング

[RequireComponent(typeof(Animator))]
public class CharacterAnimation : MonoBehaviour
{
    static readonly int SpeedHash = Animator.StringToHash("Speed");
    static readonly int JumpTrigger = Animator.StringToHash("Jump");
    Animator _anim;

    void Awake() => _anim = GetComponent<Animator>();
    void Update()
    {
        _anim.SetFloat(SpeedHash, moveSpeed);
        if (jumped) _anim.SetTrigger(JumpTrigger);
    }
}

フレームごとのハッシュ処理を避けるため、Animator.StringToHash の結果は static readonly フィールドとしてキャッシュしてください。ゲームプレイのタイミングに合わせたコールバック（足音、ヒットフレーム）には Animation Event を使用してください。IK では SetIKPosition/Rotation/Weight を使って OnAnimatorIK(int layerIndex) を実装してください。

オーディオのクイックリファレンス

[RequireComponent(typeof(AudioSource))]
public class SFXPlayer : MonoBehaviour
{
    [SerializeField] AudioClip[] clips;
    AudioSource _source;
    void Awake() => _source = GetComponent<AudioSource>();
    public void PlayRandom() => _source.PlayOneShot(clips[Random.Range(0, clips.Length)]);
}

重なる SFX には AudioSource.PlayOneShot() を使用してください。音量制御には公開パラメーターを設定した AudioMixer を使用してください。状態遷移（戦闘と探索）にはスナップショットを使用してください。

シリアライゼーション

型	シリアライズ	備考
public フィールド	はい	Inspector に表示されます
[SerializeField] private	はい	推奨 — カプセル化を維持します
[HideInInspector] public	はい、非表示	シリアライズされますが、表示されません
[NonSerialized] public	いいえ	シリアライゼーションの対象外にします
プロパティ	いいえ	Unity ではシリアライズされません
ディクショナリ	いいえ	シリアライズ可能なリストを使用して再構築するか、Odin/SerializedDictionary を使用します
インターフェース	いいえ	抽象 ScriptableObject または SerializeReference を使用します

インターフェースや抽象型をポリモーフィックにシリアライズするには、[SerializeReference] を使用します。

一般的なデザインパターン

パターン	使用する場面	アプローチ
シングルトン	グローバルマネージャー（Audio、GameState）	ScriptableObject ベース、または遅延生成する MonoBehaviour
オブザーバー	疎結合な通信	C# イベントまたは SO イベントチャネル
コマンド	入力／元に戻すシステム	コマンドインターフェース + 履歴スタック
ステートマシン	AI、プレイヤーの状態	Enum + switch、またはクラスベースの状態
オブジェクトプール	弾丸、パーティクル、敵	事前インスタンス化した Queue
サービスロケーター	テスト可能なグローバルアクセス	インターフェースをキーにした静的レジストリ

詳しい実装とコード例については、references/design-patterns.md を参照してください。

ECS/DOTS クイックリファレンス

概念	役割
Entity	軽量な ID（MonoBehaviour なし）
IComponentData	エンティティ上の純粋なデータ構造体
SystemBase / ISystem	コンポーネントクエリを処理するロジック
EntityQuery	コンポーネントの組み合わせでエンティティをフィルタリング
Jobs (IJobEntity)	マルチスレッドシステム
Burst Compiler	SIMD 最適化されたネイティブコード

ECS アーキテクチャのパターンと移行ガイダンスについては、references/design-patterns.md を参照してください。

追加リソース

リファレンスファイル

• references/design-patterns.md -- シングルトン、オブザーバー、コマンド、ステートマシン、オブジェクトプール、サービスロケーター、ECS パターンの完全な実装
• references/physics-animation-audio.md -- 詳細な物理設定（2D および 3D）、高度なアニメーション（ブレンドツリー、IK、ルートモーション、Animation Rigging）、オーディオアーキテクチャ