Neon Runner 모바일 버전 만들기 #1

📱 모바일 게임 프로젝트

모바일 게임 만들기 #1

기획 · 기술 스택 선정 · Expo + FastAPI + PostgreSQL 세팅

2026.04.23  ·  React Native · FastAPI · PostgreSQL · Supabase

📋 목차

1. 왜 모바일 버전을 새로 만들었나
2. 기술 스택 선정 이유
3. 웹버전과 달라진 점
4. 게임 기획 — 추가된 기능들
5. 프로젝트 구조 & Expo 세팅
6. FastAPI + PostgreSQL 백엔드 세팅
7. Supabase DB 연결
8. API 구조 완성

1 왜 모바일 버전을 새로 만들었나

웹버전 Neon Runner를 배포하고 나서 친구가 핸드폰으로 열어봤더니 화면이 잘리고 키보드가 없어서 조작이 안 됐다. 처음부터 모바일을 고려하지 않고 만들었으니 당연한 결과였다.

그냥 웹버전을 수정하는 것보다 처음부터 모바일을 기준으로 다시 만드는 게 낫겠다고 판단했다. 어차피 새로 만들 거면 기능도 더 추가하고 DB도 제대로 쓰고 싶었다.

💡

웹버전은 그대로 유지
모바일 버전은 완전히 별도 프로젝트로 만들었다. 웹버전(neon-runner)은 그대로 두고, 모바일 버전은 neon-runner-mobile로 따로 관리한다.

2 기술 스택 선정 이유

📱

React Native (Expo)

프론트엔드

웹버전에서 배운 React 문법을 그대로 쓸 수 있다. iOS + Android 동시 개발 가능. Expo 덕분에 복잡한 환경 설정 없이 바로 시작할 수 있다.

🐍

Python FastAPI

백엔드

웹버전과 동일하게 유지. 이미 익숙하고 코드가 간결하다. 이번엔 JWT 인증까지 추가해서 제대로 된 백엔드를 만든다.

🗄️

PostgreSQL + SQLAlchemy

데이터베이스

웹버전의 JSON 파일 대신 제대로 된 DB를 쓴다. SQLAlchemy로 Python 코드로 쿼리를 작성하고, 실제 SQL도 경험해볼 수 있다.

🔐

JWT 토큰

인증

회원가입/로그인 기능. 로그인하면 JWT 토큰을 받아서 이후 요청에 포함시킨다. 내 기록, 내 아이템을 관리할 수 있다.

☁️

Supabase

DB 호스팅

PostgreSQL을 무료로 클라우드에서 쓸 수 있게 해주는 서비스. 직접 서버 설치 없이 DB URL만 받아서 연결하면 끝이다.

3 웹버전과 달라진 점

항목	웹버전	모바일버전
프레임워크	React + Vite	React Native + Expo
렌더링	Canvas API	React Native 컴포넌트
조작	키보드 (SPACE, ↓)	터치 (왼쪽 탭, 오른쪽 탭)
데이터 저장	JSON 파일	PostgreSQL DB
인증	닉네임만 입력	회원가입 / 로그인 (JWT)
아이템	없음	쉴드 / 슬로우 / 무적 / 점수2배
스테이지	없음	4개 테마 (30초마다 변경)
콤보	없음	연속 회피 시 점수 배율 증가

4 게임 기획 — 추가된 기능들

흔한 점프게임이랑 차별화하려고 여러 요소를 추가했다.

🌍 스테이지 시스템

30초마다 배경 테마가 바뀐다. 사이버도시 → 우주 → 용암지대 → 심해 순서로. 장애물 색이나 분위기도 스테이지마다 달라져서 질리지 않는다.

⚡ 아이템 시스템

게임 중에 아이템이 맵에 등장하고, 먹으면 인벤토리에 보관된다. 원할 때 꺼내 쓸 수 있다.

아이템	효과	지속시간
🛡️ 쉴드	한 번 맞아도 안 죽음	1회
🐌 슬로우	게임 속도 느려짐	3초
🌀 무적	모든 장애물 통과	2초
💎 점수 2배	획득 점수 2배	5초

🎯 콤보 시스템

장애물을 연속으로 피할수록 콤보가 쌓이고 점수 배율이 올라간다. 맞으면 콤보 초기화.

🏆 아이템 인벤토리

100점 이상 획득하면 게임오버 후 랜덤 아이템 1개 지급. 최대 3개 보관 가능. 다음 게임에서 원할 때 사용.

5 프로젝트 구조 & Expo 세팅

D:\Lee_project\neon-runner-mobile\
├── frontend\    ← React Native (Expo)
│   ├── App.js     ← 게임 메인
│   ├── app.json
│   └── package.json
└── backend\    ← Python FastAPI
    ├── venv\
    ├── main.py    ← API 서버
    ├── .env       ← DB 주소, 비밀키
    └── .gitignore

Expo 프로젝트 생성 명령어:

PowerShell

# Expo 설치
npm install -g expo-cli

# 빈 프로젝트 생성
npx create-expo-app frontend --template blank

# 개발 서버 실행
cd frontend
npx expo start

💡

Expo가 뭔가?
React Native 앱을 만들 때 Xcode, Android Studio 같은 무거운 도구 설치 없이 바로 시작할 수 있게 해주는 도구다. 폰에 Expo Go 앱 설치하고 QR코드 스캔하면 실기기에서 바로 테스트 가능하다. 코드 수정하면 실시간으로 폰에 반영된다.

✅

React Native에서 달라지는 문법
HTML 태그 대신 React Native 전용 컴포넌트를 쓴다.
<div> → <View>
<p> → <Text>
CSS → StyleSheet.create()
클릭 → onPress
JavaScript/React 문법은 완전히 동일하다.

6 FastAPI + PostgreSQL 백엔드 세팅

웹버전과 다르게 이번엔 PostgreSQL DB를 쓰기 때문에 필요한 패키지가 더 많다.

PowerShell

# 가상환경 생성 및 활성화
cd D:\Lee_project\neon-runner-mobile\backend
python -m venv venv
venv\Scripts\activate

# 필요한 패키지 설치
pip install fastapi uvicorn sqlalchemy psycopg2-binary python-jose passlib python-multipart python-dotenv

설치한 패키지들 역할:

패키지	역할
fastapi	API 서버 프레임워크
uvicorn	서버 실행
sqlalchemy	Python으로 DB 쿼리 작성 (ORM)
psycopg2-binary	PostgreSQL 드라이버
python-jose	JWT 토큰 생성/검증
passlib	비밀번호 암호화 (bcrypt)
python-multipart	로그인 폼 데이터 처리
python-dotenv	.env 파일에서 환경변수 읽기

💡

ORM이 뭔가?
Object Relational Mapping. SQL 쿼리를 직접 쓰는 대신 Python 코드로 DB를 조작할 수 있게 해주는 도구다. SELECT * FROM users 대신 db.query(User).all() 같이 쓸 수 있다. SQLAlchemy가 대표적인 Python ORM이다.

💡

JWT가 뭔가?
JSON Web Token. 로그인하면 서버가 토큰을 발급해준다. 이후 요청할 때 이 토큰을 같이 보내면 서버가 누가 보낸 요청인지 알 수 있다. 세션처럼 서버에 저장할 필요 없이 토큰 자체에 정보가 담겨있어서 가볍다.

7 Supabase DB 연결

PostgreSQL 서버를 직접 설치하는 건 복잡하다. Supabase를 쓰면 무료로 클라우드 PostgreSQL DB를 만들 수 있다.

supabase.com에서 프로젝트 만들고 → Connect → Direct 탭에서 연결 문자열을 받았다. 비밀번호에 특수문자가 있으면 URL 인코딩이 필요하다. @는 %40, !는 %21로 바꿔야 한다.

backend/.env

DATABASE_URL=postgresql://postgres.프로젝트ID:비밀번호@aws-1-ap-northeast-1.pooler.supabase.com:5432/postgres
SECRET_KEY=neon-runner-secret-key-2026

backend/.gitignore

venv/
.env
__pycache__/
*.pyc

🚨

.env 파일은 절대 GitHub에 올리면 안 된다
DB 주소와 비밀키가 들어있기 때문이다. .gitignore에 반드시 추가해야 한다. 실수로 올렸다면 바로 Supabase에서 비밀번호를 변경해야 한다.

8 API 구조 완성

웹버전은 API가 2개(점수 저장, 리더보드)뿐이었는데 이번엔 훨씬 많아졌다.

메서드	경로	역할	인증
POST	/register	회원가입	불필요
POST	/login	로그인 → JWT 발급	불필요
GET	/me	내 정보 조회	필요 🔒
POST	/score	점수 저장 + 아이템 지급	필요 🔒
GET	/leaderboard	상위 20개 점수 조회	불필요
GET	/items	내 아이템 조회	필요 🔒
POST	/items/use	아이템 사용	필요 🔒

DB 테이블 구조는 이렇게 설계했다.

SQLAlchemy 모델 (Python)

# users 테이블
class User(Base):
    id       = Column(Integer, primary_key=True)
    username = Column(String, unique=True)
    hashed_password = Column(String)   # bcrypt 암호화
    skin     = Column(String, default="default")
    total_score = Column(Integer, default=0)

# scores 테이블
class Score(Base):
    id       = Column(Integer, primary_key=True)
    user_id  = Column(Integer, ForeignKey("users.id"))
    username = Column(String)
    score    = Column(Integer)
    time     = Column(Float)
    stage    = Column(Integer)

# items 테이블
class Item(Base):
    id        = Column(Integer, primary_key=True)
    user_id   = Column(Integer, ForeignKey("users.id"))
    item_type = Column(String)   # shield / slow / invincible / double_score
    quantity  = Column(Integer, default=1)

✅

Base.metadata.create_all()이 하는 일
Python 클래스로 정의한 테이블을 실제 DB에 자동으로 생성해준다. 서버가 처음 켜질 때 한 번 실행되고, 테이블이 이미 있으면 건너뛴다. SQL로 직접 CREATE TABLE을 쓸 필요가 없다.

---

• 완료 프로젝트 기획 및 기술 스택 선정
• 완료 Expo React Native 프로젝트 생성
• 완료 Python FastAPI + PostgreSQL 패키지 설치
• 완료 Supabase DB 생성 및 연결
• 완료 .env + .gitignore 설정
• 완료 API 7개 + DB 테이블 3개 완성
• 완료 FastAPI /docs 에서 API 동작 확인
• 다음편 게임 화면 UI 만들기 (React Native)
• 다음편 회원가입/로그인 화면

웹버전 만들 때보다 설정할 게 훨씬 많았다.

근데 DB랑 JWT 인증까지 붙이고 나니까 진짜 서비스처럼 느껴진다.

▶ 다음편: React Native로 게임 화면 만들기