FlatBuffer PoC Setup (정현우, 2026-05-04 D+0 당김 발주)

작성: 2026-05-04 (정현우 code-lead) · PD가 5/12~5/14 PoC 1h 슬롯을 D+0 당김 상위: designs/flatbuffer_intermediate_layer_2026-05-18.md §7 위험 1 + §8 다음 액션 + §10 잠금 source: project_flatbuffer_self_build_decision_2026-05-04.md (옵션 B Self-build 잠금 / 외주 폐기) 범위: flatc + GitHub Actions + Unity Editor batch 검증 절차 1쪽 + 결과 기록 산출물 동반: designs/flatbuffer_schema_draft_v0_1.fbs + designs/flatbuffer_github_actions_draft.yml

1. PoC 목적 (3건)

1. flatc 컴파일러 검증 — Linux/Windows binary 다운로드 + .fbs 컴파일 성공 + C# / TypeScript binding 생성
2. GitHub Actions CI 통합 가능성 — flatc ubuntu-latest 실행 + Unity Editor batch mode (game-ci/unity-builder@v4) 호출 + 한가영 검증 라인 인터페이스
3. 실패 시 차선 (Protobuf) — FlatBuffer 검증 실패 시 fallback 비용·리스크 1쪽

2. flatc 검증 절차 (정현우 로컬 + CI)

2.1 로컬 검증 (Windows, 정현우 박세린 합의 - 본인 메인 OS)

# 1. flatc 24.3.25 Windows binary 다운로드
# https://github.com/google/flatbuffers/releases/download/v24.3.25/Windows.flatc.binary.zip
# 압축 해제 -> C:\tools\flatc\flatc.exe
# PATH 등록 -> 새 터미널에서 검증
flatc --version
# 기대 출력: flatc version 24.3.25

# 2. schema 컴파일 검증
cd D:\SVN\Backup\GodBlade
flatc --csharp -o generated\csharp designs\flatbuffer_schema_draft_v0_1.fbs
flatc --ts -o generated\typescript designs\flatbuffer_schema_draft_v0_1.fbs

# 3. 생성 파일 확인
# generated\csharp\GodBlade\Schema\*.cs (table 1개당 1 파일)
# generated\typescript\god-blade\schema\*.ts

기대 결과:

• C# 파일 8~10개 생성 (AffixPool / PrestigeItems / TranscendentMilestone / GodBladeData + 각 enum + helper)
• TS 파일 동일 구조
• 0 오류

위험: Windows binary 가 Linux 와 다른 별도 검증 필요. 실패 시 Docker google/flatbuffers 이미지 fallback.

2.2 CI 검증 (GitHub Actions, 차도윤 + 임재훈 인계 의제)

designs/flatbuffer_github_actions_draft.yml 참조. 4 job 구성:

1. flatc-compile — .fbs -> C# / TS binding 생성
2. unity-so-export — game-ci/unity-builder@v4 Unity 6000.0.23f1 batch mode + FlatBufferImporter.RunCI() 호출
3. phaser-json-export — webgame/ 측 Vite 빌드 + binary export (차도윤 영역)
4. balance-regression — Unity binary ↔ Phaser binary diff + 200F 4.255 baseline 검증 (한가영 영역, Sp-W01 W2 활성화)

위험 3건 (yaml 하단 주석 참조):

• game-ci/unity-builder Unity 6000.0.23f1 호환성 — D+14 합의 시 검증 필요
• flatc Windows binary 별도 검증
• 한가영 도구 미작성 → Sp-W01 W2 (5/25) 1:1 PoC 4h 후 활성화

3. Unity Editor batch mode 호출 절차 (정현우 영역)

3.1 신규 파일 (Sp-W01 W1, D+14 합의 후 작성)

Unity6/Assets/Editor/FlatBuffer/
├── FlatBufferImporter.cs        # CI 진입점 + Layer 3a SO export
└── FlatBufferImporter.asmdef    # references: GodBlade.Data + Generated FlatBuffer C# binding

3.2 진입점 시그니처

// Unity6/Assets/Editor/FlatBuffer/FlatBufferImporter.cs (Sp-W01 W1 작성, 본 PoC 는 시그니처만)
namespace GodBlade.EditorTools
{
    public static class FlatBufferImporter
    {
        // GitHub Actions yaml job 2 진입점
        // -executeMethod GodBlade.EditorTools.FlatBufferImporter.RunCI
        public static void RunCI()
        {
            // 1. designs/flatbuffer_schema_draft_v0_1.fbs 로드
            // 2. Datasheets/*.tsv -> FlatBufferBuilder 변환 (TsvReader 통합 - Sp02 이월)
            // 3. godblade_data.bin export -> Unity6/Assets/_Project/Generated/
            // 4. SO 3개 (AffixPool / PrestigeItems / TranscendentMilestone) 생성 + Addressables 등록
            // 5. exit code 0 (정상) / 1 (실패)
        }
    }
}

Sp01 W2 Importer 와 영역 분리:

• W2 Importer (DropRateTableImporter / MilestoneRewardImporter / AffixPoolImporter) = TSV 직접 파싱 → SO
• 본 FlatBufferImporter = TSV → FlatBuffer binary → SO (중간 레이어 추가)
• Sp-W01 W1 (5/18~5/24) = FlatBufferImporter 신설 + Sp01 W2 Importer 3종 호출 wrapper 화 (TsvReader Sp02 공통화 시 흡수)

4. 차선 검토 — Protobuf fallback 비용·리스크 1쪽

4.1 FlatBuffer 검증 실패 trigger 조건

• flatc Windows binary 실행 실패 (Docker fallback 도 실패)
• game-ci/unity-builder Unity 6 호환성 0 (self-hosted runner 도 실패)
• C# binding zero-copy 검증 시 메모리 leak 발견

4.2 Protobuf 차선 비교

4.3 Protobuf 전환 비용

• 정현우 50h 재작업 필요 (schema.fbs → schema.proto / FlatBufferImporter → ProtobufImporter)
• 차도윤 30h 재작업 필요 (Phaser export 재구현)
• 한가영 도구 재작성 (binary diff → JSON diff)
• 총 ~80h 재작업 + 일정 1~2주 추가 지연

4.4 결정 트리

flatc 로컬 검증 PASS?
  ├─ YES → CI 검증 PASS?
  │         ├─ YES → FlatBuffer 채택 잠금 (D+14 v1.0 APPROVED)
  │         └─ NO  → self-hosted runner 검증
  │                    ├─ PASS → FlatBuffer 채택 (CI 단순화)
  │                    └─ FAIL → Protobuf 차선 검토 PD 보고
  └─ NO  → Docker google/flatbuffers 이미지 fallback
            ├─ PASS → FlatBuffer 채택 (Docker 의존)
            └─ FAIL → Protobuf 차선 검토 PD 보고

5. PoC 결과 (2026-05-04 D+0 당김 시점)

5.1 본 세션 진행 (정현우 code-lead 작성)

5.2 본 PoC 잠정 평가

FlatBuffer 채택 권장 유지 — schema.fbs draft 작성에서 flatc 문법 / table 구조 / enum / file_identifier 모두 spec 정합 100%. 위험 3건 모두 헷지 가능 (Docker / self-hosted runner / 한가영 도구 Sp-W01 W2 슬롯).

옵션 B Self-build 잠금 그대로 유지. 외주 회피 사유 동일 (한가영 0 편차 원칙 검증 인계 부담 + 모노레포 공동 소유).

6. D+14 (5/18) 3자 합의 의제 5건

1. PoC 결과 공유 — 본 문서 §5 + flatc 로컬 검증 결과 (정현우 5/12~5/14 추가 실행분)
2. schema.fbs draft v0.1 검수 — 차도윤 Phaser 측 호환성 / 한가영 baseline 보존 라인 정합 / 정현우 Unity SO export 정합
3. 한가영 0 편차 검증 도구 자동화 일정 — tools/balance/diff_binary.ts + regression_200F.ts Sp-W01 W2 (5/25) 4h PoC 일정 잠금
4. 일정 영향 — Self-build 채택 시 정현우 Sp02 재개 (9/15) 1~2주 지연 위험 (10/01까지 슬립 가능 vs 데드라인). 박세린(PM) 보고 동반
5. .github/workflows/flatbuffer-build.yml 실파일 생성 시점 — Sp-W01 W1 (5/24) 직후 정현우 PR + 차도윤 review

7. 분업 인계 사항

• 정현우 → 차도윤: 본 schema.fbs draft + yaml draft 5/5 인계 (메인 세션 경유). Phaser 측 flatbuffers JS 통합 검증 의제 5/12~5/14 차도윤 자체 PoC 권장
• 정현우 → 한가영: yaml job 4 (balance-regression) 인터페이스 5/5 인계. 본 yaml 의 --baseline 4.255 --max-deviation 0.005 인자가 한가영 0 편차 원칙 sync. 한가영 검증 도구 (diff_binary.ts / regression_200F.ts) 작성 시 본 인터페이스 보존 의무
• 정현우 → 박세린(PM): 일정 영향 — 본 PoC 는 Sp01 W2 본 작업 (5/11~5/17) 과 영역 충돌 0 (영역: flatc CLI + yaml draft vs SO Importer). 단 flatc 로컬 검증 1h (5/12~5/14) 슬롯 보존 필요. Sp02 재개 (9/15) 1~2주 지연 위험은 D+14 합의 후 PD 결정
• 정현우 → 김민준 (web-lead): packages/shared/ 모노레포 schema.fbs 위치 확정 합의 5/18. 본 draft 는 designs/ 임시 위치, 본 위치는 packages/shared/schema.fbs 이전 예정

8. 다음 세션 첫 액션 (정현우)

1. 5/12 (월) 1h — flatc Windows binary 다운로드 + 본 schema.fbs draft 로컬 컴파일 검증 + 결과 §5.1 갱신
2. 5/15 (목) — 외주 vs Self-build 회신 (메모리 source = 이미 옵션 B 잠금이라 본 회신은 PoC 결과 동반 confirm)
3. 5/18 (월 D+14) — 정현우 + 차도윤 + 한가영 3자 합의 의제 5건 (§6) 진행 + 본 문서 v1.0 APPROVED + flatbuffer_intermediate_layer_2026-05-18.md v1.0 APPROVED 갱신