React + FastAPI로 웹 게임 만들기 #3 - 완성

🎮 사이드 프로젝트

React + Python FastAPI로
웹 게임 만들기 #4

시작 화면 · 게임오버 · 닉네임 저장 · FastAPI 연동 · 리더보드 완성

2026.04.23  ·  React · FastAPI · 게임 완성

📋 목차

1. 완성된 화면들 먼저 보기
2. 시작 화면 만들기
3. 게임오버 화면 + 닉네임 입력
4. FastAPI로 점수 저장하기
5. 리더보드 화면
6. 닉네임 중복 방지
7. 진짜 힘들었던 오류들

1 완성된 화면들 먼저 보기

코드 얘기 전에 실제로 어떻게 생겼는지 먼저 보자. 총 4개 화면이 있다.

📺 시작 화면

NEON RUNNER

SURVIVE · SCORE · DOMINATE

⬆ / SPACE — 점프 (더블점프 가능)
⬇ / S — 엎드리기
─────────────────
🟥 빨간 블록 — 점프로 피하기
🟡 새 / 🟣 돌맹이 — 엎드려서 피하기

▶ GAME START

★ 순위표

📺 게임 화면

⏱ 12.4s ★ 124 ⚡ 4.2x

📺 게임오버 화면

💥 GAME OVER

SCORE

247

TIME

24.7s

닉네임 입력 후 점수 등록

NICKNAME

★ 점수 등록

▶ 다시하기

📺 리더보드 화면

★ LEADERBOARD ★

🏆 내 순위: #2

🥇

JISUN

580pt

58.0s

🥈

EUNKYU

247pt

24.7s

🥉

PLAYER3

180pt

18.0s

▶ 다시하기

🔄 새로고침

2 시작 화면 만들기

처음엔 게임이 켜지자마자 바로 시작됐다. 근데 그러면 조작법도 모르고 바로 죽어버리니까 시작 화면을 따로 만들었다. React의 useState로 현재 어떤 화면인지 관리하는 방식이다.

💡

useState로 화면 전환하는 원리
screen이라는 상태값 하나로 현재 화면을 관리한다. 값이 'start'면 시작화면, 'game'이면 게임화면, 'gameover'면 게임오버, 'leaderboard'면 순위표를 보여준다.

화면 전환 구조

const [screen, setScreen] = useState('start')

// 화면별로 다른 UI 표시
{screen === 'start' && <시작화면 />}
{screen === 'gameover' && <게임오버화면 />}
{screen === 'leaderboard' && <리더보드 />}

// 버튼 클릭 시 화면 전환
<button onClick={() => startGame()}>GAME START</button>
<button onClick={() => setScreen('leaderboard')}>순위표</button>

⚠️

canvas는 절대 숨기면 안 된다
화면 전환할 때 canvas를 display: none으로 숨겼더니 게임이 완전히 망가졌다. canvas가 DOM에서 사라지면 canvasRef.current가 끊겨서 게임 루프 자체가 동작을 안 한다. 그래서 canvas는 항상 화면에 두고, 그 위에 오버레이를 position: absolute로 씌우는 방식으로 해결했다.

3 게임오버 화면 + 닉네임 입력

장애물에 부딪히면 게임 루프를 멈추고 게임오버 오버레이를 띄운다. 거기서 닉네임 입력하고 점수 등록하는 흐름이다.

충돌 감지 후 게임오버 처리

function loop() {
  ...
  if (checkCollision()) {
    gRunning = false                    // 루프 중단
    removeListeners()                   // 키 이벤트 제거
    setFinalScore(score)                // 최종 점수 저장
    setFinalTime(elapsed.toFixed(1))   // 최종 시간 저장
    setScreen('gameover')              // 화면 전환
    return
  }
  ...
}

// 게임오버 화면 JSX
{screen === 'gameover' && (
  <div style={{ position: 'absolute', inset: 0, background: 'rgba(0,0,0,0.85)' }}>
    <div>💥 GAME OVER</div>
    <div>SCORE: {finalScore}</div>
    <div>TIME: {finalTime}s</div>
    <input value={nickname} onChange={e => setNickname(e.target.value)} />
    <button onClick={submitScore}>★ 점수 등록</button>
    <button onClick={startGame}>▶ 다시하기</button>
  </div>
)}

4 FastAPI로 점수 저장하기

점수 등록 버튼을 누르면 React가 Python 서버에 점수를 보내고, 서버가 scores.json 파일에 저장한다. 이게 서버에 저장되기 때문에 브라우저를 꺼도 데이터가 남아있다.

역할	주소	설명
점수 저장	POST /score	닉네임 + 점수 + 시간 보내면 json에 저장
리더보드 조회	GET /leaderboard	저장된 점수 상위 20개 가져오기

React → FastAPI 점수 전송 (fetch)

async function submitScore() {
  if (!nickname.trim()) return  // 닉네임 없으면 무시

  const res = await fetch('http://127.0.0.1:8000/score', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      nickname: nickname,
      score: finalScore,
      time: finalTime,
    })
  })

  const data = await res.json()

  if (data.duplicate) {
    alert('이미 존재하는 닉네임이에요!')
    return
  }

  setMyRank(data.rank)        // 내 순위 저장
  await fetchLeaderboard()   // 리더보드 새로고침
  setScreen('leaderboard')  // 리더보드 화면으로
}

FastAPI 서버 — 점수 저장 API (Python)

@app.post("/score")
def post_score(entry: ScoreEntry):
    scores = load_scores()

    # 닉네임 중복 체크
    existing = [s for s in scores if s["nickname"] == entry.nickname]
    if existing:
        return {"error": "중복 닉네임", "duplicate": True}

    # 점수 추가 후 내림차순 정렬
    scores.append(entry.model_dump())
    scores.sort(key=lambda x: x["score"], reverse=True)
    save_scores(scores)

    rank = next(i+1 for i, s in enumerate(scores)
                if s["nickname"] == entry.nickname)
    return {"rank": rank, "duplicate": False}

💡

fetch가 뭔가?
브라우저에서 서버로 데이터를 보내거나 받아오는 JavaScript 함수다. POST는 데이터를 보낼 때, GET은 데이터를 받아올 때 쓴다. await는 응답이 올 때까지 기다리는 키워드다.

✅

왜 새로고침해도 점수가 남아있나?
브라우저의 localStorage나 쿠키가 아니라 Python 서버의 scores.json 파일에 저장하기 때문이다. 브라우저를 껐다 켜도, 캐시를 지워도 서버 파일은 그대로 남아있다.

5 리더보드 화면

점수 등록이 끝나면 자동으로 리더보드로 이동한다. 서버에서 받아온 데이터를 map()으로 하나하나 화면에 그려주는 방식이다.

리더보드 데이터 불러오기 + 표시

// 서버에서 리더보드 데이터 가져오기
async function fetchLeaderboard() {
  const res = await fetch('http://127.0.0.1:8000/leaderboard')
  const data = await res.json()
  setLeaderboard(data)  // 상태에 저장
}

// 화면에 순위 표시
{leaderboard.slice(0, 10).map((entry, i) => (
  <div key={i}>
    <span>{i === 0 ? '🥇' : i === 1 ? '🥈' : i === 2 ? '🥉' : `${i+1}.`}</span>
    <span>{entry.nickname}</span>
    <span>{entry.score}pt</span>
    <span>{entry.time}s</span>
  </div>
))}

💡

map()이 뭔가?
배열의 각 항목을 변환해서 새 배열을 만드는 함수다. 서버에서 받은 점수 배열을 map()으로 순회하면서 각각을 HTML 요소로 변환해서 화면에 표시한다.

6 닉네임 중복 방지

같은 닉네임으로 여러 번 등록하면 리더보드가 도배되는 문제가 있었다. Python 서버에서 중복 체크를 해서 이미 있는 닉네임이면 등록을 막도록 했다.

Python — 닉네임 중복 체크

# 저장된 닉네임 중에 같은 게 있는지 확인
existing = [s for s in scores if s["nickname"] == entry.nickname.strip()]

if existing:
    return {"error": "이미 존재하는 닉네임", "duplicate": True}

# 중복 없으면 저장 진행

React — 중복이면 알림 표시

if (data.duplicate) {
  alert('❌ 이미 존재하는 닉네임이에요!\n다른 닉네임을 입력해주세요.')
  return  // 등록 중단
}

7 진짜 힘들었던 오류들

이번 파트에서 제일 고생한 게 오류들이었다. 특히 점프 관련 버그는 며칠을 잡았다.

🔴 오류 1 — 다시하기 누르면 점프가 아예 안 됨

다시하기 버튼을 누를 때마다 게임 루프가 새로 시작됐는데, 이전 루프가 완전히 안 끝난 채로 새 루프가 또 시작되는 거였다. keydown 이벤트 리스너도 계속 중복으로 쌓여서 결국 충돌이 났다. 해결법은 게임 루프 ID를 모듈 전역 변수 gAnimId와 gRunning으로 관리해서, 새 게임 시작 전에 이전 루프를 완전히 종료하는 거였다.

오류 1 해결 — 전역 변수로 루프 관리

// 컴포넌트 바깥에 선언 — 어디서든 접근 가능
let gAnimId = null
let gRunning = false

function startGame() {
  // 새 게임 시작 전에 이전 루프 완전 종료
  gRunning = false
  if (gAnimId) cancelAnimationFrame(gAnimId)

  gRunning = true

  function loop() {
    if (!gRunning) return  // 이전 루프면 즉시 종료
    ...
    gAnimId = requestAnimationFrame(loop)
  }
}

🔴 오류 2 — 점프는 되는데 캐릭터가 안 올라감

이건 정말 황당한 버그였다. 분명 점프 로직은 맞는데 화면에서 캐릭터가 꼼짝도 안 하는 거다. 한참 뒤에야 원인을 찾았는데, drawPlayer 함수에서 캐릭터 Y 위치를 player.y가 아닌 GROUND - ph로 고정해서 그리고 있었다. 물리 계산은 되고 있었는데 화면에 반영을 안 하고 있었던 거다.

오류 2 해결

// ❌ 잘못된 코드 — 항상 땅에 붙어서 그림
const y = GROUND - ph

// ✅ 수정 — 실제 물리 계산된 player.y 사용
const y = player.crouching ? GROUND - PH_CROUCH : player.y

🔴 오류 3 — canvas 숨기면 게임이 완전히 망가짐

처음엔 게임오버 화면으로 넘어갈 때 canvas를 display: none으로 숨겼다. 그랬더니 그 다음에 다시하기를 눌러도 아무것도 안 그려지는 거다. 이유는 canvas가 DOM에서 사라지면 useRef로 잡은 참조가 끊기기 때문이었다. canvas는 항상 DOM에 있어야 하고, 그 위에 오버레이를 position: absolute로 덮는 방식으로 바꿨다.

🔴 오류 4 — React StrictMode가 루프를 두 번 실행

개발 환경에서 React는 StrictMode라는 기능이 켜져있는데, 이게 useEffect를 의도적으로 두 번 실행한다. 그래서 게임 루프가 두 개 돌아가면서 이벤트가 완전히 꼬였다. main.jsx에서 StrictMode를 제거해서 해결했다.

🚨

다음에 꼭 기억할 것
1. canvas는 절대 DOM에서 숨기거나 제거하지 말 것
2. 게임 루프는 전역 변수로 관리해서 중복 실행 방지
3. drawPlayer에서 실제 player.y 쓰는지 확인
4. 게임에서 StrictMode는 제거

---

• 완료 시작 화면 + 조작법 안내
• 완료 게임오버 화면 + 점수/시간 표시
• 완료 닉네임 입력 + FastAPI 점수 저장
• 완료 닉네임 중복 방지
• 완료 리더보드 화면 + 내 순위 표시
• 완료 점프/다시하기 버그 수정
• 다음편 Vercel + Render로 배포하기

버그 잡는 게 코딩의 절반이다.

오류가 났을 때 포기하지 않고 원인을 찾아나가는 게 실력이 느는 방법인 것 같다.

다음 편에서는 만든 게임을 실제 서버에 올려서 누구나 접속할 수 있게 배포한다.

▶ 다음편: Vercel + Render로 배포하기