Roblox 오프라인 스킬은(는) 무엇을 하나요?

목적

이 스킬은 게임을 떠난 시간 동안 계산되는 진행을 포함한 안정적인 Roblox 플레이어 데이터 시스템을 구축하고 검토하는 데 사용됩니다. 아키텍처, 구현, 테스트, 운영 및 복구를 다룹니다. 이는 배포된 영구 저장 프레임워크가 아닌 AI 에이전트를 위한 지침입니다.

트리거 조건

다음과 같은 작업이 포함될 때 이 스킬을 사용하세요:

플레이어 데이터 저장, 로드, 초기화, 마이그레이션, 복원 또는 검사.
DataStoreService, 표준 DataStore, OrderedDataStore, MemoryStoreService, Open Cloud DataStore 또는 Creator Hub Data Store 관리자.
플레이어 프로필, 통화, 인벤토리, 펫, 업그레이드, 구역, 작물, 기계, 발전기, 리더보드 및 영구 설정.
세션 소유권, 세션 잠금, 자동 저장, 재시도, 요청 예산, 스로틀링, PlayerRemoving 또는 BindToClose.
오프라인 수익, 방치 수입, 농사 타이머, 생산, 쿨다운 또는 재연결 후 진행.
데이터 손실, 오래된 쓰기, 중복 보상, 손상된 레코드, 구매 영수증 또는 스키마 마이그레이션.

UI, 맵, 애니메이션, 전투 또는 일반 게임플레이 작업이 플레이어 영구 데이터와 관련되지 않은 경우 이 스킬을 사용하지 마세요.

핵심 사실

DataStoreService는 영구적인 Roblox 클라우드 저장소를 제공합니다. 서버 코드에서 액세스하며 Roblox 서비스 연결이 필요합니다.
Creator Hub Data Store 관리자는 데이터를 보거나 관리하기 위한 대시보드입니다. Luau 서비스나 런타임 데이터베이스 API가 아닙니다.
MemoryStoreService는 임시 크로스 서버 데이터를 제공합니다. 항목은 만료되며 영구 플레이어 프로필 저장소가 아닙니다.
OrderedDataStore는 정렬된 숫자 값(일반적으로 영구 리더보드 점수)을 위한 것입니다. 전체 플레이어 프로필이 아닙니다.
서버 메모리는 활성 서버의 휘발성 작업 복사본입니다. 저장에 성공하기 전에 프로세스가 종료되면 손실될 수 있습니다.
오프라인 진행은 일반적으로 플레이어가 돌아온 후 서버가 계산하는 제한된 따라잡기를 의미합니다. 활성 서버 없이 개인 월드가 계속 시뮬레이션된다는 의미가 아닙니다.
완전히 연결이 끊긴 클라이언트는 Roblox 클라우드 DataStore에 쓸 수 없습니다. 일반 게시된 Roblox 경험이 연결 없이도 계속 플레이하고 클라우드 저장할 수 있다고 약속하지 마세요.
DataStoreService 호출은 서버 스크립트 또는 서버 스크립트에서 요구하는 ModuleScript에 속합니다. LocalScript에서 정식 데이터를 저장하지 마세요.
UpdateAsync는 읽기-수정-쓰기 작업입니다. 그 자체로 세션 잠금을 구현하지 않습니다.
성공적인 요청이 반환된 프로필이 구조적으로 유효하거나 현재 스키마와 호환된다는 것을 증명하지 않습니다.
로드 실패는 키 누락이나 새 플레이어와 동일하지 않습니다.
대상 경험이 실제로 Studio에서 실행되지 않았다면 코드가 Roblox Studio에서 테스트되었다고 주장하지 마세요.

필수 작업 흐름

1. 편집 전 검사

실제 경험, 파일, 스크립트, ModuleScript, 리모트, 패키지 및 사용 가능한 Studio 통합을 검사하세요.

식별:

모든 DataStore 이름, 범위, 키 빌더, 키 접두사 및 저장소 어댑터.
모든 GetAsync, SetAsync, UpdateAsync, IncrementAsync, RemoveAsync, 버전 및 목록 호출.
PlayerAdded, PlayerRemoving, BindToClose, 자동 저장 작업, 구매 영수증 처리기 및 각 프로필 키에 대한 모든 작성자.
현재 스키마, 기본 템플릿, 마이그레이션 버전 및 프로필이 쓰기 가능해지는 정확한 시점.
프로젝트가 네이티브 DataStoreService, 타사 프로필 라이브러리 또는 사용자 정의 래퍼를 사용하는지 여부.
프로필 소유권, 재시도, 동일 키 순서 지정 및 종료가 현재 처리되는 방식.
사용자가 오프라인이라는 용어로 의미하는 바: 부재 시간 따라잡기, 임시 서비스 중단, 모의 테스트 또는 완전히 연결이 끊긴 플레이.

스크린샷, 저장소 이름 또는 몇 가지 분리된 코드 조각에서 아키텍처를 유추하지 마세요. 구체적인 변경 이유를 보여주는 증거가 없는 한 작동 중인 시스템을 유지하세요.

2. Roblox 동작 확인

참조 sources/official-roblox-sources.md를 소스 인덱스로 사용하세요. 코딩하기 전에 현재 Roblox Creator Hub 문서에서 API 시그니처, 할당량, 서비스 동작, 구성 및 지원 중단을 다시 확인하세요.

엔진 보장 사항은 Roblox 문서를 사용하세요. 타사 패키지의 경우 대상 프로젝트에 설치된 정확한 버전을 검사하고 해당 패키지의 자체 API를 확인하세요. 메모리나 오래된 예제에서 라이브러리 메서드를 임의로 만들지 마세요.

3. 요구 사항에 따라 저장소 선택

요구 사항	올바른 시작점
지속적인 플레이어 진행	DataStoreService를 통한 표준 DataStore 또는 관리되는 프로필 레이어
지속적인 숫자 순위	OrderedDataStore
임시 공유 크로스 서버 상태	MemoryStoreService
현재 서버의 라이브 프로필	서버 메모리
저장된 항목 검사 또는 복구	Creator Hub Data Store 관리자 및 버전 API
외부 관리	신뢰할 수 있는 백엔드를 통한 Open Cloud
부재 시간 진행	영구 프로필 및 서버 측 따라잡기 계산
완전한 연결 끊김 독립 실행형 플레이	일반 Roblox 클라우드 DataStore에서 제공하지 않음

프로필이 맞고 필드에 일관된 업데이트가 필요한 경우 안정적인 UserId 기반 프로필 키 하나를 선호하세요. 실제 크기, 처리량 또는 액세스 패턴 이유가 있는 경우에만 분할하세요. 플레이어당 DataStore를 만들지 마세요.

4. 프로필을 안전하게 로드하고 소유하기

프로필은 선택한 아키텍처에서 성공적인 로드 및 독점 소유권 이후에만 쓰기 가능해집니다.

서버가 PlayerAdded를 수신하면 로드를 시작합니다.
기존 지속성 레이어를 사용하여 프로필/세션 잠금을 획득합니다.
유효한 키 누락 결과를 네트워크 오류, 스로틀링, 세션 충돌, 잘못된 데이터 및 지원되지 않는 스키마와 구별합니다.
페이로드의 유효성을 검사하고 순서가 지정된 결정적 마이그레이션을 적용합니다.
필요한 모든 단계가 성공한 후에만 프로필을 준비 상태로 게시합니다.
서버 게임플레이가 제어된 메서드를 통해 서버 소유 작업 복사본을 수정하도록 합니다.
프로필 라이브러리가 소유권이 종료되었음을 보고하면 즉시 변경을 중지합니다.

일시적인 로드 실패 후 쓰기 가능한 기본 프로필을 절대 만들지 마세요. 이는 돌아오는 플레이어의 실제 데이터를 덮어쓸 수 있습니다.

5. 순서 지정 및 제한된 재시도로 저장

pcall 또는 프로젝트의 설정된 오류 레이어로 네트워크 호출을 처리합니다.
일시적인 오류만 재시도하고, 제한된 지수 백오프와 무작위 지터를 사용합니다.
유효하지 않은 인수나 영구적인 실패를 무기한 재시도하지 마세요.
키당 쓰기를 직렬화합니다. 오래된 지연된 재시도가 최신 성공적인 저장을 덮어쓰지 않아야 합니다.
실패한 응답이 쓰기 결과를 불확실하게 만들 수 있으므로 재시도 가능한 작업을 멱등성 있게 설계하세요.
새 값이 현재 저장된 상태에 종속되거나 동시 쓰기가 가능할 때 UpdateAsync를 사용하세요.
SetAsync는 독점 소유권과 대체 의미 체계가 설정된 경우 의도적인 전체 값 대체에 유효합니다. 보편적으로 금지되었다고 말하지 마세요.
UpdateAsync 변환 콜백을 결정적이고, 비-항복(non-yielding)하며, 외부 부작용이 없도록 유지하세요. 콜백 내에서 절대 wait, HTTP 호출, 원격 호출, 영수증 승인, 분석 또는 Instance 생성을 수행하지 마세요.
UpdateAsync 변환에서 nil 반환은 쓰기를 취소합니다.
현재 요청 예산과 스로틀 동작을 관찰하세요. UpdateAsync는 읽기 및 쓰기 예산을 모두 소비합니다.
자동 저장을 분산하세요. 매 프레임이나 모든 작은 게임플레이 이벤트에 대해 저장하지 마세요.

6. 오프라인 진행 올바르게 구현

오프라인 보상 시스템을 구축하기 전에 참조 sources/offline-progression.md 및 examples/offline-progress.luau를 읽으세요.

서버는 다음을 수행해야 합니다:

프로필을 로드하고 유효성을 검사합니다.
독점 세션 소유권을 확인합니다.
저장된 타임스탬프와 서버 소유 생산 입력을 읽습니다.
현재 서버 측 에포크 시간을 가져옵니다.
음수가 아닌 경과 시간을 계산하고 구성된 최대값으로 제한합니다.
검증된 소유권 및 서버 측 정의에서 생산 속도를 도출합니다.
구성된 오프라인 효율성, 자격 및 보상 상한선을 적용합니다.
보상과 해당 시뮬레이션 타임스탬프를 프로필 작업 복사본에서 함께 업데이트합니다.
활성 프로필 레이어를 통해 저장합니다.
프레젠테이션 데이터를 클라이언트에 복제합니다.

교차 세션 계산을 위해 os.time() 또는 다른 문서화된 서버 측 에포크 타임스탬프를 사용하세요. 에포크 타임스탬프로 os.clock()을 절대 사용하지 마세요. 클라이언트 클록, 경과 시간, 생산 속도, 작물 단계, 자산 목록 또는 마지막 클레임 타임스탬프를 절대 신뢰하지 마세요.

동일한 간격을 두 번 지급하지 마세요. 온라인 생산을 이중으로 계산하지 마세요. 오프라인 초당 한 번 무제한 루프를 실행하지 마세요. 누락, 잘못된 형식, 0, 음수 및 미래 타임스탬프를 의도적으로 처리하세요.

7. 개발 및 프로덕션 데이터 보호

라이브 DataStore 통합 테스트를 위해 별도의 게시된 개발 또는 스테이징 경험을 사용하세요.
해당 격리된 테스트 경험에서만 Studio 액세스 권한을 API 서비스에 활성화하세요.
Roblox는 Studio가 라이브 애플리케이션과 동일한 DataStore에 액세스할 수 있다고 경고합니다. 일상적인 테스트를 위해 프로덕션에서 이 설정을 활성화하지 마세요.
결정론적 논리 테스트를 위해 목(mock) 또는 인메모리 어댑터를 사용하세요. 목은 실제 플레이어 저장이 아니며 영구 저장소가 아닙니다.
일회용 계정 및 테스트 키를 사용하세요.
명시적인 운영자 승인, 정확한 대상 식별 및 복구 계획 없이 프로덕션 데이터를 삭제, 되돌리기, 이름 변경 또는 덮어쓰지 마세요.
Open Cloud 자격 증명을 신뢰할 수 있는 백엔드에 보관하세요. LocalScript, 클라이언트, 공개 저장소 또는 프롬프트 컨텍스트에 절대 노출하지 마세요.

8. 정직하게 확인하고 보고

참조 sources/test-matrix.md를 사용하세요. 첫 방문 및 재방문 프로필, 로드 실패, 충돌, 오래된 소유자, 쓰기 순서, 재시도, 자동 저장, 종료, 충돌 복구, 잘못된 형식의 페이로드, 마이그레이션, 오프라인 상한선, 반복된 클레임 및 중복 영수증을 다루세요.

검증 수준을 정확하게 보고하세요:

정적 리뷰
순수 단위 테스트
목/인메모리 통합 테스트
게시된 스테이징 DataStore 테스트
Roblox Studio 런타임 테스트
다중 서버/세션 충돌 테스트

이들은 서로 다른 검사입니다. Studio 또는 스테이징을 사용할 수 없었다면 런타임 검증이 아직 완료되지 않았다고 명시하세요.

양보할 수 없는 금지 사항

LocalScript에서 정식 플레이어 데이터를 저장하지 마세요.
클라이언트가 제공한 UserId, 잔액, 가격, 인벤토리, 소유권, 보상 비율, 타임스탬프, 경과 시간 또는 구매 결과를 절대 신뢰하지 마세요.
일시적인 로드 오류를 새 플레이어로 취급하지 마세요.
MemoryStoreService 또는 서버 RAM을 영구 프로필 저장소로 사용하지 마세요.
새로운 경험에 DataStore2를 사용하지 마세요. Roblox는 현재 이를 레거시 라이브러리로 식별합니다.
UpdateAsync 콜백에서 항복(yield)하거나 부작용을 수행하지 마세요.
동일 키 쓰기와 재시도가 경쟁하지 않도록 하세요.
일반 재시도로 활성 세션을 강제로 빼앗지 마세요.
프로필 라이브러리가 관리하는 키에 원시 값을 쓰지 마세요.
UpdateAsync 단독으로 세션 잠금을 구현한다고 주장하지 마세요.
무제한 오프라인 시뮬레이션 루프를 실행하지 마세요.
Open Cloud 비밀을 노출하지 마세요.
명시적인 승인 및 복구 계획 없이 프로덕션 데이터를 파괴적으로 수정하지 마세요.
발생하지 않은 Studio 테스트를 주장하지 마세요.

참조 맵

현재 작업에 필요한 문서만 로드하세요:

references/architecture-and-services.md: 서비스 역할, DataStore 관리자, Open Cloud 및 저장소 선택.
references/player-data-lifecycle.md: 프로필 생애주기, 인메모리 작업 복사본, 준비 상태, 이탈 및 종료.
references/session-locking-and-failures.md: 세션 소유권, UpdateAsync, 쓰기 순서, 재시도, 스로틀링 및 알 수 없는 결과.
references/offline-progression.md: 방치 보상, 작물 타이머, 발전기, 타임스탬프 수학, 상한선 및 연결 끊김 제한.
references/studio-testing.md: API 액세스, 스테이징, 목 및 안전한 테스트 격리.
references/schema-migrations-and-recovery.md: 직렬화, 스키마 버전, 마이그레이션, 버전 기록 및 복구.
references/security-and-purchases.md: 리모트, 서버 권한, 영수증, Open Cloud 비밀 및 데이터 개인정보 보호.
references/performance-and-limits.md: 문서화된 제한, 예산, 처리량 및 운영 튜닝.
references/library-selection.md: 네이티브 DataStoreService, 공식 참조 코드 및 타사 패키지 평가.
references/game-patterns.md: 프로필, 리더보드, 구역, 방치형 시스템, 거래 및 구매.
references/test-matrix.md: 검증 시나리오.
references/official-roblox-sources.md: Roblox Creator Hub 소스 링크만.
examples/profile-template.luau: 예시 프로필 형태.
examples/offline-progress.luau: 순수 제한 오프라인 보상 계산.

필수 구현 응답

구현 및 디버깅 작업의 경우:

실제 프로젝트에서 발견된 기존 아키텍처를 요약합니다.
의도된 데이터 흐름과 가장 안전한 최소 변경 사항을 설명합니다.
생성하거나 수정할 정확한 파일을 나열합니다.
분리된 조각이 아닌 완전하고 컨텍스트를 인식하는 코드를 제공합니다.
설정, 스테이징 및 모든 스키마 마이그레이션 단계를 설명합니다.
실제 테스트와 남은 런타임 검사를 보고합니다.
보장 사항을 임의로 만들지 않고 중요한 제한 사항과 위험을 명시합니다.

사용자가 요청한 언어와 스타일을 존중하세요. 작동 중인 시스템을 유지하세요. 관련 없는 기능을 추가하거나 스타일상의 이유로 기존 지속성 라이브러리를 교체하지 마세요.

Roblox 오프라인 스킬