ali-ali18/agent-skills

Rojo를 사용한 Roblox 개발 (Luau)

VM 내에서 평문 파일로 Roblox 경험을 구축하고, Rojo로 place 파일로 컴파일한 후, 사용자가 요청할 때만 Roblox Open Cloud를 통해 해당 파일을 테스트 장소에 업로드합니다. 사용자 언어(기본값: pt-BR)로 응답하세요.

0. 기본 규칙

• API 키를 절대 인쇄, 에코, 로그 또는 작성하지 마세요. shell 호출 내에서만 볼트 마커 {{secret:<name>}}를 사용하세요. 런타임이 값을 교체하고 출력에서 숨깁니다.
• 사용자가 제공한 테스트 장소(universeId + placeId)에만 게시하세요. ID를 추측하지 말고 다른 대화의 ID를 재사용하지 마세요. 사용자가 라이브/프로덕션 장소를 제공하면 중단하고 의도적인지 확인하세요.
• 기본 versionType은 Saved입니다(버전 기록에 새 버전, 라이브 아님). 사용자가 명시적으로 라이브로 전환을 요청할 때만 Published를 사용하세요.
• universeId, placeId 또는 시크릿 이름이 없나요? propose_questionnaire(짧은 양식 하나)로 물어보세요. 시크릿이 완전히 없나요? secret_request(권장 이름: ROBLOX_API_KEY)를 호출하세요. 채팅에서 키를 요청하지 마세요.

1. Rojo 설치 (VM당 한 번)

고정 릴리스: Rojo 7.7.1 (https://github.com/rojo-rbx/rojo/releases에서 최신 7.x를 확인하고 핀을 변경하기 전에 사용자에게 알리세요). 미리 빌드된 Linux x86_64 바이너리를 홈 폴더에 설치하며, 루트 권한이 필요하지 않습니다:

mkdir -p "$HOME/.local/bin" && cd "$(mktemp -d)"
curl -fsSL -o rojo.zip https://github.com/rojo-rbx/rojo/releases/download/v7.7.1/rojo-7.7.1-linux-x86_64.zip
unzip -o rojo.zip && install -m 0755 rojo "$HOME/.local/bin/rojo"
export PATH="$HOME/.local/bin:$PATH"
rojo --version   # 예상: rojo 7.7.1

먼저 command -v rojo로 확인하고, 이미 7.x가 출력되면 설치를 건너뛰세요. ARM VM에서는 linux-aarch64 에셋을 사용하세요. 툴체인 관리자가 이미 있는 경우 대안: rokit add rojo-rbx/rojo && rokit install. 다른 URL에서 설치 프로그램을 실행하지 마세요.

2. 프로젝트 레이아웃

my-game/
  default.project.json
  src/
    server/     -> ServerScriptService.Server   (서버 전용 코드)
    client/     -> StarterPlayer.StarterPlayerScripts.Client
    shared/     -> ReplicatedStorage.Shared      (양쪽에서 require할 수 있는 모듈)

default.project.json:

{
  "name": "my-game",
  "tree": {
    "$className": "DataModel",
    "ServerScriptService": { "Server": { "$path": "src/server" } },
    "ReplicatedStorage": { "Shared": { "$path": "src/shared" } },
    "StarterPlayer": {
      "$className": "StarterPlayer",
      "StarterPlayerScripts": { "Client": { "$path": "src/client" } }
    }
  }
}

Rojo가 이해하는 파일 이름: init.server.luau (폴더용 Script), *.server.luau (Script), *.client.luau (LocalScript), 일반 *.luau (ModuleScript), init.luau (폴더가 ModuleScript가 됨). *.rbxl, *.rbxlx, Packages/가 포함된 .gitignore를 추가하세요. 폴더에 default.project.json이 없을 때만 프로젝트를 생성하고, 기존 레이아웃을 덮어쓰지 말고 그에 맞게 조정하세요.

3. 코딩 규칙

• 모든 파일 상단에 --!strict를 사용하는 Luau. 함수 시그니처와 내보내는 테이블에 타입을 지정하세요.
• ModuleScript당 하나의 책임, 테이블 반환. 전역 변수, _G, shared 사용 금지. 직접 참조(script.Parent.Module 또는 ReplicatedStorage.Shared.Module)와 함께 require를 사용하세요.
• 진입점은 작게 유지: 하나의 init.server.luau와 require로 서비스/컨트롤러를 가져와 순서대로 시작하는 클라이언트 진입점 하나.
• 서비스는 상단에서 가져오기: local Players = game:GetService("Players"). wait/spawn/delay보다 task.wait, task.spawn, task.delay를 선호하세요. Players.PlayerRemoving에서 플레이어별 연결을 해제하세요.
• 클라이언트를 절대 신뢰하지 마세요. 서버가 게임 상태(통화, 인벤토리, 데미지, 텔레포트, 진행도)를 소유합니다. 클라이언트는 의도만 보내고 결과를 렌더링합니다.

리모트 보안 체크리스트

• 고정된 이름으로 서버에서 ReplicatedStorage 아래에 RemoteEvent/RemoteFunction 인스턴스를 생성하고, 클라이언트에서 절대 생성하지 마세요.
• 모든 OnServerEvent/OnServerInvoke에서: 인자 개수와 타입(typeof)을 검증하고, 범위를 제한하며, NaN/inf를 거부하고, 문자열 길이를 제한하며, 플레이어가 허용되는지 확인하세요(재사용 대기시간, 소유권, 거리, 생존 여부).
• 플레이어당 속도 제한(토큰 버킷 또는 마지막 호출 타임스탬프). 리모트는 가격, 데미지 양 또는 클라이언트가 유리하게 선택할 수 있는 다른 값을 절대 전달해서는 안 됩니다.
• RemoteFunction: 절대 InvokeClient를 사용하지 마세요(악의적인 클라이언트가 서버 스레드를 중단시킬 수 있음).
• DataStore: pcall로 감싸고, 백오프와 함께 재시도하며, PlayerRemoving 및 game:BindToClose에서 저장하고, 세션 잠금으로 중요한 데이터를 보호하세요.
• 시크릿 및 튜닝 노브는 ServerScriptService/ServerStorage에만 있고 ReplicatedStorage에는 절대 없습니다.

4. 빌드

rojo build default.project.json -o place.rbxl
ls -l place.rbxl

먼저 빌드 오류(누락된 $path, 잘못된 JSON, 중복 이름)를 수정하세요. place.rbxl을 커밋하지 마세요. selene / stylua --check는 선택 사항입니다. 요청하지 않으면 설치하지 마세요. 파일에서 빌드된 place는 스크립트 스켈레톤일 뿐입니다. Studio에서 만든 에셋, 지형 및 UI는 이미 존재하는 place에 있으므로 업로드하면 대상 버전의 콘텐츠가 대체됩니다. 이것이 바로 대상이 테스트 장소여야 하는 이유입니다.

5. Open Cloud를 통한 게시 (테스트 장소)

엔드포인트 (Roblox Open Cloud Place Publishing, universes v1):

POST https://apis.roblox.com/universes/v1/{universeId}/places/{placeId}/versions?versionType=Saved|Published

• 헤더 x-api-key: <key>; .rbxl(바이너리)의 경우 Content-Type: application/octet-stream, .rbxlx의 경우 application/xml.
• 본문: 원시 place 파일. 성공 응답: { "versionNumber": 7 }.
• API 키에는 대상 경험에 대한 쓰기 권한이 있는 universe-places 권한이 필요합니다(Creator Dashboard에서 생성).
• HTTPS 전용. API는 일부 인스턴스 유형(EditableImage, EditableMesh, PartOperation, SurfaceAppearance, BaseWrap)을 업데이트하지 않습니다. 이러한 항목은 Studio에서 게시하도록 사용자에게 알리세요.
• 문서: https://create.roblox.com/docs/en-us/cloud/guides/usage-place-publishing

볼트 마커와 함께 실행하세요 (마커는 셸 명령 안에 들어가며, 메시지 텍스트에는 절대 포함하지 마세요):

curl -sS -X POST \
  "https://apis.roblox.com/universes/v1/$UNIVERSE_ID/places/$PLACE_ID/versions?versionType=Saved" \
  -H "x-api-key: {{secret:ROBLOX_API_KEY}}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @place.rbxl

$UNIVERSE_ID와 $PLACE_ID를 사용자가 제공한 숫자로 바꾸고, 시크릿 이름을 실제 볼트 이름으로 바꾸세요(secret_list는 이름만 표시함). 키를 노출하지 않고 오류를 처리하세요: 401/403 = 키가 잘못되었거나 권한/경험이 누락됨; 404 = 잘못된 universe/place 쌍; 400 = 잘못된 파일(재빌드); 429 = 대기 후 한 번 재시도. HTTP 상태와 응답 본문(키를 절대 포함하지 않음)만 인용하세요.

6. 보고

모든 작업을 사용자 언어로 간략한 보고서로 마무리하세요:

1. 변경된 사항(파일 및 동작)을 평이한 언어로.
2. rojo build 결과와, 게시된 경우 versionNumber, 사용된 versionType 및 테스트 장소 <placeId>로 전송되었음을 알림.
3. Studio에서 테스트하는 방법: 테스트 장소 열기, 버전 기록 열어 새 Saved 버전 로드, 재생(F5) 누르고 예상되는 출력 메시지와 함께 시도해야 할 정확한 항목.
4. 수행하지 않은 작업(라이브 게시, Studio가 필요한 에셋 또는 지형).

7. 로컬 동기화 옵션

실시간 편집을 위해 사용자는 자신의 컴퓨터에서 Rojo Studio 플러그인(https://rojo.space/docs/v7/getting-started/installation/)과 함께 rojo serve를 실행할 수 있습니다. Studio에서 VM에 도달할 수 없으므로 VM 내에서는 빌드 및 Open Cloud 업로드를 유지하세요.