Cat & Dino Runner로 배우는 Flutter 기초

Flutter를 처음 보는 사람도 작은 게임 프로젝트를 따라 읽으며 핵심 개념을 익힐 수 있도록 만든 실습 프로젝트입니다.

완성된 앱은 크롬 공룡 게임처럼 자동으로 달리는 러너 게임입니다. 사용자는 고양이 또는 공룡을 고르고, 점프하거나 숙여서 장애물을 피합니다. 별도 이미지 에셋이나 게임 엔진은 사용하지 않았고, Flutter 기본 기능만으로 화면과 움직임을 만들었습니다.

앱 코드는 dino 폴더에 있습니다.

먼저 볼 파일

파일	역할	처음 볼 때 집중할 내용
dino/lib/main.dart	앱 실행, 게임 상태, 입력 처리, 화면 그리기	Flutter 앱이 시작되고 화면이 바뀌는 흐름
dino/pubspec.yaml	프로젝트 이름, SDK 버전, 의존성 설정	Flutter 프로젝트가 어떤 패키지를 쓰는지
dino/test/widget_test.dart	화면 동작 테스트	버튼 선택, 게임 시작, 재시작을 코드로 확인하는 방법
dino/README.md	앱 폴더용 간단 실행 안내	실행 명령만 빠르게 확인할 때

이 프로젝트에서 배우는 것

이 프로젝트는 Flutter의 기초 위젯 앱에서 한 단계 더 나아가 “직접 그리는 화면”과 “시간에 따라 움직이는 상태”를 다룹니다.

• MaterialApp, Scaffold: Flutter 앱의 기본 껍데기 만들기
• StatefulWidget, setState: 점수, 위치, 게임 상태처럼 바뀌는 값 관리하기
• GestureDetector, Focus: 터치와 키보드 입력 받기
• AnimationController: 매 프레임 게임 상태 갱신하기
• CustomPainter: 이미지 없이 캔버스에 캐릭터와 장애물 그리기
• Rect.overlaps: 캐릭터와 장애물의 충돌 판정하기
• flutter_test: 화면에 원하는 문구와 버튼이 나오는지 테스트하기

폴더 구조

GDGOC-SeoulTech-5th_Flutter_Session_13/
  README.md
  dino/
    lib/
      main.dart
    test/
      widget_test.dart
    pubspec.yaml
    macos/
    web/
    android/
    ios/
    windows/
    linux/

Flutter는 하나의 코드로 여러 플랫폼을 실행할 수 있습니다. 이 프로젝트도 web, macos, windows, linux, android, ios 폴더가 함께 생성되어 있습니다. 실제 게임 로직은 대부분 dino/lib/main.dart에 들어 있습니다.

앱이 시작되는 흐름

Flutter 앱은 main() 함수에서 시작합니다.

void main() {
  runApp(const MyApp());
}

runApp은 Flutter에게 “이 위젯을 화면에 올려라”라고 알려주는 함수입니다. 여기서는 MyApp이 앱의 가장 바깥 위젯입니다.

MyApp은 MaterialApp을 만들고, 실제 게임 화면인 DinoGamePage를 첫 화면으로 보여줍니다.

상태 관리: 화면이 바뀌는 이유

게임은 계속 상태가 바뀝니다. 시작 전인지, 플레이 중인지, 게임 오버인지에 따라 화면과 입력 동작이 달라집니다.

이 상태는 DinoGameStatus enum으로 표현합니다.

enum DinoGameStatus { idle, playing, gameOver }

• idle: 아직 시작하지 않은 상태
• playing: 게임이 진행 중인 상태
• gameOver: 충돌해서 다시 시작을 기다리는 상태

캐릭터 선택은 RunnerCharacter enum으로 관리합니다.

enum RunnerCharacter { cat, dino }

사용자가 고양이 또는 공룡을 선택하면 제목, 캐릭터 그림, 장애물 모양이 함께 바뀝니다.

StatefulWidget과 setState

Flutter에서 화면에 보이는 값이 바뀌어야 하면 보통 StatefulWidget을 사용합니다. 이 프로젝트의 핵심 화면인 DinoGamePage가 그 역할을 합니다.

게임 상태는 _DinoGamePageState 안의 변수들로 관리됩니다.

DinoGameStatus _status = DinoGameStatus.idle;
RunnerCharacter _character = RunnerCharacter.cat;
double _dinoLift = 0;
double _velocityY = 0;
double _obstacleX = 980;
double _speed = _baseSpeed;
double _distance = 0;
int _highScore = 0;
bool _isDucking = false;

각 변수는 다음 의미를 가집니다.

• _status: 현재 게임 상태
• _character: 선택한 캐릭터
• _dinoLift: 캐릭터가 바닥에서 떠 있는 높이
• _velocityY: 점프 중 위아래 속도
• _obstacleX: 장애물의 가로 위치
• _speed: 게임 속도
• _distance: 점수를 계산하기 위한 누적 거리
• _highScore: 최고 점수
• _isDucking: 숙이고 있는지 여부

값이 바뀐 뒤 화면도 다시 그려야 할 때는 setState를 호출합니다. Flutter는 setState가 호출되면 필요한 부분을 다시 그립니다.

게임 루프: AnimationController

일반 앱은 사용자가 버튼을 누를 때만 화면이 바뀌는 경우가 많습니다. 하지만 게임은 사용자가 아무것도 하지 않아도 매 순간 캐릭터와 장애물이 움직여야 합니다.

이 프로젝트는 AnimationController를 게임 루프처럼 사용합니다.

_gameLoop = AnimationController(
  vsync: this,
  duration: const Duration(days: 1),
)..addListener(_tick);

addListener(_tick) 때문에 애니메이션이 진행되는 동안 _tick이 반복해서 호출됩니다.

_tick에서는 다음 일을 처리합니다.

• 이전 프레임과 현재 프레임의 시간 차이 계산
• 중력 적용
• 점프 위치 갱신
• 장애물 이동
• 플레이 가능한 최소 장애물 간격 보장
• 점수 증가
• 속도 증가
• 충돌 검사
• 게임 오버 처리

여기서 중요한 점은 “프레임 수”가 아니라 “지난 시간”을 기준으로 움직임을 계산한다는 것입니다. 그래서 기기 성능이 달라도 게임 속도가 비교적 일정하게 유지됩니다.

난이도와 장애물 간격

장애물은 한 번에 하나씩 등장합니다. 장애물이 화면 왼쪽 밖으로 나가면 _resetObstacle이 다음 장애물을 화면 오른쪽 바깥에 다시 배치합니다.

점수가 높아질수록 기본 간격은 줄어들지만, 너무 촘촘해져서 피할 수 없는 상황이 생기지 않도록 최소 회복 시간을 둡니다.

final playableGap = _speed * _minimumObstacleRecoverySeconds;
_obstacleX = _viewportWidth + max(difficultyGap, playableGap);

_minimumObstacleRecoverySeconds는 다음 장애물까지 최소한 확보할 시간을 뜻합니다. 현재 값은 0.9초입니다. 속도가 빨라질수록 필요한 거리도 같이 늘어나기 때문에, 난이도는 올라가더라도 기본적으로 반응할 수 있는 간격은 유지됩니다.

입력 처리: 터치와 키보드

터치 입력은 GestureDetector가 처리합니다.

GestureDetector(
  onTap: _handleAction,
  onLongPressStart: (_) => _setDucking(true),
  onLongPressEnd: (_) => _setDucking(false),
)

• 탭: 시작, 점프, 재시작
• 길게 누르기: 숙이기

키보드 입력은 _onKeyEvent에서 처리합니다.

• Space, Enter, ArrowUp: 시작, 점프, 재시작
• ArrowDown, S: 숙이기

점프 로직은 _jump에 있고, 숙이기 로직은 _setDucking에 있습니다.

충돌 판정

게임 오버는 캐릭터와 장애물이 겹칠 때 발생합니다. 이 프로젝트는 복잡한 물리 엔진 대신 Flutter의 Rect를 사용합니다.

충돌 검사는 _hasCollision에서 합니다.

final dinoRect = Rect.fromLTWH(
  _dinoX,
  _groundY - _dinoHeight - _dinoLift,
  _dinoWidth,
  _dinoHeight,
).deflate(7);

캐릭터와 장애물을 각각 사각형으로 보고, 두 사각형이 겹치면 충돌입니다. deflate는 충돌 영역을 조금 줄이는 역할을 합니다. 실제 그림보다 충돌 박스가 살짝 작아져서 플레이 감각이 더 자연스러워집니다.

화면 그리기: CustomPainter

보통 Flutter 화면은 Text, Container, Column, Row 같은 위젯을 조합해서 만듭니다. 하지만 게임처럼 작은 물체가 매 프레임 움직이는 화면은 캔버스에 직접 그리는 방식이 더 단순할 수 있습니다.

이 프로젝트는 DinoGamePainter가 화면 대부분을 직접 그립니다.

paint 메서드 안에서 다음 요소가 그려집니다.

• 낮/밤 배경
• 구름
• 지면
• 고양이 또는 공룡
• 털실공 또는 선인장
• 날아오는 장난감 또는 익룡

캐릭터 그림은 이미지 파일이 아닙니다. _drawCat과 _drawDino에서 사각형과 원을 조합해 픽셀 스타일로 직접 그립니다.

달리기 다리 모양과 공중 장애물의 날개 모양은 _animationTime을 기준으로 천천히 바뀝니다. 점수로 애니메이션 프레임을 바꾸면 점수가 빨리 오를수록 움직임도 과하게 빨라질 수 있어서, 실제 이동 속도와 그림 프레임 전환 속도를 분리했습니다.

테스트는 무엇을 확인하나

테스트 코드는 dino/test/widget_test.dart에 있습니다.

이 파일은 앱을 실제로 실행하지 않고도 화면의 주요 흐름을 검사합니다.

• 시작 화면에 점수와 안내 문구가 보이는지
• 고양이/공룡 선택 버튼이 있는지
• 공룡 버튼을 누르면 제목이 DINO RUNNER로 바뀌는지
• 게임 화면을 탭하면 게임이 시작되는지
• 게임 오버 상태에서 다시 시작할 수 있는지

예를 들어 tester.tap은 테스트 중 버튼을 누르는 동작을 대신합니다.

실행 방법

먼저 Flutter SDK가 설치되어 있고 flutter doctor에서 사용할 대상 기기 또는 브라우저가 잡히는지 확인합니다.

flutter doctor

프로젝트 루트에서 앱 폴더로 이동합니다.

cd dino

웹 브라우저에서 개발 모드로 실행합니다.

flutter run -d chrome

macOS 데스크톱 앱으로 실행하려면 macOS 환경에서 아래 명령을 사용합니다.

flutter run -d macos

연결된 실행 대상을 확인하려면 아래 명령을 사용합니다.

flutter devices

웹 디버그 실행에서 빈 화면이 보이면 정적 웹 빌드로 실행합니다.

flutter build web
cd build/web
python -m http.server 5178 --bind 127.0.0.1

Windows에서 python 명령이 동작하지 않으면 py -m http.server 5178 --bind 127.0.0.1을 사용합니다.

브라우저에서 아래 주소를 엽니다.

http://127.0.0.1:5178

검증 명령

앱 폴더인 dino 안에서 실행합니다.

dart format lib/main.dart test/widget_test.dart
flutter analyze
flutter test
flutter build web

각 명령의 의미는 다음과 같습니다.

• dart format: Dart 코드 스타일 정리
• flutter analyze: 문법, 타입, 권장 규칙 검사
• flutter test: 테스트 실행
• flutter build web: 웹 배포용 빌드 생성

추천 읽는 순서

처음 Flutter를 본다면 아래 순서로 읽는 것이 좋습니다.

1. dino/pubspec.yaml에서 프로젝트 설정 확인
2. main()과 MyApp으로 앱 시작 흐름 확인
3. DinoGamePage에서 상태 변수가 어떻게 선언되는지 확인
4. _onKeyEvent와 GestureDetector에서 입력 처리 확인
5. _tick에서 게임이 매 프레임 갱신되는 방식 확인
6. _resetObstacle에서 장애물 간격을 조절하는 방식 확인
7. DinoGamePainter에서 화면을 직접 그리는 방식 확인
8. widget_test.dart에서 UI 동작을 테스트하는 방식 확인

핵심 정리

• Flutter 앱은 main()에서 시작해 위젯을 화면에 올립니다.
• 화면에 바뀌는 값이 있으면 StatefulWidget과 setState로 관리할 수 있습니다.
• 게임처럼 계속 움직이는 화면은 AnimationController로 반복 갱신할 수 있습니다.
• CustomPainter를 사용하면 이미지 없이도 캔버스에 직접 캐릭터와 배경을 그릴 수 있습니다.
• 장애물 간격은 현재 속도를 고려해 “피할 수 있는 최소 시간”을 보장해야 합니다.
• 움직임 애니메이션은 점수보다 별도 시간 값을 기준으로 두는 편이 안정적입니다.
• 키보드와 터치 입력은 각각 Focus, GestureDetector로 받을 수 있습니다.
• 작은 게임이라면 별도 게임 엔진 없이 Flutter 기본 기능만으로도 충분히 만들 수 있습니다.