쿠키런: 킹덤의 전투 데이터, JSON Schema로 검증하고 자동완성하기

쿠키런: 킹덤 전투 콘텐츠는 기획자가 복잡한 조건 분기를 JSON으로 직접 작성하는 구조라, 데이터 정합성 검증이 오랜 과제였다. 유니티 내장 JSON 파서가 잘못된 값을 조용히 무시해 오류가 런타임까지 발견되지 않는 문제를 JSON Schema 도입으로 해결했다. 2023년부터 클라이언트 프로그래머·기획자·QA가 모두 사용하는 편집 시점 검증·자동완성 시스템으로 정착했다.

핵심 포인트

기획자가 테이블 대신 JSON으로 전투 로직을 작성해 빠른 이터레이션이 가능하지만, 스키마 없이는 오류 검출 시점이 런타임으로 늦어진다.
유니티 내장 JSON 파서는 정의되지 않은 필드도 조용히 무시해, 기획자가 오탈자를 입력해도 실행 중 조용히 넘어가는 문제가 있었다.
C# 클래스에 [GenerateSchemaAs] 어트리뷰트를 붙여 JSON Schema를 자동 생성, 코드와 스키마를 단일 소스로 관리한다.
additionalProperties: false 설정으로 정의되지 않은 필드 입력을 편집 시점에 차단한다.
VS Code .vscode/settings.json에 스키마 경로를 등록해 기획자·QA가 별도 툴 없이 자동완성과 실시간 오류 표시를 사용한다.

상세 정리

배경: 전투 콘텐츠는 기획자가 JSON으로 복잡한 조건 분기 로직을 직접 작성한다. 테이블 형식으로 표현하기 어려운 중첩 조건을 유연하게 기술할 수 있다는 장점이 있다.
문제: 유니티 내장 JSON 파서는 스키마 없이 동작해, 오탈자나 잘못된 타입 값도 무시하고 파싱한다. 오류가 QA 단계나 실제 플레이 중에야 발견돼 수정 비용이 크다.
해결 방향: JSON Schema를 도입해 JSON 파일 편집 시점에 타입 오류·필수 필드 누락·미정의 필드를 즉시 검출하도록 전환했다.
스키마 생성 — Contract Resolver: C# 클래스에 [GenerateSchemaAs] 어트리뷰트를 추가해, JSON 직렬화 시 필드명과 타입 정보가 JSON Schema에 자동 반영된다. 코드와 스키마가 단일 소스로 유지된다.
스키마 후처리 — Enum 문자열화: 기본 직렬화는 Enum을 숫자로 출력하지만, 기획자가 의미를 이해할 수 있도록 Schema 후처리로 문자열 값 입력을 받게 변환했다.
스키마 후처리 — 추가 필드 차단: additionalProperties: false를 Schema에 추가해, 정의되지 않은 필드를 입력할 경우 VS Code가 즉시 오류를 표시하도록 했다.
VS Code 연동: .vscode/settings.json에 JSON 파일 패턴과 스키마 파일 경로를 매핑한다. 기획자·QA가 해당 JSON 파일을 열면 자동완성 목록과 실시간 검증이 자동 활성화된다.
적용 결과: 2023년부터 클라이언트 프로그래머·기획자·QA가 공동으로 사용하는 전투 콘텐츠 데이터 작성 도구로 정착, 생산성 향상과 전투 콘텐츠 버그 감소 효과를 확인했다.