level-design

레벨 구성

레벨을 조우의 순서로 적고, 조우마다 위협도가 의도한 크기인지 계산으로 본다. 목적은 "이 방은 앞 방보다 얼마나 센가", "이 구역의 보스 방은 예산 안인가", "이 처치 수를 단계 시간 안에 해낼 수 있는가", "레벨에 놓은 적이 전투 계산과 재화 흐름의 가정과 같은가", "쉬는 곳 사이가 너무 길지 않은가", "보상이 뜸한 곳은 어디인가"를 감 대신 계산으로 답하는 것이다.

조우는 그 게임이 플레이어를 적과 맞붙이는 단위다. 방, 웨이브, 무리, 시간 구간 어느 것이든 된다. 쉬는 방이나 상점처럼 적이 없는 구간도 조우로 적어 순서에 넣는다.

위협도는 스탯으로 낸 설계 가정이다. 적을 더한 값이므로 적의 조합, 지형, 동시에 몰리는 정도는 반영하지 않는다. 실제 난이도나 재미를 판정하지 않는다.

도구

공용 스킬 studio-data의 studio.py로 한다. 이 스킬과 함께 설치한다. 명령은 게임 프로젝트 폴더에서 Claude Code 설치 기준으로 적었다. Codex는 .agents/skills/…, Windows PowerShell은 python3 대신 py(실행 경로).

명령	하는 일
python3 .claude/skills/studio-data/scripts/studio.py check .	형식·참조 검사, 조우의 위협도와 예산, 전투 단계의 적, 재화 흐름의 처치 수, 단계별 처치 시간
… check . --table levels	조우 표, 단계 표, 페이싱을 적었으면 리듬 표와 구간 표, 재화 흐름에 옮길 처치 수(마크다운). 검사 보고는 그대로 나온다
… view .	레벨 구성 탭: 단계 표, 페이싱 구간, 레벨별 조우, 위협도와 예산 범위

데이터는 data/levels.json 한 파일이다. 형식은 references/levels-format.md. 적은 progression-economy의 원본에서, 위협도의 가중치는 stat-budget의 적 원가에서(없으면 threat_weights), 단계는 combat-balance에서 가져온다. 프로젝트 폴더(check .)로 검사해야 참조를 확인한다. 적이나 전투 계산을 함께 넘기지 않으면 INCOMPLETE다.

절차

1. 레벨을 전투 단계에 잇는다

레벨은 플레이어가 지나가는 한 덩어리다. 구역, 스테이지, 맵이 여기에 해당한다. 전투 계산의 단계와 id가 다르면 combat_stage에 그 단계를 적는다. 한 단계에 레벨이 여럿이면 한 판에 모두 지나는 것으로 센다. 대체 맵(한 판에 그중 하나만 나옴)은 조우의 repeat를 나오는 확률로 나눠 적는다. 레벨이 없는 전투 단계가 남으면 INCOMPLETE다.

라운드로 나뉜 게임은 무엇을 단계로 둘지 먼저 정한다. 기준 장비가 라운드마다 바뀌면(라운드 사이에 사는 게임) 라운드가 단계이고 레벨이다. 장비가 일부 라운드에서만 바뀌어도 그렇다. 막 단위로 잡아 둔 table 곡선은 나누지 말고 라운드의 크기로 다시 잡는다. 그때 앞 라운드와의 비교는 단계 표의 앞 단계 대비로 본다. 기준 장비가 여러 라운드 동안 같으면 묶음(막)을 단계로 두고 라운드를 조우로 적는다. 재화 흐름도 같은 단위로 적어야 처치 수를 옮길 수 있다. 라운드 사이에만 사는 게임은 재화 흐름에 purchase_timing: "stage_end"를 적는다. 구매가 라운드 끝으로 옮겨지고 그 장비는 다음 라운드부터 쓴다. 기존 after는 그대로 두면 된다.

2. 예산을 정한다

조우를 놓기 전에 threat_budget을 정한다. 곡선과 역할 배수는 조우 바깥의 기준에서 가져온다. 조우에 맞춰 곡선이나 배수를 잡으면 모든 조우가 "예산 안"으로 나오고 판정이 뜻을 잃는다. 조우를 놓은 뒤 경고를 없애려고 배수를 고치지 않는다.

• roles: 조우의 역할과 배수. 예를 들어 평범한 방 1, 정예 방 1.2, 숨 고르는 방 0.5. 역할 이름은 게임마다 정한다. "정예 방은 평범한 방보다 얼마나 세야 하는가"는 게임의 의도에서 나온다.
• curve: 단계가 오를수록 평범한 조우가 얼마나 세지는가. 전투 단계의 순서(1부터)를 기준으로 읽는다. 스탯 예산과 같은 linear, exponential을 쓰고, table이면 단계 id별 값을 적는다. 단계를 끼우거나 뺄 수 있으면 순서가 밀리지 않는 table을 쓴다.
• tolerance: 위협도의 허용 오차(기본 0.2). kills_tolerance: 처치 수의 허용 오차(기본 0.2).

곡선의 근거는 둘 중 하나로 잡는다. 사용자에게 확인하고 provenance의 note에 적는다.

• 적 곡선 × 무리 크기. 스탯 예산의 적 곡선에, 평범한 조우에 들어갈 적 수를 곱한다. check의 "평범한 조우의 적 수"가 의도한 무리 크기인지 본다. 스탯 예산이 없으면 적 검사가 내는 구역 평균(구역 1: 일반 5.1)을 적 곡선 대신 쓴다.
• 처치 시간. 평범한 조우를 몇 초에 치우게 할지 정하고, 그 시간에 맞는 조우의 위협도를 시작점으로 삼는다. 조우 표의 처치 시간으로 확인한다. 턴제처럼 공격 속도가 없는 게임은 처치 시간 대신 타수가 나오니 "몇 타에 치우게 할지"로 정한다.

곡선의 출처가 가정이면 check가 "근거가 아닙니다"라는 참고 줄을 낸다. 그때 "예산 안"은 곡선과 맞는다는 뜻일 뿐이다. 입력 중 하나라도 가정이면(무리 크기를 사용자가 의도로 정했으면 그렇다) kind는 assumed로 두고 근거를 note에 적는다. 참고 줄이 남는 것이 맞다. 입력이 모두 확정이고 다른 데이터에서 계산했으면 computed와 source를, 플레이 기록에서 왔으면 measured와 source를 쓴다.

3. 조우를 놓는다

판에서 지나는 순서대로 encounters에 적는다.

• enemies: 한 번 만날 때 동시에 나오는 적 {id: 수}. 무작위로 나오면 평균을 소수로 적는다.
• repeat: 한 판에서 평범하게 이 조우를 만나는 횟수(기본 1). 무작위 방은 평균을 적는다. 위협도에는 곱하지 않고 처치 수와 레벨 위협도에만 곱한다.
• enemy_repeat: 횟수가 조우와 다른 적 {id: 판에서 나오는 횟수}. 보스는 한 번인데 곁의 무리는 다시 차는 조우에 쓴다. 위협도는 동시에 있는 값이라 모두 더하고, 처치 수만 적마다 센다. 일부 횟수에만 나오는 적(열다섯 번 중 두 번 오는 정예)은 이 키로 합치지 않고 조우를 나눈다. 합치면 위협도와 앞 조우 대비가 그 적이 늘 있는 값이 된다.
• role: 예산의 역할.
• intent: 이 조우가 플레이어에게 무엇을 시험하는가. 수치로 설명되지 않는 의도를 남긴다.
• provenance: 이 조우만 출처가 다를 때 적는다. 측정값 레벨 안의 가정 조우는 --fail-on-assumed에서 따로 걸린다. kills_differ가 말하는 출처도 이 값이다.

적이 끊임없이 나오는 게임(서바이버라이크처럼 끝이 없는 시간 구간)은 "한 번 만날 때"가 없다. 한 규칙으로 통일한다. enemies는 화면에 동시에 있는 평균 수, repeat는 그 구간에서 무리가 다시 차는 횟수다. 횟수는 구간 길이 ÷ 다시 차는 주기로 낸다. 주기는 사용자에게 묻는다. 이 값 하나로 처치 수, 수입, 처치 시간 ÷ 길이가 함께 움직인다. 재화 흐름의 kills에서 거꾸로 나눠 정했으면 처치 수 대조는 근거가 되지 못한다. 구간의 누적 수를 enemies에 넣지 않는다. 곡선은 한 조우의 크기에서만 뜻이 있어서, 입도를 섞으면 같은 처치 수가 예산 안과 넘침을 오간다.

끝이 정해진 라운드는 적이 시간차로 나와도 위 규칙을 쓰지 않는다. enemies에 그 라운드의 적 전체를 적고 repeat는 1이다. 라운드 안의 웨이브를 조우로 나누지 않는다. 곡선도 그 크기로 잡는다. 동시 수로 적으면 같은 라운드의 위협도가 절반이 된다. duration은 적이 나오는 시간이나 평균 클리어 시간 중 하나로 정해 통일한다. 적을 다 잡아야 끝나서 길이가 처치 속도로 정해지면 처치 시간 ÷ 길이는 읽지 않는다.

4. 계산하고 읽는다

python3 .claude/skills/studio-data/scripts/studio.py check . --table levels

먼저 단계 표를 읽는다. 예산 판정보다 계획을 바꾸는 답이 여기서 나온다.

• 처치 시간 ÷ 길이: 그 단계의 처치 수를 한 마리씩 잡을 때 드는 시간(전투 계산의 처치 시간 × 처치 수)을 재화 흐름의 단계 길이로 나눈 값이다. 1배를 넘으면 범위 공격이나 관통이 그만큼 메워야 한다는 뜻이다. 단계끼리 비교해 유독 빡빡한 곳을 찾는다. 플레이어 스탯이 바뀌면 이 값도 바뀐다. 공격 속도가 없는 게임은 타수 합과 길이당 타수(0.25타/방)가 나온다. 칸이 비면 참고 줄이 이유를 말한다.
• 평범한 조우의 적 수: 곡선 ÷ 스탯 예산의 적 곡선. 단계가 오를수록 무리가 커지기를 바라는지와 맞는지 본다.
• 앞 조우 대비(조우 표), 앞 단계 대비(단계 표): 앞보다 몇 배 센가. 위협도 합: 그 단계에서 만나는 위협도의 총량(조우 위협도 × 횟수)이다. 앞 단계보다 줄면 참고 줄이 나온다.
• 처치 수 대조(참고 줄): 몇 단계나 맞춰 봤는가. 재화 흐름에 처치 수가 없는 단계는 대조하지 않은 것이다.
• 처치 시간에 "이상"이 붙으면 처치 시간을 모르는 적을 뺀 값이다. 실제로는 더 빡빡하다. 위협도 합이 –이거나 판 전체 위협도 줄이 없으면 빠진 레벨이나 조우가 없는 단계가 있는 것이다. 일부만 더한 값을 내지 않는다.
• 순서가 자유로운 게임(스테이지 선택)은 "앞 단계보다 줄었습니다", 앞 조우 대비, 앞 단계 대비, 판 전체 위협도, 임무를 넘는 보상 구간과 그 경고, 재화 흐름에 없는 등급의 시각을 읽지 않는다. 임무 안의 세기, 임무별 쉬는 곳 구간, 임무 안의 강한 연속은 읽는다. 곡선 값을 일부러 내린 단계에는 이 참고 줄이 나오지 않는다.

경고는 이렇게 처리한다.

• over_budget·under_budget: 조우의 위협도가 곡선 × 역할 배수에서 허용 오차를 넘게 벗어났다. 의도한 조우면 역할을 바꾸거나 이유를 acknowledged에 적는다. 메시지에 단계 순서가 당겨졌다고 나오면 적이 아니라 곡선을 본다. 스탯 예산의 over_budget은 적 하나의 원가를, 이 경고는 조우 하나의 합을 잰다. 이름만 같고 다른 값이다.
• enemy_not_in_stage: 전투 계산이 그 단계에서 재지 않는 적을 놓았다. 앞 구역의 적이 모두 계속 나오면 전투 단계에 zone_rule: "up_to"를, 일부만 이어지면 단계의 enemies 목록을 적는다. 적이 그 구역에서 끝나는 게임에 up_to를 쓰면 끝난 적까지 세어 enemy_unplaced가 난다. 플레이어 행동으로만 나오는 적은 아래 "전투 단계의 적을 바꾸면"을 따른다.
• enemy_unplaced: 전투 계산은 세는데 어떤 조우에도 없는 적이다. 앞 구역에서 끝난 적이면 단계의 enemies 목록으로 뺀다. 조우 밖에서만 나오는 적이면 그 단계의 레벨 하나의 acknowledged에 이유를 적는다.
• kills_differ: 조우로 센 처치 수가 재화 흐름의 처치 가정과 허용 오차를 넘게 다르다. 메시지가 양쪽 출처와 고칠 쪽을 말한다. 측정값이 앞서고, 측정값이 없으면 조우가 원본이다(아래 원본 규칙).
• kills_not_linked: 재화 흐름의 처치 수가 어떤 레벨과도 이어지지 않아 비교하지 못했다. 재화 흐름 단계에 combat_stage를 적거나 전투 단계와 같은 id로 둔다.
• curve_unused_point: table 곡선의 값이 가리키는 전투 단계가 없다. 단계 이름을 바꾼 뒤 남은 값일 수 있다.
• 숫자를 손으로 맞춰 경고를 없애지 않는다. 한 번에 하나만 바꾸고 전·후 표를 남긴다.

전투 단계의 적을 바꾸면 레벨 밖의 결과도 바뀐다. 단계의 enemies나 zone_rule은 simulate의 "정하는 적"과 스탯 예산의 원가 제안에 쓰인다. 바꾼 뒤 simulate와 원가 제안을 다시 보고, 저장해 둔 보고서가 있으면 새로 낸다.

플레이어 행동으로만 나오는 적(놓친 보석이 깨어나는 정예, 선택으로 부르는 증원)은 단계의 적으로 넣지 않는다. 넣으면 그 적이 단계 통과를 정한다. 조우에는 그대로 놓고, 나오는 enemy_not_in_stage와 재화 흐름의 kill_not_in_stage를 acknowledged에 이유와 함께 적는다. 그 구역이 처음인 적은 zone만으로 단계에 들어가므로 단계에 enemies 목록을 적어 뺀다. 그러면 그 적의 처치 시간을 몰라 단계 표에 "이상"이 붙고, simulate의 통과율은 그 적의 위험이 빠진 낙관값이 된다.

5. 페이싱을 본다

조우의 순서가 잡히면 리듬을 본다. 단계의 위협도 합이 맞아도 쉬는 곳이 한쪽에 몰리면 판이 고르지 않다.

표시를 적는다. 쉬는 곳에 rest: true, 보상을 주는 곳에 reward를 적는다. 돈을 내고 사는 구매 시설은 reward가 아니다. 공짜로 받는 것만 보상이다. 플레이어 행동에 달린 보상(정예를 깨워야 나오는 상자)은 repeat에 나오는 비율을 적어 조우를 나누거나 reward를 적지 않는다. 그대로 적으면 없는 판도 끊긴 것으로 읽힌다. 적이 없는 구간은 enemies를 {}로 적는다. 함정처럼 적 없이 드는 소모는 hazard에 위협도로 적는다. 쥐(위협도 5.4) 한 마리 몫의 함정이면 5.4다. 상점이나 제단에서 재화 흐름의 구매가 일어나면 purchases로 잇는다. 시설이 싸움 동안 계속 열려 있으면 at과 open_for로 적는다. 판의 시간을 차지하지 않아서 구역을 넘어도 된다. 회복이 없는 게임은 rest와 max_rest_load를 쓰지 않는다. 숨 고르는 구간은 회복이 아니라서 rest가 아니다. 계속 들어오는 레벨업 보상도 reward로 적지 않는다.

시각을 적는다. 시간이 재미에 들어가는 게임(시간 구간, 라운드)만 적는다. 시각을 모두 적으면 구간은 목록이 아니라 시각 순서로 끊는다. 방을 지나는 게임은 건너뛰어도 된다. 다만 층 중간에 상점이 있으면 구매 시점을 맞추려고 시각을 적는다. 시각이 없으면 단계로만 맞춰 보기 때문이다. 방 시각은 0부터 방 수로 적고, 택일 방은 at을 같게 적어야 층이 늘지 않는다. duration만 적으면 앞 조우에 이어 놓인다. 시각이 정해진 사건은 at을 적는다. 재화 흐름의 단계 길이와 맞춰 보고, 어떤 조우도 차지하지 않는 시간이나 단계 밖 시각을 경고한다. 재화 흐름의 단위가 방이면 시각도 방으로 적는다.

기준을 정한다. pacing의 상한은 예산처럼 조우 바깥에서 가져온다. 조우를 놓은 뒤 경고가 사라지는 값을 고르면 뜻을 잃는다. 사용자에게 묻는다.

• max_rest_load: 쉬는 곳 없이 평범한 조우 몇 개를 버티게 할 것인가. 전투 계산의 버티는 타수와 "평범한 조우에서 몇 대쯤 맞는가"에서 어림한다. 단계마다 값이 다르면 가장 빡빡한 단계로 잡는다.
• max_reward_load: 평범한 조우 몇 개마다 보상을 줄 것인가.
• max_strong_run: 강한 조우를 몇 번까지 잇는가. 강한 조우의 기준은 strong_at이다.
• carry_levels: 레벨 사이에 체력이 이어지면 true로 둔다. 회복이 없는 게임, 성문 체력이 라운드를 넘는 게임이 그렇다. 레벨마다 다시 차거나 임무가 따로인 게임은 두지 않는다. 쉬는 곳 구간과 강한 조우 연속도 이 키로 레벨을 넘는다. 키가 없는데 레벨을 넘으면 상한을 넘는 연속은 참고 줄이 알린다. 보상 구간은 늘 판 끝까지 잇는다. 층을 넘겨 더한 부담은 곡선에 견준 값이라 체력 소모로 읽지 않는다.

읽는다. --table levels의 리듬 표와 구간 표를 본다.

• 세기: 평범한 조우가 1이다. 레벨 안에서 오르내리는 모양을 본다. 세기는 계산값이다. 곡선이 단계별이라 한 층의 방은 예산이 같으므로, 층 안의 상승은 room_low 0.7, room_high 1.3처럼 역할을 나눠 적고 세기로 확인한다.
• 부담: 구간에 쌓이는 평범한 조우 몇 개 분량이다. 구간끼리 견주어 유독 긴 곳을 찾는다. 길이도 함께 본다.
• 길이당 부담: 시간 구간끼리 견준다. 시간을 나누는 조우는 묶음의 값이 행마다 같게 나온다. 끊임없이 나오는 게임의 부담과 연속 횟수는 repeat에 달렸다. 재화 흐름의 kills에서 repeat를 거꾸로 나눠 정하면 무리가 다시 차는 주기가 구간마다 달라지고 이 값이 튄다. 튀면 곡선보다 주기를 먼저 본다.
• 상한을 적지 않으면 표만 나온다. 구간끼리 견주는 것만으로도 쉬는 곳을 옮길 자리가 보인다.

경고는 이렇게 처리한다.

• long_stretch·reward_drought: 조우를 줄이거나 표시를 옮긴다. 의도한 구간이면 레벨의 acknowledged에 {"long_stretch": {"첫 조우~끝 조우": "이유"}}로 적는다. 구간이 시작하는 레벨이고, 이름은 경고의 구간 이름에서 괄호의 레벨 범위는 빼고 적는다. 경고 문장이 그대로 옮길 값을 말한다. 구간의 끝이 바뀌면 확인이 풀려 경고가 돌아온다. 값만 커지면 풀리지 않으므로 확인한 경고 줄의 값을 본다. 상한을 올려 없애지 않는다.
• strong_run: 사이에 약한 조우나 쉬는 곳을 넣는다. 한 조우의 횟수면 횟수를 줄이거나 조우를 나눠 사이에 약한 조우를 넣는다. 보스와 곁의 무리를 한 조우로 적으면 무리가 다시 차는 횟수까지 세므로 의도한 대로면 확인한다. 보스 앞 시험처럼 일부러 잇는 곳이면 같은 모양으로 확인한다.
• time_gap: 적이 없는 구간도 조우로 적는다. 시간을 비운 것이 맞으면 레벨의 acknowledged에 단계 id로 적는다.
• time_outside_stage: 시각이나 재화 흐름의 duration을 맞춘다. 단계 길이의 원본은 재화 흐름이다.
• purchase_off_span: 재화 흐름의 구매가 그 조우의 시각 밖에 일어난다. 상점이 열리기 전에 돈이 모이면 재화 흐름 구매의 after에 그 시각을 수로 적는다. 구매가 늦으면 메시지가 까닭(돈, after, 앞 구매, 단계 끝)을 말한다. 그때도 열려 있는 시설이면 open_for를 적는다.
• 참고 줄의 "쓰이지 않은 확인": acknowledged가 어떤 경고도 덮지 않았다. 코드나 대상의 오타, 이미 사라진 경고, 잘못된 자리다. 자리가 틀렸으면 줄이 적을 곳을 말한다. 재화 흐름 구매에 적은 purchase_off_span처럼 레벨 구성이 내는 경고는 레벨에 적는다.

같은 사실의 원본

한 사실을 여러 파일에 적으므로 어느 쪽이 원본인지 정해 둔다.

사실	원본	맞추는 쪽
단계 id	전투 계산 stages	레벨, 재화 흐름, 판 안 성장의 level_at, 시뮬레이터 설정
어떤 적이 어느 단계에 나오는가	전투 계산의 단계. 적의 zone은 처음 나오는 구역이다	조우의 enemies
처치 수	레벨이 있으면 조우가 처치 수의 원본이다. 측정값이 있으면 측정값이 앞선다	재화 흐름의 kills. --table levels 끝의 값을 옮긴다
단계 길이	재화 흐름의 duration	단계 표의 길이, 조우의 at·duration
구매 시점	재화 흐름의 구매 계획	조우의 purchases가 놓인 시각
단계의 기준 장비	재화 흐름의 구매 계획(사는 것이면)	전투 단계의 player.items. 늦게 사는 장비를 넣으면 gear_before_purchase가 난다

처치 수를 플레이 기록으로 보정하면(calibrate는 재화 흐름의 kills와 비교한다) 조우의 repeat도 그 값에 맞게 다시 본다.

보고

• 곡선의 근거: 무엇에서 가져왔는가. 출처가 가정이면 "예산 안"을 근거로 쓰지 않는다
• 단계 표: 처치 시간 ÷ 길이, 평범한 조우의 적 수, 유독 빡빡하거나 줄어드는 단계
• 레벨별 조우 표: 역할, 횟수, 구성, 위협도, 앞 조우 대비, 예산 범위
• 예산을 벗어난 조우와 이유
• 전투 단계·재화 흐름과 어긋난 적과 처치 수, 처치 수 대조가 몇 단계까지 됐는가
• 페이싱을 적었으면: 구간 표, 가장 긴 구간, 강한 조우 연속, 시각과 구매 대조가 어디까지 됐는가. 기준의 출처가 가정이면 "경고 없음"을 근거로 쓰지 않는다
• 오류·경고 수, INCOMPLETE 여부
• 사용자가 정해야 할 것: 곡선, 역할 배수, 조우의 구성과 횟수, 시간 구간이면 무리가 다시 차는 주기, 조건부로 나오는 적, 페이싱 기준, 체력이 레벨 사이에 이어지는가

한계

• 위협도는 적의 합이다. 조합의 시너지, 지형, 등장 간격은 넣지 않는다. 플레이어의 힘도 보지 않는다. 플레이어와 잇는 값은 처치 시간이다.
• 처치 시간은 단일 대상 기준이다. 범위 공격과 이동 시간은 넣지 않는다. 단위가 초가 아닌 재화 흐름은 비율을 내지 않는다.
• 부담은 곡선에 견준 상대값이다. 플레이어의 체력이나 회복량을 보지 않고, 맞는 비율도 넣지 않는다. 쉬는 곳은 모두 회복하는 것으로 본다. 일부만 회복하는 곳은 그만큼 부담이 남는데 표에 나오지 않는다. rest 없이 reward나 note로 적어 끊지 않는 쪽이 안전하다.
• 갈림길은 구조로 남지 않고 평균만 남는다. 한 전투 단계의 레벨은 모두 지나는 것으로 세므로 경로를 레벨로 나눠도 따로 보이지 않는다. 경로마다 구간을 보려면 레벨 파일 사본에서 한 경로만 남겨 돌린다.
• 보상의 크기는 보지 않는다. reward는 있고 없음만 센다.
• 재화 흐름 단계에 처치 수가 없으면 그 단계는 맞춰 보지 않는다.

예시: studio-data/assets/sample-project/data/levels.json (실제 게임 수치가 아니다).