Hanyul Park
Repositories 12 Projects Packages 9 Stars Public activity

@arca/rgss123 1.0.0 npm

Published 2026-10-31 12:05:39 +09:00 by hanyul in hanyul/rgss123-web

Installation

@arca:registry=
npm config set @arca:registry=
npm install @arca/rgss123@1.0.0
"@arca/rgss123": "1.0.0"

About this package

@arca/rgss123

ARCA 프로젝트의 하위 프로젝트인 rgss123-web이 게시한 정확한 release 하나를 설치하는 배포 패키지다. RPG Maker 게임을 브라우저에서 실행하려는 host가 player SDK, runtime, contracts와 Builder를 같은 release로 고정해 받는다.

  • 들어 있는 것: Player SDK, public contracts와 타입, native JS/WASM, license/provenance, release pin과 Builder OCI archive, Node 배포 helper와 RTP 관리 API.
  • 들어 있지 않은 것: 게임과 RTP 원본.
  • 런타임과 Builder를 다운로드하거나 실행하는 install hook은 없다.
  • Builder는 Docker에서 실행하는 독립 컨테이너다.

1.0.0 이름 변경

1.0.0은 0.1.x의 @rgss23/arca에서 이름을 바꾼 첫 rgss123 release다. deprecation 기간 없이 사용자 승인으로 바꿨고(2026-10-29·31 사용자 결정) 이전 이름은 export·CLI 어디에서도 받지 않는다.

  • package: @rgss23/arca → @arca/rgss123, tarball rgss23-arca-<version>.tgz → rgss123-arca-<version>.tgz. registry scope 줄은 @arca:registry=다.
  • API·타입: Rgss23*와 Arca* → Rgss123*(예: launchRgss23Player → launchRgss123Player, getArcaRelease → getRgss123Release, prepareArcaRtp → prepareRgss123Rtp, ArcaRtpOptions → Rgss123RtpOptions). ArcaBuilderError·ArcaBuilderErrorCode는 packager의 Rgss123BuilderError와 구분해 Rgss123BuilderImageError·Rgss123BuilderImageErrorCode다.
  • 오류 code: ARCA_* → RGSS123_*. message 안의 ARCA는 rgss123이다.
  • CLI: arca-release → rgss123-release.
  • contracts: schema·contract·interface ID rgss23-* → rgss123-*, links-rgss23-web-launch-v1 → links-rgss123-web-launch-v1.
  • player SDK: 기본 저장소의 save 경로 prefix arca-path-v1/ → rgss123-path-v1/, runtime 가상 경로 /arca/ → /rgss123/, OPFS·Web Lock·storage namespace rgss123-*. 이전 prefix로 저장한 snapshot 키는 원래 파일로 복원되지 않는다.

설치와 검증

@arca:registry=https://git.2ex.dev/api/packages/hanyul/npm/

pnpm add --save-exact @arca/rgss123@VERSION
pnpm exec rgss123-release verify
  • 신뢰 기준: 호스트의 lockfile integrity가 설치한 package의 신뢰 기준이다.
  • verify는 추가로 package 내부 파일·원본 release manifest·artifact hash·Builder digest를 대조한다.
  • browser import는 파일 검증이나 Node/Docker 실행을 수행하지 않는다.

처음 사용

import { launchRgss123Player } from "@arca/rgss123";
import type { Rgss123SaveAdapter } from "@arca/rgss123/contracts";
// Node deployment code only; never import this subpath in the browser.
import { getRgss123Release, stageRgss123Release } from "@arca/rgss123/deploy";
const release = await getRgss123Release();
// release.releaseDirectory: unchanged canonical release set for existing hosts.
// release.runtimeDirectory: verified static runtime assets and licenses.
// release.builder: exact digest and offline-loadable OCI archive path.
const installed = await stageRgss123Release("/runtime-releases");
// installed.releaseDirectory = /runtime-releases/<manifestSha256>

export

export 실행 환경 내용과 사용법
@arca/rgss123 browser player SDK. 사용법은 rgss123-web 저장소의 packages/player-sdk/README.md
@arca/rgss123/contracts, @arca/rgss123/contracts/* browser·Node public contracts와 타입. 사용법은 이 package의 contracts/README.md, 동일성은 contracts export 동일성
@arca/rgss123/deploy Node 전용 release 검증·배포와 Builder helper. 배포부터 배포 오류 code까지
@arca/rgss123/rtp Node 전용 RTP 준비·조회. RTP 관리
@arca/rgss123/runtime/* asset native JS/WASM과 license. bundler의 asset URL 처리 또는 Node의 import.meta.resolve()에 사용할 수 있다
@arca/rgss123/release-pin.json JSON 이 package의 release pin
@arca/rgss123/package.json JSON package metadata

JS와 WASM은 같은 release 경로로 배포하고 기존 configuration의 MIME·isolation 요구를 유지한다.

engine 선언과 지원 판정

  • engines는 지원 판정이 아니다: runtime ZIP configuration.json의 engines는 이 runtime이 해당 engine(rpg-maker-vx·rpg-maker-vx-ace·rpg-maker-xp)의 game을 받아 실행한다는 선언이다. 사용자 acceptance나 그 engine 전체의 일반 지원을 뜻하지 않는다.
  • release manifest에는 engine 목록이 없다.
  • engine·기능별 판정은 rgss123-web 저장소의 docs/compatibility-matrix.md가 소유한다.
  • rpg-maker-xp의 근거는 제공 XP 샘플 하나의 자동 smoke뿐이고 사용자 acceptance는 실행하지 않았다.

배포

stageRgss123Release(DIR) 또는 rgss123-release stage DIR을 실행하면 hash별 새 디렉터리가 완성된 뒤에만 노출된다.

  • 기존 경로의 손상이나 다른 내용은 덮어쓰지 않고 실패한다.
  • 같은 package 재배포는 검증 후 재사용한다.
  • 실패 시 이전 release와 실행 중인 generation을 그대로 보존한다.
  • 새 hash에 결속: 배포가 끝나면 호스트가 새 실행을 새 manifest hash에 결속해야 한다.
  • 이미 만들어진 game/RTP package의 재사용 판정, generation 교체, session과 save 보존은 호스트 책임이다.
  • dependency 설치만으로 기존 DB의 active build를 바꾸지 않는다.

@arca/rgss123/deploy의 API는 아래와 같다. 도입이 0.1.14인 API는 0.1.13 이하 package에 없다.

API 하는 일 도입
getRgss123Release() 설치된 package를 검증하고 release·runtime 디렉터리, pin과 Builder digest·archive 경로를 돌려준다 0.1.14 이전
stageRgss123Release(DIR) hash별 immutable 디렉터리로 배포(배포) 0.1.14 이전
verifyRgss123RuntimeDirectory() runtime 해제본 결속 검증 0.1.14
verifyRgss123Contracts() contracts export 동일성 검증 0.1.14
getRgss123BuilderIsolation(), rgss123BuilderRunArguments(), loadRgss123Builder() Builder 실행 helper 0.1.14
실패의 code 배포 오류 code 0.1.14

runtime 해제본 결속 검증

verifyRgss123RuntimeDirectory()(0.1.14부터)는 해제된 runtime 디렉터리를 release manifest의 runtime ZIP에 결속한다. 호스트는 ZIP을 직접 풀거나 별도 해제기를 둘 필요가 없다.

import { stageRgss123Release, verifyRgss123RuntimeDirectory } from "@arca/rgss123/deploy";
const installed = await stageRgss123Release("/runtime-releases");
const runtime = await verifyRgss123RuntimeDirectory({
  releaseDirectory: installed.releaseDirectory, // 기본값: package의 release/
  runtimeDirectory: "/srv/rgss123-runtime",        // 기본값: package의 runtime/, 호스트 복사본도 가능
});
// runtime.manifestSha256 === installed.pin.manifestSha256
// runtime.runtimeArtifact.sha256 === installed.pin.artifacts.runtime

검증 순서는 다음과 같으며 파일을 쓰거나 고치지 않는다.

  1. getRgss123Release()로 설치된 package를 검증한다.
  2. release 디렉터리의 runtime ZIP을 manifest·pin의 bytes·SHA-256과 대조한다.
  3. ZIP의 모든 entry를 CRC를 확인하며 읽어 runtime 디렉터리의 파일과 path·bytes·SHA-256을 1:1로 비교한다.
결과 필드 내용
manifestSha256 설치된 pin과 같은 release manifest hash
runtimeArtifact 실제로 읽은 ZIP의 { fileName, bytes, sha256 }
inventory ZIP의 모든 파일 entry(디렉터리 제외)의 { path, bytes, sha256 }. ASCII path의 ordinal 오름차순
configuration configuration.json이 가리키는 module(entrypoint와 exportName), javascript, wasm, checksums(SHA256SUMS), license(manifest의 license file·SHA-256) 각각의 inventory 항목과 interface: "rgss123-runtime-v1", saveInterface

결속 조건:

  • module path는 manifest의 entrypoint와 같아야 한다.
  • save interface는 같은 package의 contracts rgss123SaveContract.interface와 같아야 한다.
  • ZIP 안의 SHA256SUMS도 자신을 뺀 inventory와 정확히 일치해야 한다.
  • ZIP이 목록화한 빈 디렉터리는 runtime 디렉터리에 없어도 된다.
  • 그 밖의 추가 파일·디렉터리, symlink·junction 같은 link, 일반 파일이 아닌 항목은 거부한다.
  • immutable 경로로 게시: 검증은 호출 시점의 내용을 대조하므로 호스트는 검증한 디렉터리를 이후 바꾸지 않는 immutable 경로로 게시한다.

실패하면 code와 해당하는 경우 상대 path를 가진 Error를 던진다. message는 CODE: 설명 형식이다.

code 의미
RGSS123_RUNTIME_PACKAGE_INVALID 설치된 package의 integrity·pin 검증(getRgss123Release()) 실패
RGSS123_RUNTIME_RELEASE_MISMATCH release 디렉터리의 manifest를 읽을 수 없거나 hash가 설치된 pin과 다름
RGSS123_RUNTIME_ARTIFACT_MISMATCH runtime ZIP이 없거나 bytes·SHA-256이 manifest와 다름(검증 중 변경 포함)
RGSS123_RUNTIME_ARTIFACT_INVALID ZIP 구조·CRC 오류 또는 ZIP 안의 SHA256SUMS 불일치
RGSS123_RUNTIME_CONFIGURATION_MISMATCH configuration.json이 canonical이 아니거나 entrypoint·core·WASM·license·save interface 결속 불일치
RGSS123_RUNTIME_ENTRY_MISSING ZIP의 파일 또는 runtime 디렉터리 자체가 없음
RGSS123_RUNTIME_ENTRY_UNEXPECTED runtime 디렉터리에 ZIP에 없는 파일·디렉터리가 있음
RGSS123_RUNTIME_ENTRY_MISMATCH 같은 path의 bytes 또는 SHA-256이 ZIP entry와 다름
RGSS123_RUNTIME_PATH_UNSAFE link·일반 파일이 아닌 항목, ZIP entry의 경로 탈출·대소문자 중복, link인 release·runtime 디렉터리

contracts export 동일성

  • @arca/rgss123/contracts와 @arca/rgss123/contracts/*가 가리키는 package의 contracts/ 디렉터리는 release manifest·pin에 고정된 contracts tarball(rgss123-contracts-<version>.tgz)의 package/ 아래 파일과 path·bytes·내용이 1:1로 같다.
  • 이는 공개 계약이며 npm 생성 단계도 포장 전에 이 검증을 통과해야 한다.
  • 호스트는 tarball을 직접 풀거나 해제한 코드를 동적 import하지 않고 @arca/rgss123/contracts를 정적으로 import하면 된다.
import { verifyRgss123ReleaseSetPin } from "@arca/rgss123/contracts";
import { verifyRgss123Contracts } from "@arca/rgss123/deploy";
const contracts = await verifyRgss123Contracts(); // 선택: { releaseDirectory, contractsDirectory }
// contracts.contractsArtifact.sha256 === release.pin.artifacts.contracts

verifyRgss123Contracts()(0.1.14부터)는 동일성을 직접 확인한다.

  • 순서: 먼저 getRgss123Release()로 package를 검증하고, release 디렉터리의 contracts tarball을 manifest·pin과 대조한 뒤 checksum이 맞는 일반 파일 entry만 읽어 디렉터리와 비교한다.
  • 결과: manifestSha256, contractsArtifact(fileName·bytes·sha256), manifest의 package(name·version)와 ordinal path 순 inventory다.
  • 선택 인자: releaseDirectory로 stageRgss123Release() 디렉터리를, contractsDirectory로 호스트 복사본을 검증할 수 있다.
  • 실패 형식은 runtime 검증과 같다(code, 해당하면 path, message CODE: 설명).
code 의미
RGSS123_CONTRACTS_PACKAGE_INVALID 설치된 package의 integrity·pin 검증 실패(원인은 cause.code)
RGSS123_CONTRACTS_RELEASE_MISMATCH release 디렉터리의 manifest를 읽을 수 없거나 hash가 설치된 pin과 다름
RGSS123_CONTRACTS_ARTIFACT_MISMATCH contracts tarball이 없거나 bytes·SHA-256이 manifest와 다름
RGSS123_CONTRACTS_ARTIFACT_INVALID gzip·ustar header 오류, 일반 파일이 아닌 entry 또는 package/ 밖 entry
RGSS123_CONTRACTS_ENTRY_MISSING tarball의 파일 또는 contracts 디렉터리 자체가 없음
RGSS123_CONTRACTS_ENTRY_UNEXPECTED contracts 디렉터리에 tarball에 없는 파일·디렉터리가 있음
RGSS123_CONTRACTS_ENTRY_MISMATCH 같은 path의 내용이 tarball entry와 다름
RGSS123_CONTRACTS_PATH_UNSAFE link·일반 파일이 아닌 항목, entry 경로 탈출·대소문자 중복, link인 release·contracts 디렉터리

Builder 실행 helper

0.1.14부터 @arca/rgss123/deploy는 Builder OCI를 실행할 때 필요한 load·인자·격리만 제공한다. Docker socket 위치, Compose 사용, job·lease·heartbeat·재시도·출력 게시와 CAS는 호스트 정책이며 rgss123-web helper에 넣지 않는다.

import { rgss123BuilderRunArguments, getRgss123BuilderIsolation, loadRgss123Builder } from "@arca/rgss123/deploy";
const { imageId } = await loadRgss123Builder(); // 선택: { builder: staged.builder, dockerCommand, signal }
const args = rgss123BuilderRunArguments({
  image: imageId, command: "package",
  input: "/sealed/payload", output: "/attempt/output", configFile: "/attempt/build.json",
});
// execFile("docker", args): 실행·종료 감시는 호스트가 맡는다.

격리: getRgss123BuilderIsolation()

release gate가 실제로 검증한 격리를 data로 반환한다. Compose를 쓰는 호스트는 service 정의를 이 값과 대조한다.

항목 값
user 10001:10001
init init 사용
root filesystem read-only
network none
capability cap_drop: [ALL]
security option no-new-privileges:true
tmpfs /tmp:rw,noexec,nosuid,nodev,size=16m,uid=10001,gid=10001
memory 1g
mount /input·/config read-only, /output만 writable

실행 인자: rgss123BuilderRunArguments()

  • inspect(/output/inspection.json)와 package의 docker 인자를 만든다.
  • package는 다음 중 하나를 받는다: build.json 하나를 /config/build.json에 mount하는 configFile, 또는 RTP·overlay 입력까지 담은 디렉터리를 /config에 mount하는 configDirectory.
  • path는 절대 host path여야 하고 --mount를 깨는 쉼표·따옴표·줄바꿈을 거부한다.
  • memory로 큰 게임의 상한을 올리거나 null로 생략하고, name으로 호스트가 종료할 container 이름을 지정할 수 있다.
  • 다른 격리 flag는 바꿀 수 없다.

image load: loadRgss123Builder()

  • release의 Builder archive에서 OCI manifest digest(pin)와 config digest를 직접 읽는다. archive가 pin된 digest를 담지 않으면 거부한다.
  • 둘 중 하나가 이미 daemon에서 resolve되면 그대로 둔다.
  • 아니면 docker load한 뒤 출력이 두 digest 또는 archive의 rgss123-builder:<version> tag를 알리고 docker image inspect가 두 digest 중 하나로 성공하는지 확인한다.
  • pull·run은 하지 않는다.

반환값은 { digest, configDigest, imageId, imageName, loaded }다.

필드 내용
digest pin된 manifest digest
configDigest archive의 OCI image config descriptor digest(0.1.21부터)
imageId (0.1.18부터) daemon이 resolve한 image ID. containerd image store는 manifest digest, Docker Engine 24·graphdriver store는 config digest
imageName load가 붙이는 tag(0.1.18부터)
loaded 이번 호출이 docker load를 실행했으면 true, 이미 resolve되어 그대로 두었으면 false
  • imageId로 실행: Docker 24는 load한 image에 RepoDigests를 기록하지 않아 manifest digest로 실행할 수 없으므로 Builder는 imageId로 실행한다.
  • tag는 다른 load가 옮길 수 있어 identity로 쓰지 않는다.

Docker 없이 identity 대조

  • getRgss123Release().builder(stageRgss123Release()도 같음)의 digest·configDigest를 쓴다. daemon socket이 필요 없다.
  • 0.1.21부터 release pin builderConfigDigest가 config digest를 담는다. 0.1.20 이하 pin에는 이 필드가 없다.
  • getRgss123Release()는 integrity로 결속된 archive의 OCI manifest·config blob을 읽어 두 digest가 pin과 같을 때만 값을 돌려준다. 다르면 RGSS123_RELEASE_BUILDER_MISMATCH, archive bytes가 바뀌면 그 전에 RGSS123_RELEASE_INTEGRITY_MISMATCH다.
  • host는 docker load 뒤 daemon이 resolve한 image ID가 둘 중 하나와 같을 때만 그 ID로 실행한다.
  • rgss123-release verify·stage 출력 JSON에도 같은 builder.configDigest가 들어간다.

archive 형식

Builder archive(rgss123-builder-<version>.oci.tar)는 0.1.18부터 OCI image layout에 Docker Engine 24가 읽는 docker-save manifest.json을 더한 형식이다. 파일 이름과 MIME application/vnd.oci.image.layout.v1.tar는 그대로다.

Builder 오류 code

code 의미
RGSS123_BUILDER_ARGUMENT_INVALID image·command·path·memory·name 또는 config 조합이 계약 밖
RGSS123_BUILDER_DOCKER_UNAVAILABLE docker 실행 파일을 찾지 못함
RGSS123_BUILDER_LOAD_FAILED docker load가 archive를 거부하거나, archive를 읽을 수 없거나 OCI layout·manifest.json 구조가 계약 밖
RGSS123_BUILDER_DIGEST_MISMATCH archive가 pin된 digest를 담지 않거나, load 뒤 manifest·config digest가 출력·daemon에서 확인되지 않음

배포 오류 code

  • 0.1.14부터 getRgss123Release()와 stageRgss123Release()의 실패에는 code가 붙는다.
  • message 문장은 0.1.13과 같지만 1.0.0에서 문장 안의 ARCA가 rgss123으로 바뀌었으므로 message 대신 code로 분류한다.
  • 설치 package 파일이 없을 때의 ENOENT 같은 Node system error는 자신의 code를 유지한다.
code 의미
RGSS123_RELEASE_PATH_UNSAFE package·release 경로의 link, 일반 파일이 아닌 항목 또는 안전하지 않은 path
RGSS123_RELEASE_PACKAGE_INVALID package 이름·integrity.json 형식 오류, 그 밖에 읽을 수 없는 package metadata
RGSS123_RELEASE_INTEGRITY_MISMATCH integrity.json과 package 파일 hash 불일치
RGSS123_RELEASE_PIN_MISMATCH package version·manifest·pin·.sha256 결속 불일치
RGSS123_RELEASE_MANIFEST_INVALID artifact role·file name·license 승인 정책 위반
RGSS123_RELEASE_ARTIFACT_MISMATCH release artifact의 bytes·SHA-256이 manifest·pin과 다름
RGSS123_RELEASE_BUILDER_MISMATCH Builder digest가 manifest·pin과 다름
RGSS123_RELEASE_STORE_UNSAFE stageRgss123Release() 저장 경로가 link
RGSS123_RELEASE_STAGE_CONFLICT 같은 hash 경로에 다른 내용 또는 디렉터리가 아닌 항목이 있음(덮어쓰지 않음)
RGSS123_RELEASE_STAGE_INCOMPLETE 같은 hash 경로가 불완전함(덮어쓰지 않음)

rgss123-release CLI

rgss123-release --help는 명령 목록을 출력한다. 0.1.14에서 verify-contracts, builder-isolation, builder-load 명령을 추가했다.

명령 API
rgss123-release verify getRgss123Release()
rgss123-release stage DIR stageRgss123Release(DIR)
rgss123-release verify-contracts verifyRgss123Contracts()
rgss123-release builder-isolation getRgss123BuilderIsolation()
rgss123-release builder-load loadRgss123Builder()
rgss123-release rtp-catalog, rtp-prepare CONFIG.json, rtp-get CONFIG.json RTP CLI
  • 성공 시 JSON 한 줄을 stdout에 쓴다.
  • 실패하면 stack trace 대신 stderr에 CODE: message 한 줄을 쓰고 exit 1로 끝난다(message가 이미 code로 시작하면 그대로).
  • 사용법 오류는 RGSS123_CLI_USAGE, code가 없는 오류는 RGSS123_CLI_FAILED다. RTP code는 RTP 관리를 따른다.

RTP 관리

Node 전용 API(0.1.7부터)가 공식 VX/VX Ace RTP와 XP RTP(RPGXP, 1.0.0 @arca/rgss123부터)의 다운로드·추출·패키징·검증·캐시를 처리한다.

  • 호스트는 RTP ID와 영구 저장 경로만 제공한다.
  • npm에는 원본 데이터 대신 고정된 공식 source catalog와 Windows x64·Linux x64/glibc용 innoextract 1.9가 들어 있다.
  • Node 22 이상을 사용하며 별도 추출 도구 설치나 Docker socket은 필요 없다.
import { getRgss123RtpCatalog, prepareRgss123Rtp, getRgss123Rtp } from "@arca/rgss123/rtp";
const catalog = await getRgss123RtpCatalog();
const rtp = await prepareRgss123Rtp({ id: "RPGVXAce", storeRoot: "/state/rgss123-rtp" });
// rtp.archivePath + rtp.manifestPath → existing Builder/host portable RTP inputs.
const cached = await getRgss123Rtp({ id: "RPGVXAce", storeRoot: "/state/rgss123-rtp" });

다운로드와 재시도

  • 캐시가 없을 때만 prepare가 공식 원본을 다운로드한다.
  • 시간 제한(0.1.15부터): 60초 동안 데이터를 받지 못하면 그 시도를 중단하고 전체 1시간을 넘기지 않는다. 0.1.14는 재시도 없이 전체 300초에서 끝냈다.
  • 재시도 대상: 연결 거부·재설정·끊김·시간 초과 같은 네트워크 전송 오류(Node·undici 오류 code로 판정), HTTP 5xx·429, 무수신. 같은 호출 안에서 최대 3회 다시 시도한다.
  • 대기: 2·8·30초 backoff 각각의 절반~전체 사이 jitter다. 5xx·429의 Retry-After보다 짧게 기다리지 않으며 Retry-After가 5분을 넘으면 더 시도하지 않고 실패한다.
  • 무수신이 계속되면 약 4~5분 뒤 실패로 보고한다.
  • 이어 받기: 재시도에서는 서버가 206과 받은 위치·전체 크기가 맞는 Content-Range로 응답할 때만 받은 부분 뒤부터 이어 받고, 그 밖에는 처음부터 받는다. 그런 206이 전체 크기 전에 끝나면(서버 range 상한) 받은 부분을 두고 다음 시도에서 이어 받는다.
  • 정상 종료된 200이 lock보다 짧으면 다른 파일로 보고 RGSS123_RTP_INPUT_MISMATCH로 끝낸다.
  • 재시도하지 않는 실패: HTTP 4xx, redirect·TLS·호스트 없음·URL 오류, 크기 초과, hash 불일치와 호출자 취소.
  • 최종 크기·SHA-256 검증은 항상 수행한다.

오프라인, 취소와 네트워크 경계

  • 오프라인은 sourceZipPath로 공식 원본(VX·VX Ace는 ZIP, XP는 설치 파일 xp_rtp104e.exe)을 제공하고 download: false를 지정한다.
  • signal로 다운로드·추출을 취소할 수 있다.
  • 설치 hook, catalog 조회, get은 네트워크를 사용하지 않는다. OS RTP 설치 프로그램도 실행하지 않는다.
  • Linux musl/Alpine·ARM64·macOS의 공식 ZIP 준비는 지원 대상으로 검증하지 않았다.

진행 알림: onProgress

prepareRgss123Rtp()의 선택 onProgress(event)(1.0.0부터)는 진행을 알린다.

event 필드 내용
phase downloading, verifying, extracting, packaging, storing, ready 중 하나. verifying은 공식 원본의 pin 검사와 공식 ZIP에서 고정된 설치 파일 member를 꺼내는 단계를 포함한다
storedBytes 이번 호출이 staging에 저장한 공식 원본 bytes. 재시도가 처음부터 다시 받으면 0으로 돌아간다
totalBytes 고정된 공식 원본 크기. 캐시 적중과 legacy 입력에서는 null
retries 지금까지 예약한 다운로드 재시도 수
  • 다운로드 중에는 저장한 chunk마다 event를 보내므로 화면 갱신 빈도는 host가 조절한다.
  • 캐시 적중은 ready 하나만 보낸다.
  • listener가 던진 오류는 준비 결과에 영향을 주지 않는다. 함수가 아닌 값은 RGSS123_RTP_OPTIONS_INVALID다.

legacy 입력과 반환 manifest

  • legacy 입력 sourceArchivePath(operator-provided .mkxpz)와 strict lock도 유지한다.
  • 기본 조회는 공식 캐시를 우선하고, 없으면 legacy 캐시를 재사용한다. sourceZipPath를 명시하면 공식 경로를 선택한다.
  • 공식 Ace는 1.0.0+official, legacy Ace는 0.0.0+locked.f66bd7f3이므로 반환된 manifest의 버전·hash를 사용한다.
  • XP는 1.4.0+english이고 archive 이름은 Game.ini RTP1=Standard에 맞춘 Standard.mkxpz다. RTP ID RPGXP와 다르므로 browser artifact fileName은 반환된 archivePath의 이름을 쓴다.
  • XP의 legacy lock은 공식 결과와 같은 bytes다.
  • 원본을 보고 lock을 추정하거나 손상된 기존 캐시를 덮어쓰지 않는다.
  • cache identity는 runtime 버전과 분리되며 host의 release binding·CAS·승인·generation·save 정책은 유지한다.

RTP CLI

CLI는 rgss123-release rtp-catalog, rgss123-release rtp-prepare CONFIG.json, rgss123-release rtp-get CONFIG.json이다. CONFIG는 API와 같은 JSON이며 signal과 onProgress를 제외한다. 최소 설정은 { "id": "RPGVXAce", "storeRoot": "/state/rgss123-rtp" }이다.

RTP 오류 code

  • 0.1.14부터 getRgss123Rtp()·prepareRgss123Rtp() 실패에 code가 붙는다. message 문장은 0.1.13과 같지만 접두어가 1.0.0에서 ARCA_RTP_*에서 RGSS123_RTP_*로 바뀌었다.
  • message 대신 error.code: 접두어가 없던 실패도 code로 분류되므로 호스트는 message 대신 error.code를 사용한다.
  • code는 실패한 단계가 직접 붙이므로 rgss123-web RTP 코드가 던지는 실패는 모두 아래의 구체 code를 갖는다.
  • package 검증 실패는 RGSS123_RELEASE_*다. 불완전한 캐시의 ENOENT 같은 Node system error는 자신의 code를 유지한다.
  • 호출자 signal의 취소·timeout은 error.name(AbortError·TimeoutError)으로 구분한다.
  • 다운로드의 rgss123-web 내부 제한(무수신·전체 시간)은 0.1.14까지 TimeoutError로 나왔지만 0.1.15부터는 RGSS123_RTP_DOWNLOAD_FAILED이고 error.cause.name이 TimeoutError다.
  • 단 동봉 innoextract 실행 중 취소·시간 초과는 0.1.13과 같은 RGSS123_RTP_EXTRACT_FAILED message·code이고 error.cause가 취소 오류다.
  • 원래 오류는 error.cause에 남을 수 있다.
code 의미
RGSS123_RTP_CACHE_MISS 준비된 캐시가 없음(getRgss123Rtp)
RGSS123_RTP_CACHE_INVALID 캐시가 있으나 lock·manifest·archive 내용·파일 형식이 맞지 않음(덮어쓰지 않음)
RGSS123_RTP_SOURCE_REQUIRED 오프라인 준비에 입력 ZIP·legacy archive가 필요함
RGSS123_RTP_OPTIONS_INVALID 함께 쓸 수 없는 입력 옵션 조합
RGSS123_RTP_ID_UNSUPPORTED RPGVX·RPGVXAce·RPGXP가 아닌 ID. message는 1.0.0에서 ARCA supports only RPGVX and RPGVXAce RTP.가 rgss123 supports only RPGVX, RPGVXAce and RPGXP RTP.로 바뀌었다
RGSS123_RTP_LOCK_INVALID lock 형식 오류, ID·engine 불일치 또는 HTTPS가 아닌 source
RGSS123_RTP_PLATFORM_UNSUPPORTED 동봉 innoextract가 없는 platform
RGSS123_RTP_DOWNLOAD_FAILED 공식 다운로드의 HTTP·네트워크 실패 또는 무수신·전체 시간 제한 초과(재시도 대상은 재시도 후)
RGSS123_RTP_INPUT_MISMATCH 입력·다운로드의 이름·bytes·SHA-256이 lock과 다르거나 준비 중 입력이 바뀜
RGSS123_RTP_SOURCE_INVALID 공식 ZIP·legacy archive의 구조, 고정 member 또는 portable payload 규칙 불일치
RGSS123_RTP_EXTRACT_FAILED 동봉 innoextract 추출 실패 또는 추출본을 RTP archive로 만들 수 없음
RGSS123_RTP_PATH_UNSAFE RTP 경로에 link·junction이 있음
RGSS123_RTP_OUTPUT_FAILED store staging의 출력 파일 작성·게시 실패
RGSS123_RTP_FAILED 어떤 RTP 단계도 분류하지 않은 실패(예: 손상된 release catalog)

license

  • 단일 MIT library가 아니다: native bundle에는 개별 재배포 조건이 있다. 패키지 전체를 단일 MIT library로 취급하지 말고 runtime/LICENSES/THIRD_PARTY_NOTICES.json과 동봉된 license/source provenance를 함께 배포한다.

RTP와 추출 도구의 license

  • 공식 RTP 약관은 데이터 재배포에 사전 서면 동의를 요구한다.
  • API는 실행 환경에서 원본을 취득·처리하며, 호출자는 이용·처리·제공에 필요한 권한을 확보해야 한다.
  • 권한은 별도다: 다운로드 자동화와 hash 일치는 사용·재배포 권한을 부여하지 않는다.
  • innoextract는 Daniel Scharrer의 Zlib license 도구다. 동봉 바이너리의 Boost, liblzma, libstdc++ runtime exception, Linux libbz2/zlib 등 전체 license는 rtp/tools/win32-x64/license/와 rtp/tools/linux-x64/license/에 보존한다.
  • 원본 archive URL·크기·SHA-256과 포함 파일의 SHA-256은 rtp/innoextract.lock.json에 고정한다.
  • native runtime의 별도 license는 runtime/LICENSES/THIRD_PARTY_NOTICES.json을 따른다.

Details

hanyul
hanyul/rgss123-web
npm
SEE LICENSE IN README.md
latest
99 MiB
Published 2026-10-31 12:05:39 +09:00
Downloads 161
Last downloaded 2026-11-04 20:45:01 +09:00

Assets 1

Versions 1

View all
Issues