66 Mini-Game: Marble Race

Mini-Game: Marble Race

완성:

Marble Race

---

🎮 게임 개요

• 플레이어는 구슬(마블)을 조종해 다양한 트랩이 있는 레벨을 통과해야 함.
• 기능
  • 키보드로 구슬 이동/점프
  • 구슬이 움직이기 시작하면 타이머 시작
  • 레벨 끝에 도달하면 Restart 버튼 표시
  • Restart 시 초기화 + 새로운 랜덤 트랩 생성 → 매번 다른 레벨

---

⚙️ Setup

• 기본 오브젝트: 오렌지 구체, 보라색 큐브, 초록색 바닥
• <Lights> 컴포넌트에 directionalLight + ambientLight 정의
• Shadows 활성화

<directionalLight 
    castShadow 
    position={[4, 4, 1]} 
    intensity={1.5} 
    shadow-mapSize={[1024, 1024]} 
    shadow-camera-near={1} 
    shadow-camera-far={10} 
    shadow-camera-top={10} 
    shadow-camera-right={10} 
    shadow-camera-bottom={-10} 
    shadow-camera-left={-10} 
/>

• OrbitControls 추가 (디버깅용, 나중에 제거)

---

레벨/트랩/플레이어 구현

---

🏗️ 레벨 구성

Level 컴포넌트 생성

/src/Level.jsx

// 레벨 컴포넌트
export default function Level() {
  return (
    <>
      <mesh castShadow position-x={-2}>
        <sphereGeometry />
        <meshStandardMaterial color="orange" />
      </mesh>
      <mesh castShadow position-x={2} scale={1.5}>
        <boxGeometry />
        <meshStandardMaterial color="mediumpurple" />
      </mesh>
      <mesh
        receiveShadow
        position-y={-1}
        rotation-x={-Math.PI * 0.5}
        scale={10}>
        <planeGeometry />
        <meshStandardMaterial color="greenyellow" />
      </mesh>
    </>
  );
}

→ 이후 Experience.jsx에서 불러오기:

import Level from './Level.jsx';

export default function Experience() {
  return (
    <>
      <OrbitControls makeDefault />
      <Lights />
      <Level />
    </>
  );
}

---

🧩 Physics 추가

npm install @react-three/rapier@2.0

import { Physics } from '@react-three/rapier';

export default function Experience() {
  return (
    <>
      <OrbitControls makeDefault />
      <Physics debug>
        <Lights />
        <Level />
      </Physics>
    </>
  );
}

---

🟩 블록 시스템

• 레벨은 여러 Block 단위로 구성
• BlockStart, BlockEnd, BlockSpinner, BlockLimbo, BlockAxe 등 구현
• 블록들은 <group>으로 감싸서 위치를 position prop으로 제어

BlockStart 예시

function BlockStart({ position = [0, 0, 0] }) {
  return (
    <group position={position}>
      <mesh
        geometry={boxGeometry}
        material={floor1Material}
        position={[0, -0.1, 0]}
        scale={[4, 0.2, 4]}
        receiveShadow
      />
    </group>
  );
}

---

📦 Geometry & Material 최적화

• 모든 블록에서 동일한 BoxGeometry, MeshStandardMaterial를 반복 생성 → 성능 저하
• 외부에서 한 번만 생성 후 재사용

import * as THREE from 'three';

const boxGeometry = new THREE.BoxGeometry(1, 1, 1);

// 재사용할 Material들
const floor1Material = new THREE.MeshStandardMaterial({ color: 'limegreen' });
const floor2Material = new THREE.MeshStandardMaterial({ color: 'greenyellow' });
const obstacleMaterial = new THREE.MeshStandardMaterial({ color: 'orangered' });
const wallMaterial = new THREE.MeshStandardMaterial({ color: 'slategrey' });

---

🔄 Spinner Trap (회전 장치)

BlockSpinner

import { RigidBody } from '@react-three/rapier';
import { useFrame } from '@react-three/fiber';
import { useState, useRef } from 'react';

export function BlockSpinner({ position = [0, 0, 0] }) {
  const obstacle = useRef();
  const [speed] = useState(
    () => (Math.random() + 0.2) * (Math.random() < 0.5 ? -1 : 1),
  );

  useFrame((state) => {
    const time = state.clock.getElapsedTime();
    const rotation = new THREE.Quaternion();
    rotation.setFromEuler(new THREE.Euler(0, time * speed, 0));
    obstacle.current.setNextKinematicRotation(rotation);
  });

  return (
    <group position={position}>
      {/* 바닥 */}
      <mesh
        geometry={boxGeometry}
        material={floor2Material}
        position={[0, -0.1, 0]}
        scale={[4, 0.2, 4]}
        receiveShadow
      />

      {/* 장애물 */}
      <RigidBody
        ref={obstacle}
        type="kinematicPosition"
        position={[0, 0.3, 0]}
        restitution={0.2}
        friction={0}>
        <mesh
          geometry={boxGeometry}
          material={obstacleMaterial}
          scale={[3.5, 0.3, 0.3]}
          castShadow
          receiveShadow
        />
      </RigidBody>
    </group>
  );
}

• kinematicPosition: 물리엔진의 힘이 아니라 코드로 직접 움직임 제어
• setNextKinematicRotation 으로 회전 구현
• useState로 랜덤 속도/방향 부여 → 블록마다 다르게 동작

---

⬆️ Limbo Trap (상하 이동 장치)

• setNextKinematicTranslation 사용
• Math.sin(time + offset) 활용해 상하 반복 운동 구현
• timeOffset을 랜덤 부여 → 블록 간 애니메이션 비동기화

---

⬅️➡️ Axe Trap (좌우 이동 장치)

• Limbo 구조와 동일, 단축 방향만 다름
• x축으로 이동하며 Math.sin(time) * 1.25 적용 → 양옆 왕복 운동

---

🍔 End Block

• 종료 블록에 hamburger.glb 모델 배치
• GLTF 로딩: useGLTF('./hamburger.glb')
• 물리 적용: <RigidBody type="fixed" colliders="hull" />
• 그림자 적용: hamburger.scene.children.forEach(mesh => mesh.castShadow = true)

---

🧱 Bounds (벽 & 바닥)

• 양쪽 벽, 끝 벽, 바닥에 RigidBody type="fixed" + CuboidCollider 추가
• 마찰력 & 반발력 조정

<RigidBody type="fixed" restitution={0.2} friction={0}> 
	<CuboidCollider 
    	args={[2, 0.1, 2 * length]} 
        position={[0, -0.1, -(length * 2) + 2]} 
        restitution={0.2} 
        friction={1} 
    /> 
</RigidBody>

현재까지 구현된 오브젝트들

---

🟣 Player (구슬)

/src/Player.jsx

import { RigidBody } from '@react-three/rapier';

export default function Player() {
  return (
    <RigidBody
      canSleep={false}
      colliders="ball"
      restitution={0.2}
      friction={1}
      linearDamping={0.5}
      angularDamping={0.5}
      position={[0, 1, 0]}>
      <mesh castShadow>
        <icosahedronGeometry args={[0.3, 1]} />
        <meshStandardMaterial flatShading color="mediumpurple" />
      </mesh>
    </RigidBody>
  );
}

• colliders="ball" → 회전 및 구르기 적합
• canSleep={false} → 물체가 절전 모드로 안 들어가게 설정
• linearDamping, angularDamping → 구슬이 점점 느려지도록 제어

---

중간 정리

• Level 시스템 구축 (Start, End, Traps)
• Physics 적용 (RigidBody, Collider)
• 3종 트랩 구현 (Spinner, Limbo, Axe)
• End Block 보상 (햄버거 모델)
• Bounds (벽 + 바닥 충돌 영역)
• Player 구슬 생성 (구현 완료)

---

카메라 추적, 조명, UI, 글로벌 상태 관리, 게임 메커닉(타이머/리셋) 구현

---

🎥 카메라 추적 (Camera Controller)

플레이어 구슬을 따라다니는 카메라 구현:

import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';
import { useRapier } from '@react-three/rapier';
import * as THREE from 'three';

export default function CameraController({ player }) {
  const cameraTarget = useRef(new THREE.Vector3());

  useFrame((state) => {
    if (!player.current) return;

    // 플레이어 위치 가져오기
    const playerPos = player.current.translation();

    // 목표 카메라 위치 (뒤쪽 & 위쪽 오프셋)
    const idealCameraPos = new THREE.Vector3(
      playerPos.x,
      playerPos.y + 2,
      playerPos.z + 5,
    );

    // Lerp로 부드럽게 추적
    state.camera.position.lerp(idealCameraPos, 0.05);
    state.camera.lookAt(playerPos.x, playerPos.y + 0.5, playerPos.z);
  });
}

• player.current.translation() : Rapier rigid body 위치
• lerp(Linear Interpolation)으로 카메라 움직임을 부드럽게
• lookAt을 사용해 항상 구슬을 응시

---

💡 조명 (Lights 최적화)

• 게임 전체가 다 보이도록 기본 조명 보완
• 그림자 품질 유지하면서 성능도 고려해야 함

export function Lights() {
  return (
    <>
      <ambientLight intensity={0.3} />
      <directionalLight
        castShadow
        position={[5, 10, 5]}
        intensity={1.5}
        shadow-mapSize={[1024, 1024]}
        shadow-camera-far={20}
        shadow-camera-left={-10}
        shadow-camera-right={10}
        shadow-camera-top={10}
        shadow-camera-bottom={-10}
      />
    </>
  );
}

---

🕹️ 키보드 컨트롤 (Keyboard Controls)

Zustand Store 생성

npm install zustand

import create from 'zustand';

export const useGameControls = create((set) => ({
  forward: false,
  backward: false,
  left: false,
  right: false,
  jump: false,
  setKey: (key, value) => set((state) => ({ ...state, [key]: value })),
}));

이벤트 리스너

useEffect(() => {
  const handleKeyDown = (e) => {
    if (e.code === 'ArrowUp' || e.code === 'KeyW') setKey('forward', true);
    if (e.code === 'ArrowDown' || e.code === 'KeyS') setKey('backward', true);
    if (e.code === 'ArrowLeft' || e.code === 'KeyA') setKey('left', true);
    if (e.code === 'ArrowRight' || e.code === 'KeyD') setKey('right', true);
    if (e.code === 'Space') setKey('jump', true);
  };

  const handleKeyUp = (e) => {
    if (e.code === 'ArrowUp' || e.code === 'KeyW') setKey('forward', false);
    if (e.code === 'ArrowDown' || e.code === 'KeyS') setKey('backward', false);
    if (e.code === 'ArrowLeft' || e.code === 'KeyA') setKey('left', false);
    if (e.code === 'ArrowRight' || e.code === 'KeyD') setKey('right', false);
    if (e.code === 'Space') setKey('jump', false);
  };

  window.addEventListener('keydown', handleKeyDown);
  window.addEventListener('keyup', handleKeyUp);

  return () => {
    window.removeEventListener('keydown', handleKeyDown);
    window.removeEventListener('keyup', handleKeyUp);
  };
}, []);

---

⚡ Player 이동 제어

Player.jsx 내에서 Rapier force 적용:

import { useRef } from 'react';
import { useFrame } from '@react-three/fiber';
import { RigidBody } from '@react-three/rapier';
import { useGameControls } from './store';

/**
 * Player
 * - 설계 의도: 구(마블) 형태의 플레이어를 물리로 굴리며 이동/점프시키는 컨트롤러
 * - 구조상의 이유:
 *   1) 이동은 '임펄스(impulse)'로 밀어 간단하고 반응성 좋은 제어를 구현
 *   2) 점프는 현재 선속도(linvel)로 '지면 접촉에 가까운 상태'를 판정해 중복 점프 방지
 *   3) 물리 매개변수(마찰/반발/댐핑)로 자연스러운 감속과 바닥 접지력 확보
 */
export default function Player() {
  // body: Rapier RigidBody에 접근하기 위한 ref
  //   - 타입(개념): React.RefObject<RapierRigidBody>
  const body = useRef();

  // controls: 전역/로컬 스토어에서 가져온 현재 입력 상태
  //   - 구조(예): { forward:boolean, backward:boolean, left:boolean, right:boolean, jump:boolean }
  const controls = useGameControls();

  /**
   * useFrame
   * - 매 프레임 호출되어 물리 힘(impulse)을 적용
   * - 매개변수:
   *   - state: RenderLoop 상태(여기서는 미사용)
   *   - delta: number — 이전 프레임 대비 경과 시간(초). 프레임 독립 움직임을 원하면 스케일링에 사용
   */
  useFrame(() => {
    if (!body.current) return;

    /**
     * impulse: { x:number, y:number, z:number }
     * - 역할: 한 프레임 동안 물체에 '순간적인 선형 운동량'을 부여
     * - 단위(개념): 질량 * 속도
     * - 적용 방향:
     *    X: 좌/우, Z: 전/후 (three.js/R3F는 보통 -Z가 '앞')
     * - 참고: delta를 곱해 프레임 독립적 제어를 할 수 있으나,
     *   여기선 고정 값(0.02)으로 반응성을 높임.
     */
    const impulse = { x: 0, y: 0, z: 0 };

    // 이동 입력 → 임펄스 누적
    if (controls.forward)  impulse.z -= 0.02; // -Z 방향(앞)
    if (controls.backward) impulse.z += 0.02; // +Z 방향(뒤)
    if (controls.left)     impulse.x -= 0.02; // -X 방향(좌)
    if (controls.right)    impulse.x += 0.02; // +X 방향(우)

    /**
     * applyImpulse(impulse, wakeUp?)
     * - 매개변수:
     *   - impulse: { x,y,z }  | 타입: VectorLike
     *   - wakeUp?: boolean     | true면 수면(sleep) 중인 바디를 깨움
     * - 설계 의도: 키 입력마다 짧고 작은 힘을 계속 누적 → '굴러가는' 느낌
     */
    body.current.applyImpulse(impulse, true);

    /**
     * 점프
     * - 설계 의도: 공중에서 연타 점프를 막기 위해 '수직 속도'로 접지 상태 근사
     * - linvel(): 현재 선속도 벡터 반환 | 타입: { x:number, y:number, z:number }
     * - 임계값 0.05:
     *    |vel.y|가 작다면 바닥에 거의 붙어 있는 상태로 간주(완벽한 접지 판정은 아님)
     *   → 실제로는 raycast/Contact 이벤트로 더 정확히 판정 가능
     */
    if (controls.jump) {
      const vel = body.current.linvel();
      if (Math.abs(vel.y) < 0.05) {
        // applyImpulse로 위쪽(y+) 방향 가속 → 튀어 오름
        body.current.applyImpulse({ x: 0, y: 0.4, z: 0 }, true);
      }
    }
  });

  return (
    <RigidBody
      ref={body}
      /**
       * colliders="ball"
       * - 역할: 구형 콜라이더 사용(회전/굴림 시 접촉이 안정적)
       */
      colliders="ball"
      /**
       * restitution: number
       * - 역할: 반발계수(bounciness). 0에 가까울수록 덜 튀고, 1에 가까울수록 잘 튐
       * - 여기선 0.2 → 약간만 튀도록
       */
      restitution={0.2}
      /**
       * friction: number
       * - 역할: 마찰 계수. 구가 바닥에서 '굴러가며 전진'하도록 필수
       * - 너무 낮으면 헛돌고, 너무 높으면 갑자기 멈칫거릴 수 있음
       */
      friction={1}
      /**
       * linearDamping / angularDamping: number
       * - 역할: 선속/각속 감쇠(공기저항 같은 감쇠 효과)
       * - 키에서 손을 떼면 서서히 멈추도록 0.5로 세팅(취향껏 조정)
       */
      linearDamping={0.5}
      angularDamping={0.5}
      /**
       * position: [x,y,z]
       * - 시작 위치(바닥에서 살짝 띄워 스폰)
       */
      position={[0, 1, 0]}
    >
      <mesh castShadow>
        {/* 반지오십이면체: 구와 비슷하지만 면이 살아 있어 회전이 시각적으로 잘 보임 */}
        <icosahedronGeometry args={[0.3, 1]} />
        {/**
         * meshStandardMaterial
         * - flatShading: true → 면 단위 음영으로 회전감 강조
         */}
        <meshStandardMaterial flatShading color="mediumpurple" />
      </mesh>
    </RigidBody>
  );
}

---

⏱️ 타이머 & UI

Zustand에 게임 상태 추가

export const useGame = create((set) => ({
  phase: 'ready', // ready, playing, ended
  startTime: 0,
  endTime: 0,
  start: () => set({ phase: 'playing', startTime: Date.now() }),
  end: () => set({ phase: 'ended', endTime: Date.now() }),
  restart: () => set({ phase: 'ready', startTime: 0, endTime: 0 }),
}));

HUD UI

import { Html } from '@react-three/drei';
import { useGame } from './store';

export function Interface() {
  const phase = useGame((state) => state.phase);
  const startTime = useGame((state) => state.startTime);
  const endTime = useGame((state) => state.endTime);

  let elapsed = 0;
  if (phase === 'playing') elapsed = (Date.now() - startTime) / 1000;
  if (phase === 'ended') elapsed = (endTime - startTime) / 1000;

  return (
    <Html position={[0, 2, 0]} center>
      <div className="hud">
        {phase !== 'ready' && <h1>{elapsed.toFixed(2)}s</h1>}
        {phase === 'ended' && (
          <button onClick={() => useGame.getState().restart()}>Restart</button>
        )}
      </div>
    </Html>
  );
}

---

🔄 Restart 기능

• Restart 시:
  • Player 위치 초기화
  • 타이머 초기화
  • 레벨 재랜덤 생성

function RestartButton() {
  const restart = useGame((state) => state.restart);
  return (
    <button onClick={restart} className="restart-btn">
      Restart
    </button>
  );
}

---

🎉 최종 구조

src/
 ├── Experience.jsx
 ├── Level.jsx
 ├── Player.jsx
 ├── CameraController.jsx
 ├── Lights.jsx
 ├── store.js   (zustand 상태 관리)
 ├── Interface.jsx
 └── assets/
      └── hamburger.glb

---

정리

• 카메라 추적 : 플레이어를 따라오는 부드러운 카메라
• 조명 최적화 : 성능 고려한 그림자 세팅
• Zustand 상태 관리 : 키보드 입력 & 게임 상태 관리
• 플레이어 이동 제어 : Rapier impulse를 이용한 이동/점프
• UI & 타이머 : 게임 시간 표시, Restart 버튼
• Restart 메커닉 : 레벨 리셋 + 새로운 트랩 배치

---

// index.jsx
import './style.css';
import ReactDOM from 'react-dom/client';
import { Canvas } from '@react-three/fiber';
import Experience from './Experience.jsx';
import { KeyboardControls } from '@react-three/drei';
import Interface from './Interface.jsx';

const root = ReactDOM.createRoot(document.querySelector('#root'));

root.render(
  <KeyboardControls
    map={[
      {
        name: 'forward',
        keys: ['ArrowUp', 'KeyW'],
      },
      {
        name: 'backward',
        keys: ['ArrowDown', 'KeyS'],
      },
      {
        name: 'leftward',
        keys: ['ArrowLeft', 'KeyA'],
      },
      {
        name: 'rightward',
        keys: ['ArrowRight', 'KeyD'],
      },
      {
        name: 'jump',
        keys: ['Space'],
      },
    ]}>
    <Canvas
      shadows
      camera={{
        fov: 45,
        near: 0.1,
        far: 200,
        position: [2.5, 4, 6],
      }}>
      <Experience />
    </Canvas>
    <Interface />
  </KeyboardControls>,
);

// Experience.jsx
import { OrbitControls } from '@react-three/drei';
import Lights from './Lights.jsx';
import { Level } from './Level.jsx';
import { Physics } from '@react-three/rapier';
import { Perf } from 'r3f-perf';
import Player from './Player.jsx';
import useGame from './stores/useGame.js';

export default function Experience() {
  const blocksCount = useGame((state) => state.blocksCount);
  const blockSeed = useGame((state) => state.blockSeed);

  return (
    <>
      <color args={['#bdedfc']} attach="background" />
      <Perf position="top-left" />
      <OrbitControls makeDefault />

      <Physics debug={false}>
        <Lights />
        <Level count={blocksCount} seed={blockSeed} />
        <Player />
      </Physics>
    </>
  );
}

// Light.jsx
import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';

export default function Lights() {
  const light = useRef();

  // 카메라가 앞으로 이동할 때(현재 Z축) 빛도 함께 이동시켜 그림자 맵이 플레이어 주변을 덮도록.
  useFrame((state) => {
    light.current.position.z = state.camera.position.z + 1 - 4;
    light.current.target.position.z = state.camera.position.z - 4;
    light.current.target.updateMatrixWorld();
  });

  return (
    <>
      <directionalLight
        ref={light}
        castShadow
        position={[4, 4, 1]}
        intensity={4.5}
        shadow-mapSize={[1024, 1024]}
        shadow-camera-near={1}
        shadow-camera-far={10}
        shadow-camera-top={10}
        shadow-camera-right={10}
        shadow-camera-bottom={-10}
        shadow-camera-left={-10}
      />
      <ambientLight intensity={1.5} />
    </>
  );
}

// Level.jsx
import * as THREE from 'three';
import { CuboidCollider, RigidBody } from '@react-three/rapier';
import { useState, useRef, useMemo } from 'react';
import { useFrame } from '@react-three/fiber';
import { Float, Text, useGLTF } from '@react-three/drei';

const boxGeometry = new THREE.BoxGeometry(1, 1, 1);
const floorMaterial = new THREE.MeshStandardMaterial({ color: 'limegreen' });
const floor2Material = new THREE.MeshStandardMaterial({ color: 'greenyellow' });
const obstacleMaterial = new THREE.MeshStandardMaterial({ color: 'orangered' });
const wallMaterial = new THREE.MeshStandardMaterial({ color: 'slategrey' });

function BlockStart({ position = [0, 0, 0] }) {
  return (
    <group position={position}>
      <Float floatIntensity={0.25} rotationIntensity={0.25}>
        <Text
          font="./bebas-neue-v9-latin-regular.woff"
          scale={0.5}
          maxWidth={0.25}
          lineHeight={0.75}
          textAlign="right"
          position={[0.75, 0.65, 0]}
          rotation-y={-0.25}>
          Marble Race
          <meshBasicMaterial toneMapped={false} />
        </Text>
      </Float>

      {/* Floor */}
      <mesh
        geometry={boxGeometry}
        material={floorMaterial}
        position={[0, -0.1, 0]}
        scale={[4, 0.2, 4]}
        receiveShadow
      />
    </group>
  );
}
function BlockEnd({ position = [0, 0, 0] }) {
  const hamburger = useGLTF('./hamburger.glb');

  // burger shadow on
  hamburger.scene.children.forEach((mesh) => {
    mesh.castShadow = true;
  });
  return (
    <group position={position}>
      <Text
        font="./bebas-neue-v9-latin-regular.woff"
        scale={1}
        position={[0, 2.25, 2]}>
        Finish
        <meshBasicMaterial toneMapped={false} />
      </Text>
      {/* Floor */}
      <mesh
        geometry={boxGeometry}
        material={floorMaterial}
        position={[0, 0, 0]}
        scale={[4, 0.2, 4]}
        receiveShadow
      />
      <RigidBody
        type="fixed"
        colliders="hull"
        position={[0, 0.25, 0]}
        restitution={0.2}
        castShadow
        friction={0}>
        <primitive castShadow object={hamburger.scene} scale={0.2} />
      </RigidBody>
    </group>
  );
}

export function BlockSpinner({ position = [0, 0, 0] }) {
  const obstacle = useRef();
  const [speed] = useState(
    // 최소 회전 속도 0.2 * 회전 방향 설정
    () => (Math.random() + 0.2) * (Math.random() < 0.5 ? -1 : 1),
  );

  useFrame((state) => {
    const time = state.clock.elapsedTime;

    const rotation = new THREE.Quaternion();
    rotation.setFromEuler(new THREE.Euler(0, time * speed, 0));
    obstacle.current.setNextKinematicRotation(rotation);
  });

  return (
    <group position={position}>
      {/* Floor */}
      <mesh
        geometry={boxGeometry}
        material={floor2Material}
        position={[0, -0.1, 0]}
        scale={[4, 0.2, 4]}
        receiveShadow
      />

      {/* obstacle */}
      <RigidBody
        ref={obstacle}
        type="kinematicPosition"
        position={[0, 0.3, 0]}
        restitution={0.2}
        friction={0}>
        <mesh
          geometry={boxGeometry}
          material={obstacleMaterial}
          scale={[3.5, 0.3, 0.3]}
          castShadow
          receiveShadow
        />
      </RigidBody>
    </group>
  );
}
export function BlockLimbo({ position = [0, 0, 0] }) {
  const obstacle = useRef();
  const [timeOffset] = useState(() => Math.random() * Math.PI * 2);

  useFrame((state) => {
    const time = state.clock.elapsedTime;

    const y = Math.sin(time * timeOffset) + 1.15;
    obstacle.current.setNextKinematicTranslation({
      x: position[0],
      y: position[1] + y,
      z: position[2],
    });
  });

  return (
    <group position={position}>
      {/* Floor */}
      <mesh
        geometry={boxGeometry}
        material={floor2Material}
        position={[0, -0.1, 0]}
        scale={[4, 0.2, 4]}
        receiveShadow
      />

      <RigidBody
        ref={obstacle}
        type="kinematicPosition"
        position={[0, 0.3, 0]}
        restitution={0.2}
        friction={0}>
        <mesh
          geometry={boxGeometry}
          material={obstacleMaterial}
          scale={[3.5, 0.3, 0.3]}
          castShadow
          receiveShadow
        />
      </RigidBody>
    </group>
  );
}
export function BlockAxe({ position = [0, 0, 0] }) {
  const obstacle = useRef();
  const [timeOffset] = useState(() => Math.random() * Math.PI * 2);

  useFrame((state) => {
    const time = state.clock.elapsedTime;

    const x = Math.sin(time * timeOffset) * 1.25;
    obstacle.current.setNextKinematicTranslation({
      x: position[0] + x,
      y: position[1] + 0.75,
      z: position[2],
    });
  });

  return (
    <group position={position}>
      {/* Floor */}
      <mesh
        geometry={boxGeometry}
        material={floor2Material}
        position={[0, -0.1, 0]}
        scale={[4, 0.2, 4]}
        receiveShadow
      />

      <RigidBody
        ref={obstacle}
        type="kinematicPosition"
        position={[0, 0.3, 0]}
        restitution={0.2}
        friction={0}>
        <mesh
          geometry={boxGeometry}
          material={obstacleMaterial}
          scale={[1.5, 1.5, 0.3]}
          castShadow
          receiveShadow
        />
      </RigidBody>
    </group>
  );
}

// Walls
function Bounds({ length = 1 }) {
  return (
    <RigidBody type="fixed" restitution={0.2} friction={0}>
      {/* Right wall */}
      <mesh
        position={[2.15, 0.75, -(length * 2) + 2]}
        geometry={boxGeometry}
        material={wallMaterial}
        scale={[0.3, 1.5, 4 * length]}
        castShadow
      />
      {/* Left wall */}
      <mesh
        position={[-2.15, 0.75, -(length * 2) + 2]}
        geometry={boxGeometry}
        material={wallMaterial}
        scale={[0.3, 1.5, 4 * length]}
        receiveShadow
      />
      {/* End wall */}
      <mesh
        position={[0, 0.75, -(length * 4) + 2]}
        geometry={boxGeometry}
        material={wallMaterial}
        scale={[4, 1.5, 0.3]}
        receiveShadow
      />
      {/* Floor collider */}
      <CuboidCollider
        args={[2, 0.1, 2 * length]}
        position={[0, -0.1, -(length * 2) + 2]}
        restitution={0.2}
        friction={1} // friction이 있어야 굴러감.
      />
    </RigidBody>
  );
}

export function Level({
  count = 5,
  types = [BlockSpinner, BlockAxe, BlockLimbo],
  seed = 0,
}) {
  const blocks = useMemo(() => {
    const blocks = [];

    for (let i = 0; i < count; i++) {
      const type = types[Math.floor(Math.random() * types.length)];
      blocks.push(type);
    }

    return blocks;
  }, [count, types, seed]);

  return (
    <>
      <BlockStart position={[0, 0, 0]} />

      {blocks.map((Block, index) => (
        <Block key={index} position={[0, 0, -(index + 1) * 4]} />
      ))}
      <Bounds length={count + 2} />

      <BlockEnd position={[0, 0, -(count + 1) * 4]} />
    </>
  );
}

// Player.jsx
import { useRapier, RigidBody } from '@react-three/rapier';
import { useFrame } from '@react-three/fiber';
import { useKeyboardControls } from '@react-three/drei';
import { useCallback, useEffect, useRef, useState } from 'react';
import * as THREE from 'three';
import useGame from './stores/useGame';

export default function Player() {
  const body = useRef();
  // index.js KeyboardControls와 연결되어 있음.
  const [subscribeKeys, getKeys] = useKeyboardControls();
  const { rapier, world } = useRapier();

  const [smoothedCameraPosition] = useState(
    // camera position 초기값 설정으로 player까지 가는 애니메이션 설정
    () => new THREE.Vector3(10, 10, 10),
  );
  const [smoothedCameraTarget] = useState(() => new THREE.Vector3());
  const start = useGame((state) => state.start);
  const end = useGame((state) => state.end);
  const restart = useGame((state) => state.restart);
  const blocksCount = useGame((state) => state.blocksCount);

  /**
   * Jump
   */
  const jump = useCallback(() => {
    if (!body.current) return;

    // 1) 원점: 구의 아래쪽 가장자리보다 살짝 더 아래
    // RigidBody의 월드 위치를 {x:number, y:number, z:number}로 반환.
    const origin = body.current.translation();
    // 구(반지름 0.3)의 아래쪽 가장자리보다 살짝 더 아래에서 레이를 쏘려고 0.31만큼 내림
    origin.y -= 0.31; // radius 0.3 + epsilon

    // 2) 아래 방향(-y로 ,단위 벡터)
    const direction = { x: 0, y: -1, z: 0 };

    // 3) Ray 생성 + 캐스팅
    const ray = new rapier.Ray(origin, direction); // 구의 -0.31지점에서, 아래 방향으로
    // ray: 위에서 만든 레이
    // maxToi: 최대 충돌 길이(월드 유닛) — 여기선 10
    // solid: true면 콜라이더 내부에서 시작해도 즉시 교차로 간주(= “고체처럼” 취급)
    const hit = world.castRay(ray, 10, true); // maxToi=10, solid=true

    // 4) 버전별 필드 호환, hit.toi(이전 버전) == hit.TimeOfImpact(히트 지점까지의 거리 = t * 거리)
    const toi = hit ? hit.timeOfImpact ?? hit.toi : null;

    // 5) 접지 임계 판정 후 점프
    if (toi !== null && toi < 0.15) {
      body.current.applyImpulse({ x: 0, y: 0.5, z: 0 }, true);
    }
  }, [world, rapier]);

  const reset = () => {
    body.current.setTranslation({ x: 0, y: 1, z: 0 });
    body.current.setLinvel({ x: 0, y: 0, z: 0 });
    body.current.setAngvel({ x: 0, y: 0, z: 0 });
  };

  useEffect(() => {
    const unsubscribeReset = useGame.subscribe(
      (state) => {
        return state.phase;
      },
      (value) => {
        if (value === 'ready') reset();
      },
    );

    const unsubscribeJump = subscribeKeys(
      // state: const state = getKeys();와 같은 값을 리턴
      (state) => state.jump, // selector
      // jump boolean 값을 return
      (pressed) => {
        if (pressed) jump();
      }, // listener
    );

    // phase
    const unsubscribeAny = subscribeKeys(() => {
      start();
    });

    // cleanup: 마운트 해제/리렌더 시 안전
    return () => {
      unsubscribeReset();
      unsubscribeJump();
      unsubscribeAny();
    };
  }, [subscribeKeys, jump]);

  useFrame((state, delta) => {
    /**
     * Controls
     */
    const { forward, backward, leftward, rightward } = getKeys();

    const impulse = { x: 0, y: 0, z: 0 };
    const torque = { x: 0, y: 0, z: 0 };

    const impulseStrength = 0.6 * delta;
    const torqueStrength = 0.2 * delta;

    if (forward) {
      impulse.z -= impulseStrength; // 직접 밀면서 -Z로 이동
      torque.x -= torqueStrength; // X축으로 회전 토크 = -Z로 굴러가게끔(부호 맞춘 것)
    }
    if (backward) {
      impulse.z += impulseStrength;
      torque.x += torqueStrength;
    }
    if (rightward) {
      impulse.x += impulseStrength;
      torque.z -= torqueStrength;
    }
    if (leftward) {
      impulse.x -= impulseStrength;
      torque.z += torqueStrength;
    }

    body.current.applyImpulse(impulse);
    // 회전 TorqueImpulse 이해하기
    // 바퀴(또는 구체)의 전진 방향은 항상 회전축과 직교한다.
    // R3F(위=Y) 기준으로 X축으로 회전시키면 Z축 방향(보통 −Z)으로 굴러 전진한다.
    // 바닥과의 마찰이 있어야 회전이 병진으로 바뀌며, 마찰이 없으면 제자리에서 헛돈다.
    // Blender에서 X축 회전(R → X) 을 떠올리면 이해가 쉽다(좌표계 차이는 감안).
    // 자동차의 경우 두 바퀴를 잇는 차축(X축) 이 회전축이고, 차량은 그 축에 직교하는 진행축(앞/뒤)으로 나아간다.
    body.current.applyTorqueImpulse(torque);

    /**
     * Camera
     */
    const bodyPosition = body.current.translation();

    // new THREE.Vector3()에 값을 복사해 두는 게 안전
    // const [cameraPosition] = useState(() => new THREE.Vector3());로 만들어서 재사용하는 방법도 있음.
    const cameraPosition = new THREE.Vector3();
    cameraPosition.copy(bodyPosition); // copy 대신 set도 가능
    cameraPosition.z += 2.25;
    cameraPosition.y += 0.65;

    const cameraTarget = new THREE.Vector3();
    cameraTarget.copy(bodyPosition);
    cameraTarget.y += 0.25;

    // Vector3.lerp(v: THREE.Vector3Like, alpha: number)
    // Linear Interpolation(lerp): 이전 값을 담아서 두 vector3 사이에 중간점을 찾음.
    smoothedCameraPosition.lerp(cameraPosition, 5 * delta); // 비교 vec3 , alpha
    smoothedCameraTarget.lerp(cameraTarget, 5 * delta);

    // 카메라 포지션 지정과 카메라 방향 지정
    state.camera.position.copy(smoothedCameraPosition); // 카메라 world 위치 변경
    state.camera.lookAt(smoothedCameraTarget); // 회전 변경

    /**
     * Phases
     */
    if (bodyPosition.z < -(blocksCount * 4 + 2)) {
      end();
    }
    if (bodyPosition.y < -4) {
      restart();
    }
  });

  return (
    <RigidBody
      ref={body}
      canSleep={false} // 잠들면 키보드가 동작하지 않으므로 sleep false 설정
      colliders="ball"
      restitution={0.2}
      friction={1}
      position={[0, 1, 0]}
      linearDamping={0.5} // 선속 감쇠 (키에서 손을 떼면 서서히 멈추도록 0.5로 세팅)
      angularDamping={0.5} // 각속도 감쇠
    >
      <mesh castShadow>
        <icosahedronGeometry args={[0.3, 1]} />
        <meshStandardMaterial
          flatShading // segment 보이도록
          color="mediumpurple"
        />
      </mesh>
    </RigidBody>
  );
}

// interface.jsx
import { useKeyboardControls } from '@react-three/drei';
import useGame from './stores/useGame';
import { useEffect, useRef } from 'react';
import { addEffect } from '@react-three/fiber';

export default function Interface() {
  const time = useRef();

  const restart = useGame((state) => state.restart);
  const phase = useGame((state) => state.phase);

  const forward = useKeyboardControls((state) => state.forward);
  const backward = useKeyboardControls((state) => state.backward);
  const leftward = useKeyboardControls((state) => state.leftward);
  const rightward = useKeyboardControls((state) => state.rightward);
  const jump = useKeyboardControls((state) => state.jump);

  useEffect(() => {
    // addEffect: canvas 밖에서도 useFrame 다음 호출됨.
    const unsubscribeEffect = addEffect(() => {
      const state = useGame.getState();

      let elapsedTime = 0;

      if (state.phase === 'playing') elapsedTime = Date.now() - state.startTime;
      else if (state.phase === 'ended')
        elapsedTime = state.endTime - state.startTime;

      elapsedTime /= 1000;
      elapsedTime = elapsedTime.toFixed(2);

      if (time.current) time.current.textContent = elapsedTime;
    });

    return () => {
      unsubscribeEffect();
    };
  }, []);

  return (
    <div className="interface">
      {/* Time */}
      <div ref={time} className="time">
        0.00
      </div>

      {/* Restart */}
      {phase === 'ended' && (
        <div className="restart" onClick={restart}>
          RESTART
        </div>
      )}

      {/* Controls */}
      <div className="controls">
        <div className="raw">
          <div className={`key ${forward ? 'active' : ''}`}></div>
        </div>
        <div className="raw">
          <div className={`key ${leftward ? 'active' : ''}`}></div>
          <div className={`key ${backward ? 'active' : ''}`}></div>
          <div className={`key ${rightward ? 'active' : ''}`}></div>
        </div>
        <div className="raw">
          <div className={`key large ${jump ? 'active' : ''}`}></div>
        </div>
      </div>
    </div>
  );
}

js:

// useGame.js
import { create } from 'zustand';
import { subscribeWithSelector } from 'zustand/middleware';

export default create(
  subscribeWithSelector((set) => {
    return {
      blocksCount: 10,
      blockSeed: 0,

      // Time
      startTime: 0,
      endTime: 0,

      // Phases
      phase: 'ready',

      start: () => {
        set((state) => {
          if (state.phase === 'ready')
            return { phase: 'playing', startTime: Date.now() };

          return {};
        });
      },
      restart: () => {
        set((state) => {
          if (state.phase === 'playing' || state.phase === 'ended')
            return { phase: 'ready', blockSeed: Math.random() };

          return {};
        });
      },
      end: () => {
        set((state) => {
          if (state.phase === 'playing')
            return { phase: 'ended', endTime: Date.now() };

          return {};
        });
      },
    };
  }),
);

css:

html,
body,
#root {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background: ivory;
}

@font-face {
  font-family: 'Bebas Neue'; /* A name you choose for your font */
  src: url('./bebas-neue-v9-latin-regular.woff') format('woff');
  font-weight: normal; /* Define font weight if applicable */
  font-style: normal; /* Define font style if applicable */
  font-display: swap; /* Optional: Controls font loading behavior */
}

/* Interface */
.interface {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  pointer-events: none;
  font-family: 'Bebas Neue', sans-serif;
}

/* Time */
.time {
  position: absolute;
  top: 15%;
  left: 0;
  width: 100%;
  color: #fff;
  font-size: 6vh;
  background-color: #00000033;
  padding-top: 5px;
  text-align: center;
}
/* Restart */
.restart {
  display: flex;
  justify-content: center;
  position: absolute;
  top: 40%;
  left: 0;
  width: 100%;
  color: #fff;
  font-size: 80px;
  background: #00000033;
  padding-top: 10px;
  pointer-events: auto;
  cursor: pointer;
}

/* Controls */
.controls {
  position: absolute;
  bottom: 10%;
  left: 0;
  width: 100%;
}

.controls .raw {
  display: flex;
  justify-content: center;
}

.controls .key {
  width: 40px;
  height: 40px;
  margin: 4px;
  border: 2px solid #ffffff;
  background: #ffffff44;
}

.controls .key.large {
  width: 144px;
}

.controls .key.active {
  background: #ffffff99;
}