ZUKU 개발 문서

01 / FIRST RUN

HTML5 ZIP에서 ZWF2까지

zwf 저장소의 컴파일러는 HTML5 ZIP을 ZWF2 .zwf로 만들고 매니페스트와 파일 해시를 검사합니다. Git, Node.js 22 이상, npm, zip을 준비하세요. npm 게시 패키지가 아닌 저장소 소스에서 실행합니다.

1. 공개 저장소를 복제하고 테스트를 실행합니다.
2. 포함된 HTML 예제를 ZIP으로 묶습니다.
3. 컴파일한 파일을 inspect로 다시 검사합니다.

git clone https://github.com/zukuapp/zwf.git
cd zwf
npm ci
npm test
zip -j hello.zip examples/hello/index.html
node src/cli.mjs compile hello.zip -o hello.zwf --title "Hello ZWF"
node src/cli.mjs inspect hello.zwf

검사 결과에서 version: 2, profile: "html5-sandbox/2", entry_point: "index.html"을 확인하세요. 컴파일러는 기존 출력 파일을 덮어쓰지 않습니다. 직접 만든 앱은 스크립트·글꼴·이미지 등 필요한 파일을 ZIP에 포함하고 상대 경로를 사용해야 합니다.

전체 사용법 ↗ZWF2 형식 명세 ↗GitHub 입문 문서 ↗

02 / SOURCE MAP

공개 저장소 지도

각 저장소는 서로 다른 역할을 맡습니다. 먼저 상태를 확인하고, 정확한 명령과 데이터 구조는 해당 저장소의 문서를 따르세요.

Next2D 기반 ZUKBOX 저장소는 아래 저작·재생 경로에서 분리해 설명합니다.

03 / JUMP

Jump 패키지 계약

zuku-engine-next2d에는 패키지 매니페스트 스키마와 런타임 계약, 공개 검증·어댑터 코드가 있습니다. 이 저장소만으로 서비스 호스트의 격리 환경이나 배포 파이프라인이 제공되는 것은 아닙니다.

zuku-cli는 현재 시제품입니다. create, validate, package, upload 명령의 성공 메시지를 실제 작업 완료로 해석하지 마세요. 로컬에서 실제 HTML5 ZIP을 패키징하려면 위의 ZWF2 경로를 사용하세요.

04 / API

서비스 API와 공개 명세

실제 ZUKU 서비스의 /api/v1 연동은 ZUKU API 가이드에서 시작하세요. 인증, 콘텐츠·미디어 게시, 커뮤니티와 게임 클라우드의 현재 사용 범위 및 예제가 정리돼 있습니다.

별도의 공개 OpenAPI 3.1 초안은 설계 중인 경로와 요청·응답 형태를 설명합니다. 예를 들어 이 초안은 /contents 경로와 offset/limit 페이지 이동을 정의합니다. 공개 SDK 소스는 골격 단계이며, 초안만으로 npm 설치나 운영 엔드포인트 이용 가능 여부를 판단할 수 없습니다.

서비스 API 가이드 ↗저장소와 상태 보기 ↗OpenAPI 원문 ↗

05 / AUTHORING & PLAYBACK

ZUKBOX 저작·재생

zukbox는 Next2D 저작 도구 포크, zukbox-player는 렌더링 플레이어 포크, zukbox-lang은 언어 리소스 포크입니다. zukbox-runtime은 이전 ZWF1 바이너리의 파싱과 타임라인 평가를 맡는 별도 Rust/WebAssembly 코드입니다.

포크의 원본 API 문서와 라이선스는 그대로 따라야 합니다. ZUKU 변경점과 로컬 실행 명령은 각 포크의 README를 확인하세요.

06 / FORMAT BOUNDARY

같은 확장자, 다른 형식

두 형식은 .zwf 확장자를 공유하지만 같은 파서에 넣을 수 없습니다. ZWF2 플레이어는 컨테이너·경로·크기·해시를 검증하고 불투명 출처의 격리된 iframe과 CSP 등 명세의 실행 경계를 따라야 합니다. 이 경계가 CPU·메모리 사용량의 결정적 제한을 의미하지는 않습니다.

공개 아키텍처 전체 보기 ↗저장소 지도 ↗

07 / WORK TOGETHER

문서·코드 변경 제안

변경할 코드나 명세를 소유한 저장소에 이슈 또는 PR을 남기고, 재현 절차·예상 결과·검증 결과를 적어 주세요. 이 사이트의 오탈자나 잘못된 링크는 사이트 저장소에서 제안할 수 있습니다.

취약점은 공개 이슈에 적지 말아 주세요. 비공개 신고 경로를 이용해 주세요.

기여 안내 ↗보안 정책 ↗지원 안내 ↗