majidmanzarpour/threejs-game-skills

Agent skills for building playable, polished Three.js browser games with gameplay, AAA-style graphics, UI, QA, and optional AI-generated 3D, image, and audio assets.

threejs-game-skills – Three.js 브라우저 게임을 구축하기 위한 AI 기반 스킬 팩

무엇인가요 – 대규모 언어 모델(LLM) 어시스턴트인 Codex 및 Claude Code 가 Three.js용 풀스택 게임 개발자처럼 행동할 수 있도록 해주는 에이전트 스킬 모음입니다. 이 팩은 Vite + TypeScript 스크래치, 헬퍼 스크립트, 결정론적 테스트 훅, 그리고 전문 서브스킬(게임플레이, 그래픽스, UI, 자산 생성, 오디오, 디버깅, QA, 릴리스)을 조율하는 디렉터 스킬을 함께 제공합니다. 예를 들어 "고급 호버 레이싱 게임을 만들라"고 지시하면 디렉터는 적절한 서브스킬을 자동으로 호출하고 코드와 자산을 생성하며 Playwright 기반 스모크/시각적 회귀 테스트를 실행하고, 릴리스 준비 완료된 빌드를 생성합니다. 저수준의 Three.js 코드를 직접 작성할 필요가 없습니다.

주요 구성 요소

스킬	역할
threejs-game-director	진입점; 범위를 결정하고 다른 스킬으로 라우팅하며 프로젝트 노트를 유지하고 검증 프로세스를 실행합니다.
threejs-gameplay-systems	게임 루프, 입력, 카메라, 물리, 스코어링, 전반적인 아키텍처를 설정합니다.
threejs-aaa-graphics-builder	모델, 재질, 조명, VFX를 개선하고 시각적 스코어카드를 생성합니다.
threejs-game-ui-designer	HUD, 메뉴, 반응형 오버레이, 터치 영역 안전성 검사 등을 구축합니다.
threejs-debug-profiler	런타임 오류, 성능 병목, 모바일 전용 버그를 탐지합니다.
threejs-qa-release	프로덕션 빌드를 생성하고 Playwright 스크린샷, 캔버스 픽셀 체크, 뷰포트 테스트를 실행하며 릴리스 리스크 리포트를 생성합니다.
threejs-3d-generator	(옵션) Tripo API를 호출하여 텍스트나 이미지를 GLB/FBX 자산으로 변환합니다.
threejs-image-generator	(옵션) Gemini 이미지 생성을 사용해 텍스처, 스카이박스, UI 아트 등을 생성합니다.
threejs-audio-generator	(옵션) ElevenLabs를 사용해 SFX, 음악 루프, 음성 오버레이/TTS를 생성합니다.

모든 스킬은 skills/ 폴더 내에 있으며, 각각 SKILL.md 설명, 참조 문서, 에이전트가 호출할 수 있는 스크립트를 포함합니다.

설치

# Codex 에이전트용 설치
npx skills add majidmanzarpour/threejs-game-skills --skill '*' -a codex -g -y

# Claude Code 에이전트용 설치
npx skills add majidmanzarpour/threejs-game-skills --skill '*' -a claude-code -g -y

skills CLI가 -a 플래그를 지원하지 않는 경우, 리포지토리를 클론하고 포함된 설치 스크립트를 실행하세요:

./install.sh --codex      # Codex 스킬만
./install.sh --claude     # Claude Code 스킬만
./install.sh --all        # 둘 다

설치 스크립트는 skills/ 디렉터리를 적절한 에이전트 스킬 위치에 복사하며, 중복 이름은 --force가 지정되지 않은 경우 건너뜁니다. 관련 없는 사용자 스킬은 절대 삭제하지 않습니다.

사용 방법

빈 폴더(또는 기존 Three.js 프로젝트)를 LLM 에이전트 UI에서 열기.

자연어 요청을 에이전트에 제시하고 디렉터 스킬 이름을 지정합니다. 예를 들어:

threejs-game-director를 사용하여 미래 지향적인 타워 디펜스 게임을 처음부터 구축하세요.
관련된 게임플레이, 그래픽스, UI, 자산 생성, 오디오, 디버깅, QA 스킬을 자동으로 사용하세요.
먼저 플레이 가능한 루프를 만들고, 브라우저, 모바일, 시각적, 성능, 릴리스 검사를 통과할 때까지 반복하세요.

디렉터는 스크래치를 로드하고 코어 루프를 생성하며, 필요한 경우 그래픽스/UI/오디오 서브스킬을 호출하고, 포함된 Playwright 테스트를 실행한 후, 빌드 로그, 스크린샷, 성능 메트릭, 자산 ID를 포함한 요약을 반환합니다.

동일한 프롬프트는 Codex와 Claude Code 모두에서 작동합니다. 왜냐하면 SKILL.md 파일이 공유되기 때문입니다.

옵션 API 키

핵심 워크플로우는 유료 서비스 없이도 작동합니다. 다음 키를 제공하면 자산 생성 스킬이 더 고품질의 외부 자산을 가져올 수 있습니다:

제공업체	스킬	환경 변수
Tripo	`threejs-3d-generator`	`TRIPO_API_KEY`
Google Gemini	`threejs-image-generator`	`GEMINI_API_KEY`
ElevenLabs	`threejs-audio-generator`	`ELEVENLABS_API_KEY`

디렉터에는 각 키가 설정되었는지 여부를 보고하는 작은 프로브 스크립트(probe_asset_credentials.sh)가 포함되어 있습니다.

데모

게임	동영상	실행 가능한 링크
Neon Ridge Drift	X에서 보기	https://ridgedrift.netlify.app
Championship Snooker Arena	X에서 보기	https://snookerarena.netlify.app
Starship Dogfight	X에서 보기	https://starshipdogfight.netlify.app
Tide Singer	X에서 보기	https://tidesinger.netlify.app
Ripcore	X에서 보기	https://ripcore.netlify.app

각 데모는 스킬 팩으로 생성되었으며, 디렉터가 최소한의 수동 코드로 완전하고 정교한 Three.js 게임을 생성할 수 있음을 보여줍니다.

증거 및 검증

스킬이 성공을 주장할 때는 구체적인 아티팩트를 제공해야 합니다. 예를 들어:

npm run build 출력 및 프로덕션 번들.
Playwright 스크린샷 및 시각적 회귀 기준.
캔버스 픽셀이 비어 있지 않은 체크 및 렌더링 예산 메트릭(삼각형 수, 드로우 콜 수, 텍스처 메모리).
그래픽스가 변경될 때의 성능 스냅샷.
AAA 수준 주장에 대한 시각적 스코어카드 (참조 앵커에 따라 보정됨).
게임플레이 루프에 대한 봇 플레이테스트 메트릭.
생성된 3D/2D/오디오 자산 경로 또는 자격 증명이 부족하다는 메모.

디렉터의 check_evidence.py 스크립트는 이러한 아티팩트를 나열하는 매니페스트를 검증합니다.

유지보수 및 테스트

개발자는 리포지토리 자체의 체크를 실행할 수 있습니다:

npm install
npm run check:scripts
npm run validate:skills
npm run test:helpers

헬퍼 스크립트도 수동 실행용으로 공개되어 있습니다 (예: inspect-threejs-canvas.mjs).

라이선스

MIT – 자유롭게 사용, 수정, 재배포 가능.

TL;DR

threejs-game-skills는 LLM 에이전트 스킬의 즉시 설치 가능한 팩으로, AI 어시스턴트가 완전한 Three.js 게임 스튜디오처럼 작동할 수 있게 합니다. 팩을 설치하고 디렉터에게 원하는 게임 유형을 알려주면, 시스템은 코드와 자산을 생성하고 자동 테스트를 실행하며 릴리스 준비 완료된 웹 게임을 제공합니다. 저수준의 Three.js 보일러플레이트를 직접 작성할 필요가 없습니다.