maplecontest/docs/superpowers/specs/2026-06-06-maps-monsters-tiles-design.md

맵 개선: 다양한 preset 몬스터 + 맵별 타일셋 + StS2 배치 설계

• 날짜: 2026-06-06
• 브랜치: feature/maps-batch (기존 맵 작업 이어서)
• 대상: tools/gen-maps.mjs, map/map02.map~map11.map (재생성)

목표

map02~map11 각 맵에서:

1. 다양한 몬스터 2마리를 배치하되, 기존 map01의 4종(StaticMonster/MoveMonster/ChaseMonster/monster-43) 스프라이트를 재사용하지 않고, 공식 맵에서 수확한 다양한 몬스터로 채운다.
2. 몬스터를 Slay the Spire 2 배치(플레이어 좌측, 몬스터 우측 전투 포메이션)로 둔다.
3. 맵마다 다른 타일셋(TileSetRUID)을 적용한다(같은 바닥 지형, 다른 타일 텍스처).
4. 배경은 기존에 수확한 10종(맵별 상이) 유지.

범위

포함

• 공식 맵 import로 몬스터 변형 세트 + 타일셋 RUID 수확
• 생성기에 MONSTER_VARIANTS(수확 변형), TILESETS(타일셋 풀) 반영
• 맵당 서로 다른 몬스터 2종, StS2 우측 배치
• 맵당 다른 TileSetRUID
• map02~map11 재생성

제외 (YAGNI)

• 지형(Tiles/Foothold) 통째 교체 — 타일셋(텍스처)만 교체
• 포털 연결, 카드-전투 로직 연동
• map01 변경

수확 (공식 맵 import 기법)

배경 수확과 동일: maker_import_maplestory_map(id)가 현재 맵을 그 공식 맵으로 교체 → maker_save → map/<current>.map에서 데이터 추출.

• 몬스터 변형 { sprite, stand, hit, die }(RUID): 몬스터가 있는 필드/사냥맵을 import해 몬스터 엔티티의 SpriteRendererComponent.SpriteRUID + StateAnimationComponent.ActionSheet(stand/hit/die)를 추출. ≥12종 distinct 목표. (타운맵은 몬스터 없을 수 있어 필드맵 선택)
• 타일셋 TileSetRUID: import한 맵의 TileMapComponent.TileSetRUID 추출. 10종 distinct (map01의 9dfea380…과 겹치지 않게).

스파이크 선행: 필드맵 1개를 import해 몬스터 엔티티 구조가 {sprite, stand, hit, die} 추출 가능한지 먼저 확인. 구조가 다르면 폴백(아래).

생성기 변경 (tools/gen-maps.mjs)

• MONSTER_VARIANTS = [ {sprite, stand, hit, die}, ... ] — 수확 결과로 채움(≥12종).
• TILESETS = [ ruid, ... ] — 수확한 타일셋 10종.
• buildMap(nn):
  • 몬스터 2마리: MONSTER_VARIANTS에서 서로 다른 2종을 맵 시드로 선택(맵 내 중복 금지). 클론 몬스터 엔티티의 SpriteRUID + ActionSheet를 변형으로 덮어씀. (기존 map01 스프라이트 미사용 보장 — 항상 변형으로 덮어쓰므로)
  • 위치: StS2 배치 — 화면 우측에 2자리 고정(예: Position.x ≈ +3.5, +5.5; y는 map01 몬스터 y값). map01 전투 구도를 기준으로 우측 포메이션.
  • 타일셋: TileMap 엔티티의 TileMapComponent.TileSetRUID.DataId를 TILESETS[(nn-2)%len]로 설정.
  • 배경: 기존 BACKGROUNDS 유지.
• GUID 재발급·경로 치환·SectorConfig 로직은 그대로.

검증

1. 스파이크(map02): reload→play→screenshot + Lua로
   • 몬스터 2마리의 SpriteRUID가 수확 변형과 일치(= map01 4종 아님), 우측 배치
   • TileMap.TileSetRUID가 새 타일셋
   • 화면상 몬스터 외형·타일 텍스처가 바뀌어 보임
2. 전체: 맵별 몬스터 2종 distinct, 타일셋 distinct, 배경 distinct, 엔티티 id 중복 없음
3. Maker 표본 맵 시각 확인

리스크/폴백

• 몬스터 엔티티 구조가 {sprite,stand,hit,die}로 안 맞으면 → SpriteRUID만 교체하고 ActionSheet는 map01 템플릿 유지(최소 시각 변화 보장).
• 타일셋 교체 시 tileIndex 의미 차이로 타일이 어색하면 → 스파이크에서 확인 후 호환 타일셋만 선별하거나 사용자와 상의.
• 수확 시 import는 현재 맵(map02, 재생성 가능)에 적용 → 수확 후 generator로 map02 재생성하여 정리.

산출물/형상관리

• tools/gen-maps.mjs 갱신, map/map02.map~map11.map 재생성을 커밋. 수확 RUID는 문자열만 포함(공식 콘텐츠).