CyberFormulaRacing/CLAUDE.md

🏎️ 사이버포뮬러 레이싱 게임

로블록스 스튜디오로 제작한 사이버포뮬러 스타일 레이싱 게임

---

로블록스 프로젝트 전용 지침

MCP 서버 사용 규칙

🔴 필수: 이 프로젝트에서는 Roblox Studio MCP 서버를 항상 사용해야 합니다.

Roblox Studio MCP 사용

• 모든 로블록스 작업에 mcp__Roblox_Studio__run_code 또는 mcp__Roblox_Studio__insert_model 사용
• 절대 금지: 일반 파일 시스템 접근으로 .rbxl 파일 읽기/쓰기
• Lua 스크립트 확인/수정: MCP를 통한 run_code 사용

주요 작업 패턴

프로젝트 구조 확인

mcp__Roblox_Studio__run_code:
-- Workspace, StarterPlayer, ReplicatedStorage 등 확인
for _, obj in pairs(game.Workspace:GetChildren()) do
    print(obj.Name)
end

스크립트 분석

mcp__Roblox_Studio__run_code:
-- 스크립트 소스 확인
local script = game.StarterPlayer.StarterCharacterScripts.VehicleControl
print(script.Source)

오브젝트 생성/수정

mcp__Roblox_Studio__run_code:
-- 새 파트, 스크립트, UI 등 생성
local part = Instance.new("Part")
part.Parent = game.Workspace

왜 MCP를 사용해야 하는가?

• ✅ 실시간 게임 상태 접근: 로블록스 스튜디오와 직접 통신
• ✅ Lua 실행: 게임 엔진에서 직접 코드 실행 및 테스트
• ✅ 안전한 수정: 파일 손상 없이 오브젝트 조작
• ❌ 파일 접근 불가: .rbxl은 바이너리 포맷으로 직접 읽기 불가능

금지 사항

• ❌ Read 툴로 .rbxl 파일 읽기
• ❌ Edit 툴로 .rbxl 파일 수정
• ❌ Write 툴로 Lua 스크립트 파일 생성
• ❌ Glob 툴로 .lua 파일 검색 (프로젝트 내부에는 없음)

올바른 워크플로우

1. 상태 확인: mcp__Roblox_Studio__run_code로 현재 구조 파악
2. 로직 구현: mcp__Roblox_Studio__run_code로 코드 작성/수정
3. 테스트: MCP를 통해 직접 실행 및 검증
4. 문서화: CLAUDE.md 업데이트 (유일한 파일 시스템 작업)

---

📋 프로젝트 개요

• 플랫폼: Roblox Studio
• 언어: Lua
• 스타일: 사이버포뮬러 (Future GPX Cyber Formula)
• 장르: 레이싱, 멀티플레이어

✨ 주요 기능

1. 트랙 시스템

• 프로페셔널 서킷 디자인
• 아스팔트 트랙 + 차선 마킹
• 빨강-흰 연석 (Kerbs)
• 금속 가드레일
• 스타트/피니시 라인

2. 차량 시스템

• 사이버포뮬러 스타일 (네온 효과)
• 커스텀 운전 시스템 (WASD)
• 안정성 시스템 (전복 방지)
• 헤드라이트/테일라이트
• 사운드 시스템 (엔진, 부스트, 아이템)

3. 부스트 시스템

• F 키 발동
• 오일 게이지 관리 (100%)
• 부스트 소모: 30% / 회복: 초당 5%
• 엔진 블로우 메커니즘 (10% 이하 강제 부스트)

4. 아이템 시스템

• ⛽ 오일 캔 (x4): 오일 +50% 회복
• 🚀 부스트 패드 (x4): 강력 가속
• 🔧 리페어 킷 (x2): 엔진 즉시 수리 + 오일 100%

5. UI 시스템

• 오일 게이지 (색상 변화)
• 속도계 (실시간 속도 표시)
• 부스트 상태 표시
• 알림 시스템
• 랩타임 디스플레이

6. 랩타임 시스템

• 스타트라인 감지
• 랩타임 기록
• 최고 기록 추적
• 실시간 UI 업데이트
• 최소 랩타임 검증 (10초 이상)

7. 리더보드 시스템

• 실시간 순위표 표시
• 최고 랩타임 기반 정렬
• 플레이어별 통계 (Best Lap, Total Laps)
• 1-3위 특별 표시 (금, 은, 동메달)
• 자신의 순위 하이라이트
• 최대 8명 멀티플레이어 지원

🎮 조작법

• W: 전진
• S: 후진
• A: 왼쪽 회전
• D: 오른쪽 회전
• F: 부스트 발동
• Space: 차량 하차

📁 프로젝트 구조

Workspace/
├── RacingCircuit/              # 서킷 트랙
│   ├── HomeStretch             # 홈 스트레이트
│   ├── BackStretch             # 백 스트레이트
│   ├── Turn1_2, Turn3_4        # 코너
│   ├── LaneLines/              # 차선
│   ├── Kerbs                   # 연석
│   ├── Guardrails              # 가드레일
│   ├── LightTowers             # 조명
│   └── StartLine               # 스타트/피니시 라인
├── SimpleCyberCar/             # 차량 모델
│   ├── Chassis                 # 차체
│   ├── DriveSeat               # 운전석
│   ├── Wheels (x4)             # 바퀴
│   ├── NeonLines               # 네온 장식
│   └── Sounds/                 # 사운드 시스템
│       ├── EngineSound         # 엔진 소리
│       ├── BoostSound          # 부스트 효과음
│       ├── PickupSound         # 아이템 획득
│       └── BlowSound           # 엔진 블로우
└── Items/                      # 아이템
    ├── OilCan (x4)
    ├── BoostPad (x4)
    └── RepairKit (x2)

StarterPlayer/
└── StarterCharacterScripts/
    └── VehicleControl          # 메인 운전 스크립트 (사운드 통합)

StarterGui/
└── RacingUI/                   # UI 시스템
    ├── OilGauge                # 오일 게이지
    ├── Speedometer             # 속도계
    ├── BoostStatus             # 부스트 상태
    ├── Notification            # 알림
    ├── LapTime                 # 랩타임 표시
    └── LeaderboardUI           # 실시간 순위표

ReplicatedStorage/
├── OilPickup                   # 오일 아이템 이벤트
├── RepairPickup                # 리페어 아이템 이벤트
└── LapEvent                    # 랩타임 이벤트

ServerScriptService/
├── LapTimer                    # 랩타임 서버 로직
└── Leaderboard                 # 리더보드 관리

🎯 게임플레이

1. 차량 탑승: 네온 차량에 접근해서 클릭
2. 레이싱: WASD로 서킷을 주행
3. 부스트 관리: F 키로 부스트, 오일 게이지 주의
4. 아이템 수집: 트랙의 아이템으로 오일 회복
5. 랩타임 도전: 스타트라인을 통과하며 기록 측정
6. 주의: 오일 10% 이하에서 부스트 → 엔진 블로우!

🔧 기술 스택

• Lua: 게임 로직
• Roblox Studio: 게임 엔진
• BodyVelocity/BodyGyro: 차량 물리
• HingeConstraint: 바퀴 회전
• RemoteEvent: 클라이언트-서버 통신
• ParticleEmitter: 부스트 효과
• Sound: 오디오 시스템

📊 게임 밸런스

항목	값
기본 속도	80
부스트 속도	160 (2배)
후진 속도	40
조향 각도	5°
부스트 지속	3초
부스트 소모	30%
오일 회복	초당 5%
엔진 블로우	10초 정지

🚀 TODO

• UI 시스템 (오일 게이지, 속도계)
• 사운드 이펙트
• 랩타임 시스템
• 리더보드 시스템
• UI 정리 및 레이아웃 최적화
• 추가 서킷 맵
• 타임 어택 모드

📝 버전 히스토리

v0.3.0 (2025-10-07)

• ✅ 리더보드 시스템 (실시간 순위표)
• ✅ 멀티플레이어 지원 (최대 8명)
• ✅ 플레이어 통계 시스템 (Best Lap, Total Laps)
• ✅ 순위별 색상 차별화 (1-3위 메달)

v0.2.0 (2025-10-07)

• ✅ 사운드 시스템 (엔진, 부스트, 아이템, 엔진 블로우)
• ✅ 랩타임 시스템 (기록 측정 및 UI 표시)
• ✅ 최고 기록 추적 시스템

v0.1.0 (2025-01-XX)

• ✅ 일반 서킷 트랙 구현
• ✅ 사이버포뮬러 스타일 차량
• ✅ 오일 게이지 부스트 시스템
• ✅ 엔진 블로우 메커니즘
• ✅ 아이템 시스템 (3종)
• ✅ 차량 안정성 시스템
• ✅ UI 시스템 완성

🎨 디자인 컨셉

컨셉: "일반 서킷 위를 달리는 미래형 네온 차량"

• 트랙: 리얼리스틱한 F1 스타일 서킷
• 차량: 사이버포뮬러 애니메이션 스타일 (네온 효과)
• 대비: 현실적 배경 + 미래적 차량 = 시각적 임팩트

📄 라이선스

MIT License

👨‍💻 개발자

• 개발: Claude + tindevil82
• 플랫폼: Roblox Studio
• 개발 기간: 2025