Cubound

Cube + bound, "어딘가로 향하는 큐브의 여행".

작은 큐브가 칸을 하나씩 건너 집을 찾아가는 미니멀 아이소메트릭 퍼즐 게임입니다.

칸마다 높이가 있어 내려갈 수는 있어도 올라갈 수는 없고, 상자를 밀어 계단을 만들고 스위치를 눌러 문을 열고 사다리를 옮겨 걸며 길을 내는데, 게임 오버가 없어 조용히 생각만 하면 됩니다.

Live demo: https://cubound.vercel.app

아키텍처

주요 기능

• 아이소메트릭 필드 — 3D 라이브러리 없이 SVG로만 그리고, 큐브는 6면을 회전시켜 보이는 세 면만 투영합니다.
• 카메라 — 판 전체가 충분히 크게 들어가는 화면에서는 판 전체를 가운데에 두고, 작은 화면에서는 구역으로 나눠 큐브가 넘어갈 때 그 구역으로 옮겨 갑니다. 폰 세로는 칸을 키워 큐브에 붙어 따라가고, 전체 보기 버튼으로 판 전체를 볼 수 있습니다.
• 풀이 검사기 — 게임과 같은 규칙 함수로 가능한 상태를 전부 펼쳐 최소 이동 수를 구하고, 별점 기준과 보스 제한을 그 값으로 정합니다.
• 별점과 보스 — 최소 이동 수면 별 3개이고, 열 번째 판마다 붙는 보스 제약은 최소 풀이가 쓰는 만큼이라 여유가 없습니다.
• 조작 — 타이틀에서 클리어까지 키보드만으로 가고, 모바일은 화면 어디서 밀어도 되며 연출 중에 눌러도 입력이 밀리지 않습니다.
• 다국어 — 여섯 언어를 기기 설정에 맞춰 보여주고, 번역이 없는 문구는 영어로 내보냅니다.

오브젝트

색으로 역할을 나눠 큐브는 블루, 밀고 옮기는 도구는 옐로, 지형은 무채색입니다.

오브젝트	월드	설명
상자	1	밀어서 옮기고 못 밀면 큐브가 그 위로 올라섭니다
스위치	1	큐브나 상자가 올라가 있는 동안만 연결된 대상이 반응합니다
문	1	닫히면 한 층 벽, 열리면 바닥 높이
사다리	1	주워서 들고 다니다 한 층 높은 칸에 기대 놓고 오릅니다
얼음	2	도착한 칸이 얼음이면 멈출 때까지 미끄러지고 전체가 이동 1회입니다
엘리베이터 발판	2	연결된 스위치가 눌린 동안 한 층 올라가고 위에 있는 것이 같이 오릅니다
무너지는 칸	3	큐브나 물건이 올라서면 금이 깊어지고 다 닳은 칸은 비는 순간 사라집니다
짝 칸	3	밟으면 짝인 칸으로 곧바로 옮겨가고 상자는 옮겨가지 않습니다
움직이는 발판	4	큐브가 한 번 움직일 때마다 정해진 길을 한 칸씩 오가고 위에 탄 것도 같이 갑니다
늪	6	들어가면 두 수를 제자리에서 버둥거린 뒤에야 나가고 상자를 밀어 넣으면 가라앉아 평지가 됩니다
버섯	7	밟으면 그 방향으로 두 칸 튀고 사이 칸은 높이를 보지 않아 벽도 구덩이도 넘습니다
덩굴	8	큐브가 한 번 움직일 때마다 바닥 없는 칸을 한 칸씩 메워 다리가 되고 되돌아오지 않습니다
씨앗	9	주워 들고 다니다 한 층 높은 칸 쪽으로 밀면 발밑에 심고, 4수 뒤 위의 것과 함께 한 층 솟습니다
물과 뜬 상자	11	큐브는 물에 못 들어가고 물에 민 상자는 떠서 큐브가 타고 한 칸씩 저어 갑니다
소용돌이	12	같은 가로세로 물길의 빈 배를 매 수 한 칸씩 끌어당기고 큐브가 탄 배는 끌지 않습니다
얼음 돌	13	둘레 네 칸의 같은 높이 물을 얼리고 물에 밀면 떠서 한 칸씩 밀리며 얼음길을 냅니다
물 스위치	14	큐브나 상자, 얼음 돌이 올라가 있는 동안 판 전체 물이 한 층 높아져 낮은 땅이 잠기고 배가 함께 오릅니다
번지는 불	16	불씨 칸을 밟으면 맞닿은 같은 높이 숯 벽과 숯 다리를 따라 한 수에 한 칸씩 타고, 숯 벽은 길이 열리고 숯 다리는 끊깁니다
화로	17	밟으면 큐브에 불이 붙고, 4수 안에 같은 높이 숯 벽 쪽으로 밀면 그 벽에 불이 옮겨붙습니다
화약통	18	상자처럼 밀고, 같은 높이 불이 닿으면 그 수에 터져 둘레 네 칸 땅을 한 층씩 깎습니다. 보스는 4수 뒤에 터지는 심지 화약통
쇠막대	19	두 칸에 누운 쇠 막대입니다. 길이 방향으로 밀면 한 칸, 옆에서 끝을 밀면 반대쪽 끝을 축으로 90도 돕니다. 두 칸 구덩이에 걸치면 다리가 됩니다. 보스는 불에 닿으면 세 칸으로 늘어나는 달군 쇠

50판이 한 장(chapter)이고 장마다 세계 색이 다르며, 목록 헤더의 월드 덩이를 누르면 화면을 갈아 끼우지 않고 그 자리에서 장 고르기로 바뀝니다.

스테이지 제작

스테이지는 높이 격자와 오브젝트가 든 JSON 한 장이고, 손으로 풀어 보는 대신 명령줄 도구가 검사합니다.

$ pnpm stage:check src/stages/world-1/10.json

  형식  통과
  가림  없음
  최소  34수 (best 34 일치)
  제한  41수 (여유 7수)
  밀기  최소 2번
  탐색  상태 352개
  막힘  0개
  대체  34수 풀이 6가지, 제한 안 상태 138개
  구역  1구역 8수, 2구역 6수, 3구역 10수, 4구역 10수

가림은 앞쪽 높은 칸에 가려 안 보이는 오브젝트 수이고, 막힘이 0개면 되돌릴 수 없는 실수가 없고 대체 풀이가 1가지면 외길이며 구역별 이동 수가 한쪽에 쏠리면 퍼즐이 한 구역에만 몰려 있다는 신호라, 이 값들로 best와 보스 제한을 확정합니다.

설계 노트

• 순수 함수 — 게임 규칙을 game/ 아래 순수 함수로 두어 게임과 검사기와 테스트가 한 벌만 공유하고, 규칙을 고치면 어느 스테이지가 깨지는지 바로 드러납니다.
• 연출 — move()가 결과를 즉시 돌려주고 화면이 그 사이를 보간해서, 연출 프레임 계산도 진행도 t를 받는 순수 함수라 단위 테스트가 붙습니다.
• 별점 기준 — 최소 이동 수 best를 검사기로 구하고 테스트가 모든 스테이지를 그 값과 대조해, 맵에 남은 지름길 때문에 별 3개 기준이 조용히 틀어지는 것을 막습니다.
• 성능 — 체감 문제는 Playwright로 먼저 쟀고, CPU를 4배 느리게 두고 프레임 간격을 재서 찾은 원인을 고쳐 상자 밀기 평균 프레임이 28.6ms에서 17.5ms가 됐습니다.

기술 스택

영역	사용
패키지 매니저	pnpm 9 워크스페이스 모노레포, Node.js 22.12+
빌드	Vite 8
UI	React 19 + TypeScript strict
게임 화면	SVG 아이소메트릭, Motion
상태	Zustand
스타일	Tailwind CSS v4
영속화	localStorage 키 cubound:progress, cubound:session, cubound:language, cubound:world
테스트	Vitest 순수 함수 2300여 개 + Playwright 스모크와 화면 캡처
코드 퀄리티	oxlint + Prettier + Husky + lint-staged
호스팅	Vercel

시작하기

Node.js 22.12+, pnpm 9가 필요하고 환경 변수는 없습니다.

pnpm install
pnpm dev

명령	설명
pnpm build	프로덕션 빌드, 타입 검사 포함
pnpm test	Vitest 단위 테스트
pnpm e2e	Playwright 스모크 테스트
pnpm shot	핵심 화면 캡처, 아이콘과 공유 카드도 다시 찍음
pnpm shot:stages	스테이지별 장면 캡처
pnpm stage:check <경로>	스테이지 형식 검사와 난이도 지표, 생략하면 전체

프로젝트 구조

apps/web/
  src/
    game/         # 순수 로직 — 규칙 / 풀이 검사기 / 형식 검사 / 가림 처리 / 진행 / 이어하기 / 좌표 / 카메라
    stages/       # 스테이지 JSON — world-1 ~ world-13
    store/        # Zustand — 게임 상태 / 연출 / 입력 대기열 / 설정
    platform/     # 브라우저 의존 — 저장 / 입력
    routes/       # 주소 / 탭 제목
    hooks/        # 훅 — 주소 / 문구 / 포커스 가두기 / 필드 연출과 카메라 / 반복 연출
    dev/          # 개발 서버 전용 — 최단 풀이 따라가기 / 풀이 재생
    components/   # board 필드와 연출 / guide 스텝 가이드 / ui 공용
    screens/      # 타이틀 / 스테이지 선택 / 게임
    i18n/         # 언어별 사전
  public/         # 아이콘 / manifest / 공유 카드 / robots.txt
  tools/          # pnpm stage:check
  e2e/            # Playwright 스모크와 화면 캡처
apps/server/      # 추후 NestJS 서버 도입 예정
packages/         # 추후 web과 server 공용 코드 도입 예정
docs/             # 기획, 설계, 디자인 브리프

주소는 #/ 타이틀, #/stages/:world 스테이지 선택, #/stages/:world/chapters 장 고르기, #/play/1-10 게임입니다.

문서

문서	내용
docs/PRD.md	게임 규칙, 오브젝트, 스테이지 구성, 전체 스테이지 계획
docs/ARCHITECTURE.md	게임 모델, 렌더링, 애니메이션, 디자인 기준값, 저장
.claude/history.md	만든 순서대로의 작업 이력