시나리오 리소스 합성

resources/scenario/scenario_*.json은 공통 이벤트, 규칙과 아이템 구성을 extends로 조합할 수 있습니다. 시나리오마다 같은 배열과 아이템 표를 복사하지 말고, 독립적으로 켜고 끌 수 있는 기능은 resources/scenario/extensions/ 아래의 작은 확장 리소스로 분리해 주세요.

기본 형태

다음 시나리오는 표준 월 이벤트와 구매 가능한 전투 특기·유니크 아이템 구성을 함께 사용합니다.

{
    "title": "조합 시나리오",
    "extends": ["extensions/events/standard.json", "extensions/items/buyable-war-special-uniques.json"],
    "startYear": 184,
    "const": {
        "defaultMaxGeneral": 500
    }
}

경로는 현재 리소스 파일을 기준으로 해석합니다. 절대 경로, 시나리오 리소스 루트 밖으로 나가는 ../ 경로와 순환 참조는 거부합니다. 확장 파일도 다른 확장 파일을 extends할 수 있습니다.

합성 규칙

extends 배열을 왼쪽부터 차례로 합성합니다.
마지막에 현재 파일의 값을 적용합니다.
객체는 key별로 재귀 병합합니다.
배열과 문자열·숫자·boolean·null은 뒤 레이어의 값으로 교체합니다.

따라서 const.allItems처럼 객체인 설정은 여러 확장에서 slot 또는 item key를 추가할 수 있습니다. 반대로 events와 availableSpecialWar처럼 순서가 계약인 배열은 암묵적으로 이어 붙이지 않습니다. 배열을 바꾸는 확장이 전체 배열과 순서를 소유하도록 작성해 주세요. 같은 key를 여러 확장이 설정한다면 extends의 뒤쪽 확장이 우선하며, 시나리오 본문이 항상 최종 우선권을 가집니다.

default.json의 능력치·아이콘 기본값은 확장 합성이 끝난 뒤 기존과 같은 파서 단계에서 적용됩니다. parseScenarioDefinition()은 이미 합성된 객체를 정규화하는 함수이므로 파일을 직접 읽는 코드에서는 사용하지 말아 주세요. 실제 설치는 loadScenarioDefinitionById(), Git commit 미리보기는 composeScenarioResource()를 거쳐 같은 합성 규칙을 사용합니다.

제공하는 확장

경로	내용
`extensions/events/classic.json`	초기 core 시나리오 공통 월 이벤트
`extensions/events/standard.json`	역사·가상 시나리오 표준 천통 이벤트
`extensions/events/expanded.json`	후기 이벤트 시나리오의 교역·천통 이벤트
`extensions/initial-events/research.json`	도시 초기화 이벤트
`extensions/initial-events/expanded.json`	전 도시 교역 초기화 이벤트
`extensions/items/buyable-war-special-uniques.json`	구매 가능한 전특과 해당 유니크 아이템 풀

기존 시나리오 70개가 위 확장을 사용합니다. 특히 구매 가능한 전특/유니크 표를 가지던 10개 시나리오는 같은 item 확장 하나를 참조합니다.

검증

확장 파일을 추가하거나 합성 순서를 바꾼 뒤 다음 검사를 실행해 주세요.

pnpm generate:resource-schemas
pnpm validate:resources
pnpm --filter @sammo-ts/game-engine test scenarioComposition.test.ts scenarioLoader.test.ts
pnpm --filter @sammo-ts/gateway-api test scenarioCatalog.test.ts

validate:resources는 하위 extensions/**/*.json도 재귀적으로 검사합니다. scenarioLoader.test.ts는 추적 중인 시나리오 80개를 실제 합성 로더로 모두 읽습니다. 기존 시나리오를 확장으로 이관할 때에는 변경 전 JSON과 합성 결과를 전수 구조 비교하여 이벤트 배열 순서와 const 값이 같은지도 확인해 주세요.

4.0 KiB Raw Blame History

시나리오 리소스 합성

기본 형태

합성 규칙

제공하는 확장

검증

4.0 KiB

Raw Blame History