blub-blub/README.md

# Blub Blub

화면 아래 가장자리에 가로로 깔리는 바닷속 방치형 스트립.
다른 일을 하는 동안 화면 밑에서 조용히 돌아간다. **집을 지어 자리를 만들고, 그 자리에 생물을 들이면**
생물이 알아서 거품을 모은다. 모은 거품으로 바다를 꾸미면 더 빨리 모인다.

창은 화면 폭 전체를 차지하고 높이만 160~300px이다. 작업표시줄은 덮지 않는다.

## 실행

- 게임만: `.\run.ps1`
- 테스트: `.\test.ps1`
- 에디터: Godot 실행 파일로 이 폴더를 연다. 이미 임포트되어 있으면 프로젝트 목록에서 **Blub Blub** 선택

`run.ps1`과 `test.ps1`은 Godot을 `%LOCALAPPDATA%\Programs\Godot`, 바탕화면, 다운로드,
`%ProgramFiles%\Godot`, PATH 순으로 찾는다. 다른 데 있으면 `GODOT_BIN` 환경 변수에 경로를 넣으면 된다.
클론 직후처럼 `.godot`이 없으면 두 스크립트가 먼저 임포트를 한 번 돌린다
(임포트 전에는 `class_name`이 등록되지 않아 스크립트가 통째로 안 뜬다).

## 조작

| 동작 | 방법 |
| --- | --- |
| 물 만지기 | 빈 곳 좌클릭 (거품이 퍼진다 · 거품은 생물이 번다) |
| 층 오가기 | 왼쪽 아래 층 선택기 · 마우스 휠 · ↑↓ 키 |
| 감상 모드 | **F11** 또는 메뉴 · Esc나 F11로 돌아온다 |
| 집 짓기 | 상점 **집** 탭에서 고른 뒤 칸을 클릭 (우클릭·Esc로 취소) |
| 생물 들이기 | 상점 **생물** 탭에서 클릭 — 그 자리에서 바로 들어온다 (빈 자리 필요) |
| 집 옮기기 | 집을 끌어다 다른 칸에 놓기 (공짜 · 살던 생물도 따라간다) |
| 집 헐기 | 집을 끌어서 아래 휴지통에 (절반 환불 · 세입자가 갈 곳이 있어야 한다) |
| 생물 내보내기 | 생물을 끌어서 아래 휴지통에 (절반 환불 · 마지막 한 마리는 안 된다) |
| 상점 열기 | 왼쪽 위 **상점** (패널은 오른쪽에 열린다) |
| 메뉴 | **···** 버튼 또는 물 위 우클릭 |

메뉴: 항상 위에 표시 · 클릭 통과 · 전체화면으로 감상 · **시간** · 높이(낮게/보통/높게) · 위아래 도킹 · 화면 선택(모니터가 여러 대일 때) · 지금 저장 · 처음부터 다시 · 종료

**시간** 하위 메뉴에서 바다의 하루를 정한다 — 실제 시각(기본), 빠르게(하루 5분),
또는 새벽/아침/낮/저녁/밤 한 시각에 멈추기. 고른 값은 저장된다.
**클릭 통과**를 켜면 클릭이 바탕화면으로 지나가고, 안쪽 모서리(84×56px)만 계속 눌린다.
이 모서리를 눌러 메뉴로 돌아와 통과를 끌 수 있다. (아래 도킹이면 오른쪽 위, 위 도킹이면 오른쪽 아래)

## 구조

```
project.godot          창 설정(투명·테두리 없음·항상 위·1:1 픽셀)과 오토로드 등록
run.ps1 / test.ps1     게임 실행 / 스모크 테스트 (find-godot.ps1이 Godot을 찾아준다)
autoload/
  catalog.gd           밸런스 데이터 전부. 아이템 추가는 여기서만.
  day_cycle.gd         실제 시각에 맞춘 하루의 빛 (새벽/아침/낮/저녁/밤)
  game_state.gd        보유 자원·배치 상태와 파생 수치(bps, 아름다움, 아름다움 배율)
  save_manager.gd      저장/불러오기, 30초 자동 저장, 오프라인 보상, 창 위치
scenes/
  main.tscn/.gd        도킹(폭 전체·가장자리 스냅)·클릭 통과·메뉴와 화면 조립
  aquarium/            먼 바다 배경, 격자 바닥, 물빛 셰이더, 물속 오브젝트
  ui/                  왼쪽 위 정보 바, 오른쪽 상점 패널
scripts/
  korean.gd            받침을 보고 을/를·이/가를 고른다
  number_format.gd     1234 -> "1.23K", 경과 시간 표기
  ui_style.gd          UI 색과 스타일박스
tests/smoke.tscn/.gd   경제 로직 스모크 테스트
```

## 게임 루프

1. 바다에 있는 **생물**이 시간에 따라 알아서 **거품**을 모은다. 클릭으로 버는 길은 없다.
   그래서 새로 시작하면 **항아리 집 한 채와 거품돌·구피 한 마리씩**이 이미 있고, 거품 20을 쥐고 시작한다.
2. 생물은 **집**에 산다. 한 채가 3마리를 들이므로, 더 키우려면 먼저 집을 지어야 한다.
   집은 칸을 차지하고 거품을 벌지 않는다. 자리와 **아름다움**을 준다.
3. 생물을 들이면 초당 생산량과 아름다움이 오른다. 비싼 생물일수록 한 마리가 더 번다.
4. 아름다움은 다시 전체 생산량에 `1 + sqrt(아름다움) × 0.02` 배율로 되돌아온다.
   → **꾸미는 것이 곧 성장이다.**
5. 앞 구역을 충분히 꾸미고 거품을 모으면 오른쪽 다음 구역이 열린다.
   얕은 바다 → 산호초 → 켈프 숲 → 심해 → 열수구

## 격자와 배치

바다는 **3/4 부감 격자**다. **한 화면에 한 층**만 담기고, 층마다 36열 × 6행 = 216칸이다.
바닥은 위에서 내려다보지만 그 위에 선 것은 **서 있는 모습**으로 그린다.
러스티의 농장과 같은 방식이고, 완전한 탑다운과는 다르다.

격자 칸을 차지하는 것은 **집뿐이다.** 생물은 칸이 아니라 **집에 산다.**
한 채가 3마리를 들이므로, 한 구역에서 키울 수 있는 수는 그 구역에 지은 집 × 3이다.
그래서 한계가 두 겹으로 걸린다.

```
칸  →  집을 몇 채 지을 수 있는가
집  →  생물을 몇 마리 키울 수 있는가
생물 →  거품을 얼마나 버는가
```

거품이 아무리 많아도 자리가 없으면 생물을 더 들일 수 없다. 성장은 세 갈래다.

1. 집을 더 지어 자리를 늘린다 (칸을 먹는다)
2. 싼 생물을 내보내고 비싼 생물로 갈아 끼운다 (내보내면 절반을 돌려받는다)
3. 다음 구역을 열어 칸 자체를 늘린다

집은 여러 칸을 차지한다. 난파선·잠수정·고래 뼈는 3×2, 석주·석상·굴뚝·수정은 2×2,
항아리와 닻은 2×1, 유리병 편지는 1×1이다. **정원은 어느 집이든 3으로 같으므로**,
넓은 집은 아름다움이 크고 좁은 집은 칸을 아낀다. 그 사이에서 고르는 것이 배치의 고민이다.

**집 짓는 법**: 상점 집 탭에서 고르면 상점이 잠시 닫히고 배치 모드가 된다.
지을 칸을 클릭하면 그때 값이 지불된다. 우클릭이나 Esc로 취소.
이미 지은 집은 끌어서 옮길 수 있고(공짜), 끄는 동안 아래에 나타나는
휴지통에 떨구면 헐고 절반을 돌려받는다. 단 살고 있는 생물이 남는 집에 다 들어가야 한다.

**생물 들이는 법**: 상점 생물 탭에서 클릭하면 끝이다. 자리를 고를 필요가 없고,
그 구역의 집에 알아서 배정된다. 내보낼 때만 끌어서 휴지통에 넣는다.

**물고기는 집을 맴돈다.** 헤엄치는 생물(물고기·해파리)은 제 집을 중심으로 타원을 그리며
돌고, 뒤로 돌아갈 때는 집에 가려 들어간 것처럼 보였다가 앞으로 다시 나온다.
해초나 거품돌처럼 바닥에 붙는 생물은 집 둘레 제자리에 선다.
집(`vessel`·`wreck`·`pillar`)과 생물(`plant`·`rock`·`fish`·`glow`)은 그림 형태가 아예
갈라져 있어서, 어느 것이 건물이고 어느 것이 사는 것인지 한눈에 읽힌다.

## 구역

다섯 층이 있고, **위층에서 아래층으로 내려갈수록 깊어진다.**
왼쪽 아래 층 선택기, 마우스 휠, ↑↓ 키로 오간다.
처음에는 맨 왼쪽 얕은 바다만 열려 있고 나머지는 어둡게 덮여 있다.
잠긴 구역을 클릭하면 해금 조건과 남은 양이 그 자리에 뜬다.

다음 구역을 열려면 두 가지가 필요하다.

1. **바로 앞 구역의 아름다움** — 앞바다를 대충 두고 다음으로 넘어갈 수 없다.
2. **해금 비용(거품)**

생물과 집은 각자 자기 구역에 속한다. 그 구역이 열려야 상점에 나타나고,
집은 그 구역 밖에 지을 수 없다(구역 경계를 걸치는 것도 안 된다).
생물도 자기 구역의 집에만 들어가므로, 얕은 바다에 빈 자리가 남아도
산호초 물고기를 거기 들일 수는 없다.
모래색과 물빛은 구역 중심 색을 기준으로 이어 붙여서 경계가 보이지 않게 그린다.

자세한 수치와 앞으로 붙일 것들은 [docs/DESIGN.md](docs/DESIGN.md) 참고.
## 저장 위치

`%APPDATA%\Godot\app_userdata\Blub Blub\save.json` (한 세대 전 백업은 `save.bak.json`)

## 부팅 시 자동 실행

내보내기(Export)로 exe를 만든 뒤, `Win+R` → `shell:startup` 폴더에 그 exe의 바로가기를 넣으면 된다.