Expo Rn Game

빠른 시작 체크리스트

새 게임 프로젝트를 시작할 때 순서대로 따른다:

1. 프로젝트 세팅 → references/setup.md 참고
2. 게임 캔버스 구성 → references/rendering.md 참고
3. 게임 루프 구현 → references/game-loop.md 참고
4. 터치/제스처 연동 → references/gestures.md 참고
5. 상태 관리 설계 → references/state.md 참고
6. 아키텍처 정리 → references/architecture.md 참고
7. 성능 최적화 → references/optimization.md 참고

핵심 패턴 요약

Skia + Reanimated 연동 (가장 중요한 패턴)

import { useSharedValue } from 'react-native-reanimated';
import { Canvas, Circle } from '@shopify/react-native-skia';

// SharedValue를 Skia props에 직접 전달 → bridge 없이 UI 스레드에서 렌더링
const EnemySprite = ({ startX, startY }) => {
  const x = useSharedValue(startX);
  const y = useSharedValue(startY);

  return (
    <Canvas style={{ flex: 1 }}>
      <Circle cx={x} cy={y} r={15} color="crimson" />
    </Canvas>
  );
};

UI → JS 스레드 브릿지 (runOnJS)

import { runOnJS } from 'react-native-reanimated';

// worklet 안에서 Zustand 업데이트가 필요할 때
const tick = (frameInfo) => {
  'worklet';
  if (enemy.hp.value <= 0) {
    enemy.isAlive.value = false;
    // Zustand는 JS 스레드 → runOnJS 필수
    runOnJS(onEnemyKilled)(enemy.id.value, enemy.goldReward.value);
  }
};

제스처 + Reanimated + Skia 삼각 연동

import { Gesture, GestureDetector } from 'react-native-gesture-handler';
import { useSharedValue, withDecay, runOnJS } from 'react-native-reanimated';
import { Canvas, Group } from '@shopify/react-native-skia';

const RouletteWheel = ({ onSpinComplete }) => {
  const rotation = useSharedValue(0);

  const panGesture = useMemo(() =>
    Gesture.Pan()
      .onUpdate((e) => { 'worklet'; rotation.value += e.changeY * 0.01; })
      .onEnd((e) => {
        'worklet';
        rotation.value = withDecay(
          { velocity: e.velocityY * 0.005, deceleration: 0.997 },
          (finished) => { 'worklet'; if (finished) runOnJS(onSpinComplete)(rotation.value); }
        );
      }),
  [rotation, onSpinComplete]);

  return (
    <GestureDetector gesture={panGesture}>
      <Canvas style={{ width: 300, height: 300 }}>
        <Group transform={[{ rotate: rotation }]} origin={{ x: 150, y: 150 }}>
          {/* 룰렛 세그먼트 */}
        </Group>
      </Canvas>
    </GestureDetector>
  );
};

게임 장르별 주요 참고 파일

버전 요구사항 (2025 기준)

{
  "react-native": ">=0.79",
  "react": ">=19",
  "@shopify/react-native-skia": ">=2.0.0",
  "react-native-reanimated": ">=4.0.0",
  "react-native-gesture-handler": ">=2.0.0",
  "expo": ">=52"
}

React Native < 0.79라면 @shopify/[email protected] 이하를 사용해야 한다.

자주 발생하는 실수

1. worklet 안에서 Zustand 직접 호출 → runOnJS로 감싸야 한다
2. 제스처 객체를 매 렌더마다 재생성 → useMemo로 메모이제이션 필수
3. 프레임 콜백을 useCallback 없이 작성 → Reanimated 공식 권장사항 위반
4. Reanimated 3.x API 사용 → runOnUI, scheduleOnRuntime은 react-native-worklets로 이동됨
5. delta time 무시 → 프레임 독립적 이동을 위해 timeSincePreviousFrame / 1000을 반드시 곱한다

레퍼런스 파일 목록

• setup.md — 프로젝트 초기 세팅, 패키지 설치, babel 설정
• rendering.md — Skia Canvas, 드로잉 컴포넌트, 스프라이트, 파티클
• game-loop.md — useFrameCallback, 게임 루프, 타워 AI, 충돌 감지
• gestures.md — Tap/Pan 제스처, 룰렛 스핀, 타워 배치
• state.md — Zustand 스토어 설계, 선택적 구독
• architecture.md — 파일 구조, 스레드 분리 전략
• optimization.md — 성능 최적화, 알려진 이슈