For - Garden

이터널 시티 — 멸종 동물 복원 연구 도시

세로형 모바일 수집형 RPG. 멸종한 DNA를 되살린 호문쿨루스 소녀 RELIC들이 사는 이터널 시티에 유일한 연구원(주인공)이 입주하며 그들을 관리해 나가는 이야기.

소녀전선 스타일의 코어 컨텐츠, 니케 스타일의 세로형 화면, 림버스 컴퍼니 같은 인디 감성을 목표로 한다. 1인 개발로 감당 가능한 범위를 우선한다.

• 세계관 전문: docs/lore.md
• 수집형 RPG로서 비어 있는 축: docs/design-gaps.md
• 다섯 속성 상성과 직업 태그: docs/combat-affinities.md
• 무과금 재화 공급·소비 기준: docs/economy-design.md
• 기간 이벤트의 데이터·서버 경계: docs/event-content.md
• 출시 이후 비동기 방어전 설계: docs/asynchronous-arena.md

현재 상태

코어 전투 루프와 메인 화면의 첫 형태가 돈다.

타이틀(로딩) → 로비 → (출격) → 스테이지 지도 → 파티 편성 → 전투 → 결과

타이틀이 곧 로딩 화면이다. 제목 아래 마름모 다섯 칸이 원화·아이콘·Puppet 묶음을 하나씩 채우고, 다 차면 화면 아무 곳이나 눌러 들어간다.

하단에 탭 세 개가 늘 떠 있다.

• 렐릭: 보유한 렐릭을 훑어본다. 아직 없는 렐릭도 ???로 자리를 남겨 둔다. 상세 정보에서 즐겨찾기와 로비에 세울 애착 렐릭을 따로 정하고, 급여·돌파·각성·유대와 Heart Gem 세 슬롯을 확인한다. 하루 한 번 관찰 인터뷰를 기록하는 관찰 일지도 여기서 연다.
• 로비: 메인 화면. 광장에 애착 렐릭이 서 있고 그 위에 출격 버튼이 얹힌다. 인게임 재화 무역과 일일/주간 임무는 동작하며, 우편·친구·교류는 아직 준비 중이다. 원정의 일일 복원은 UTC 하루 3회까지 즉시 치즈케이크를 지급하는 현재의 최소 일일 콘텐츠다.
• 연구소: 화석(흔한 재화)과 호박석(귀한 재화)으로 렐릭을 발굴한다. 1회 · 10회 뽑기가 있고 10회가 낱개보다 싸다. 뽑기 규칙은 src/core/gacha.ts에 순수 함수로 있고 난수를 밖에서 받는다 — 나중에 서버가 결과를 정하게 되어도 계산식을 그대로 쓸 수 있다. 등급별 확률·픽업, 10연 SR 보장과 배너 그룹별 SSR 100회 천장을 적용한다. 같은 그룹은 천장과 다음 SSR 픽업 확정을 이월한다. 중복은 5단계까지 각성을 올리고 이후에는 DNA 조각이 된다. 현재는 GameApi 인터페이스와 비동기 FakeServer가 재화 검사·차감·난수 결과를 한곳에서 확정하며, 실제 서버가 준비되면 API 구현체만 HTTP 통신으로 교체할 수 있다.

진행 상태는 SaveManager가 버전 있는 JSON으로 localStorage에 저장한다. 수집·편성·클리어, 성장과 유대, 관찰 일지, 대사 완료, 재화·천장, 일일/주간 진행과 구매 제한을 검증하고 구버전 저장을 마이그레이션한다. 아직 계정 서버 저장이나 기기 간 동기화는 없다.

• 스테이지 지도: 세로 게임이므로 진행 경로가 아래에서 위로 뻗는다. 1-1부터 1-5까지 있고, 직전 스테이지를 깨야 다음이 열린다.
• 파티 편성: 위쪽에 이번 전투의 전장을 그대로 축소해 보여준다. 적 진형에서 누가 선봉인지 들어가기 전에 눌러 확인할 수 있고, 내가 고른 렐릭이 어느 자리에 서는지도 함께 보인다. 아래쪽 보유 렐릭 그리드는 짧게 누르면 편성, 꾹 누르면 상세 정보다.
• 전투: 적은 우상단, 아군은 좌하단에 각각 삼각형으로 서서 비스듬히 대치한다. 전방에 선 쪽이 상대를 향해 튀어나온 꼭짓점이다.

임시 아트

public/puppets/에는 현재 역할별 Puppet ZIP 아홉 개가 있다.

• char_001.zip~char_003.zip — 토리카·렉시아·스피나의 로비/정보창용 전신
• charSD_001.zip~charSD_003.zip — 세 렐릭의 전투용 SD
• enemy_001.zip, enemy_002.zip, enemy003.zip — 토비·아모·리파의 전용 적 SD

나머지 플레이 가능 렐릭(도도·스밀라·케찰)은 전용 아트가 생길 때까지 토리카 전신과 SD를 placeholder로 공유하고 src/puppets/tints.ts의 색 필터로 구분한다. 전용 에셋이 연결된 세 아군과 세 적은 placeholder tint를 사용하지 않는다. 전신 placeholder의 tint만 얼굴이 뭉개지지 않도록 흰색 쪽으로 옅게 섞는다.

발끝을 바닥에 맞추는 일은 src/puppets/assets.ts가 맡는다. PuppetCreature는 Phaser Mesh라 원점이 이미지 한가운데인데 이미지에는 투명한 여백이 넓게 붙어 있어서, 좌표를 그대로 넣으면 캐릭터가 공중에 뜬다. 그림이 실제로 있는 영역을 미리 재어 두고 발끝과 가로 중앙을 맞춰 놓는다.

전투 화면 조작

• 상단 전투 칩: 배속은 1 → 2 → 3 → 1로 순환하고, 궁극 자동 발동은 별도로 켜고 끈다.
• 하단 아군 프로필: 체력·궁극기·야성을 함께 표시한다. 궁극기가 준비된 카드를 누르면 즉시 발동하지만, 야성이 100이면 같은 입력이 궁극기 대신 야성 진압으로 바뀐다.

정보창은 src/managers/CharacterInfoManager.ts를 공개 진입점으로 쓰고, src/ui/info.ts의 공용 프리팹이 실제 배치를 전담한다. 도감·편성·스테이지 지도에서 아군과 적의 능력치 · 패시브 · 기본 공격 · 궁극기를 같은 순서로 내 화면마다 정보 형식이 갈라지지 않게 한다.

전투 규칙

src/core/skirmish.ts가 좌표와 시간을 계산하는 6인 실시간 자동 난전이다. 양 팀 세 명이 동시에 이동해 사거리 안의 대상을 자동 기본 공격하고, 기본 공격과 궁극기는 각자의 재사용 간격을 다시 센다. 적은 준비된 궁극기를 자동 사용하며 아군 궁극기는 프로필 입력 또는 자동 궁극기 설정으로 발동한다. 치명타 난수는 코어에 주입하므로 같은 초기 상태·입력·난수열은 다시 재현할 수 있다.

기본 공격과 궁극기는 야성을 쌓는다. 야성 단계가 오를수록 피해가 강해지고 유대 레벨이 높을수록 더 빨리 쌓인다. 100에서도 궁극기를 사용할 수 있지만, 프로필을 누르면 현재 UI 규칙상 진압을 먼저 선택해 게이지를 0으로 비운다. 진압에 기절 같은 추가 불이익은 없다. 개체별 야성 특성 문구는 아직 정보 표기 중심이며 전투 보너스는 공용 규칙을 따른다.

파티 편성에서는 적 속성 분포와 선택한 아군의 유리·불리 매치 수를 확인하거나 자동 배치로 상성 점수가 높은 세 명을 고를 수 있다. 실시간 전투 중에는 1/2/3배속과 자동 궁극기를 각각 독립적으로 전환한다.

불·물·풀·땅·바람은 각자 두 속성에 강하고 두 속성에 약하다. 유리하면 최종 피해 1.25배, 불리하면 0.8배이며 같은 속성은 1배다. 전사·탱커·암살자·지원가는 고정 보정이 없는 특화 태그이고, 자세한 표와 공식은 docs/combat-affinities.md에 둔다.

기술 스택

• Phaser 3 + TypeScript + Vite
• 기준 해상도 1080×1920 (9:16), Phaser.Scale.FIT으로 축소·중앙 정렬
  • 데스크톱의 넓은 창: 좌우 레터박스로 세로 화면이 그대로 축소되어 보인다 (컴퓨터 테스트용)
  • 모바일 기기가 실제로 가로로 눕혀졌을 때만 회전 안내 오버레이가 뜬다 (pointer: coarse + orientation: landscape 조합으로 감지, src/style.css)
• 입력은 Phaser의 pointerdown/pointerup 추상화를 사용한다. 모바일에서는 touchstart/touchend, PC에서는 마우스로 동작하므로 모바일 우선 반응과 개발 편의성을 함께 유지한다.
• PuppetForge (WebGLE)를 puppetforge 패키지로 git 의존성 설치 — 이후 캐릭터 스탠딩/전투용 종이인형 애니메이션을 여기서 가져다 쓴다. 설치 시 prepare 스크립트가 자동으로 dist-lib를 빌드하므로 별도 설정이 필요 없다.

스크립트

npm install       # puppetforge git 의존성도 함께 빌드된다
npm run dev        # 로컬 개발 서버 (컴퓨터 브라우저로 세로 화면 확인)
npm run build      # tsc --noEmit + vite build
npm run build:test # E2E 주입 경로가 열린 test mode 빌드(배포 금지)
npm test           # Vitest (코어 로직)
npm run typecheck
npm run test:e2e:smoke # Playwright — @slow 실시간 완주를 뺀 Chromium 공통 기능
npm run test:e2e:full  # Playwright — @slow와 두 모바일 기기 선별 회귀까지 모두 확인

구동 확인

CI는 두지 않는다. 배포는 Vercel이 맡고, 품질 게이트는 커밋 전에 로컬에서 직접 돌린다.

npm run typecheck && npm test && npm run build
npm run test:e2e:full # 공통 기능과 iPhone 14 / Pixel 7 선별 회귀를 실제로 띄워 본다

Playwright는 실행 전에 test mode 산출물을 직접 만들며, 배포용 npm run build에는 결정론적 전투 초기 상태 주입 창구가 포함되지 않는다. 전투 전체를 실제 시간으로 완주하는 @slow 한 편은 full 실행에서만 돌고, 전투 공식·전멸·충전 검증은 Vitest의 skirmish.test.ts가 맡는다.

e2e는 캔버스가 세로로 렌더링되는지, 탭(터치)으로 씬이 전환되는지, 기기를 가로로 눕히면 회전 안내가 뜨는지를 확인하고 test-results/에 스크린샷을 남긴다. 실제 모바일 기기가 없을 때는 그 스크린샷으로 화면을 확인하면 된다.

배포 (Vercel)

배포는 Vercel의 GitHub 연동이 전담한다. vercel.json에 빌드 설정을 미리 넣어뒀지만, Vercel 쪽 저장소 연결(Import)은 계정 인증이 필요해 아래 절차를 Vercel 대시보드에서 직접 한 번 해야 한다.

1. https://vercel.com/new 에서 GitHub 계정으로 로그인 → Bell7080/For-Garden Import
2. Framework Preset은 Vite로 자동 인식됨 (vercel.json이 있으면 그대로 따른다)
3. 이후로는 main에 push할 때마다 Vercel이 자체적으로 빌드·배포한다 (PR에는 미리보기 배포 URL이 자동으로 달린다).

빌드가 깨진 채로 push하면 Vercel 배포가 그대로 실패한다. 막아 줄 CI가 없으니 위의 품질 게이트는 반드시 커밋 전에 돌린다.

구조

src/
  api/        # 서버 통신 규격(GameApi)과 백엔드 전까지 사용할 비동기 FakeServer
  config/     # 기준 해상도 등 상수
  core/       # 실시간 난전 · 뽑기 · 성장 규칙과 타입. Phaser를 전혀 모른다 (Vitest 대상)
  data/       # 렐릭 · 스테이지 · 배너 정의. 밸런스는 코드가 아니라 여기서 만진다
  state/      # 직렬화 가능한 진행 상태와 localStorage 저장·마이그레이션
  managers/   # 수집 상태 규칙 · 여러 화면에서 재사용하는 캐릭터 정보창 진입점
  puppets/    # PuppetForge 묶음 불러오기와 바닥 맞춤, 임시 색 필터
  scenes/     # Phaser 씬 (그리기와 입력만)
  ui/         # 버튼 · 프로필 카드 · 하단 탭 · 정보창 · 색과 글꼴 토큰
  debug.ts    # E2E가 씬 전환과 전투 상태를 확인하기 위한 window 훅
tests/
  unit/       # Vitest — 전투 규칙
  e2e/        # Playwright — 모바일 화면비 + 화면 흐름

핵심 의존 방향은 scenes → core, scenes → data다. core는 렌더러를 모른다. 획득·재화·보상 확정은 GameApi, 로컬 영속화는 SaveManager 경계를 통과한다.

수집 상태 변경은 RelicCollectionManager를 통해 검증한다. 캐릭터 정보창은 CharacterInfoManager를 통해 열기 때문에 도감·편성·스테이지 지도가 레이아웃을 각자 복제하지 않는다.

애니메이션 재생 안정화

Puppet ZIP 다운로드·파싱은 첫 캐릭터가 나타나는 프레임이 아니라 BootScene에서 미리 끝내고 공용 캐시에 보관한다. 일회성 공격/피격 모션은 개체별 최신 동작 번호를 사용하므로 이전 동작의 idle 복귀 타이머가 새 동작을 중간에 끊지 않는다. Phaser는 60fps를 목표로 프레임 간격을 평활화하고 WebGL이 가능한 브라우저에서는 GPU 렌더링을 사용한다.

다음 단계

• FakeServer를 인증된 계정 서버로 교체해 저장·발굴·재화·보상·구매 제한을 서버 권위로 옮긴다.
• 목표 30종까지 렐릭과 전용 전신·SD·대사·야성 효과를 채우고 placeholder tint를 걷어낸다.
• 경제 목표를 실제 지급처에 연결하고 임무·상점·기간 이벤트를 운영 가능한 데이터와 서버 시각으로 확장한다.
• 우편·친구·프로필을 구현하고, 경제와 이벤트가 안정된 뒤 비동기 방어전을 별도 마일스톤으로 진행한다.
• Google Play 출시 우선, 여지에 따라 iOS도 고려. 웹 빌드가 안정되면 Capacitor 등으로 네이티브 래핑을 검토한다 (지금은 과설계하지 않고 웹 토대만).