게임 구축하기
플레이 가능하고 올바른 브라우저 게임을 만드세요 — 정적 스크린샷이 아닙니다. 게임은 React 라우트에 <canvas>(또는 R3F의 <Canvas>)와 DOM 오버레이 UI를 더한 것입니다. 오버레이(시작 화면, HUD, 메뉴)는 design-ui 스킬로 스타일링하고, 이 스킬은 게임플레이 루프와 월드를 담당합니다.
컨트롤 / 반전된 A/D: WASD, 조향, 비행 입력을 구현하기 전에 .grok/skills/controls/SKILL.md 를 열어야 합니다. 차량/비행 데모는 이 파일이나 단일 장르 플레이북만 참고하면 A/D가 뒤바뀐 상태로 제공되는 경우가 많습니다.
범위 참고 — 싱글 플레이어, 봇, 또는 소규모 P2P 협동:
- 기본적으로 싱글 플레이어 또는 싱글 플레이어 + AI/봇을 제공합니다.
- 2~8인 협동 / 캐주얼 실시간(공유 커서, 파티 게임, 친구 간 캐주얼 액션)을 지원합니다. 이 경우
multiplayer-p2p스킬(WebRTC mesh,/api/rtc에서 시그널링)을 사용하세요. 먼저 신뢰 모델을 읽어보세요. - P2P가 현재 지원되는 유일한 멀티플레이어 방식입니다. 연결할 수 없는 소켓을 반쯤 만들지 마세요.
참고 자료(필요할 때 불러오기):
controls스킬(../controls/) — 이동/조향/비행에 필수: 플레이어가 볼 수 있는 A/D, 반전 조향 안티패턴, 비행 에일러론, 필수 자체 테스트 +window.__controlsTest. 차량/비행의 경우 선택이 아닙니다.references/threejs-foundational.md— 심층 3D/루프/성능 참고 자료. 3D 작업 시 읽어보세요.references/3d-libs.md— three.js + @react-three/fiber + drei + rapier 사용법.threejs스킬(../threejs/) — 공식 전체 Three.js + TSL API 덤프(llms-full.txt). 고급 재질/셰이더/WebGPU/로더에 사용하며, 간단한 2D 캔버스 게임에는 필요하지 않습니다.references/babylon.md— 배터리 포함 3D 엔진 대안인 Babylon.js.references/phaser.md— 2D 게임의 기본 엔진인 Phaser 3.references/ecs-architecture.md— 대규모 게임을 위한 엔티티-컴포넌트-시스템 구조.references/genres/*.md— 장르별 플레이북(FPS, platformer-2d, racing-kart, puzzle-match3-tetris, voxel-minecraft, endless-runner, topdown-twin-stick, tower-defense, board-card-chess). 장르 파일은controls를 대체하지 않습니다.references/game-feel-juice.md,input.md,audio.md,collision-physics.md,save-persistence.md,procedural-generation.md,ai-pathfinding.md.game-asset-core(+game-animation-frames/game-tilesets/game-character-consistency/game-ui-icons) — 스프라이트, 시트, 타일, UI 생성 시 엔진에 적합한 2D 아트 기본값 및 검증(§6 참조).
빌드에 맞는 특정 장르/주제 참고 자료를 선택하세요. 이 파일은 루프/월드를 위한 범용 핵심입니다. 입력 부호 → controls. 2D 게임 아트 → game-asset-core.
1. 게임 루프 및 타이밍(#1 정확성 문제)
- 엔진의 RAF 루프(
renderer.setAnimationLoop, R3FuseFrame, 또는 2D 캔버스용requestAnimationFrame)로 루프를 구동하세요. 게임 타이밍에 절대setInterval/setTimeout/Date.now()를 사용하지 마세요. - 모든 이동/애니메이션을 델타 시간(초)으로 스케일링하여 속도가 프레임 속도에 독립적이도록 하세요(60Hz vs 144Hz). 델타는 프레임당 한 번 계산하고 재사용하세요.
- three.js:
THREE.Timer를 사용하세요(Clock대신 —Clock.getDelta()는 같은 프레임에서 두 번째 호출 시 ~0을 반환하는 고전적인 프리즈 버그입니다).
- three.js:
- 델타를 제한하세요(
min(delta, 0.1)). 백그라운드 탭에서 물체가 순간이동하는 것을 방지합니다. - 물리/게임플레이를 위한 고정 타임스텝: 델타를 누적하고 디스플레이 속도로 렌더링하는 동안 시뮬레이션을 고정 속도(예: 1/60)로 스텝 처리하세요 — 터널링과 비결정성을 방지합니다.
2. 컨트롤(controls 스킬에 위임)
WASD/조향/비행 코드를 구현하기 전에 .grok/skills/controls/SKILL.md를 여세요. 해당 스킬은 다음에 대한 진실의 원천입니다:
- 플레이어가 볼 수 있는 A = 왼쪽 / D = 오른쪽(추적 카메라, 전진 이동 시)
KeyA → steer−+yaw += steer * +rate가 반전되는 이유(가장 흔한 버그)- 차량 vs FPS(스트레이프 ≠ 조향), 고정익 에일러론, 헬리콥터/드론 참고 사항
- 필수 자체 테스트 +
window.__controlsTest프로브
genres/racing-kart.md를 조향 부호가 있는 유일한 곳으로 취급하지 마세요 — 비행기, 제트스키, 메카는 절대 열지 않습니다.
간단한 알림(자세한 내용은 controls에서):
// 차량 요(yaw) 바디(추적 카메라): A는 이 기저에서 요를 증가시켜야 함
forward = (-sin(yaw), 0, -cos(yaw))
// KeyA → steer = +1; yaw += steer * turnRate * speedFactor * dt
// 틀림(반전되어 제공됨): KeyA → steer = -1; yaw += steer * turnRate * dt
- 포인터 잠금: 마우스 룩만 허용 — WASD는 직접 구현하세요. 클릭투플레이 오버레이; 잠금 시 해제.
- 키를 누름 상태 + dt로 추적하세요.
references/input.md를 통해 장치를 통합하세요. - 완료:
controls스킬 체크리스트를 실행하세요. 차량/비행의 경우 스크린샷만으로는 충분하지 않습니다.
3. 3D 방향 및 월드 객체("옆으로/뒤로" 버그)
- three.js는 오른손 좌표계, +Y가 위: +X 오른쪽, +Y 위, +Z가 뷰어를 향함. 메시는 +Z를 향하고, 카메라는 −Z를 봄(고전적인 "카메라가 뒤에 있음" 문제).
Cone/Cylinder같은 프리미티브는 기본적으로 +Y를 가리킴 → 팁을 전진 방향과 정렬하려면 회전(geo.rotateX(Math.PI/2)).- 메시를
forward방향으로 정렬하기(메시는 +Z를 향함): 가장 간단한 올바른 방법은mesh.lookAt(mesh.position.clone().add(forward))입니다. 수동으로 기저를 구축하려면 +Z 열을forward로 설정하고, x축을 올바른 오른손 회전(det = +1)을 유지하도록 선택하세요.xAxis = normalize(cross(up, forward)), 그런 다음makeBasis(xAxis, up, forward)를 호출합니다. 이는cross(up, forward)입니다 — §2의 이동right = cross(forward, up)와 다릅니다. +Z를 대상으로 하면(카메라의 −Z 대신) x축 부호가 뒤집혀xAxis × up = forward가 됩니다. 프레임은 오른손 좌표계를 유지합니다(미러링 없음). 메시의 경우makeBasis(xAxis, up, -forward)를 사용하지 마세요 — 이는 -forward(카메라 규칙)를 대상으로 하여 메시가 뒤를 향하게 됩니다. - 카메라를
forward방향으로 정렬하기(카메라는 −Z를 봄): +Z 열을-forward로 설정하세요 —xAxis = normalize(cross(forward, up)), 그런 다음makeBasis(xAxis, up, -forward)(또는 그냥camera.lookAt(target)). - 일관된 월드
up을 유지하여 객체가 똑바로 서 있도록 하세요. 평면 프리미티브만 회전시켜 세웁니다. - glTF 가져오기 방향을 확인하세요.
AxesHelper/ArrowHelper로 디버깅하세요. 똑바로 서 있는지 자체 테스트: 캐릭터가 지면에 서 있어야 하며, 눕거나 가라앉지 않아야 합니다.
4. 카메라는 이동과 일치해야 합니다
- 전용
moveForward/moveRight를 이동용으로 유지하고, 한 번 계산한 후 카메라 코드에서 절대 변경하지 마세요(공유 임시 벡터를 앨리어싱하면 카메라와 이동이 불일치하게 됩니다 — 실제 재현 가능한 버그). - 3인칭 추적:
desired = playerPos + up*height + moveForward*(-followDist); 카메라를 부드럽게 보간하고(지수 기반 스무딩, 델타 스케일),lookAt(player). - 레이어 분리 디버그 순서: (1) 키 등록 → (2) 이동 부호 올바름 → (3) 카메라 일치. 이 순서로 수정하세요.
5. 성능
- 드로우 콜 최소화(
renderer.info.render.calls, 대상 <100): 재질 공유, 반복 객체에InstancedMesh/BatchedMesh, 아틀라스 사용. - 레벨 변경 시 GPU 리소스를 직접 해제(
geometry/material/texture.dispose()) — three.js는 가비지 컬렉션하지 않습니다. 총알/적/파티클을 풀링하세요. - 프레임당 할당 없음(임시 벡터 재사용). 텍스처 압축; 거리별 LOD.
6. 자산(생성된 사진 함정 피하기)
- 인터랙티브 3D 요소(무기 뷰모델, 캐릭터, 소품, 발사체) → 생성된 이미지가 아닌 3D 기하학 / glTF로 구축하세요. FPS 뷰모델로 사용되는 손에 든 총의 평면 사진 같은 JPG는 보기에 좋지 않고, 애니메이션도 안 되며, (JPG는 알파 채널이 없음) 검은색 상자로 렌더링됩니다. 실제 3D 뷰모델을 카메라에 오버레이 렌더 레이어로 부모화하세요.
- 이미지 생성은 평면 2D 자산(텍스처, 하늘/메뉴 배경, 2D 스프라이트, UI 아트)에만 예약하세요. 생성된 사진을 3D 메시, 뷰모델 또는 캐릭터 대용으로 절대 사용하지 마세요 — 이런 것은 3D 기하학 / glTF로 구축하세요. 캔버스나 텍스처에 그려지는 이미지에
crossOrigin="anonymous"를 설정하세요.imagine-grok-build스킬 참조(2D 전용 — 이미지 도구는 실제 3D를 생성할 수 없음). - 엔진 준비 게임 아트 교리 →
game-asset-core(../game-asset-core/)를 열어 기본값 + 블라인드 검증 + 재시도 규율을 확인한 후, 해당 전문가를 참조하세요:game-animation-frames(루프/모션 법칙),game-tilesets,game-character-consistency,game-ui-icons. 이들은 QC/교리이며, 내보내기 파이프라인이 아닙니다. 실제 아트가 예상되는데 막대기 인형 자리 표시자를 제공하지 마세요. - 2D 게임 스프라이트 / 애니메이션 시트 →
generate2dsprite(.grok/skills/generate2dsprite/SKILL.md) 실행: 단색#FF00FF마젠타imagine_text_to_image시트 + 크로마 후처리 스크립트(마젠타는 프로세서에 필요). 투명 PNG/GIF를 Canvas/Phaser에 연결하세요. 여전히game-asset-core(+ 해당되는 경우 애니메이션/캐릭터 전문가)를 적용하세요. - 2D 맵 / 레벨 / 소품 팩 →
generate2dmap(.grok/skills/generate2dmap/SKILL.md)를 여세요. 플레이 가능한 맵의 경우 기초만 있는 베이스 + 별도 소품/충돌을 선호하세요. 브라우저 기본값:raw_canvas/ Phaser. 타일 가능한 지면/벽 → 또한game-tilesets에서 2×2 이음새 검사. - 선택적 밀도 높은 로코모션 →
video2dsprite(Grokimagine_image_to_video+ 샌드박스 스크립트; 마젠타 베이스)를 실행하세요. 선명한 프로덕션 히어로에는generate2dsprite를 선호하세요. 루프/플립-테스트 법칙에는game-animation-frames를 사용하세요. 이 샌드박스에서는 임시방편 ffmpeg-only 수확보다video2dsprite를 선호하세요.
7. 오디오, 저장, 느낌
- 오디오: 첫 번째 사용자 제스처(탭투스타트)에서
AudioContext를 잠금 해제하거나 iOS는 무음이 됩니다.visibilitychange시 다시 재개하세요. (references/audio.md) - 저장:
localStorage/IndexedDB를version필드 + 마이그레이션과 함께 사용하세요. - 쥬스: 화면 흔들기, 힛스톱, 이징 트윈, 파티클 — 저렴하지만 지각된 품질이 크게 향상됩니다. 프레젠테이션을 시뮬레이션과 분리하여 유지하세요.
8. 모바일
- 캔버스 버퍼 크기와 CSS 크기를 구분하고
devicePixelRatio를 존중하세요. touch-action: none, 기본 해상도에 레터박스 맞춤, 방향 처리.- 터치 컨트롤(가상 조이스틱 + 액션 버튼), ≥44px 대상.
스택 / 엔진 선택
- 3D → three.js, 이상적으로는 @react-three/fiber + drei(React 앱에 적합; drei는 포인터 잠금/컨트롤/로더 제공) + 물리/캐릭터 컨트롤러를 위한 @react-three/rapier를 사용하세요.
references/3d-libs.md참조. - 2D → 네이티브 Canvas 2D는 뱀/테트리스/플래피/플랫포머에 충분합니다. 장르에서 필요할 때만 Phaser를 사용하세요.
- 이러한 게임 종속성은 사전 설치되지 않았습니다 —
npm install로 설치하고(그리고package.json에 포함되어 Vercel 빌드가 이를 가지는지 확인하세요).
완료 기준("완료" 전)
- 콘솔 오류 없이 로드됨; 볼 수 있는 게임플레이(빈 캔버스 아님).
controls스킬 자체 테스트 통과(추적 카메라에서 전진 이동 시 A = 왼쪽 / D = 오른쪽; 반전된 경우 하나의 부호를 뒤집음). 스크린샷만으로는 안 됨.- 3D 똑바로 서 있음 및 카메라 일치 자체 테스트 통과(§3, §4).
- 모바일 뷰포트에서 터치 컨트롤로 실행.
- 프로덕션 빌드(
npm run build)가 개발 버전뿐만 아니라 빌드된 출력물을 렌더링합니다. - 공유 / X 카드:
og스킬을 여세요 — 사용자 지정public/og.jpg그리고src/lib/og/site.json에"type": "x:game"을 추가하세요. X는og:type="x:game"을 사용하여 언펄을 게임 카드로 표시합니다. 이를 위해twitter:card를 사용하거나x:type을 발명하지 마세요.browser-smoke/brand-check는 캔버스 앱이site.json필드를 생략할 때 경고합니다.