..

## 주요 변경사항

### 🚗 차량 물리 시스템
- BodyVelocity/BodyGyro → AssemblyLinearVelocity로 전환
- LocalScript에서 작동하는 최신 물리 엔진 사용
- 차량 무게 150kg → 642kg 증가 (Density 0.7 → 3.0)
- Elasticity 0.5 → 0.2로 조정 (덜 튀도록)

### 🗺️ 맵 시스템 정리
- Workspace 대청소 (9개 불필요 오브젝트 제거)
- 복잡한 도시 도로 제거 → 간단한 레이싱 트랙
- 평평한 바닥 추가 (턱 문제 해결)
- 차량 8대 스타트 라인 재배치

### 📝 문서화
- CLAUDE.md에 LocalScript 물리 엔진 제약사항 추가
- AssemblyLinearVelocity 사용법 가이드 추가

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,373 @@
+# 🏎️ 사이버포뮬러 레이싱 게임
+
+로블록스 스튜디오로 제작한 사이버포뮬러 스타일 레이싱 게임
+
+---
+
+# 로블록스 프로젝트 전용 지침
+
+## MCP 서버 사용 규칙
+
+**🔴 필수**: 이 프로젝트에서는 **Roblox Studio MCP 서버**를 항상 사용해야 합니다.
+
+### Roblox Studio MCP 사용
+- **모든 로블록스 작업**에 `mcp__Roblox_Studio__run_code` 또는 `mcp__Roblox_Studio__insert_model` 사용
+- **절대 금지**: 일반 파일 시스템 접근으로 `.rbxl` 파일 읽기/쓰기
+- **Lua 스크립트 확인/수정**: MCP를 통한 `run_code` 사용
+
+### 주요 작업 패턴
+
+#### 프로젝트 구조 확인
+```lua
+mcp__Roblox_Studio__run_code:
+-- Workspace, StarterPlayer, ReplicatedStorage 등 확인
+for _, obj in pairs(game.Workspace:GetChildren()) do
+    print(obj.Name)
+end
+```
+
+#### 스크립트 분석
+```lua
+mcp__Roblox_Studio__run_code:
+-- 스크립트 소스 확인
+local script = game.StarterPlayer.StarterCharacterScripts.VehicleControl
+print(script.Source)
+```
+
+#### 오브젝트 생성/수정
+```lua
+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` 업데이트 (유일한 파일 시스템 작업)
+
+---
+
+## 🚨 중요 개발 노트 (반드시 숙지!)
+
+### ❌ LocalScript 물리 엔진 제약사항
+
+**문제**: LocalScript에서 BodyVelocity/BodyGyro를 생성하면 클라이언트에서만 보이고 실제 물리 엔진에 영향을 주지 못함
+
+**증상**:
+- Output 창에 "✅ BodyVelocity 생성" 메시지는 나오지만
+- 실제로 `workspace.RaceCar1.Chassis:FindFirstChildOfClass("BodyVelocity")`는 nil 반환
+- `bodyVelocity.Velocity` 설정해도 차량이 움직이지 않음
+- 키 입력은 감지되고 속도 계산은 정상이지만 이동 없음
+
+**원인**:
+- LocalScript는 클라이언트 전용이므로 서버에 물리 오브젝트를 생성할 수 없음
+- BodyVelocity/BodyGyro는 서버에서만 작동하는 물리 엔진 컴포넌트
+
+**해결책**:
+```lua
+-- ❌ 작동하지 않음 (LocalScript)
+local bodyVel = Instance.new("BodyVelocity")
+bodyVel.Parent = chassis
+bodyVel.Velocity = moveDirection  -- 효과 없음!
+
+-- ✅ 올바른 방법 (LocalScript)
+chassis.AssemblyLinearVelocity = moveDirection  -- 직접 설정
+chassis.CFrame = chassis.CFrame * CFrame.Angles(0, rotation, 0)  -- 회전
+```
+
+**추가 제약**:
+- `SetNetworkOwner()` - LocalScript에서 호출 불가 (서버 전용 API)
+- `BodyGyro`, `BodyPosition`, `BodyForce` 등 모든 Body* 계열 동일한 문제
+
+### ✅ Roblox 최신 물리 엔진 권장 사항
+
+**최신 방식**: AssemblyLinearVelocity/AssemblyAngularVelocity 직접 사용
+- LocalScript/Script 모두에서 작동
+- 더 빠르고 효율적
+- Body* 계열보다 예측 가능
+
+**참고 코드**:
+```lua
+-- 속도 설정
+chassis.AssemblyLinearVelocity = chassis.CFrame.LookVector * speed
+
+-- 회전
+chassis.CFrame = chassis.CFrame * CFrame.Angles(0, math.rad(turnSpeed), 0)
+
+-- 물리 속성 조정 (선택사항)
+chassis.CustomPhysicalProperties = PhysicalProperties.new(
+    0.7,  -- Density
+    0.3,  -- Friction
+    0.5   -- Elasticity
+)
+```
+
+---
+
+# 📋 프로젝트 개요
+
+- **플랫폼**: Roblox Studio
+- **언어**: Lua
+- **스타일**: 사이버포뮬러 (Future GPX Cyber Formula)
+- **장르**: 레이싱, 멀티플레이어
+
+## ✨ 주요 기능
+
+### 1. 도로 시스템 (v0.4.0)
+- **대규모 도시 도로 네트워크** (2500x2500 studs)
+- 주요 간선도로 5개 (4-6차선)
+- 보조 도로 8개 (2-3차선)
+- 남북 연결도로 4개
+- 차선 마킹 시스템
+- 강변도로 시스템
+- 교량 3개 (난간 포함)
+- 스타트/피니시 라인 (체커보드 패턴)
+
+### 2. 차량 시스템
+- 사이버포뮬러 스타일 (네온 효과)
+- 커스텀 운전 시스템 (WASD)
+- 안정성 시스템 (전복 방지)
+- 헤드라이트/테일라이트
+- 사운드 시스템 (엔진, 부스트, 아이템)
+
+### 3. 부스트 시스템
+- **F 키** 발동
+- 오일 게이지 관리 (100%)
+- 부스트 소모: 30% / 회복: 초당 5%
+- 엔진 블로우 메커니즘 (10% 이하 강제 부스트)
+
+### 4. 아이템 시스템 (v0.4.0 확장)
+- ⛽ **오일 캔** (x10): 오일 +50% 회복
+- 🚀 **부스트 패드** (x6): 강력 가속
+- 🔧 **리페어 킷** (x4): 엔진 즉시 수리 + 오일 100%
+- 맵 전역에 분산 배치
+- 회전 애니메이션 효과
+
+### 5. UI 시스템
+- 오일 게이지 (색상 변화)
+- 속도계 (실시간 속도 표시)
+- 부스트 상태 표시
+- 알림 시스템
+- 랩타임 디스플레이
+
+### 6. 랩타임 시스템
+- 스타트라인 감지
+- 랩타임 기록
+- 최고 기록 추적
+- 실시간 UI 업데이트
+- 최소 랩타임 검증 (10초 이상)
+
+### 7. 리더보드 시스템
+- 실시간 순위표 표시
+- 최고 랩타임 기반 정렬
+- 플레이어별 통계 (Best Lap, Total Laps)
+- 1-3위 특별 표시 (금, 은, 동메달)
+- 자신의 순위 하이라이트
+- 최대 8명 멀티플레이어 지원
+
+### 8. 환경 시스템 (v0.4.0 신규)
+- 강(하천) 시스템 (구불구불한 자연스러운 형태)
+- 강둑 및 교량 시스템
+- 가로등 50개 (자동 조명)
+- 맵 경계 안전장치
+- 강변도로와 도심도로의 조화
+
+## 🎮 조작법
+
+- **W**: 전진
+- **S**: 후진
+- **A**: 왼쪽 회전
+- **D**: 오른쪽 회전
+- **F**: 부스트 발동
+- **Space**: 차량 하차
+
+## 📁 프로젝트 구조 (v0.4.0)
+
+```
+Workspace/
+├── CityRoads/                  # 도시 도로 네트워크 (2500x2500)
+│   ├── EastWestMainRoad        # 동서 주간선도로 (6차선)
+│   ├── NorthSouthMainRoad      # 남북 주간선도로 (5차선)
+│   ├── RiversideRoad1_2        # 강변도로 (4차선)
+│   ├── DiagonalMainRoad        # 대각선 간선도로 (5차선)
+│   ├── SecondaryRoad[1-8]      # 보조도로 (2-3차선)
+│   ├── VerticalConnector[1-4]  # 남북 연결도로
+│   └── StreetLights (x50)      # 가로등 시스템
+├── River/                      # 강 시스템
+│   ├── RiverSegment[1-6]       # 강 본류
+│   ├── Riverbank[1-5]          # 강둑
+│   └── Bridge[1-3]             # 교량 및 난간
+├── SimpleCyberCar/             # 차량 모델
+│   ├── Chassis                 # 차체
+│   ├── DriveSeat               # 운전석
+│   ├── Wheels (x4)             # 바퀴
+│   ├── NeonLines               # 네온 장식
+│   └── Sounds/                 # 사운드 시스템
+│       ├── EngineSound         # 엔진 소리
+│       ├── BoostSound          # 부스트 효과음
+│       ├── PickupSound         # 아이템 획득
+│       └── BlowSound           # 엔진 블로우
+├── Items/                      # 아이템 (맵 전역 분산)
+│   ├── OilCan (x10)
+│   ├── BoostPad (x6)
+│   └── RepairKit (x4)
+└── StartLine                   # 스타트/피니시 라인 (체커보드)
+
+StarterPlayer/
+└── StarterCharacterScripts/
+    └── VehicleControl          # 메인 운전 스크립트 (사운드 통합)
+
+StarterGui/
+└── RacingUI/                   # UI 시스템
+    ├── OilGauge                # 오일 게이지
+    ├── Speedometer             # 속도계
+    ├── BoostStatus             # 부스트 상태
+    ├── Notification            # 알림
+    ├── LapTime                 # 랩타임 표시
+    └── LeaderboardUI           # 실시간 순위표
+
+ReplicatedStorage/
+├── OilPickup                   # 오일 아이템 이벤트
+├── RepairPickup                # 리페어 아이템 이벤트
+└── LapEvent                    # 랩타임 이벤트
+
+ServerScriptService/
+├── LapTimer                    # 랩타임 서버 로직
+└── Leaderboard                 # 리더보드 관리
+```
+
+## 🎯 게임플레이
+
+1. **차량 탑승**: 네온 차량에 접근해서 클릭
+2. **도시 레이싱**: WASD로 대규모 도시 도로 네트워크 주행 (2500x2500 studs)
+3. **부스트 관리**: F 키로 부스트, 오일 게이지 주의
+4. **아이템 수집**: 맵 곳곳의 아이템으로 오일 회복 및 부스트
+5. **랩타임 도전**: 스타트라인을 통과하며 기록 측정
+6. **환경 탐험**: 강변도로, 교량, 도심 간선도로 등 다양한 환경
+7. **주의**: 오일 10% 이하에서 부스트 → 엔진 블로우!
+
+## 🔧 기술 스택
+
+- **Lua**: 게임 로직
+- **Roblox Studio**: 게임 엔진
+- **BodyVelocity/BodyGyro**: 차량 물리
+- **HingeConstraint**: 바퀴 회전
+- **RemoteEvent**: 클라이언트-서버 통신
+- **ParticleEmitter**: 부스트 효과
+- **Sound**: 오디오 시스템
+
+## 📊 게임 밸런스
+
+| 항목 | 값 |
+|------|-----|
+| 기본 속도 | 80 |
+| 부스트 속도 | 160 (2배) |
+| 후진 속도 | 40 |
+| 조향 각도 | 5° |
+| 부스트 지속 | 3초 |
+| 부스트 소모 | 30% |
+| 오일 회복 | 초당 5% |
+| 엔진 블로우 | 10초 정지 |
+
+## 🚀 TODO
+
+- [x] UI 시스템 (오일 게이지, 속도계)
+- [x] 사운드 이펙트
+- [x] 랩타임 시스템
+- [x] 리더보드 시스템
+- [x] 대규모 도시 도로 네트워크 (v0.4.0)
+- [x] 강/하천 시스템 (v0.4.0)
+- [ ] UI 정리 및 레이아웃 최적화
+- [ ] 교통 시스템 (신호등, 표지판)
+- [ ] 타임 어택 모드
+- [ ] 미니맵 시스템
+
+## 📝 버전 히스토리
+
+### v0.5.0 (2025-10-07)
+- ✅ **8대 차량 그리드 스타트 시스템**
+  - 가로 1줄 8대 배치 (P1~P8)
+  - 스타트라인 240 studs 폭
+  - 차량 간격 30 studs
+  - 무지개 그라데이션 색상
+- ✅ **플레이어 자동 탑승**
+  - 맵 입장 시 자동으로 빈 차량 배정
+  - P1부터 순서대로 배치 (최대 8명)
+  - 포지션 알림 시스템
+- ✅ **스타트 그리드 시스템**
+  - 체커보드 패턴 스타트라인
+  - 스폰 포인트 마커 (P1~P8)
+  - 시각적 포지션 표시
+
+### v0.4.0 (2025-10-07)
+- ✅ **대규모 도시 도로 네트워크** (2500x2500 studs)
+  - 주요 간선도로 5개 (4-6차선)
+  - 보조 도로 8개 (2-3차선)
+  - 남북 연결도로 4개
+- ✅ **강/하천 시스템**
+  - 구불구불한 강 본류 6개 세그먼트
+  - 강둑 5개
+  - 교량 3개 (난간 포함)
+- ✅ **환경 시스템**
+  - 가로등 50개 (자동 조명)
+  - 맵 경계 안전장치
+  - 강변도로와 도심도로 조화
+- ✅ **아이템 확장**
+  - 오일캔 10개, 부스트패드 6개, 리페어킷 4개
+  - 맵 전역 분산 배치
+- ✅ 기존 작은 서킷을 대규모 도시 맵으로 완전 교체
+
+### 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 시스템 완성
+
+## 🎨 디자인 컨셉
+
+**v0.4.0 컨셉**: "대규모 도시를 질주하는 사이버포뮬러 차량"
+
+- 맵: 실제 도시 스케일의 도로 네트워크 (2500x2500 studs)
+- 환경: 강변도로, 교량, 도심 간선도로, 가로등이 있는 야간 분위기
+- 차량: 사이버포뮬러 애니메이션 스타일 (네온 효과)
+- 대비: 현실적 도시 환경 + 미래적 차량 = 극대화된 시각적 임팩트
+- 게임플레이: 3초 주행으로 지나가는 작은 서킷 → 광활한 도시 탐험
+
+## 📄 라이선스
+
+MIT License
+
+## 👨‍💻 개발자
+
+- 개발: Claude + tindevil82
+- 플랫폼: Roblox Studio
+- 개발 기간: 2025

README.md

@@ -1,138 +0,0 @@
-# 🏎️ 사이버포뮬러 레이싱 게임
-
-로블록스 스튜디오로 제작한 사이버포뮬러 스타일 레이싱 게임
-
-## 📋 프로젝트 개요
-
-- **플랫폼**: Roblox Studio
-- **언어**: Lua
-- **스타일**: 사이버포뮬러 (Future GPX Cyber Formula)
-- **장르**: 레이싱, 멀티플레이어
-
-## ✨ 주요 기능
-
-### 1. 트랙 시스템
-- 프로페셔널 서킷 디자인
-- 아스팔트 트랙 + 차선 마킹
-- 빨강-흰 연석 (Kerbs)
-- 금속 가드레일
-- 스타트/피니시 라인
-
-### 2. 차량 시스템
-- 사이버포뮬러 스타일 (네온 효과)
-- 커스텀 운전 시스템 (WASD)
-- 안정성 시스템 (전복 방지)
-- 헤드라이트/테일라이트
-
-### 3. 부스트 시스템
-- **F 키** 발동
-- 오일 게이지 관리 (100%)
-- 부스트 소모: 30% / 회복: 초당 5%
-- 엔진 블로우 메커니즘 (10% 이하 강제 부스트)
-
-### 4. 아이템 시스템
-- ⛽ **오일 캔** (x4): 오일 +50% 회복
-- 🚀 **부스트 패드** (x4): 강력 가속
-- 🔧 **리페어 킷** (x2): 엔진 즉시 수리 + 오일 100%
-
-## 🎮 조작법
-
-- **W**: 전진
-- **S**: 후진
-- **A**: 왼쪽 회전
-- **D**: 오른쪽 회전
-- **F**: 부스트 발동
-- **Space**: 차량 하차
-
-## 📁 프로젝트 구조
-Workspace/
-├── RacingCircuit/              # 서킷 트랙
-│   ├── HomeStretch             # 홈 스트레이트
-│   ├── BackStretch             # 백 스트레이트
-│   ├── Turn1_2, Turn3_4        # 코너
-│   ├── LaneLines/              # 차선
-│   ├── Kerbs                   # 연석
-│   ├── Guardrails              # 가드레일
-│   └── LightTowers             # 조명
-├── SimpleCyberCar/             # 차량 모델
-│   ├── Chassis                 # 차체
-│   ├── DriveSeat               # 운전석
-│   ├── Wheels (x4)             # 바퀴
-│   └── NeonLines               # 네온 장식
-└── Items/                      # 아이템
-├── OilCan (x4)
-├── BoostPad (x4)
-└── RepairKit (x2)
-StarterPlayer/
-└── StarterCharacterScripts/
-└── VehicleControl          # 메인 운전 스크립트
-ReplicatedStorage/
-├── OilPickup                   # 오일 아이템 이벤트
-└── RepairPickup                # 리페어 아이템 이벤트
-
-## 🎯 게임플레이
-
-1. **차량 탑승**: 네온 차량에 접근해서 클릭
-2. **레이싱**: WASD로 서킷을 주행
-3. **부스트 관리**: F 키로 부스트, 오일 게이지 주의
-4. **아이템 수집**: 트랙의 아이템으로 오일 회복
-5. **주의**: 오일 10% 이하에서 부스트 → 엔진 블로우!
-
-## 🔧 기술 스택
-
-- **Lua**: 게임 로직
-- **Roblox Studio**: 게임 엔진
-- **BodyVelocity/BodyGyro**: 차량 물리
-- **HingeConstraint**: 바퀴 회전
-- **RemoteEvent**: 클라이언트-서버 통신
-- **ParticleEmitter**: 부스트 효과
-
-## 📊 게임 밸런스
-
-| 항목 | 값 |
-|------|-----|
-| 기본 속도 | 80 |
-| 부스트 속도 | 160 (2배) |
-| 후진 속도 | 40 |
-| 조향 각도 | 5° |
-| 부스트 지속 | 3초 |
-| 부스트 소모 | 30% |
-| 오일 회복 | 초당 5% |
-| 엔진 블로우 | 10초 정지 |
-
-## 🚀 TODO
-
-- [ ] UI 시스템 (오일 게이지, 속도계)
-- [ ] 멀티플레이어 최적화
-- [ ] 사운드 이펙트
-- [ ] 추가 서킷 맵
-- [ ] 리더보드 시스템
-- [ ] 타임 어택 모드
-
-## 📝 버전 히스토리
-
-### v0.1.0 (2025-01-XX)
-- ✅ 일반 서킷 트랙 구현
-- ✅ 사이버포뮬러 스타일 차량
-- ✅ 오일 게이지 부스트 시스템
-- ✅ 엔진 블로우 메커니즘
-- ✅ 아이템 시스템 (3종)
-- ✅ 차량 안정성 시스템
-
-## 🎨 디자인 컨셉
-
-**컨셉**: "일반 서킷 위를 달리는 미래형 네온 차량"
-
-- 트랙: 리얼리스틱한 F1 스타일 서킷
-- 차량: 사이버포뮬러 애니메이션 스타일 (네온 효과)
-- 대비: 현실적 배경 + 미래적 차량 = 시각적 임팩트
-
-## 📄 라이선스
-
-MIT License
-
-## 👨‍💻 개발자
-
-- 개발: Claude + tindevil82
-- 플랫폼: Roblox Studio
-- 개발 기간: 2025

run_claude.bat

@@ -0,0 +1 @@
+claude --dangerously-skip-permissions