📔Boilerplate (GPU Instancing)

GPU Instancing 기반 아트워크 시스템

[사용 방법]

1. 이 파일을 복사해서 새 이름으로 저장합니다.
2. 클래스 이름을 파일명과 동일하게 변경합니다.
3. [아트워크 로직] 섹션만 수정해서 새로운 아트워크를 만듭니다.
4. 나머지 섹션([인프라 코드])은 수정하지 않아도 됩니다.

[코드의 기능]

• Scene 에디터에서 즉시 아트워크 미리보기
• 인스펙터 파라미터 변경 시 실시간 반영
• Play 모드에서만 애니메이션 재생 (Scene은 정지)
• GPU Instancing으로 수천 개 오브젝트도 고성능 렌더링
• 렌더 파이프라인 자동 감지 (URP / HDRP / Built-in)

[보일러플레이트 구조]

GenArtBoilerplate
│
├── [인프라 코드] 수정 불필요
│   ├── OnEnable → EnsureResources → Generate → CacheStructureParams
│   ├── OnValidate → QueueGenerate (구조 변경) / Animate(0f) (시각 변경)
│   ├── QueueGenerate → EditorApplication.delayCall → Generate
│   ├── Update → Animate(t) + RenderInstances
│   ├── EnsureResources: 메시·머티리얼 자동 생성
│   ├── RenderInstances: DrawMeshInstanced 1023개 배치 분할
│   └── DetectPipeline: URP/HDRP/Built-in 자동 감지
│
└── [아트워크 로직] 여기만 수정
    ├── Generate() 내부: 인스턴스 배치 공식
    └── Animate() 내부: 매 프레임 위치·색상 계산 공식

📄BoilerplateGPUInstancing.cs

using UnityEngine;
using System.Collections.Generic;

#if UNITY_EDITOR
using UnityEditor; // EditorApplication.delayCall 사용을 위해 에디터 전용으로 임포트
#endif

[ExecuteAlways] // 에디터 모드(Play 전)에서도 Update 등 Unity 이벤트가 호출되게 합니다
public class BoilerplateGPUInstancing : MonoBehaviour
{
    // ============================================================
    // 인스펙터 파라미터
    // Header 어트리뷰트로 인스펙터를 섹션별로 구분합니다.
    // ============================================================

    // ----- 구조 파라미터 ----------------------------------------
    // 이 값들이 바뀌면 오브젝트를 전부 삭제하고 다시 생성합니다.
    // "몇 개를 어디에 놓을 것인가"를 결정하는 파라미터입니다.
    [Header("구조 설정 (변경 시 오브젝트 재생성)")]
    public int gridSize = 20;   // 가로/세로 큐브 개수
    public float spacing = 0.8f; // 큐브 간격
    public float cubeSize = 0.3f; // 큐브 크기
    public int colorSeed = 0;    // 색상 무작위 시드 (같은 시드 = 같은 색상 배치)

    // ----- 애니메이션 파라미터 ----------------------------------
    // 이 값들이 바뀌면 재생성 없이 ApplyAnimation(0f)만 호출합니다.
    // "어떻게 움직이고 어떻게 보일 것인가"를 결정하는 파라미터입니다.
    [Header("애니메이션 설정 (실시간 반영)")]
    public float waveHeight = 2.0f; // 파동 높이
    public float waveSpeed = 1.2f; // 파동 속도 (클수록 빠름)
    public float waveFrequency = 0.8f; // 파동 주파수 (클수록 잘게 파동)

    // ----- 색상 파라미터 ----------------------------------------
    [Header("색상 설정 (실시간 반영)")]
    [Range(0f, 1f)] public float hueBase = 0.55f; // 색상 시작 hue
    [Range(0f, 1f)] public float hueRange = 0.40f; // 큐브 간 hue 분포 범위
    [Range(0f, 1f)] public float saturation = 0.80f; // 채도 (0 = 흑백, 1 = 풀 컬러)
    public float emissionIntensity = 1.0f;  // 발광 강도

    // ----- 재질 설정 --------------------------------------------
    [Header("재질 설정")]
    public Mesh instanceMesh;     // GPU 드로우에 사용할 메시 (null이면 자동 생성)
    public Material instanceMaterial; // GPU 드로우에 사용할 머티리얼 (null이면 자동 생성)

    // ============================================================
    // 내부 데이터 구조
    // ============================================================

    // 인스턴스 하나의 정적 데이터 (Generate 시 한 번만 계산)
    // 애니메이션 루프에서 매 프레임 참조합니다.
    struct InstanceData
    {
        public Vector3 basePos;    // 생성 시 결정된 기준 위치 (Y=0 평면)
        public float hue;        // 생성 시 결정된 고유 색상 (애니메이션 중 변하지 않음)
        public float brightness; // 생성 시 결정된 기본 밝기
    }

    List<InstanceData> _instances = new List<InstanceData>(); // 전체 인스턴스 데이터 목록

    // GPU에 넘길 배열 (Animate에서 매 프레임 갱신, RenderInstances에서 GPU로 전송)
    Matrix4x4[] _matrices;  // 각 인스턴스의 위치/회전/크기 행렬
    Vector4[] _colors;    // 각 인스턴스의 albedo 색상
    Vector4[] _emissions; // 각 인스턴스의 emission 색상

    // DrawMeshInstanced는 한 번 호출에 최대 1023개까지만 처리합니다.
    // 1023개를 초과하면 여러 번 나눠서 호출해야 합니다.
    const int BATCH_SIZE = 1023;

    bool _generated = false; // Generate 완료 여부. false면 Update에서 렌더링 건너뜀

    // 렌더 파이프라인 종류 (OnEnable에서 자동 감지)
    enum RenderPipeline { BuiltIn, URP, HDRP }
    RenderPipeline _pipeline;

    // ============================================================
    // 구조 파라미터 캐시
    // OnValidate에서 "구조 파라미터가 실제로 바뀌었는지" 비교하기 위한 이전 값 저장소.
    // 바뀌지 않은 경우 불필요한 재생성을 막습니다.
    // ============================================================
    int _cachedGridSize;
    float _cachedSpacing;
    float _cachedCubeSize;
    int _cachedColorSeed;

#if UNITY_EDITOR
    // QueueGenerate의 중복 호출 방지 플래그 (에디터 전용)
    bool _generateQueued = false;
#endif

    // ============================================================
    // Unity 이벤트 메서드
    // ============================================================

    // OnEnable: 컴포넌트가 활성화될 때 호출 (씬 로드, 컴포넌트 체크 ON 등)
    void OnEnable()
    {
        _pipeline = DetectPipeline(); // 현재 프로젝트의 렌더 파이프라인을 감지합니다
        EnsureResources();            // 메시와 머티리얼이 없으면 자동 생성합니다
        Generate();                   // 인스턴스 데이터를 생성합니다
        CacheStructureParams();       // 현재 구조 파라미터 값을 캐시에 저장합니다
    }

    // OnValidate: 인스펙터에서 값이 바뀔 때마다 호출
    // 주의: 이 콜백 안에서 SetParent(), CreatePrimitive() 등 씬 그래프를
    //       직접 수정하면 Unity 경고가 발생합니다.
    //       → 씬 그래프 변경이 필요하면 반드시 QueueGenerate()를 사용합니다.
    void OnValidate()
    {
#if UNITY_EDITOR // OnValidate의 QueueGenerate 로직은 에디터에서만 필요합니다
        _pipeline = DetectPipeline();
        EnsureResources();

        if (StructureParamsChanged())
        {
            // 구조 파라미터가 바뀌었을 때
            // → 오브젝트 재생성이 필요하므로 다음 프레임으로 Generate를 예약합니다
            CacheStructureParams();
            QueueGenerate();
        }
        else
        {
            // 애니메이션/색상 파라미터만 바뀌었을 때
            // → 재생성 없이 t=0 상태로 시각적 결과만 즉시 갱신합니다
            Animate(0f);
        }
#endif
    }

#if UNITY_EDITOR
    // QueueGenerate: Generate()를 한 프레임 뒤로 미루어 실행합니다.
    // OnValidate 컨텍스트에서 직접 씬을 수정하면 Unity 내부 직렬화와 충돌하기 때문에
    // EditorApplication.delayCall로 안전한 타이밍에 실행합니다.
    void QueueGenerate()
    {
        if (_generateQueued) return; // 이미 예약되어 있으면 중복 예약하지 않습니다

        _generateQueued = true;

        EditorApplication.delayCall += () => // 다음 에디터 루프 타이밍에 실행
        {
            _generateQueued = false;

            if (this == null) return; // 오브젝트가 삭제된 경우 안전하게 건너뜁니다

            Generate();
        };
    }
#endif

    // Update: 매 프레임 호출
    void Update()
    {
        if (!_generated) return; // 생성이 완료되지 않았으면 건너뜁니다

        if (!Application.isPlaying)
        {
            // 에디터 Scene 뷰: 애니메이션 없이 t=0 정지 상태로만 렌더링합니다
            Animate(0f);
            RenderInstances();
            return;
        }

        // Play 모드: 시간 기반으로 애니메이션 갱신 후 렌더링합니다
        Animate(Time.time * waveSpeed);
        RenderInstances();
    }

    // ============================================================
    // 구조 파라미터 캐시 유틸
    // ============================================================

    // 이전에 캐시해둔 값과 현재 값을 비교합니다.
    // 하나라도 다르면 true를 반환하여 재생성을 트리거합니다.
    bool StructureParamsChanged()
    {
        return gridSize != _cachedGridSize
            || spacing != _cachedSpacing
            || cubeSize != _cachedCubeSize
            || colorSeed != _cachedColorSeed;
    }

    // 현재 구조 파라미터 값을 캐시에 저장합니다.
    void CacheStructureParams()
    {
        _cachedGridSize = gridSize;
        _cachedSpacing = spacing;
        _cachedCubeSize = cubeSize;
        _cachedColorSeed = colorSeed;
    }

    // ============================================================
    // 리소스 초기화
    // 메시와 머티리얼이 인스펙터에서 할당되지 않은 경우 자동으로 생성합니다.
    // ============================================================
    void EnsureResources()
    {
        if (instanceMesh == null)
        {
            // 큐브 메시를 임시 오브젝트에서 추출 후 즉시 삭제합니다
            GameObject temp = GameObject.CreatePrimitive(PrimitiveType.Cube);
            instanceMesh = temp.GetComponent<MeshFilter>().sharedMesh;
            DestroyImmediate(temp); // 씬에 남지 않도록 즉시 삭제
        }

        if (instanceMaterial == null)
        {
            // 프로젝트의 렌더 파이프라인에 맞는 셰이더를 자동으로 찾습니다
            Shader shader =
                Shader.Find("Universal Render Pipeline/Lit") ??
                Shader.Find("HDRP/Lit") ??
                Shader.Find("Standard");

            instanceMaterial = new Material(shader);
            instanceMaterial.enableInstancing = true; // GPU Instancing 반드시 활성화
            instanceMaterial.EnableKeyword("_EMISSION");
            instanceMaterial.globalIlluminationFlags =
                MaterialGlobalIlluminationFlags.RealtimeEmissive;

            Debug.Log("[GenArtBoilerplate] 머티리얼 자동 생성 완료");
        }
    }

    // ============================================================
    // 생성 (GameObject를 만들지 않고 데이터 배열만 구성합니다)
    // GPU Instancing은 GameObject가 필요 없습니다.
    // 위치, 색상 등 데이터만 배열로 준비해서 GPU에 넘깁니다.
    // ============================================================
    void Generate()
    {
        _instances.Clear(); // 이전 데이터를 초기화합니다
        _generated = false; // 생성 완료 플래그를 리셋합니다

        // ---- [아트워크 로직] 여기를 수정하세요 ----
        // 예시: 정사각형 그리드 배치

        Random.InitState(colorSeed); // 시드 고정 → 같은 시드면 항상 동일한 배치 재현

        // 그리드 전체를 로컬 원점(0,0,0) 기준으로 중앙 정렬합니다.
        // offset 없이 배치하면 (0,0,0)~(max,0,max) 범위가 되어 한쪽으로 치우칩니다.
        float offset = (gridSize - 1) * spacing * 0.5f;

        for (int x = 0; x < gridSize; x++)
        {
            for (int z = 0; z < gridSize; z++)
            {
                _instances.Add(new InstanceData
                {
                    // offset을 빼서 그리드 중심이 (0,0,0)이 되게 합니다
                    basePos = new Vector3(x * spacing - offset, 0f, z * spacing - offset),
                    hue = (hueBase + Random.value * hueRange) % 1f, // 큐브마다 고유 색상
                    brightness = Random.Range(0.5f, 1.0f)                  // 큐브마다 기본 밝기
                });
            }
        }
        // ---- [아트워크 로직 끝] ----

        // GPU에 넘길 배열을 인스턴스 수에 맞게 사전 할당합니다
        _matrices = new Matrix4x4[_instances.Count];
        _colors = new Vector4[_instances.Count];
        _emissions = new Vector4[_instances.Count];

        _generated = true; // 생성 완료 → Update에서 렌더링을 허용합니다

        Animate(0f); // 생성 직후 t=0 기준으로 초기 상태를 계산합니다
    }

    // ============================================================
    // 애니메이션 (매 프레임 배열 값을 갱신합니다)
    // t = 0       → Scene 에디터 정지 상태
    // t = Time.time * waveSpeed → Play 모드 애니메이션
    // ============================================================
    void Animate(float t)
    {
        for (int i = 0; i < _instances.Count; i++)
        {
            InstanceData inst = _instances[i];

            // ---- [아트워크 로직] 여기를 수정하세요 ----
            // 예시: X+Z 방향 사인 파동

            // x와 z 좌표의 합으로 사인파를 계산합니다 → 대각선 방향 파동
            float wave = Mathf.Sin(
                (inst.basePos.x + inst.basePos.z) * waveFrequency + t
            ) * waveHeight;

            // normalized: wave 값을 0~1 범위로 변환 (색상/크기 계산에 활용)
            float normalized = (wave / waveHeight + 1f) * 0.5f;

            // 월드 좌표로 변환: 부모 Transform의 위치/회전이 반영됩니다
            Vector3 worldPos = transform.TransformPoint(
                new Vector3(inst.basePos.x, wave, inst.basePos.z)
            );

            // TRS 행렬: Translation(위치) × Rotation(회전) × Scale(크기)
            // GPU는 이 행렬 하나로 인스턴스의 모든 변환을 처리합니다
            _matrices[i] = Matrix4x4.TRS(
                worldPos,
                transform.rotation,
                Vector3.one * cubeSize
            );

            // 고유 hue는 유지, 파동 높이에 따라 밝기만 변조합니다
            float animBrightness = inst.brightness * Mathf.Lerp(0.2f, 1.0f, normalized);
            Color albedo = Color.HSVToRGB(inst.hue, saturation, animBrightness);
            Color emission = Color.HSVToRGB(inst.hue, saturation, normalized)
                                   * emissionIntensity;
            // ---- [아트워크 로직 끝] ----

            // 계산 결과를 GPU 전송용 배열에 저장합니다
            _colors[i] = new Vector4(albedo.r, albedo.g, albedo.b, 1f);
            _emissions[i] = new Vector4(emission.r, emission.g, emission.b, 1f);
        }
    }

    // ============================================================
    // GPU 드로우
    // Graphics.DrawMeshInstanced로 GameObject 없이 메시를 렌더링합니다.
    // 한 번에 최대 1023개 제한이 있으므로 배치로 나눠서 호출합니다.
    // ============================================================
    void RenderInstances()
    {
        if (instanceMesh == null || instanceMaterial == null) return;

        int total = _instances.Count; // 남은 인스턴스 수
        int index = 0;                // 현재 배치의 시작 인덱스

        while (total > 0)
        {
            int batch = Mathf.Min(BATCH_SIZE, total); // 이번 배치 크기 (최대 1023)

            // 배치 크기만큼 임시 배열을 만들고 데이터를 복사합니다
            Matrix4x4[] batchMatrices = new Matrix4x4[batch];
            Vector4[] batchColors = new Vector4[batch];
            Vector4[] batchEmissions = new Vector4[batch];

            System.Array.Copy(_matrices, index, batchMatrices, 0, batch);
            System.Array.Copy(_colors, index, batchColors, 0, batch);
            System.Array.Copy(_emissions, index, batchEmissions, 0, batch);

            // MaterialPropertyBlock: 인스턴스별 색상을 GPU에 전달합니다.
            // 중요: 배치마다 반드시 new로 새 인스턴스를 만들어야 합니다.
            //       _block을 재사용하면 이전 배치 데이터가 간섭을 일으킵니다.
            MaterialPropertyBlock block = new MaterialPropertyBlock();
            block.SetVectorArray("_BaseColor", batchColors);
            block.SetVectorArray("_EmissionColor", batchEmissions);

            // GPU에 드로우 명령을 전달합니다
            // → GameObject 없이 메시를 씬에 렌더링합니다
            Graphics.DrawMeshInstanced(
                instanceMesh,   // 렌더링할 메시
                0,              // 서브메시 인덱스 (단일 메시는 항상 0)
                instanceMaterial,
                batchMatrices,  // 인스턴스별 TRS 행렬 배열
                batch,          // 이번 배치의 인스턴스 수
                block           // 인스턴스별 머티리얼 프로퍼티
            );

            index += batch; // 다음 배치 시작 인덱스로 이동
            total -= batch; // 남은 인스턴스 수 차감
        }
    }

    // ============================================================
    // 렌더 파이프라인 감지
    // 프로젝트 설정을 읽어 URP / HDRP / Built-in을 자동 판별합니다.
    // 셰이더 프로퍼티 이름이 파이프라인마다 다르기 때문에 필요합니다.
    //   URP:     _BaseColor,    _EmissionColor
    //   HDRP:    _BaseColor,    _EmissiveColor
    //   Built-in: _Color,       _EmissionColor
    // ============================================================
    RenderPipeline DetectPipeline()
    {
        var pipeline = UnityEngine.Rendering.GraphicsSettings.currentRenderPipeline;

        if (pipeline == null) return RenderPipeline.BuiltIn; // Built-in은 에셋이 null

        string name = pipeline.GetType().Name;

        if (name.Contains("Universal")) return RenderPipeline.URP;
        if (name.Contains("HighDefinition") || name.Contains("HDRP")) return RenderPipeline.HDRP;

        return RenderPipeline.BuiltIn;
    }
}

---

0. 코드의 설계 구조

이 보일러플레이트는 "아트워크 로직만 교체하면 새로운 작품이 완성" 되는 구조를 목표로 설계되었습니다.

코드는 두 레이어로 명확히 나뉩니다.

레이어	역할	수정 여부
인프라 코드	Unity 이벤트 처리, GPU 드로우, 파이프라인 감지	수정 불필요
아트워크 로직	오브젝트 배치 공식, 애니메이션 공식	이 부분만 수정

---

1. 전체 실행 흐름

[ 컴포넌트 활성화 ]
        │
        ▼
   OnEnable()
   ├─ DetectPipeline()      ← 렌더 파이프라인 감지
   ├─ EnsureResources()     ← 메시 / 머티리얼 자동 생성
   ├─ Generate()            ← 인스턴스 데이터 배열 구성
   │   └─ Animate(0f)       ← 초기 정지 상태 계산
   └─ CacheStructureParams() ← 현재 구조 파라미터 저장

        │
        ▼ (인스펙터 값 변경)

   OnValidate()
   ├─ DetectPipeline
   ├─ EnsureResources
   ├─ StructureParamsChanged ?
        ├─ [ Yes ] → CacheStructureParams → QueueGenerate() → delayCall → Generate()
        └─ [ No ] → Animate(0f) (구조변경에 따른 재생성 없음)

        │
        ▼ (매 프레임)

   Update()
   ├─ generated 확인
   ├─ [Editor 모드] → Animate(0f) + RenderInstances()
   └─ [Play 모드]   → Animate(Time.time * waveSpeed) + RenderInstances()

핵심 포인트: Generate()는 비용이 큰 연산입니다. 구조가 바뀔 때만 호출하고,
구조가 안 바뀌면 기존 데이터를 재사용한 채 시각적인 변화(waveHeight, hueBase 등)를 Animate()만으로 처리합니다.

---

2. 함수별 상세 분석

2-1. OnEnable() — 컴포넌트 진입점

void OnEnable()
{
    _pipeline = DetectPipeline();
    EnsureResources();
    Generate();
    CacheStructureParams();
}

씬 로드, 컴포넌트 활성화, 에디터에서 스크립트 컴파일 재적용 등
컴포넌트가 "켜지는" 모든 상황에서 호출됩니다.

호출 순서가 중요합니다. Generate() 이전에 EnsureResources()가 실행되어야
메시와 머티리얼이 준비된 상태에서 데이터 배열을 구성할 수 있습니다.

---

2-2. DetectPipeline() — 렌더 파이프라인 자동 감지

RenderPipeline DetectPipeline()
{
    var pipeline = UnityEngine.Rendering.GraphicsSettings.currentRenderPipeline;
    if (pipeline == null) return RenderPipeline.BuiltIn;
    string name = pipeline.GetType().Name;
    if (name.Contains("Universal"))    return RenderPipeline.URP;
    if (name.Contains("HighDefinition")) return RenderPipeline.HDRP;
    return RenderPipeline.BuiltIn;
}

URP, HDRP, Built-in은 셰이더 프로퍼티 이름이 다릅니다.

파이프라인	Albedo 프로퍼티	Emission 프로퍼티
URP	_BaseColor	_EmissionColor
HDRP	_BaseColor	_EmissiveColor
Built-in	_Color	_EmissionColor

GraphicsSettings.currentRenderPipeline이 null이면 Built-in입니다.
Built-in은 별도의 Render Pipeline Asset을 사용하지 않기 때문입니다.

---

2-3. EnsureResources() — 메시·머티리얼 자동 생성

void EnsureResources()
{
    if (instanceMesh == null)
    {
        GameObject temp = GameObject.CreatePrimitive(PrimitiveType.Cube);
        instanceMesh = temp.GetComponent<MeshFilter>().sharedMesh;
        DestroyImmediate(temp);
    }
    if (instanceMaterial == null)
    {
        Shader shader =
            Shader.Find("Universal Render Pipeline/Lit") ??
            Shader.Find("HDRP/Lit") ??
            Shader.Find("Standard");
        instanceMaterial = new Material(shader);
        instanceMaterial.enableInstancing = true; // 반드시 true
        instanceMaterial.EnableKeyword("_EMISSION");
    }
}

설계 의도: 인스펙터에서 직접 할당하지 않아도 컴포넌트가 동작하도록 합니다.
GameObject.CreatePrimitive()로 임시 오브젝트를 만들고 sharedMesh만 추출한 뒤
즉시 DestroyImmediate()로 씬에서 제거합니다. 씬 계층에 잔류 오브젝트를 남기지 않습니다.

enableInstancing = true는 GPU Instancing의 필수 조건입니다.
이 플래그가 꺼져 있으면 DrawMeshInstanced()를 호출해도 인스턴싱이 적용되지 않습니다.

---

2-4. Generate() — 인스턴스 데이터 배열 구성

void Generate()
{
    _instances.Clear();
    _generated = false;

    // [아트워크 로직] — 배치 공식
    Random.InitState(colorSeed);
    float offset = (gridSize - 1) * spacing * 0.5f;
    for (int x = 0; x < gridSize; x++)
        for (int z = 0; z < gridSize; z++)
            _instances.Add(new InstanceData { ... });

    // GPU 전송 배열 사전 할당
    _matrices  = new Matrix4x4[_instances.Count];
    _colors    = new Vector4[_instances.Count];
    _emissions = new Vector4[_instances.Count];

    _generated = true;
    Animate(0f);
}

Generate()는 GameObject를 만들지 않습니다.

GPU Instancing은 씬 계층(Hierarchy)에 오브젝트를 등록하지 않습니다.
대신 InstanceData 구조체 배열을 메모리에 구성하고,
이후 Animate()가 이 데이터를 읽어 GPU 전송용 배열(_matrices, _colors)을 채웁니다.

_generated 플래그는 생성이 완료되기 전에 Update()가 렌더링을 시도하는 것을 막는
가드 조건입니다. 이 패턴은 초기화 순서에 의한 NullReferenceException을 예방합니다.

Random.InitState(colorSeed)로 시드를 고정합니다. 동일한 시드 값이면
에디터를 재시작해도 항상 동일한 색상 배치가 재현됩니다.

---

2-5. OnValidate() + QueueGenerate() — 에디터 실시간 반영

void OnValidate()
{
    if (StructureParamsChanged()) {
        CacheStructureParams();
        QueueGenerate();        // → 다음 프레임에 Generate() 실행
    } else {
        Animate(0f);            // → 즉시 시각 갱신
    }
}

void QueueGenerate()
{
    if (_generateQueued) return;
    _generateQueued = true;
    EditorApplication.delayCall += () => {
        _generateQueued = false;
        if (this == null) return;
        Generate();
    };
}

OnValidate()는 인스펙터에서 값이 바뀔 때마다 호출됩니다.
이 콜백 안에서 직접 씬을 수정하면 Unity 내부 직렬화와 충돌합니다.
EditorApplication.delayCall은 현재 프레임의 직렬화 사이클이 끝난 뒤
안전한 타이밍에 콜백을 실행하도록 보장합니다.

QueueGenerate()는 EditorApplication.delayCall을 사용해 Generate()를 한 프레임 뒤로 미룹니다.

_generateQueued 플래그는 인스펙터 슬라이더를 드래그할 때 OnValidate가
수십 번 연속 호출되어도 Generate()가 단 한 번만 예약되도록 보장합니다.

핵심 설계 포인트는 두 가지입니다.

• 중복 예약 방지를 위한 _generateQueued 플래그.
• delay callback 실행 시 this == null 체크.

---

2-6. Animate(float t) — 매 프레임 배열 갱신

void Animate(float t)
{
    for (int i = 0; i < _instances.Count; i++)
    {
        InstanceData inst = _instances[i];

        // [아트워크 로직] — 위치·색상 공식
        float wave = Mathf.Sin(
            (inst.basePos.x + inst.basePos.z) * waveFrequency + t
        ) * waveHeight;

        float normalized = (wave / waveHeight + 1f) * 0.5f;

        Vector3 worldPos = transform.TransformPoint(
            new Vector3(inst.basePos.x, wave, inst.basePos.z)
        );

        _matrices[i]  = Matrix4x4.TRS(worldPos, transform.rotation, Vector3.one * cubeSize);
        _colors[i]    = (Vector4)Color.HSVToRGB(inst.hue, saturation, animBrightness);
        _emissions[i] = (Vector4)(Color.HSVToRGB(inst.hue, saturation, normalized) * emissionIntensity);
    }
}

t = 0f이면 정지 상태(에디터 씬 뷰),
t = Time.time * waveSpeed이면 Play 모드 애니메이션입니다.

Matrix4x4.TRS() 는 Translation × Rotation × Scale 행렬을 한 번에 생성합니다.
GPU는 이 행렬 하나로 인스턴스의 모든 공간 변환을 처리합니다.

transform.TransformPoint() 는 로컬 좌표를 월드 좌표로 변환합니다.
컴포넌트가 붙어 있는 GameObject의 위치/회전이 자동으로 반영됩니다.

normalized 변수는 사인파의 -1 ~ +1 범위를 0 ~ 1로 정규화한 값입니다.
이 값을 색상의 밝기(Value)에 연결하면 파동 높낮이와 색상 밝기가 연동됩니다.

---

2-7. RenderInstances() — GPU 드로우 명령 발행

void RenderInstances()
{
    int total = _instances.Count;
    int index = 0;
    while (total > 0)
    {
        int batch = Mathf.Min(BATCH_SIZE, total); // BATCH_SIZE = 1023

        Matrix4x4[] batchMatrices  = new Matrix4x4[batch];
        Vector4[]   batchColors    = new Vector4[batch];
        Vector4[]   batchEmissions = new Vector4[batch];

        System.Array.Copy(_matrices,  index, batchMatrices,  0, batch);
        System.Array.Copy(_colors,    index, batchColors,    0, batch);
        System.Array.Copy(_emissions, index, batchEmissions, 0, batch);

        MaterialPropertyBlock block = new MaterialPropertyBlock();
        block.SetVectorArray("_BaseColor",     batchColors);
        block.SetVectorArray("_EmissionColor", batchEmissions);

        Graphics.DrawMeshInstanced(
            instanceMesh, 0, instanceMaterial,
            batchMatrices, batch, block
        );

        index += batch;
        total -= batch;
    }
}

Graphics.DrawMeshInstanced()는 GameObject 없이 메시를 렌더링하는 핵심 API입니다.
이 함수 하나로 batch개의 메시를 GPU에 단 한 번의 드로우 콜로 렌더링합니다.

1023 제한의 이유:
DrawMeshInstanced()는 내부적으로 GPU 상수 버퍼(Constant Buffer)를 사용합니다.
플랫폼 공통 최소 보장 상수 버퍼 크기(D3D11 기준 4096 float4 슬롯)와
Unity 내부 오버헤드를 고려한 실질적 상한이 1023입니다.

MaterialPropertyBlock을 배치마다 new로 생성하는 이유:
같은 block 인스턴스를 SetVectorArray()로 덮어쓰면
이전 배치에 대한 드로우 콜이 아직 GPU 큐에 있는 시점에 데이터가 변경될 수 있습니다.
배치마다 새 인스턴스를 만드는 것이 안전합니다.

---

3. 데이터 흐름 요약

Generate()
│
├── InstanceData[] _instances          (정적 데이터 — 배치 후 변하지 않음)
│     ├── basePos  : Vector3           기준 위치 (Y=0 평면)
│     ├── hue      : float             고유 색상
│     └── brightness : float           기본 밝기
│
Animate(t)
│
├── _matrices[]   : Matrix4x4[]        ← TRS 행렬 (위치 + 회전 + 크기)
├── _colors[]     : Vector4[]          ← Albedo 색상
└── _emissions[]  : Vector4[]          ← Emission 색상
│
RenderInstances()
│
└── Graphics.DrawMeshInstanced()       GPU → 화면
      └── MaterialPropertyBlock        인스턴스별 색상 주입

_instances는 Generate()에서 한 번만 구성됩니다.
_matrices, _colors, _emissions는 Animate()가 매 프레임 덮어씁니다.
RenderInstances()는 완성된 배열을 그대로 GPU에 전달합니다.

---

4. [ExecuteAlways]의 의미

[ExecuteAlways]
public class BoilerplateGPUInstancing : MonoBehaviour

기본적으로 Update(), OnEnable() 등 Unity 이벤트는 Play 모드에서만 호출됩니다.
[ExecuteAlways]를 붙이면 에디터 씬 뷰에서도 이벤트가 호출됩니다.

이 보일러플레이트에서는 이 속성 덕분에:

• 씬 뷰를 열자마자 아트워크가 미리보기로 표시됩니다.
• 인스펙터 값을 바꾸면 Play 버튼 없이도 결과가 즉시 업데이트됩니다.

Update() 안에서 Application.isPlaying으로 분기하여
에디터에서는 Animate(0f) (정지),
Play 모드에서는 Animate(Time.time * waveSpeed) (애니메이션)을 선택합니다.

---

5. 최소 보일러플레이트 체크리스트

나만의 GPU Instancing 보일러플레이트를 처음부터 작성할 때 반드시 포함해야 할 항목입니다.

필수 구조

• [ExecuteAlways] 어트리뷰트
• struct InstanceData — 정적 데이터 저장 구조체
• List<InstanceData> _instances — 인스턴스 목록
• Matrix4x4[] _matrices, Vector4[] _colors — GPU 전송 배열
• const int BATCH_SIZE = 1023 — 배치 상한
• bool _generated — 생성 완료 가드 플래그

필수 함수

• OnEnable() → EnsureResources() → Generate() → CacheStructureParams()
• OnValidate() → 구조 변경 여부 분기 → QueueGenerate() or Animate(0f)
• QueueGenerate() → EditorApplication.delayCall 패턴
• Update() → isPlaying 분기 → Animate(t) + RenderInstances()
• EnsureResources() → 메시·머티리얼 null 체크 + 자동 생성
• Generate() → _instances 구성 + 배열 할당 + Animate(0f) 호출
• Animate(float t) → _matrices, _colors 갱신 루프
• RenderInstances() → 1023 배치 분할 while 루프 + DrawMeshInstanced()

아트워크 로직 교체 포인트

함수	교체 내용
Generate()	인스턴스를 몇 개, 어떤 패턴으로 배치할 것인가
Animate(t)	매 프레임 위치·색상을 어떤 수식으로 계산할 것인가

이 두 함수의 수식만 바꾸면 파동, 나선, 노이즈 필드, 어트랙터 등
어떤 아트워크 패턴으로도 확장할 수 있습니다.

---

6. 참고 — 주요 Unity API

API	설명
Graphics.DrawMeshInstanced()	GameObject 없이 GPU 인스턴싱으로 메시 렌더링
MaterialPropertyBlock	머티리얼 복사 없이 인스턴스별 프로퍼티 설정
Matrix4x4.TRS()	Translation·Rotation·Scale 복합 행렬 생성
transform.TransformPoint()	로컬 좌표 → 월드 좌표 변환
EditorApplication.delayCall	에디터 루프 다음 틱에 콜백 예약
GraphicsSettings.currentRenderPipeline	현재 렌더 파이프라인 에셋 반환
Random.InitState(seed)	Unity 내장 난수 시드 초기화