# VRBeatSaber 기술 기획서
> 비트세이지 데이터 연동 온디맨드 스트리밍 및 에디터 통합 시스템

**작성일:** 2026년 5월 20일 | **문서 버전:** v1.0 | **프로젝트:** VRBeatSaber

---

## 1. 개요 (Introduction)

본 시스템은 오큘러스 퀘스트(독립형 VR) 하드웨어의 제한된 컴퓨팅 자원(CPU, RAM) 및 저장 공간 한계를 극복하기 위해 설계된 플랫폼 형태의 리듬 게임 인프라이다.

기기 내부에 대용량 음원을 상주시키는 대신, 필요 시 서버에서 동적으로 다운로드(On-Demand)하고, 외부의 무료 오토 매핑 서비스인 **비트세이지(Beat Sage)**의 연산 결과물(비트세이버 표준 포맷)을 흡수하여 구현한다.

이를 통해 자체적인 AI 모델 구축 비용(서버 유지비, GPU 연산 리소스)을 **0원으로 절감**하는 동시에 대량의 하이퀄리티 맵 데이터를 빠르게 수급할 수 있다. 개발자는 파이썬 머신러닝 레이어를 직접 다루지 않고, 오직 유니티 C# 환경 내에서 비트세이버 포맷을 자체 JSON 포맷으로 변환하는 데이터 컨버터 및 온디맨드 다운로드 시스템 구축에만 집중한다.

---

## 2. 전체 데이터 파이프라인 (Data Pipeline)

전체 워크플로우는 다음 4단계 구조를 가진다.

```
[외부 수급] → [서버 저장 및 관리] → [유니티 다운로드 및 포맷 변환] → [에디터 수정/인게임 플레이]
```

| 단계 | 구성요소 | 역할 |
|------|----------|------|
| 1 | **비트세이지 웹사이트** | 유저/개발자가 웹 인터페이스로 음원 입력 → 무료 AI 매핑 → 맵 데이터 패키지(`.zip`) 확보 |
| 2 | **자체 백엔드 서버 (Synology NAS)** | Web Station 정적 웹서버로 곡 메타데이터 리스트(`songs.json`), 음원 파일(`.mp3`), 비트세이지 원본 데이터 보관 |
| 3 | **유니티 클라이언트** | `UnityWebRequest`로 무선 네트워크 스트리밍, 오큘러스 퀘스트 임시 경로에 다운로드 후 내부 컨버터로 자체 포맷 변환 |
| 4 | **맵 에디터 통합** | 변환 완료된 데이터를 `MapEditor` 씬으로 로드, 기계 생성 초안(80%) 기반으로 개발자가 정교하게 디렉팅 및 수정 |

---

## 3. 데이터 구조 비교 및 변환 명세 (Data Mapping Spec)

### 3.1 비트세이지 결과물 포맷 (비트세이버 표준 v2 포맷)

비트세이지에서 생성된 압축파일 내 `Expert.dat` 등의 파일 구조:

```json
{
  "_version": "2.0.0",
  "_notes": [
    { "_time": 1.5, "_lineIndex": 0, "_lineLayer": 0, "_type": 0, "_cutDirection": 1 },
    { "_time": 2.3, "_lineIndex": 3, "_lineLayer": 0, "_type": 1, "_cutDirection": 0 }
  ]
}
```

### 3.2 현재 프로젝트 자체 포맷 (`Map_[곡이름].json`)

유니티 직렬화 및 기존 인게임 스폰 프레임워크가 요구하는 데이터 구조:

```json
{
  "target": [
    { "time": 0.75, "position": 0, "colorType": 0 },
    { "time": 1.15, "position": 3, "colorType": 1 }
  ]
}
```

### 3.3 구조 변환 규칙 (Mapping Rules)

| 비트세이지 원본 필드 | 자체 프로젝트 매핑 필드 | 변환 연산 및 예외 처리 규칙 |
|---------------------|------------------------|--------------------------|
| `_time` (float) | `time` (float) | 비트 단위 → 초 단위 환산<br>**`Time(s) = (_time × 60) / BPM`** |
| `_lineIndex` (int) | `position` (int) | 가로 라인 0~3 범위 1:1 매칭 |
| `_type` (int) | `colorType` (int) | `0`: 빨간색 노트(왼손)<br>`1`: 파란색 노트(오른손)<br>폭탄(`value: 3`)은 `continue` 처리로 필터링 |

> ⚠️ **주의사항:** 비트세이지의 시간 축은 절대적인 초 단위가 아닌 BPM에 종속적인 비트 카운트이므로, 변환 연산 시 음원의 정확한 메타데이터 **BPM 값이 필수적으로 제공**되어야 동기화가 유지된다.

---

## 4. 유니티 클라이언트 코어 구현 (C#)

네트워크 비동기 수신처리와 수신 즉시 인메모리/로컬 캐시 직렬화 변환을 수행하기 위한 DTO 및 핵심 컨버터 C# 스크립트 설계 구조이다.

### 4.1 수신용 데이터 구조 클래스

```csharp
using System;
using System.Collections.Generic;

[Serializable]
public class BeatSageRoot
{
    public string _version;
    public List<BeatSageNote> _notes;
}

[Serializable]
public class BeatSageNote
{
    public float _time;        // 비트 단위 시간
    public int _lineIndex;     // 가로 위치 (0~3)
    public int _lineLayer;     // 세로 위치
    public int _type;          // 타입 (0: Red, 1: Blue)
    public int _cutDirection;  // 베는 방향
}
```

### 4.2 포맷 컨버터 코어 로직 (`BeatSageConverter.cs`)

```csharp
using UnityEngine;
using System.Collections.Generic;

public class BeatSageConverter : MonoBehaviour
{
    /// <summary>
    /// 비트세이지 .dat 텍스트 데이터를 우리 게임의 NoteData 리스트로 변환합니다.
    /// </summary>
    public List<NoteData> ConvertBeatSageToMyFormat(string rawJson, float songBPM)
    {
        BeatSageRoot sageData = JsonUtility.FromJson<BeatSageRoot>(rawJson);
        List<NoteData> convertedNotes = new List<NoteData>();

        if (sageData == null || sageData._notes == null) return convertedNotes;

        foreach (var sageNote in sageData._notes)
        {
            // 일반 노트(0: 빨강, 1: 파랑)만 처리하고 나머지 오브젝트는 제외
            if (sageNote._type != 0 && sageNote._type != 1) continue;

            // BPM 공식을 대입하여 실제 게임 시간(초) 계산
            float realTimeSeconds = (sageNote._time * 60f) / songBPM;

            NoteData myNote = new NoteData
            {
                time = realTimeSeconds,
                position = sageNote._lineIndex,
                colorType = sageNote._type
            };

            convertedNotes.Add(myNote);
        }

        Debug.Log($"[컨버터] 비트세이지 포맷 변환 성공: {convertedNotes.Count}개 노트 생성됨.");
        return convertedNotes;
    }
}
```

---

## 5. 디바이스 스토리지 최적화 (Oculus Quest)

### 온디맨드 다운로드 패턴
유저가 인게임 UI 또는 맵 에디터에서 특정 곡을 선택하여 트리거하기 전까지는 음원(`.mp3`)과 데이터(`.json`) 파일을 다운로드하지 않아 앱 기본 설치 용량을 최소화한다.

### 임시 캐시 경로 활용
모든 스트리밍 다운로드 리소스는 `Application.temporaryCachePath`에 저장하여 오큘러스 내부 저장소의 파일 오염을 방지하며, OS의 메모리 부족 시 정리 가능한 대상 영역으로 권한을 위임한다.

### LRU (Least Recently Used) 삭제 메커니즘
게임 또는 툴 초기화 시 캐시 디렉터리 용량을 확인하여 **누적 용량이 1GB를 초과**할 경우, 파일 시스템의 '최근 접근 시간(Last Access Time)'이 가장 오래된 곡 폴더부터 순차적으로 `Directory.Delete`로 자동 소거한다.