플레이어용 레벨 에디터를 추가하면 리듬 게임을 더 오래 즐길 수 있지만, 채보 형식, 오디오 클록, 채점, 입력, 저장은 물론 경우에 따라 커뮤니티 기능에도 영향을 줍니다. 기존 재생 시스템을 타이밍의 기준으로 삼으세요. 첫 단계에서는 이미 출시된 레벨의 플레이 방식을 바꾸지 않고, 음악의 박자 그리드에 이벤트를 배치하고 채보를 미리 보고 검증한 뒤 버전이 명시된 초안을 저장할 수 있는 로컬 제작 기능부터 구현하세요.

이 가이드는 기존 프로젝트에 에디터를 추가하는 방법을 다룹니다. 리듬 엔진을 교체하는 가이드는 아닙니다. 예시 게임과 사운드트랙, 인터페이스, 채보 데이터, 결과는 모두 가상입니다. 프로젝트 파일, 음악, 파서, 빌드는 제공되지 않았습니다. 체크리스트는 검증 방법을 제안하는 것이며 테스트 결과가 아닙니다.
에디터의 작업 범위 정하기
작업 트리에 변경 사항이 없는 커밋에서 시작하고, 이미 정상적으로 재생되는 채보 하나를 기준으로 기록해 두세요. 오디오 클록, 채보 로더, 템포 맵, 입력 바인딩, 노트 레인, 채점 규칙, 곡 오프셋, 저장 경로, 진행 상태 플래그를 확인해 기록하세요. 빌드가 없다면 제공된 파일만 살펴보고, 실행 시 동작은 확인할 수 없다고 명시하세요.
첫 버전은 핵심 로컬 기능에 집중하세요. 플레이어가 사용 가능한 곡을 고르고, 이벤트를 배치하고 옮기고, 변경을 취소하고, 특정 구간을 미리 듣고 플레이해 볼 수 있어야 합니다. 초안을 저장하거나 다시 열고, 검증 메시지도 확인할 수 있어야 합니다. 온라인 공유, 평점, 콘텐츠 관리, 구독, 기기 간 동기화는 별도로 계획할 수 있습니다. 이런 기능을 동시에 추가하면 타이밍에 문제가 생겼을 때 원인을 찾기가 어려워집니다.
| 기존 시스템 | 작업 전 기록할 사항 | 기본 보호 원칙 |
|---|---|---|
| 오디오와 타이밍 | 클록 소스, 지연 시간 오프셋, 템포 변경 | 재생 클록을 교체하지 않음 |
| 채보 런타임 | 파일 필드, 이벤트 순서, 로더 동작 | 이미 출시된 채보와의 호환성을 유지 |
| 채점과 입력 | 판정 시간 범위, 액션 이름, 레인 매핑 | 미리보기에도 같은 규칙을 적용 |
| 게임 진행 | 잠금 해제, 완료 상태, 저장된 점수 | 초안을 공식 기록과 분리 |
파일을 수정하기 전에 AI에 실제 파일을 살펴보고 변경 계획을 작성하도록 요청하세요. 수정이 허용된 파일 목록과 변경하지 않을 시스템 목록을 명시하도록 하세요. “레벨 에디터를 추가해 줘”처럼 범위가 넓은 요청은 새로운 타이밍 모델을 도입하거나 잘 작동하는 채보 로더를 교체하는 결과로 이어질 수 있습니다. 채보 형식 하나, 로컬 저장 경로 하나, 기존 재생 코드를 호출하는 작은 화면 하나를 지정하는 편이 더 안전합니다.
음악적 시간 좌표로 이벤트 배치하기
이벤트는 사용자가 블록을 드래그한 순간의 실제 시각이 아니라 곡 안에서 해당 이벤트가 놓일 위치로 표현하세요. 현재 런타임이 박 위치를 사용한다면 그 좌표를 유지하세요. 초 단위를 사용한다면 변환을 담당하는 어댑터를 명시적으로 추가하고, 기존 템포 맵을 기준으로 변환이 정확한지 확인하세요. 모든 템포 구간에서 에디터의 눈금과 실제 플레이용 채보가 일치해야 합니다.
이벤트에는 예를 들어 변경되지 않는 ID, 레인, 마디, 박, 세분 위치, 이벤트 유형, 선택 사항인 지속 시간을 담을 수 있습니다. 필드는 최소한으로 유지하고 프로젝트의 실제 로더에 맞추세요. 런타임이 이미 템포 변경을 지원하거나 기능 계획에 해당 지원을 추가한다고 명시한 경우에만 채보 형식에 템포 변경을 저장하세요. 스크린샷만 보고 전체 스키마를 추정하거나, 제공되지 않은 예시 채보를 근거로 삼지 마세요.

Godot의 안정 버전 문서는 FileAccess와 관련 API를 사용해 런타임에 파일을 읽고 쓰는 방법을 설명하며, 사용자가 제공한 콘텐츠를 다루는 예제도 포함합니다. 데이터 경로 가이드에는 사용자 데이터를 영구 저장하는 데 쓰이는 user://가 설명되어 있습니다. 이 문서들은 엔진에서 사용할 수 있는 파일 입출력 방법을 보여 줍니다. 특정 리듬 게임 채보 형식을 요구하거나 보안을 보장하는 근거는 아니며, Pulse Harbor 구현을 테스트했다는 뜻도 아닙니다.
이벤트 하나를 옮기거나 삭제해도 나머지 이벤트의 번호를 다시 매길 필요가 없도록 변경되지 않는 식별자를 사용하세요. 재생 순서가 항상 같도록 정렬하고, 동시에 발생하는 노트를 어떻게 처리할지 정하세요. 선택 필드가 빠진 경우와 필수 필드의 값이 잘못된 경우도 구분하세요. 프로젝트가 이미 채보를 리소스로 저장한다면, 별도 구조로 기존 형식을 우회하는 대신 그 형식에 맞는 에디터 어댑터를 만드세요.
편집 결과를 예측하고 되돌릴 수 있게 만들기
저장된 타이밍에 영향을 주지 않는 확대·축소 기능을 박자 그리드에 제공하세요. 클릭하면 이벤트가 추가되고, 드래그하면 이동하도록 하세요. 삭제할 대상을 알 수 있도록 선택 상태를 분명히 표시하고, 실행 취소로 직전 편집을 되돌릴 수 있게 하세요. 키보드 단축키는 기존 게임 액션과 충돌하지 않아야 합니다. 현재 마디, 박의 세분 단위, 선택된 레인, 재생 헤드를 표시해 제작자가 자신의 입력이 무엇을 의미하는지 알 수 있게 하세요.
초안 작업은 공식 완료 상태와 분리하세요. 미리보기에서 게임 진행도가 올라가거나, 이미 출시된 채보가 덮어써지거나, 순위표에 점수가 제출되어서는 안 됩니다. 초안은 전용 폴더에 저장하고, 플레이어가 기존 커스텀 채보를 열 때는 원본 사본을 보관하세요. 게임이 기본 제공 곡만 지원한다면 에디터에서도 해당 곡만 제공하세요. 임의의 오디오 파일을 가져올 수 있는 것처럼 보여 주어서는 안 됩니다.
가상의 Pulse Harbor 사례에서 에디터는 버전 번호가 포함된 로컬 채보 초안을 저장하고 기존 미리보기 씬을 재사용합니다. 이는 제안된 구성으로, 실제 파일이나 연동 결과를 보고하는 것이 아닙니다. 프로젝트에 따라 다른 방식으로 범위를 나눠야 할 수 있습니다. 특히 채보 로딩이 리소스 가져오기 파이프라인과 연결되어 있다면 그렇습니다.
미리보기 전에 로컬 채보 파일 검증하기
플레이어가 만든 파일은 실행할 명령이 아니라 검증할 데이터로 취급하세요. 파일 버전, 필수 속성, 레인 식별자, 이벤트 유형, 숫자 범위, 중복 ID, 참조하는 곡을 확인하세요. 프로젝트 한도를 초과하거나 사용할 수 없는 리소스를 가리키는 채보는 거부하세요. 오류 메시지에는 문제가 있는 이벤트나 필드를 표시하고, 제작자가 어떻게 수정할 수 있는지 알기 쉽게 설명하세요.
경고와 치명적인 오류를 구분하세요. 노트 밀도가 이례적이어도 유효하다면 경고를 표시하는 것으로 충분할 수 있습니다. 반면 레인이 누락됐거나 박 위치가 잘못됐고 런타임이 이를 처리할 수 없다면 미리보기를 차단해야 합니다. 프로젝트에 맞는 값으로 파일 크기와 이벤트 수를 제한하고, 빈 파일, 중간에 잘린 파일, 이전 버전 파일, 형식이 잘못된 파일을 파서가 어떻게 처리하는지 테스트하세요. 이 한도는 모든 게임에 통용되는 숫자를 임의로 정하는 것이 아니라 대상 게임의 설계에 따라 정해야 합니다.
| 검증 항목 | 확인할 질문 | 검증 실패 시 동작 |
|---|---|---|
| 버전 | 에디터가 이 스키마 버전을 읽을 수 있나요? | 업그레이드 방법이나 읽기를 거부한 이유를 안내 |
| 곡 참조 | 이 곡이 허용된 곡 목록에 있나요? | 안내 없이 다른 오디오로 대체하지 않음 |
| 이벤트 좌표 | 지원되는 레인과 박 값인가요? | 잘못된 이벤트를 표시 |
| 이벤트 식별자 | ID가 고유하고 변경되지 않나요? | 안전한 수정 방법을 제안하거나 저장을 차단 |
| 파일 한도 | 내용이 프로젝트 한도 내에 있나요? | 로드 전에 예측 가능한 방식으로 처리를 중단 |
프로젝트 변경 범위를 최소화하기
패치를 적용하기 전에 파일별 변경 계획과 대조하세요. 첫 단계에서 손댈 파일은 에디터 씬, 에디터 컨트롤러, 채보 데이터 어댑터, 로컬 초안 서비스, 몇 가지 테스트 정도일 수 있습니다. 이 과정에서 예고 없이 모든 곡을 다시 작성하거나, 판정 시간 범위를 바꾸거나, 오디오 드라이버를 수정하거나, 초안 채보를 공식 진행 상태에 반영해서는 안 됩니다.
AI에 전체 diff를 보여 주고, 호환성에 관한 가정을 명시하며, 기능을 제거하는 방법을 설명하도록 요청하세요. 브랜치나 프로젝트 사본에서 작업하세요. 정상 동작이 확인된 채보와 기준 녹화는 그대로 보관하세요. 새 데이터 버전이 필요하다면 플레이어 데이터를 변경하기 전에 마이그레이션 계획을 작성하고 채보 사본으로 테스트하세요. 재생 동작이 달라졌다면 기준 상태로 되돌린 뒤 원인을 좁혀 가세요.
프로젝트 사본에서 타이밍 일치 여부와 회귀 문제 테스트하기
에디터 화면이 열리는지만 확인해서는 부족합니다. 변경 전후에 동일한 기준 채보를 비교하세요. 시작 부분의 노트, 중간 구간, 템포가 바뀌는 지점, 곡의 끝부분을 확인하세요. 에디터의 재생 헤드, 미리보기 소리, 노트 애니메이션, 입력 판정, 점수가 모두 동일한 타이밍 소스를 사용하는지 확인하세요. 화면상 그리드가 맞아 보인다고 해서 오디오 지연이나 게임 플레이 타이밍이 정확하다는 뜻은 아닙니다.

| 제안하는 확인 항목 | 수행할 작업 | 기록할 내용 |
|---|---|---|
| 기준 채보 | 이전 빌드에서 정상 동작이 확인된 채보 하나를 실행 | 빌드, 곡, 예상 타임스탬프 |
| 에디터 저장 및 불러오기 | 이벤트를 배치하고 초안을 저장한 뒤, 다시 열어 미리보기 | 직렬화된 이벤트와 달라진 점 |
| 템포 변경 지점 | 템포가 바뀌기 전후에 이벤트를 배치 | 박, 오디오 재생 위치, 재생 헤드 위치 |
| 형식이 잘못된 파일 | 필드가 누락됐거나, 잘못됐거나, 지원되지 않는 경우를 테스트 | 프로그램이 비정상 종료되지 않고 실패를 명확히 알리는지 여부 |
| 회귀 | 변경하지 않은 기준 채보를 다시 플레이 | 타이밍, 채점, 입력, 게임 진행 상태 |
| 롤백 | 기능 브랜치를 제거하거나 사본을 복원 | 원래 채보를 계속 플레이할 수 있는지 여부 |
이 표는 테스트 제안이며, 타이밍 정확도가 유지됐다는 증거는 아닙니다. 실제로 테스트할 때는 프로젝트 버전, 오디오 장치, 채보, 오프셋, 정확히 어떤 조작을 했는지, 예상 동작과 관찰된 동작, 발견된 회귀 문제를 기록하세요. 생성한 화면 목업을 근거로 에디터나 검증 패널이 구현됐다고 주장하지 마세요.
게시와 커뮤니티 공유는 별도로 다루기
장기 목표에 공유 기능이 포함된다면 콘텐츠 관리, 신고, 삭제, 소유권, 음원 라이선스, 저장 용량 제한, 게임 버전 간 호환성부터 정하세요. 로컬 에디터가 있다고 해서 안전한 온라인 라이브러리가 자동으로 생기는 것은 아닙니다. 해당 서비스와 정책을 구현하고 테스트하기 전에는 사용자가 만든 채보를 게시하거나 다운로드할 수 있다고 안내하지 마세요.
별도의 리듬 게임 콘셉트를 구상해 보고 싶다면 SEELE AI Game Maker를 사용해 보세요. 게임 콘셉트를 구상하는 도구이며, 기존 프로젝트를 편집하는 에디터는 아닙니다.
자주 묻는 질문
리듬 게임 레벨 에디터에서 플레이어가 무엇을 할 수 있어야 하나요?
채보를 만들고 미리 보는 데 필요한 기능부터 구현하세요. 곡을 고르고, 박자 그리드에 이벤트를 배치하고, 이벤트를 편집하거나 작업을 취소하고, 초안을 저장하고 검증할 수 있어야 합니다. 로컬 제작이 안정적으로 작동할 때까지 게시, 공유, 콘텐츠 관리는 별도 기능으로 두세요.
채보 이벤트는 초 단위와 박 단위 중 어느 쪽으로 저장해야 하나요?
게임에 이미 템포 맵이 있다면 마디, 박, 세분 위치처럼 일정한 음악적 좌표를 사용하는 편이 좋습니다. 재생 시간으로 변환할 때는 기존 타이밍 시스템을 사용하세요. 현재 오디오 클록과 오프셋 규칙을 유지한 다음, 템포 변경과 구간 경계 근처의 노트를 테스트하세요.
리듬 게임의 재생 동작을 바꾸지 않고 에디터를 추가하려면 어떻게 해야 하나요?
현재 채보 로더, 오디오 클록, 채점, 입력, 노트 레인을 기준으로 삼으세요. 에디터가 런타임의 기존 형식으로 데이터를 만들거나 버전이 명시된 어댑터를 통해 데이터를 만들도록 하세요. 변경 전후에 정상 동작이 확인된 채보를 비교하고, 이벤트 타이밍이 달라지면 변경을 되돌리세요.
플레이어가 만든 채보는 어떻게 검증해야 하나요?
미리보기 전에 파일 버전, 필수 필드, 곡 참조, 이벤트 유형, 박 값의 범위, 중복 ID, 지원되지 않는 값을 확인하세요. 수정할 수 있는 문제는 에디터에 표시하고, 형식이 잘못된 콘텐츠는 안전하게 거부하세요. 스키마 체크리스트만으로 실제 파서가 모든 악성 파일을 처리할 수 있음이 입증되지는 않습니다.
AI로 기존 리듬 게임에 레벨 에디터를 만들 수 있나요?
AI는 제공된 파일을 살펴보고, 범위가 명확한 패치를 제안하고, 검증 사례의 초안을 작성하는 데 도움을 줄 수 있습니다. 실제 프로젝트와 테스트 없이는 타이밍이나 호환성을 검증할 수 없습니다. 수정이 허용된 파일 목록, 변경하지 않은 기준 채보, 예상되는 박자 동작, 롤백할 커밋을 제공하고 전체 diff를 검토하세요.
재생 시스템을 다시 작성하지 않고 채보 제작 기능 추가하기
타이밍은 기존 리듬 엔진에 맡기세요. 버전 정보와 함께 음악적 좌표로 이벤트를 저장하고, 미리보기 전에 이벤트를 검증하며, 초안을 이미 출시된 채보와 공식 점수에서 분리하는 데 초점을 맞춘 로컬 에디터를 추가하세요. 전체 diff를 검토하고, 프로젝트 사본에서 정상 동작이 확인된 채보를 테스트하고, 롤백 지점을 남겨 두세요. 실제 게임을 테스트하기 전까지는 어떤 결과도 검증된 것으로 간주하지 마세요.


