Northbound/AGENTS.md

# Northbound Project Guidance

이 파일은 Northbound 프로젝트에서 작업하는 모든 세션이 공유해야 하는 현재 디자인 기준이다. 새로운 기획이나 구현이 아래 방향과 충돌하면 조용히 가정하지 말고 충돌 지점과 대안을 먼저 설명한다. 이후 사용자가 방향을 변경하면 이 문서도 함께 갱신한다.

## Unity Verification Workflow

- Unity 검증을 위해 프로젝트를 임시 폴더나 복제 프로젝트로 복사하지 않는다.
- 현재 프로젝트가 Unity에서 열려 있어 배치 모드 검증을 실행할 수 없으면 우회 검증을 만들지 않는다.
- 검증에 사용자의 확인이나 Unity 창 조작이 필요하면 사용자에게 직접 요청한다.

## Gameplay Data Architecture

- 비용, 시간, 체력, 공격 수치, 행동 정책처럼 여러 개체가 공유하거나 반복 사용하는 설정은 씬 인스턴스와 행동 코드에 중복 저장하지 않는다.
- 공유 설정은 목적에 맞는 재사용 가능한 정의 타입과 ScriptableObject 자산으로 관리하고, 씬 개체는 해당 정의를 참조한다.
- 정적 정의 데이터와 런타임 상태를 분리한다. 예를 들어 건설 비용·전체 시간·완성 프리팹은 정의에, 현재 진행도·비용 지불 여부·일시 정지 상태는 건설 지점 인스턴스에 둔다.
- 개체별 로직은 공통 정의를 소비하되 정의 자체에 특정 씬 개체나 단일 사용처의 상태를 넣지 않는다.
- 프로토타입 기본 도형 표현은 정의의 선택적 폴백으로만 허용하고, 완성·미리보기 프리팹을 연결할 수 있는 구조를 유지한다.
- 새로운 개체 종류를 추가할 때 기존 코드에 수치 분기를 늘리기보다 새 정의 자산을 추가하는 방향을 우선한다.
- 건물의 기준 정보는 `BuildingDefinition`이 소유한다. 건물 ID, 이름, 설명, 최대 체력, 완성·건설 미리보기 프리팹과 프로토타입 표현은 이 정의에 둔다.
- `TowerDefinition`과 `ConstructionDefinition`은 건물 번호나 이름을 복사하지 않고 대상 `BuildingDefinition` SO를 직접 참조한다.
- 타워 기능과 건설 규칙이 함께 사용되는 지점에서는 두 정의가 동일한 `BuildingDefinition`을 참조하는지 검증한다.
- 건물 ID는 저장·네트워크 식별용 영구 번호이며 배열 순서로 사용하거나 한 번 사용한 번호를 다른 건물에 재사용하지 않는다.

## Gameplay Data Architecture

- 비용, 시간, 체력, 공격 수치, 행동 정책처럼 여러 개체가 공유하거나 반복 사용하는 설정은 씬 인스턴스와 행동 코드에 중복 저장하지 않는다.
- 공유 설정은 목적에 맞는 재사용 가능한 정의 타입과 ScriptableObject 자산으로 관리하고, 씬 개체는 해당 정의를 참조한다.
- 정적 정의 데이터와 런타임 상태를 분리한다. 예를 들어 건설 비용·전체 시간·완성 프리팹은 정의에, 현재 진행도·비용 지불 여부·일시 정지 상태는 건설 지점 인스턴스에 둔다.
- 개체별 로직은 공통 정의를 소비하되 정의 자체에 특정 씬 개체나 단일 사용처의 상태를 넣지 않는다.
- 프로토타입 기본 도형 표현은 정의의 선택적 폴백으로만 허용하고, 완성·미리보기 프리팹을 연결할 수 있는 구조를 유지한다.
- 새로운 개체 종류를 추가할 때 기존 코드에 수치 분기를 늘리기보다 새 정의 자산을 추가하는 방향을 우선한다.

## Core Identity

Northbound는 플레이어들이 주력 전투원이 되어 북쪽으로 탐험하고, 크리스탈 거점을 연결해 작전 영역을 확장하며, 정기적으로 남하하는 적에 대응하는 4인 협동 액션 전략 게임이다.

전통적인 타워 디펜스처럼 건물이 전투를 대신하는 게임이 아니다. 핵심 재미는 제한된 인원·시간·마나를 방어, 탐험, 성장, 거점 확보, 포탈 공격 중 어디에 사용할지 계속 판단하는 데 있다.

핵심 질문은 다음과 같다.

> 지금 방어에 남을 것인가, 미래의 성장을 위해 더 북쪽으로 갈 것인가?

## Map and Camera

- 북진하는 세로형 맵 구성을 유지한다.
- 남쪽에는 본진, 북쪽에는 포탈과 최종 목표가 있다.
- 플레이어는 남쪽에서 북쪽으로 확장하고 적은 북쪽에서 남쪽으로 침공한다.
- 필드의 가로 영역 전체가 항상 한 화면에 들어오는 것이 핵심이다.
- 카메라는 주로 세로축으로 이동하며, 플레이어를 화면 아래쪽에 두어 전방을 더 많이 보여준다.
- 시작 지점에서는 남쪽 본진 코어 전체가 보이도록 전방 오프셋을 줄이고, 북진하면서 일반 전방 오프셋으로 부드럽게 전환한다.
- 가로 방향의 위협은 숨기기보다 모두 보여주고, 플레이어가 동시에 모든 위치에 대응할 수 없게 만든다.
- 긴 맵은 빈 이동 공간이 아니라 본진, 첫 확장, 분기, 위험 자원, 포탈 전초, 포탈, 최종 코어 같은 의미 있는 세로 구간으로 나눈다.
- 일반적인 16:9 활용을 이유로 가로 진행형 맵으로 변경하지 않는다.
- 적은 본진, 크리스탈 거점, 포탈, 타워 같은 건물을 관통하지 않는다. 건물 공격은 중심점이 아니라 충돌 표면을 기준으로 사거리와 정지 위치를 계산한다.
- 적은 본진, 크리스탈 거점, 포탈, 타워 같은 건물을 관통하지 않는다. 건물 공격은 중심점이 아니라 충돌 표면을 기준으로 사거리와 정지 위치를 계산한다.

## Player and Tower Roles

플레이어가 주력 전투원이다.

- 정예 및 보스 처치
- 위험 지역 탐험
- 크리스탈 거점 확보
- 특수 위협 해결
- 무너지는 전선 긴급 지원

타워는 플레이어보다 약하며 다음 역할을 맡는다.

- 플레이어가 도착할 때까지 적 지연
- 약한 적 일부 처리
- 시야, 경보, 둔화 제공
- 비어 있는 지역을 잠시 유지

본진과 확보된 크리스탈 거점은 약한 기본 공격 기능을 가진다. 이 기본 방어는 소수의 약한 적을 처리하거나 적을 지연시키는 최소 안전망이며, 집중 웨이브나 정예 위협을 플레이어 없이 해결할 정도로 강하지 않다. 별도의 방어 슬롯과 거점 역할은 이 기본 기능 위에 추가된다.

핵심 원칙:

> 플레이어가 전투에서 승리하고, 타워는 플레이어의 시간과 관심을 대신한다.

플레이어의 기본 전투 스펙은 거점 지원과 준비가 의미 없게 될 정도로 높이지 않는다. 준비 없이도 위협을 직접 해결할 수는 있지만 체력, 마나, 시간 또는 후방 피해 중 하나를 크게 지불해야 한다.

타워만으로 전체 웨이브를 안정적으로 해결하는 전략은 게임 방향과 맞지 않는다.

## Combat Controls

전투 입력은 단순하게 유지하고 실시간 판단을 강조한다.

- 좌클릭: 자원 소모 없는 일반 공격
- 우클릭: 마나 또는 재사용 대기시간을 사용하는 특수 공격
- 이동: 거리 조절, 공격 범위 이탈, 전선 선택
- 별도의 회피, 방어, 패리, 복잡한 콤보 입력은 우선 사용하지 않는다.
- 플레이어, 적, 타워, 본진과 크리스탈 거점의 모든 공격은 공격 주체와 목표 또는 실제 판정 범위를 즉시 알아볼 수 있는 시각 피드백을 제공한다.
- 체력을 가진 모든 개체는 화면에서 현재 체력과 최대 체력을 확인할 수 있는 월드 체력바를 제공한다.

플레이어 이동 속도는 일반 적보다 빠르되, 적을 장시간 안전하게 몰고 다니며 타워나 거점 공격만으로 처리할 수 있을 정도로 높이지 않는다. 초기 프로토타입 기준 이동 속도는 초당 5m로 둔다.

이동을 제외한 플레이어의 모든 행위는 공통 행동 시스템을 사용한다. 각 행동은 이름, 지속시간, `행동 중 이동 가능`, `취소 가능` 여부를 가지며 현재 행동의 설정에 따라 이동과 취소 입력을 허용하거나 차단한다. 한 번에 하나의 행동만 활성화하며 조준 방향 전환은 이동과 별개로 허용한다. 취소 가능한 상호작용의 결과와 비용은 행동 완료 시 적용하여 중도 취소 시 결과가 남지 않게 한다.

건설은 예외적으로 지속되는 월드 과정이다. 최초 착공 시 비용을 지불하고, 플레이어가 건설 행동을 취소하면 부분 건설물과 진행도가 현장에 남는다. 다시 상호작용하면 남은 진행도부터 이어서 건설하며 비용을 다시 지불하지 않는다.

건설은 예외적으로 지속되는 월드 과정이다. 최초 착공 시 비용을 지불하고, 플레이어가 건설 행동을 취소하면 부분 건설물과 진행도가 현장에 남는다. 다시 상호작용하면 남은 진행도부터 이어서 건설하며 비용을 다시 지불하지 않는다.

전투의 깊이는 조작 난도보다 위치, 공격 대상의 우선순위, 특수 공격 사용 시점, 후방 방어와 북진 사이의 판단에서 만든다. 적 공격은 이동만으로 피할 수 있도록 충분히 예고하며 공격 속도 강화로 반응 속도를 과도하게 요구하지 않는다.

## Economy

- 일꾼 유닛과 반복적인 수동 채취는 사용하지 않는 방향을 우선한다.
- 본진 크리스탈 거점은 처음부터 자동으로 작동하며 낮지만 안정적인 기본 마나 수입을 제공한다.
- 시작 자원은 중요한 투자 하나를 선택할 수 있는 정도로 제공한다.
- 기본 경제만으로 최소한의 생존은 가능하지만 빠른 성장을 위해서는 외부 크리스탈 확보가 필요하다.
- 외부 크리스탈은 주변 적을 제거하고 채취 거점을 설치하면 자동으로 공용 마나를 생산한다.
- 추가 인컴 건물을 반복해서 쌓는 구조는 피한다.
- 경제 성장은 새로운 크리스탈 확보와 기존 채취 효율 강화로 제한하는 방향을 우선한다.

## Crystal Outposts and Mana Fields

크리스탈 채취 건물은 단순한 경제 시설이 아니라 팀의 영토와 작전권을 표시하는 전진 거점이다.

기본 기능:

- 마나 자동 생산
- 주변 시야와 공격 경보
- 마나장 생성
- 주변 작전 기능 활성화
- 팀 소유 영역 표시

마나장은 프로토스 파일론처럼 영향력을 제공하지만 자유로운 타워·인컴 건물 도배를 허용하는 공간이 아니다.

권장 제한:

- 크리스탈 하나당 거점 하나
- 거점마다 전략 역할 하나 선택
- 제한된 방어 슬롯 1~2개
- 별도의 추가 인컴 건물 없음
- 자유 배치 장치는 임시적이거나 플레이어 조작을 요구
- 영역 중첩에 생산·화력 보너스를 주지 않음

마나장 강화는 빈 건설 면적을 늘리는 것보다 거점의 작전·지원 범위를 확대해야 한다.

## Outpost Roles

장기적으로 고려하는 역할은 다음과 같다.

- 방어: 보호막, 둔화, 약탈자 지연
- 정찰: 시야 확대, 잠입자·균열 조기 탐지, 웨이브 정보
- 지원: 회복, 정화, 수리, 제한적인 부활
- 공격 지원: 정예·보스 및 포탈 원정 지원

거점은 위협을 자동으로 제거하지 않는다. 적절한 거점은 플레이어가 직접 대응하는 데 드는 시간, 이동, 위험을 줄인다.

## Portal Network

세로형 맵에는 고정된 포탈 부지가 남북 순서로 배치된다. 적 포탈을 파괴한 뒤 같은 부지에 아군 포탈을 건설해 이동 연결망을 북쪽으로 확장한다.

- 포탈 상태는 적 포탈, 폐허, 아군 포탈로 단순화한다.
- 점거, 해킹, 불안정 같은 중간 상태는 사용하지 않는다.
- 아군 포탈이 파괴되면 폐허가 되어 사용할 수 없으며 같은 자리에서 재건할 수 있다.
- 포탈은 맵에 정해진 바로 북쪽·남쪽 인접 포탈하고만 연결된다.
- 플레이어가 포탈을 통과하는 방향에 따라 북쪽 또는 남쪽 인접 포탈로 이동한다.
- 중간 포탈이 파괴되어도 그 너머의 포탈로 연결을 건너뛰지 않는다. 예를 들어 1-2-3 중 2가 파괴되면 1과 3은 연결되지 않는다.
- 포탈망이 끊겨도 모든 지역은 걸어서 오갈 수 있어야 한다.

활성 적 포탈 수는 웨이브 단계와 별개의 `포탈 공명`으로 적의 전투 스펙을 강화한다.

- 웨이브 단계는 적의 수, 구성, 출현 위치를 결정한다.
- 포탈 공명은 적의 체력, 공격력, 제한적인 경직 저항을 강화한다.
- 이동 속도와 공격 속도는 공명으로 강화하지 않는다.
- 포탈 수에 따른 보정은 합연산이며 상한을 둔다.
- 웨이브 시작 시 활성 적 포탈 수를 기록해 해당 웨이브에 적용한다.
- 포탈 수비대와 포탈 본체는 공명 보정을 받지 않아 뒤처진 팀도 회복할 기회를 갖는다.

적 포탈 하나는 적 강화원, 북진 목표, 파괴 후 아군 이동 거점이라는 세 역할을 함께 맡는다. 별도의 적대 둥지나 북진해서 파괴해야 하는 추가 위협 시설은 근시일 프로토타입에 넣지 않는다.

## Wave Threats

거점 역할을 의미 있게 만들기 위해 적은 코어만 향하지 않는다.

- 약탈자: 채취 거점 공격
- 굴착병·잠입자: 후방이나 시야 밖으로 우회
- 공성 괴수: 타워 사거리 밖에서 거점 포격
- 마나 기생체: 생산량과 마나장 축소
- 동시 균열: 여러 거점에 동시에 위기 발생
- 차원 폭풍: 회복과 시설 작동 방해
- 정예 지휘관: 플레이어의 직접 출동 유도

모든 위협은 특정 거점 역할 없이도 플레이어가 직접 해결할 수 있어야 한다. 거점 역할은 하드 카운터가 아니라 대응 효율을 높이는 수단이다.

이 위협들은 우선 웨이브 구성과 적 역할로 구현한다. 별도의 맵 시설을 추가해 북진 목표를 분산하지 않는다. 위협은 충분히 예고하며 예고 없이 거점이나 포탈을 파괴하지 않는다.

## Core Loop

1. 기본 경제가 자동으로 작동한다.
2. 플레이어가 북쪽 미확보 지역을 탐험한다.
3. 적 포탈과 수비대를 직접 전투로 제거한다.
4. 크리스탈 거점을 확보한다.
5. 파괴한 포탈 부지에 아군 포탈을 재건한다.
6. 인접 포탈 연결망과 작전 범위를 북쪽으로 확장한다.
7. 활성 적 포탈 수에 의해 강화된 웨이브에 대응한다.
8. 다음 적 포탈을 파괴할지 후방을 강화할지 결정한다.
9. 최북단 주 포탈 공격 시점을 결정한다.

## Near-Term Prototype

초기 프로토타입의 권장 범위:

- 세로형 맵과 고정 가로폭 카메라
- 플레이어 캐릭터 1종
- 본진, 중간 포탈 2~3개, 최북단 주 포탈
- 크리스탈 3~4개
- 기본 채취 거점
- 방어·정찰 거점
- 적 포탈 파괴, 폐허, 아군 포탈 재건
- 입장 방향에 따른 인접 아군 포탈 이동과 중간 연결 단절
- 활성 적 포탈 수에 따른 포탈 공명
- 기본 타워 1종
- 일반 적, 약탈자, 굴착병, 정예 적
- 90초 웨이브
- 10~15분 테스트 런

검증 기준:

1. 시작 직후 기다리지 않고 의미 있는 선택이 발생하는가?
2. 플레이어가 자발적으로 북진하는가?
3. 타워가 전투를 대신하지 않고 시간을 벌어주는가?
4. 거점 역할에 따라 대응 방식과 동선이 달라지는가?
5. 화면 전체의 좌우 상황을 읽고 우선순위를 판단하는가?
6. 더 전진할지 후방을 안정시킬지 고민하게 되는가?

## Scope Guardrails

핵심 루프가 검증되기 전에는 다음 요소를 우선 구현하지 않는다.

- 많은 영웅과 장비
- 복잡한 제작 조합
- 자유로운 건물 도배
- 여러 종류의 추가 인컴 건물
- 일꾼 개별 관리
- 반복적인 수동 채취
- 수십 단계 타워 업그레이드
- 너무 많은 거점 역할
- 타워만으로 웨이브를 해결하는 전략

서바이벌 노스테일에서는 캐릭터 성장, 빌드 분기, 웨이브 사건과 협동 운영의 영감을 취하되, 콘텐츠 양을 그대로 복제하지 않는다. 먼저 크리스탈을 확보하고 거점 역할을 선택하며, 그 선택 때문에 다음 위협에 대응하는 방식이 달라지는지를 검증한다.