rgss23-web

RPG Maker VX(RGSS2)와 VX Ace(RGSS3) 게임을 URL로 열어 실제 웹 브라우저에서 플레이하기 위한 런타임·패키저·런처 프로젝트다. 독립 upstream으로서 버전된 runtime·builder·contract를 배포하고, LINKS 같은 host 제품이 설치본을 붙여 실행할 수 있는 구조를 목표로 한다.

핵심 경로는 mkxp-z + CRuby + Libretro + Emscripten이다. 원본 게임은 수정하지 않고, RTP 합성·브라우저 변환·게임별 호환 처리는 파생 package와 overlay로 격리한다.

지원 범위

문서 갱신: 2026-09-06 KST · 아래 사용자 acceptance 기준: 2026-08-05 KST

대상	현재 판정	범위
제공 VX Ace 샘플	사용자 검증 PASS	Edge·Chrome·Firefox 핵심 흐름
제공 VX 샘플	사용자 검증 PASS	Edge·Chrome·Firefox 핵심 흐름
RPG Maker MV/MZ	유지보수 기준선	HTTP hosting·런처 회귀 fixture
RPG Maker XP	범위 밖	지원하지 않음

PASS는 저장소에 포함된 제공 샘플과 확인한 브라우저 흐름에만 적용한다. 추가 샘플을 검증하기 전에는 VX/VX Ace 엔진 전체 지원으로 일반화하지 않는다. 자동 회귀 범위와 사용자 acceptance는 호환성 매트릭스에 분리해 기록한다.

현재 개발 상태

현재 package와 로컬 release set은 0.1.1이다. public contract, portable Builder, host-neutral player SDK와 release pipeline은 구현돼 있으며 로컬 release 생성·검증 기록이 있다. 0.1.1 자체의 clean 재현 실행과 외부 게시는 NOT RUN이다. 기존 LINKS 통합 기록은 VX Ace PARTIAL, VX BLOCKED이며 이 문서 갱신으로 최신 host acceptance를 주장하지 않는다.

현재 상태의 단일 요약은 프로젝트 상태, 앞으로 남겨 둔 후순위 작업은 로드맵을 따른다.

정식 소비 경계는 ARCA 배포와 LINKS 통합 설계, 이를 구현하는 현재 순서는 개발 계획에 있다. ARCA는 VX/VX Ace 실행과 package 형식을 소유하고, LINKS는 catalog·Installation·PlaySession·production cache/save와 실행 origin을 소유한다.

저장소 구조

apps/web/                    웹 런처와 게임 route
packages/contracts/          공개 schema·parser·fixture와 compatibility policy
packages/manifest/           공통 manifest schema
packages/inspector-rgss/      VX/VX Ace 감지와 정적 검사
packages/packager-rgss/       결정적 portable package builder와 verifier
packages/adapter-rgss/        게임별 compatibility overlay
packages/player-sdk/         host-neutral launch/cache/save와 브라우저 runtime lifecycle
runtimes/mkxp-z/             고정 source, build recipe와 runtime lock
runtimes/rpgvx/              RPGVX RTP package 계약
games/                       읽기 전용 원본 fixture
work/                        생성·진단·호환 작업물
dist/                        사용자 제공 결과물
docs/                        현재 상태·설계·검증 문서

apps/web은 fixture catalog와 MV/MZ route를 유지하는 player SDK의 첫 reference consumer다. production host는 catalog나 URL query를 SDK에 넘기지 않고 검증된 단일 descriptor, opaque namespace와 artifact/storage/save adapter를 주입한다. API 경계는 @rgss23/player-sdk README에 있다.

games/**는 수정하지 않는다. 자세한 작업 계약은 AGENTS.md에 있다.

시작하기

요구 사항:

• Node.js와 package.json의 packageManager에 고정된 pnpm
• 런타임 재빌드용 Docker Desktop 또는 Linux Docker
• 검증용 Edge·Chrome·Firefox

Windows PowerShell에서는 실행 정책 충돌을 피하기 위해 pnpm.cmd를 사용할 수 있다.

pnpm.cmd install --frozen-lockfile
pnpm.cmd typecheck
pnpm.cmd test
pnpm.cmd build

위 명령은 최초 개발환경 확인용이다. 이후에는 변경 범위별 검증 선택에 따라 필요한 검사만 실행한다. 기본 test는 입력·OPFS·package와 runtime patch의 빠른 핵심 회귀이며, runtime 또는 native lock까지 점검할 때는 pnpm.cmd verify:locks를 별도로 실행한다. browser:smoke:*는 package 준비와 build를 포함하므로 같은 준비·build를 바로 앞에서 반복하지 않는다.

정식 형식의 source-free release set 생성과 검증:

pnpm.cmd runtime:export
pnpm.cmd release:build
pnpm.cmd release:verify
pnpm.cmd release:reproduce

결과는 dist/release/<version>/의 contract tarball, runtime ZIP, Builder OCI, canonical manifest와 exact pin이다. 이 과정은 정식 release 생성·검증용이며 일반 코드·문서 변경의 기본 게이트가 아니다. release:reproduce는 clean detached worktree에서 동일 identity를 재생성하며 외부 release/registry 게시는 수행하지 않는다.

샘플 검사:

pnpm.cmd inspect:samples

브라우저 package와 통합 catalog 생성:

pnpm.cmd browser:build:local
pnpm.cmd fixtures:serve

런처 첫 화면에는 games/의 VX, VX Ace, MZ, MV fixture만 표시한다. 선택은 URL query에 기록하지 않으며 VX/VX Ace는 검증 package, MV/MZ는 원본 HTML5 payload로 실행한다.

전체 명령과 옵션의 진실 원천은 package.json이다. 외부 source·toolchain·artifact identity는 runtimes/**의 lock과 검증 스크립트를 따른다.

문서

전체 문서와 API 안내는 문서 지도에서 관리한다. 작업 규칙은 루트 AGENTS.md 하나를 따른다.