Flutter 앱 개발기 (5/5) — 육각 지뢰찾기: 큐브 좌표계와 BLoC 상태 관리

-

육각 그리드 좌표계 설계, 이벤트 기반 상태 관리, 커스텀 렌더링 판정까지 — 사각형과 무엇이 다른지 정리한다.

이 글이 전달하는 것

  • 육각형 그리드에서 오프셋 좌표 대신 큐브 좌표(Cube Coordinates)를 쓰는 이유와 변환 규칙
  • 게임처럼 단일 입력이 연쇄 상태 변화를 유발할 때 Riverpod보다 BLoC이 맞는 근거
  • Flood Fill, 터치 판정(Cube Round), 테스트 경계 — 육각 그리드에서 바뀌는 구현 포인트
  • 상태 폭발을 막는 BLoC 분리 기준

1. 좌표계 — 오프셋 vs 큐브

사각 그리드는 (row, col) 2차원 배열로 충분하다. 육각 그리드는 그렇지 않다. 오프셋 좌표로 시작하면 홀수/짝수 행의 이웃 인덱스가 달라지고, 방향 계산이 조건 분기로 흩어진다.

큐브 좌표는 3축 (q, r, s)로 셀을 표현하되 q + r + s = 0 제약을 유지한다. 이 표현의 핵심 이득은 다음과 같다.

  • 이웃 계산의 균일성: 6방향 오프셋 배열 하나로 모든 이웃을 얻는다. 행 패리티 분기가 사라진다.
  • 거리 계산 단순화: 두 셀의 거리는 (|dq| + |dr| + |ds|) / 2.
  • 회전·반사의 수학적 표현: 축 치환만으로 구현 가능.

오프셋 좌표는 렌더링 시 화면 좌표와 가까워서 편하지만, 로직은 큐브, 표시는 오프셋으로 분리하는 편이 깨끗하다. 두 체계 간 변환 함수(offsetToCube / cubeToOffset)만 유지하면 나머지 로직이 일관된다.

적용 원칙

육각 그리드를 다룬다면 초기부터 큐브 좌표로 시작하는 것이 바람직하다. 오프셋 좌표 기반 이웃 로직은 버그가 반복되고, 후반에 전면 교체하는 비용이 크다.

2. 상태 관리 — BLoC이 맞는 경우

Flutter 상태 관리 선택은 프로젝트 특성에 따른다. 같은 앱 생태계에서도 적합한 도구가 다르다.

프로젝트 유형 특성 적합한 패턴
뷰어·리더 계열 입력이 단순하고 상태 그래프가 얕음 Riverpod (반응형)
게임·워크플로우 계열 단일 입력이 연쇄 전이를 유발 BLoC (이벤트 기반)

게임 상태의 특성

지뢰찾기의 "셀 탭" 한 번은 다음 흐름을 트리거한다.

입력: CellTapped(q, r, s)
  → 지뢰 여부 판정
  → 빈 셀이면 Flood Fill
  → 승리 조건 확인
  → UI 상태 업데이트

이 흐름은 하나의 트랜잭션으로 다뤄져야 한다. BLoC의 Event → State 매핑은 이 구조와 직접 대응한다. 각 Event가 어떤 State 전이를 유발했는지가 로그에 그대로 드러나서, 회귀 추적과 재현이 쉽다.

Riverpod이 불리한 지점

Riverpod은 Provider 간 의존 그래프로 상태를 조합하는 모델이다. "한 입력 → 여러 상태 연쇄"에서는 Provider 업데이트 순서가 암묵적이 되기 쉽고, 디버깅 시 원인 이벤트를 역추적하기 어렵다.

판단 규칙

  • 입력 → 상태 변화가 1:다이고 순서가 중요하다 → BLoC
  • 입력 → 상태 변화가 대부분 1:1이고 선언적 조합이 중심 → Riverpod

3. Flood Fill — BFS 기반 구현

지뢰 없는 빈 셀을 탭하면 이웃 중 지뢰가 0인 셀들이 연쇄적으로 열린다. 원리는 사각과 동일하지만, 이웃 집합을 큐브 좌표 기준으로 돌린다.

directions = [
  (+1, -1,  0), (+1,  0, -1), ( 0, +1, -1),
  (-1, +1,  0), (-1,  0, +1), ( 0, -1, +1),
]

재귀 대신 BFS

큰 보드에서는 한 번의 Flood Fill이 수백 셀을 연다. 재귀 DFS는 스택 오버플로 위험이 있다. 큐 기반 BFS로 구현하면 안전하고, 방문 마킹(visited Set)으로 중복 확장을 막는다.

성능 관측 포인트

  • Flood Fill 1회의 비용은 O(열리는 셀 수)
  • UI 업데이트는 Flood Fill 종료 후 일괄 방출한다. 셀마다 state emit을 호출하면 리빌드가 폭발한다.

4. 커스텀 렌더링과 터치 판정

CustomPainter로 정육각형

  • 짝수/홀수 행의 x 오프셋이 다르다
  • 행 간 y 간격은 타일 높이의 3/4 (height * 0.75)
  • 타일은 30도 회전된 정육각형(pointy-top) 또는 평평한 상단(flat-top) 중 하나로 통일한다

터치 판정 — Cube Round

육각형은 모서리가 비스듬해서 경계 박스 비교로는 오판이 잦다. 타일 경계가 인접 셀과 교차하는 영역에서 틀린 셀이 잡힌다.

해법은 화면 좌표 → 연속 큐브 좌표 → 정수 큐브 좌표 반올림(Cube Round) 순서로 내려오는 것이다.

1. 터치 좌표 (px, py) 를 픽셀 단위로 큐브 좌표 (qf, rf, sf) 로 변환
2. 각 축을 반올림 → (qi, ri, si)
3. q + r + s = 0 제약이 깨지면, 가장 반올림 오차가 큰 축을 나머지 두 축으로 재계산

이 방식은 "가장 가까운 타일의 중심"을 수학적으로 보장한다. 포인트-인-폴리곤 검사를 타일마다 돌리는 것보다 저렴하고 정확하다.

5. 테스트 경계 — BLoC이 주는 분리선

BLoC 구조의 이점은 UI 독립 테스트가 가능하다는 점이다. 게임 로직과 렌더링이 분리되므로 다음을 순수 Dart 테스트로 검증할 수 있다.

검증 대상 입력 기대 출력
게임 오버 지뢰 셀 CellTapped GameState.over
승리 비지뢰 전부 열림 GameState.victory
Flood Fill 지뢰 0 셀 CellTapped 연쇄 열림 집합
좌표 변환 offset → cube → offset 원래 좌표 일치 (라운드트립)

좌표 변환 라운드트립이 깨지면 모든 기능이 연쇄 실패한다. 가장 먼저 고정해야 할 테스트 대상이다.

6. BLoC 분리 기준 — 상태 폭발 방지

게임 상태를 단일 BLoC에 몰아넣으면 이벤트 타입과 분기가 빠르게 늘어난다. 책임 기준으로 분리한다.

BLoC 책임
GameBloc 보드 상태, 셀 열기/깃발, 승패 판정
TimerBloc 경과 시간, 일시정지
LeaderboardBloc 기록 저장/조회 (Hive 연동)

분리 기준은 상태 수명과 업데이트 주기다. Timer는 초 단위로 emit하고, Game은 입력 단위로 emit한다. 둘을 합치면 Timer의 고빈도 업데이트가 Game 리스너까지 흔들어서 불필요한 리빌드가 발생한다.

한계와 열린 질문

  • 큐브 좌표 도입 비용: 팀원이 익숙하지 않으면 학습 곡선이 있다. 문서화가 필수.
  • 육각 타일 UI의 접근성: 스크린 리더, 고대비 모드에서의 타일 식별은 추가 설계가 필요하다.
  • 난이도 생성 알고리즘: 균일한 지뢰 배치가 반드시 "좋은 게임"을 만들지 않는다. 첫 클릭 안전 보장, 보장 가능한 논리 경로 등은 별도 주제.
  • 플랫폼별 제스처: 모바일의 롱프레스(깃발)와 데스크톱의 우클릭은 BLoC 이벤트로 동일하게 흡수할 수 있으나, UX 가이드는 플랫폼 별로 분리하는 편이 안전하다.

적용 가능 범위

  • 육각 기반 보드게임(턴제 전략, 퍼즐) 일반에 동일 좌표계 적용 가능
  • "단일 입력 → 연쇄 상태 전이" 구조가 있는 워크플로우성 앱(체크아웃 흐름, 단계형 폼, 턴 기반 UI)도 BLoC이 유리
  • Cube Round는 육각뿐 아니라 비정형 타일 기반 좌표 보정에 일반화 가능

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »