20-build-domain

Status: ACTIVE
AppliesTo: v10

0. 목적

• 특정 게임이 아니라 도메인/프로토콜이 동적으로 바뀌는 빌드를 표준화한다.
• DomainKey와 ProtocolGroup이 추가될 때마다 빌드 산출물이 자동으로 늘어나는 구조를 정의한다.
• 빌드 입력/설정/산출물 원칙을 명확히 하여 빌더 구현과의 불일치를 제거한다.

1. 적용 범위

적용 대상

• framework-ts/tools/builder/build.js 기반 빌드 전반
• 입력: {buildInputJson} (예: input/input_common.json)
• 설정: {configJson} (예: input/config.json)

비대상

• 런타임 실행 로직
• 에러/로그 표준 (→ skills/devian-tools/21-build-error-reporting/SKILL.md)

2. 용어

3. 빌드 실행

스크립트 실행

bash input/build.sh <buildInputJson>

직접 실행

node framework-ts/tools/builder/build.js <buildInputJson>

• <buildInputJson>은 빌드 입력 JSON 파일 경로 (예: input/input_common.json)
• 빌더는 buildInputJson을 읽고, 그 안의 configPath로 설정 파일을 로드한다.

4. 입력 파일 스펙 (build json)

최상위 필드

domains (map)

{
  "DomainKey": {
    "contractDir": "Domains/Game/contracts",
    "contractFiles": ["*.json"],
    "tableDir": "Domains/Game/tables",
    "tableFiles": ["*.xlsx"]
  }
}

• key는 DomainKey (예: "Game", "Common")
• contractDir, tableDir는 buildInputJsonDir 기준 상대경로

protocols (array)

[
  {
    "group": "Game",
    "protocolDir": "Protocols/Game",
    "protocolFiles": ["C2Game.json", "Game2C.json"]
  }
]

• group은 ProtocolGroup 식별자

5. 설정 파일 스펙 (config.json)

csConfig (C# 출력)

tsConfig (TypeScript 출력)

upmConfig (UPM 패키지)

tableConfig (데이터 출력)

CRITICAL: config.json에 dataConfig 키가 존재하면 빌드가 즉시 FAIL한다 (deprecated). tableConfig의 각 Dir 배열에 대해 해당 데이터 유형이 출력된다.

samplePackages

Hard Rule: samplePackages cannot contain libraries/domains

• samplePackages에는 com.devian.samples만 포함할 수 있다.
• com.devian.foundation 또는 com.devian.domain.* 가 들어가면 FAIL (Generated 덮어쓰기/삭제 위험).
• staticUpmPackages 키는 금지이며 존재 시 FAIL.

6. 산출물 규칙

원칙

• 도메인/프로토콜 추가에 따라 출력이 늘어남 (동적)
• 개별 도메인 고정표 대신 템플릿 기반으로 산출물 경로가 결정됨
• 정확한 디렉토리/파일 배치는 빌더 구현이 SSOT

C# Domain 템플릿

{csConfig.generateDir}/Devian.Domain.{DomainKey}/

TypeScript Domain 템플릿

{tsConfig.generateDir}/devian-domain-{domainKeyLower}/

UPM Domain 템플릿

{upmConfig.sourceDir}/com.devian.domain.{domainKeyLower}/

Protocol 템플릿 (동일 원칙)

C#:  {csConfig.generateDir}/Devian.Protocol.{ProtocolGroup}/
TS:  {tsConfig.generateDir}/devian-protocol-{protocolGroupLower}/
UPM: {upmConfig.sourceDir}/com.devian.protocol.{protocolGroupLower}/

데이터 산출물

일반 테이블 (tableConfig.tableDirs):

{tableDir}/ndjson/{TableName}.json
{tableDir}/pb64/{TableName}.asset

String Table (tableConfig.stringDirs):

{stringDir}/ndjson/{Language}/{TableName}.json
{stringDir}/pb64/{Language}/{TableName}.asset

Sound 데이터 (tableConfig.soundDirs):

{soundDir}/ndjson/{TableName}.json
{soundDir}/pb64/{TableName}.asset

• 복수 타겟 가능 (각 Dir 배열의 모든 경로에 복사)
• 도메인 폴더 미사용: 최종 경로에 {DomainKey} 폴더 없음
• 동일 파일명 충돌 시 빌드 FAIL (조용한 덮어쓰기 금지)

7. Hard Rules

Staging 규칙

• {tempDir}는 staging 전용이며 커밋 금지
• 빌드 완료 후 staging에서 최종 위치로 복사됨

필수 필드 FAIL

Forbidden 필드 FAIL

아래 필드가 존재하면 즉시 FAIL 처리됨:

총 8개 금지 필드. 하나라도 발견되면 빌드가 중단된다.

8. 예시

Game 도메인/프로토콜 예제의 상세 설명은 별도 스킬 문서를 참조한다:

예제 정책: skills/devian-examples/01-policy/SKILL.md

예제 입력 위치:

• devian/input/Domains/Game/contracts/**
• devian/input/Domains/Game/tables/**
• devian/input/Protocols/Game/**

Verification Checklist

1. input/config.json에 samplePackages: ["com.devian.samples"]만 존재한다.
2. input/config.json에 staticUpmPackages 키가 존재하지 않는다 (금지 필드).
3. 빌드 후 framework-cs/upm/com.devian.domain.sound/Runtime/Generated/Sound.g.cs 가 존재한다.
4. 빌드 후 framework-cs/apps/UnityExample/Packages/com.devian.domain.sound/Runtime/Generated/Sound.g.cs 가 존재한다.
5. samplePackages 처리 이후에도 (3), (4)가 삭제되지 않는다.
6. Unity 컴파일 에러 CS0246 (SOUND/VOICE not found) 가 발생하지 않는다.

Verification Checklist (Dependencies)

• framework-cs/upm/**/package.json에서 com.devian.core, com.devian.unity dependency가 0개여야 한다.
• framework-cs/apps/UnityExample/Packages/**/package.json에서도 위 dependency가 0개여야 한다.

9. Reference

빌더 (SSOT)

• framework-ts/tools/builder/build.js

입력/설정 예시

• input/input_common.json — 빌드 입력 예시
• input/config.json — 설정 파일 예시

관련 스킬