rgss123-web

RPG Maker VX·VX Ace 게임을 원본 그대로 브라우저에서 플레이한다.

게임을 설치하거나 고치지 않고, URL 하나나 Game.ini가 든 폴더로 Edge·Chrome·Firefox에서 실행한다.

	VX Ace	VX
타이틀
게임 안

위 화면은 게시 1.0.0 runtime으로 reference app을 실행해 캡처했다(촬영 기록). 맨 위 그림은 실제 게임 화면이 아닌 합성 일러스트다.

특징

• RGSS 그대로 실행: 오픈소스 RGSS 구현 mkxp-z, CRuby, RetroArch를 Emscripten으로 WebAssembly 빌드했다. 게임의 Ruby script를 브라우저 안의 CRuby가 그대로 실행하므로 script를 JavaScript로 옮기거나 RGSS를 다시 만들지 않는다.
• 원본 보존: 설치본은 읽기 전용 입력이다. 브라우저용 변환은 결정적 .mkxpz package와 게임별 overlay로 따로 만들고, 외부 DLL과 Win32API는 게임이 실제로 부르는 함수만 좁게 맞춘다.
• 빠른 시작: 지연 콘텐츠는 읽은 chunk만 받아 cache하고, 선부팅은 클릭 전에 타이틀까지 미리 부팅해 둔다. 제공 VX Ace 샘플은 클릭부터 첫 frame까지 Chrome 89 ms, Firefox 138 ms였다(측정).
• 폴더 실행: reference app의 "게임 폴더 열기"로 Game.ini가 있는 폴더를 고르면 package 빌드 없이 실행한다.
• 입력과 저장: 원래 키 배치와 RGSS 마우스 script, 표준 게임패드를 받고, 터치 기기에서는 화면 pad가 나타난다. 저장은 게임마다 따로 둔다.
• 재현 가능한 release: upstream source, toolchain, RTP, 글꼴을 full commit SHA와 hash로 고정하고 SDK, runtime, Builder, contract를 한 npm package로 묶는다.

빠르게 써 보기

Windows PowerShell 기준이다. 명령의 기준은 package.json이다. 개발에는 Node.js 26과 packageManager에 고정된 pnpm 12.16.1을 쓴다. runtime은 threaded WASM과 AudioWorklet을 쓰므로 secure context(HTTPS 또는 localhost)와 cross-origin isolation(COOP/COEP)이 필요하다.

1. 게임 폴더 검사

Docker나 build 없이 원본을 읽기만 한다. 엔진, Game.ini의 RTP·Library·Scripts, source fingerprint와 호환 finding(외부 RTP, DLL·Win32API, script·경로 위험)을 JSON으로 출력한다.

pnpm.cmd install --frozen-lockfile
pnpm.cmd inspect "D:\Games\My VX Ace Game" --json

finding의 의미는 아키텍처 4절에 있다.

2. reference app 실행

reference app(apps/web)은 로컬 fixture(games/README.md)를 쓰는 개발용 launcher다. Docker named volume에서 WASM runtime을 빌드하고(clean build 수십 분, build 단계) lock에 고정된 RTP를 받는다.

pnpm.cmd runtime:image
pnpm.cmd runtime:preflight
pnpm.cmd runtime:checkout
pnpm.cmd runtime:all            # Stage 1·core clean build와 frontend build
pnpm.cmd runtime:export         # work/runtime/mkxp-z로 검증된 JS/WASM 내보내기
pnpm.cmd rtp:vx-ace:acquire     # lock에 고정된 VX Ace RTP archive 취득·검증
pnpm.cmd browser:build:vx-ace   # VX Ace fixture package·catalog 준비와 전체 build
pnpm.cmd fixtures:serve         # http://127.0.0.1:4173

VX는 browser:build:vx(RPGVX RTP는 package:rpgvx-rtp가 Docker 없이 만든다), XP는 browser:build:xp, 로컬 fixture 전체를 한 catalog로 보려면 browser:build:local을 쓴다. RTP 입력의 출처와 재배포 조건은 준비와 RTP cache에 있다.

"게임 폴더 열기"로 폴더를 고르면 브라우저 안에서 엔진과 RTP, 호환 경고를 바로 보여 준다.

게임 화면에는 전체화면 단추가 있고(마우스를 움직이거나 화면을 누르면 잠시 보인다), 터치가 주 입력인 기기에서는 방향·결정·취소 pad가 나타난다(표시 규칙).

3. 내 서비스에 붙이기

host는 exact version 하나로 player SDK, contract, native JS/WASM, license·provenance, release pin, Builder OCI archive를 함께 받는다. install hook은 없고 Builder는 network-off Docker 컨테이너로 실행한다.

# .npmrc: registry 주소는 운영자가 정한다
@arca:registry=<registry-url>

pnpm.cmd add --save-exact @arca/rgss123@1.0.0
pnpm.cmd exec rgss123-release verify

import { launchRgss123Player } from "@arca/rgss123";

const player = await launchRgss123Player({
  descriptor,      // engine, namespace, runtime·game·RTP의 파일명·bytes·SHA-256
  canvas,
  artifactSource,  // descriptor key를 실제 파일로 바꾸는 host adapter
  save,            // 영구 저장과 revision을 맡는 host adapter
});

host는 검증된 descriptor, opaque namespace, artifact·save adapter를 주고 catalog·사용자·cache·save 정책을 맡는다. export와 CLI는 @arca/rgss123 README, 브라우저 API는 player SDK README, 적용 절차는 host 적용 가이드, 책임 경계는 통합 설계에 있다.

동작 방식

flowchart LR
    G["원본 게임 폴더<br/>(읽기 전용)"] --> I["inspector<br/>엔진 감지·정적 검사"]
    I --> P["packager / Builder<br/>결정적 .mkxpz + RTP + overlay"]
    G -. "폴더 실행(package 없음)" .-> S
    R["WASM runtime<br/>mkxp-z + CRuby + RetroArch"] --> S
    P --> S["player SDK<br/>검증·mount·저장·종료"]
    S --> B["브라우저 canvas<br/>Edge, Chrome, Firefox"]
    S <--> V["저장<br/>OPFS 또는 host save adapter"]

구성 요소	위치	하는 일
inspector	packages/inspector-rgss	엔진 감지와 RTP·DLL·Win32API·script·경로 위험 정적 검사
packager, Builder	packages/packager-rgss	결정적 .mkxpz·RTP package와 verifier, network-off Builder CLI/OCI
overlay	packages/adapter-rgss	원본 hash에 고정한 게임별 호환 overlay
contracts	packages/contracts	공개 schema·parser·fixture와 version 정책
player SDK	packages/player-sdk	descriptor 기반 실행, 지연 콘텐츠·선부팅·폴더 실행, 저장·종료·재시작
WASM runtime	runtimes/mkxp-z, tools/build-runtime	source·toolchain pin, patch, 재현 가능한 Docker build
RTP	runtimes/rtp, @arca/rgss123/rtp	공식 XP·VX·VX Ace RTP 취득·추출·검증·cache(Node)
reference app	apps/web	fixture catalog launcher이자 SDK의 기준 consumer
release	tools/release	runtime ZIP·Builder OCI·contracts를 manifest/pin과 npm package로 묶음

문서

전체 목록은 문서 안내에 있다.

하려는 일	먼저 볼 문서
지금 무엇이 되는지 보기	프로젝트 상태, 호환성 매트릭스, 남은 작업
내 서비스에 붙이기	host 적용 가이드, 통합 설계, @arca/rgss123 README, player SDK, RTP 관리
저장소 고치기	AGENTS.md, 아키텍처, mkxp-z runtime, 샘플 인벤토리
직접 플레이해 확인하기	검증 체크리스트, 로컬 fixture 배치

라이선스

저장소 source는 MIT다. runtime ZIP과 npm의 native bundle은 LicenseRef-rgss123-runtime-bundle이며 mkxp-z, RetroArch, 의존 라이브러리, 내장 글꼴, SoundFont 각각의 재배포 조건을 따른다. 배포할 때는 LICENSES/THIRD_PARTY_NOTICES.json과 동봉된 license·source provenance를 함께 둔다. 정책은 runtimes/mkxp-z/redistribution-policy.json에 있다.

게임과 RTP 원본은 저장소와 release에 들어 있지 않다. 공식 RTP 약관은 데이터 재배포에 사전 서면 동의를 요구하며, 다운로드 자동화와 hash 일치는 사용·재배포 권한을 주지 않는다.