맵 모듈 작성완료구현밸런싱미완료

본 문서는 한 런이 진행되는 무대인 맵과 그 위에 얹히는 모듈들이 어떻게 구성되어 인게임을 생성하는지를 정의한다.

이 시스템의 핵심

• 맵은 거대한 단일 씬이 아니라 모듈을 베이스맵 위에 얹어 조립한다 — 위치는 수동 디자인, 내용물은 그룹 데이터로 자동 추첨.
• 모든 내용물 후보는 런 진입 시 1회 확정 — 런 도중 재추첨 없음.
• 탈출 지점은 한 세션에 한 곳만 활성화되며, 시작 지점에서 가장 가까운 후보는 제외된다.

플레이 흐름

flowchart LR
subgraph INIT [런 진입 시 초기화]
  I[MapModule.Initialize]
  MG[MonsterGroup 후보 확정]
  CG[ChestGroup 후보 확정]
  IG[ItemGroup 후보 확정]
end
subgraph RUN [런 중]
  EX[플레이어 탐색]
  LOOT[루팅 · 상자 개봉]
  ESC[탈출 지점 점유]
end
subgraph RESULT [결과]
  OK[탈출 성공]
  FAIL[시간 초과 · 사망]
end

I --> MG & CG & IG
MG & CG & IG --> EX
EX --> LOOT & ESC
ESC -->|n초 점유| OK
EX -->|타이머 만료 · HP 0| FAIL

classDef init fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#4c1d95
classDef run fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f
classDef ok fill:#bbf7d0,stroke:#16a34a,stroke-width:2.5px,color:#14532d
classDef bad fill:#fecaca,stroke:#dc2626,stroke-width:2.5px,color:#7f1d1d
class I,MG,CG,IG init
class EX,LOOT,ESC run
class OK ok
class FAIL bad

핵심 원칙

원칙	규칙	의미
모듈 조립 방식	맵은 베이스맵 + 모듈 단위 조립	맵 구성을 데이터로 제어한다
그룹 = 배치 단위	몹·상자·아이템은 그룹 단위로 묶어 관리	그룹마다 ID·핀·드랍 규칙이 독립적
핀(Pin) = 후보 좌표	스폰 위치는 ModulePin* 트랜스폼으로 사전 지정	위치 디자인과 내용물 데이터가 분리
인게임 진입 시 1회 추첨	모듈 내용물은 진입 시점에 전부 확정	런 도중 재추첨 없음
탈출 지점 1곳	세션당 탈출 모듈 1곳만 활성화	시작 지점 가장 가까운 후보는 제외

1. 맵 계층 구조

코드 기준 4계층으로 정의된다.

Map (전체 맵, 예: Map01)
 └─ MapModule (베이스맵 위에 얹히는 모듈 단위)
      ├─ MonsterGroup (몹 배치 단위)
      │    └─ ModulePinMonster (개별 몹 핀)
      ├─ ItemGroup (낱개 아이템 배치 단위)
      │    └─ ModulePinItem (개별 아이템 핀)
      ├─ ChestGroup (상자 배치 단위)
      │    └─ ModulePinChest (개별 상자 핀)
      └─ ModulePinPlayer (플레이어 시작 위치 핀 — 시작 모듈 한정)

flowchart TD
subgraph L1 [맵 단위]
  M[Map<br/>Map01 등]
end
subgraph L2 [모듈 단위]
  MM[MapModule<br/>맵 위 모듈]
end
subgraph L3 [그룹 단위]
  MG[MonsterGroup]
  IG[ItemGroup]
  CG[ChestGroup]
end
subgraph L4 [핀 좌표]
  PM[ModulePinMonster]
  PI[ModulePinItem]
  PC[ModulePinChest]
end

M --> MM
MM --> MG --> PM
MM --> IG --> PI
MM --> CG --> PC

classDef map fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#075985
classDef module fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#4c1d95
classDef monster fill:#fecaca,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
classDef item fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f
classDef chest fill:#fed7aa,stroke:#ea580c,stroke-width:2px,color:#7c2d12
classDef pin fill:#f1f5f9,stroke:#64748b,stroke-width:1.5px,color:#0f172a
class M map
class MM module
class MG monster
class IG item
class CG chest
class PM,PI,PC pin

2. 모듈 분류

코드(MapModuleType1) 기준 모듈 1차 분류는 7종 (None 제외 6종).

코드	정의	사용
Main	메인 모듈 — 맵의 핵심 구역 단위	BaseCamp, LumberYard, Hamlet 등
Sub	서브 모듈 — 메인 모듈에 포함되는 부속 영역	메인 모듈 내 부분 구역
Monster	몬스터 배치 전용 모듈	몹 그룹 컨테이너
Item	아이템 배치 전용 모듈	낱개 아이템 컨테이너
Chest	상자 배치 전용 모듈	상자 그룹 컨테이너
Escape	탈출 지점 모듈	세션당 1개 활성화

주의

개요 PDF의 모듈 분류(Zone / Fixed / Move + Monster / Chest / Patrol / Item)와 현재 코드 분류(Main / Sub + Monster / Item / Chest / Escape)가 다르다. 본 문서는 현재 코드 상태 기준이다.

3. 현재 운영되는 맵 — Map01

코드(MapType) 기준 현재 정의된 맵은 Map01 하나. Map02는 클래스 파일이 존재하지만 MapType.enum에 미등록 상태.

Map01의 메인 모듈 3종.

메인 모듈	컨셉	몹 그룹 수
BaseCamp	군영·거점	5
LumberYard	벌목장	5
Hamlet	작은 마을	17

상자 그룹: BaseCamp 1개(6핀), LumberYard 1개(3핀), Hamlet 1개(11핀).

참고

몹 그룹 ID 규칙: mg_{스테이지}{지역}{순번}. 예: mg_1101 ~ mg_1105는 1스테이지 1지역(BaseCamp) 1번~5번.

4. 모듈 정의 테이블 (MapModuleTableData)

컬럼	의미
moduleType1	1차 분류 (Main/Sub/Monster/Item/Chest/Escape)
moduleType2	2차 분류 (BaseCamp 등 인스턴스 식별)
monsterGroupIDs	이 모듈에 포함된 몹 그룹 ID 배열
itemGroupIDs	이 모듈에 포함된 아이템 그룹 ID 배열
chestGroupIDs	이 모듈에 포함된 상자 그룹 ID 배열

5. 몬스터 그룹 (MonsterGroupTableData)

한 몹 그룹은 최대 3종의 몹 슬롯을 가진다.

컬럼	의미
groupID	그룹 식별자
isLinked	true면 한 명 어그로 시 그룹 전원 어그로 (추정)
name1, level1, count1	슬롯 1의 몹 ID·레벨·마릿수
name2, level2, count2	슬롯 2
name3, level3, count3	슬롯 3

• count 합이 핀 수보다 많으면 핀 좌표가 부족해진다. 핀 수와 일치하도록 관리한다.
• isLinked true 그룹은 MapModule.GetLinkedMonsters로 어그로 연동 처리된다.

6. 상자 그룹 (ChestGroupTableData)

상자 그룹은 그룹 단위 드랍 규칙을 가진다. 아이템·루팅·드랍 §1.2에서 알고리즘 정의.

주요 컬럼: groupID, count, dropWorthValue, dropEquipKindsValue, dropPartsRateValue, dropMiscKindsValue, dropGradeValue, dropMoneyValue, dropStackCountValue, dropStackCountAlpha, weaponQueryTags, mainPartsQueryTags, subPartsQueryTags, armorQueryTags, miscQueryTags.

7. 아이템 그룹 (ItemGroupTableData)

낱개 아이템 배치용 그룹. 상자 그룹과 동일한 컬럼 구조 (count 없음). ModulePinItem 핀에 배치된다.

8. 존 단위 개수 제어 (PDF 모델)

존(지역)별로 등장할 모듈 종류와 개수를 Min–Max 범위로 정의해 런 진입 시 추첨한다.

Zone	Type	Min	Max
1	Move	2	3
1	Monster	3	5
1	Chest	2	4
1	Item	0	1
1	Patrol	0	2

주의

위 표는 개요 PDF 모델이다. 현재 코드의 MapModuleTableData는 그룹 ID를 직접 명시하는 방식으로 Min–Max 추첨 적용 위치가 미확인 상태다.

9. 베이스맵·배치 규칙

시작 지점

• 시작 지점은 메인 모듈에서 최소 10 유닛(추정) 이상 떨어진 위치.
• StartingZone 모듈이 시작 위치 영역에 대응한다.
• 플레이어 시작 좌표는 ModulePinPlayer 핀에 정의된다.

탈출 지점

• 세션당 탈출 스팟 1곳.
• 시작 지점에서 가장 가까운 탈출 후보는 제외 (의도적 동선 강제).
• MapModuleEscape가 탈출 지점 컨테이너, EscapeInteractable이 상호작용 트리거.

수동 vs 자동

• 모듈 위치·탈출 지점·핀 좌표는 수동 배치.
• 내용물(몹·상자·아이템)은 그룹 데이터로 자동 추첨.

10. 모듈 초기화 흐름

런 시작
  → MapModule.Awake
    → 자식 컴포넌트 수집 (MonsterGroup / ItemGroup / ChestGroup)
  → MapModule.Initialize
    → MonsterGroup.Initialize × N  → 핀 좌표 수집, 몹 생성 데이터 준비
    → ItemGroup.Initialize × N     → 핀 좌표 수집, 후보 추첨, 배치
    → ChestGroup.Initialize × N    → 핀 좌표 수집, 후보 추첨, 상자 배치

이 시점에 모든 그룹이 후보를 확정한 상태가 된다. 이후 루팅 시 등급·수량 보정이 적용된다 (아이템·루팅·드랍 §3).

▶ 탐색과 모듈 밀도 판단

1. 런 진입 직후 플레이어는 StartingZone 근처에 있다. 주변 모듈 배치는 이미 확정되어 있다.
2. BaseCamp 방향으로 이동하면 몹 그룹 5개, 상자 그룹 6핀이 기다리고 있다.
3. Hamlet은 몹 그룹 17개 — 밀도가 높아 전투 부담이 크지만 상자도 11핀으로 가장 많다.
4. 세션 타이머를 보며 어느 지역까지 파밍하고 탈출 지점으로 향할지 루트를 결정한다.

연결 시스템

시스템	연결 지점
런 구조	진입 시 모듈 초기화, 탈출 모듈 1곳 활성화.
아이템·루팅·드랍	그룹 단위 후보 확정, 루팅 시 등급·수량 보정.
몬스터 AI	MonsterGroup.isLinked 어그로 연동.

데이터 시트 매핑

시스템 영역	시트
맵 정의	MapInfoTableSheet
모듈 정의	MapModuleTableSheet
몹 그룹	MonsterGroupTableSheet
상자 그룹	ChestGroupTableSheet
아이템 그룹	ItemGroupTableSheet

열린 질문

• PDF “고정/이동(Fixed/Move)” 운영과 코드 Main/Sub 매핑 — Sub가 이동 모듈에 해당하는가.
• 코드에 별도 Patrol 모듈 없음 — 정찰 루트가 MonsterGroup 내부에 어떻게 표현되는가.
• PDF 존 모듈 관리 테이블의 Min–Max 추첨이 현재 코드에서 적용되는 위치.
• MonsterGroup.isLinked의 정확한 어그로 전파 규칙 (거리·트리거·해제 조건).
• Map02 향후 등록 계획 및 추가 맵 절차.
• 모듈 사이 공간 확보 정확한 기준값.