@immercy/cli

CLI 하나로 로그인하고 게임·컨트롤러 정적 파일을 검증·배포한 뒤 출시 상태를 확인합니다. Node.js 24 LTS를 사용하세요.

immercy help
immercy login
immercy project --json
immercy init
npm --prefix controller install
npm --prefix controller run build
immercy controller validate --json
immercy controller upload --json
# 게임을 빌드한 뒤 두 빌드를 함께 배포
immercy validate --json
immercy deploy --json
immercy preview --json
immercy release --json

프리뷰 다음: 출시와 공유

PC와 스마트폰으로 프리뷰를 확인한 뒤 원하는 공개 범위를 지정하세요.

immercy release --visibility unlisted  # 링크를 받은 사용자에게 공개
immercy release --visibility public    # 검토 승인 후 전체 공개
immercy release --visibility private   # 공개 중단

immercy release는 상태만 조회합니다. --visibility를 지정할 때만 공개 범위를 변경합니다. 에이전트는 사용자가 출시나 공개 범위 변경을 요청한 경우에 실행하세요. 게임과 컨트롤러 빌드가 모두 있어야 출시할 수 있습니다.

전체 공개는 공개 검토 중 또는 공개 차단이 될 수 있습니다. release로 저장된 상태를 다시 확인하고, 공유 가능한 상태에서 표시되는 게임 링크를 전달하세요. 문의가 필요하면 결과에 나온 문의하기 주소를 사용하세요.

deploy와 controller upload는 공개 범위를 유지합니다. 이미 출시한 게임은 같은 링크에서 새 빌드로 바뀌며, 전체 공개 게임은 다시 검토될 수 있습니다.

출력과 에이전트 연동

일반 출력은 상태와 다음 행동을 보여 줍니다. --json은 자동화용 전체 데이터를 반환합니다.

• project, deploy, controller upload: links, release, nextSteps 포함.
• release: 위 정보와 서버에서 반환한 project, 실제 변경 요청 여부인 changed 포함.
• preview: 기존 controllerPreview, integrationPreview, game 유지. gamePreview, releasePage, analytics, support, release, nextSteps 추가.
• release.status: missing-builds, private, pending, blocked, unlisted, public.
• release.available: 다른 사용자가 플레이할 수 있는 공개 상태인지 표시. true일 때만 release.shareUrl에 공유 주소가 들어갑니다. 실제 기기·게임 동작 검증 여부와는 별개입니다.

기존 game·배포 결과의 url은 페이지 주소입니다. 주소가 있다는 이유만으로 출시됐다고 판단하지 마세요. 공유 여부는 release.available을 사용하세요. 브라우저의 프리뷰·출시하기·통계에는 소유자 로그인이 필요합니다.

제작과 검증

init은 React + TypeScript + Vite 컨트롤러 소스와 연결 모듈을 생성합니다. 기존 파일은 유지합니다. HTML/CSS/JS나 다른 정적 빌드 도구도 사용할 수 있습니다. 모듈 API와 전체 규격은 immercy help를 확인하세요.

project --json과 init --json은 프로젝트 정보와 함께 gameIntegration, verificationGuide를 반환합니다. 에이전트는 웹 문서를 열지 않아도 자이로 aim 값 형식·좌표 변환 예제·게임 쪽 필수 구현·배포 및 실기기 확인 기준을 받을 수 있습니다. help game도 같은 입력 규격을 안내합니다.

자이로 조준 게임은 aim 수신 코드를 게임의 실제 조준선과 발사 방향에 연결해야 합니다. 플랫폼은 센서 권한·보정·좌표 전송을 처리합니다. 보정 포인터가 움직이거나 버튼이 동작하는 것만으로 게임 조준이 구현되지는 않습니다. 게임 입력 수정 후에는 게임을 재빌드하고 deploy로 업로드하세요.

validate와 deploy 결과의 inputVerification은 정적 파일 검사와 실제 입력 검증을 구분합니다. CLI는 게임의 aim 구현과 실제 스마트폰 동작을 실행 검사하지 않으므로, 게임 시작 후 조준선 이동·조준 위치로 발사·중앙 맞추기를 별도로 확인해야 합니다.

설정은 { projectId, buildDir: "dist", controllerBuildDir: "controller/dist", origin }입니다. 각 폴더에 index.html이 필요합니다. CLI는 빌드 명령을 실행하지 않으며 파일 검사 후 직접 Blob 업로드와 서버 검증을 거쳐 교체합니다. 전체 배포는 게임·컨트롤러를 원자적으로 교체하고 controller upload는 컨트롤러만 교체합니다.

키는 숨김 입력·환경 변수·Git에서 제외한 로컬 인증 파일로 관리합니다. 공통 옵션은 --config와 --json입니다. JSON 결과는 stdout, 오류와 진행은 stderr입니다.

이전 설정의 controller 속성은 삭제하고 controllerBuildDir을 지정하세요. 예전 컴포넌트 API는 제거되었습니다. 기존 게임도 새 연결 모듈로 다시 빌드하고 정적 컨트롤러와 함께 재배포해야 합니다.