개발자 문서

웹 게임은 window.altis로 이벤트 기록과 클라우드 세이브를 쓸 수 있어요. 승인될 때 자동으로 붙으니 스크립트 태그를 넣지 않아요. SDK를 쓰지 않아도 플레이 횟수·시간은 집계돼요.

// SDK 는 없을 수도 있으니 항상 옵셔널 체이닝
window.altis?.track("level_clear", { level: 3, time_sec: 42.1 });

// 클라우드 세이브
await window.altis?.save("main", { level: 3, hp: 80 });
const save = await window.altis?.load<{ level: number; hp: number }>("main"); // 없으면 {}

• 내 PC에서 개발할 때는 window.altis가 없어요. 항상 window.altis?.로 불러 SDK가 없어도 게임이 돌아가게 해요.
• 플레이 세션 시작·끝 이벤트는 자동으로 집계돼요. 직접 보내지 않아요.
• 개인정보(이메일 등)를 이벤트나 세이브에 넣지 않아요. 저장은 매 프레임이 아니라 체크포인트에서, 5초 넘는 간격으로 해요.

AI에게 통합 맡기기

아래 프롬프트를 게임 코드와 함께 붙여 넣으면 같은 규칙으로 통합해 줘요.

너는 HTML5 게임에 Altis 플랫폼 SDK 를 통합하는 작업을 한다. 규칙:

1. SDK 는 window.altis 로 제공되며 존재하지 않을 수 있다. 모든 호출은 window.altis?. 옵셔널 체이닝으로 감싸고, 없을 때도 게임이 정상 동작해야 한다. 스크립트 태그를 추가하지 마라 (플랫폼이 자동 주입한다).

2. API
   - window.altis.track(name: string, props?: object): boolean — 이름은 snake_case 64자 이내, props 는 JSON 직렬화 1KB 이내(초과 시 props 만 버려짐), 세션당 500회.
   - window.altis.save(slot?: string, data: object): Promise<{data, updated_at} | {local: true}> — JSON 직렬화 가능, 슬롯당 64KB 이내, 슬롯명 [A-Za-z0-9_-]{1,32} (생략 시 "default").
   - window.altis.load<T>(slot?: string): Promise<T | {}> — 없으면 빈 객체.
   - window.altis.user(): { id: string|null, anon_id: string, logged_in: boolean }
   - window.altis.flush(): void — 큐에 쌓인 이벤트 즉시 전송 (보통 필요 없음).
   - 로그인 메서드는 없다. 로그인은 Altis 플레이 페이지가 담당한다.

3. 하지 말 것
   - 플레이 세션 시작/종료 이벤트를 직접 보내지 마라 (자동 집계).
   - 개인정보(이메일, IP, 기기 식별자)를 props 나 save 데이터에 넣지 마라.
   - 매 프레임 track 이나 save 를 호출하지 마라. 세이브는 체크포인트·레벨 클리어·메뉴에서, 최소 5초 간격.
   - 게임 안에 로그인 화면을 만들지 마라. 로그인은 Altis 가 플레이 전에 처리한다.

4. 해야 할 것
   - 게임 시작 시 load("main") 으로 세이브를 불러오고, 빈 객체면 새 게임. 실패해도 새 게임으로 진행.
   - 기존 localStorage 세이브 코드가 있으면 altis.save/load 로 바꾸되, window.altis 가 없을 때는 기존 localStorage 경로를 그대로 쓴다.
   - 의미 있는 진행 이벤트만 track: game_start, level_start {level}, level_clear {level, time_sec, deaths}, game_over {level, score}, ending {id}.

5. 출력: 바뀐 파일 전체와, 어디에 무엇을 추가했는지 3줄 요약. 새 의존성은 추가하지 마라.

• 게임은 사이트 안의 iframe에서 돌아가요. sandbox 값은 allow-scripts allow-same-origin allow-pointer-lock allow-forms예요.
• 팝업·새 창·파일 다운로드는 동작하지 않아요.
• 외부 서버를 부르는 코드는 심사 때 표시돼 확인 대상이 돼요. 외부 로그인이나 개인정보 요구는 창작자 약관상 금지예요.
• 플레이어는 로그인한 뒤 플레이해요. 게임 안에 로그인 화면을 만들지 않아요.
• 승인되면 index.html에 플레이 집계 스크립트가 자동으로 붙어요.
• Unity WebGL은 멀티스레드(threads) 옵션을 켠 빌드가 동작하지 않아요.

• 승인되면 맨 위에 {게임 이름}.exe(Altis 실행 도우미), 그 옆에 game/(올린 파일 그대로, exe 이름 유지)과 파일 확인용 목록이 놓여요.
• 실행 도우미는 세이브 내려받기 → 게임 실행 → 세이브 올리기, 플레이 기록, 파일 변조 검사를 해요. 처음 게임을 설치하거나 켤 때 Windows 가 “Altis 도우미”(방화벽 허용) 설치를 물어봐요. 거절해도 게임은 켜져요.
• 승인된 코드 파일(exe·dll·asar·pck 등)이 바뀌면 실행이 막혀요. 수정은 새 버전으로 올려요.
• Unity·Godot·Unreal은 클라이언트가 전체화면 옵션을 붙여 실행해요. 그 밖의 엔진은 게임 설정에서 전체화면을 기본으로 켜 둬요.
• 게임을 켜는 exe는 하나로 정할 수 있어야 해요. Unity·Godot·Unreal·RPG Maker·Electron은 엔진 규칙으로 찾고, 그 밖의 엔진은 exe가 하나여야 해요.

• 업로드 1단계에서 적은 폴더를 통째로 저장해요. 플레이어·게임당 100MB, 최근 3개 보관.
• 되는 곳: %APPDATA%, %LOCALAPPDATA%, %USERPROFILE% 아래의 게임 전용 폴더, 또는 게임 폴더 안(.\saves, .\save.json, .\*.sav).
• 안 되는 곳: 넓은 폴더(문서, AppData 자체 등), .., {Company} 같은 자리표시자, 다른 드라이브, 다른 프로그램 폴더.
• 300자 이하. C:\Users\이름\...로 적으면 변수 표기로 바꿔 저장해요.
• 심사 때 관리자가 게임을 실행해 실제로 저장되는지 확인해요. 맞지 않으면 보류되고, 경로만 고치면 순서 그대로 이어서 심사해요.

• zip 하나, 최대 500MB. 압축을 풀면 합계 2GB, 항목 50,000개까지.
• 올리다 끊겨도 24시간 안에 같은 파일을 다시 고르면 이어서 올라가요. 새로 올리기는 한 시간에 10번까지예요.
• zip 전체가 폴더 하나로 감싸져 있으면 그 폴더를 벗겨 내고 봐요.
• 막히는 것: 폴더 밖을 가리키는 경로, 심볼릭 링크, Windows에서 못 쓰는 이름(CON AUX NUL COM1 등, < > : " | ? *, 끝의 점·공백), 대소문자만 다른 같은 이름, 압축 폭탄.
• Altis에서 받은 배포본(altis-manifest.json이 든 zip)은 다시 올리지 않아요.

업로드 화면은 브라우저에서 zip 목록을 읽어 종류와 엔진을 정하고, 둘 다 가능할 때만 물어봐요.

Windows 게임은 Epic Online Services(EOS)로 온라인 멀티플레이를 만들 수 있어요. 방장 PC + EOS P2P(필요하면 릴레이), 기기 ID 로그인, 창작자가 직접 등록한 EOS 키를 써요. 전용 서버와 웹 게임의 온라인 멀티는 아직 받지 않아요.

처음이면 7단계 안내부터. 준비 순서는 EOS 준비하기, 엔진별 연결은 Godot · Unity · Unreal, 올릴 때 체크는 멀티 게임 올리기를 보세요. Windows 방화벽 창은 Altis 클라이언트가 미리 허용해 둬서 뜨지 않아요.