엄트리스 (Umtris)

브라우저는 키보드·시계·모니터를 흉내 내는 가상 하드웨어이고, 엄랭 프로그램이 그 하드웨어 위에서 실행되는 게임 본체다.

엄트리스는 테트리스의 상태와 규칙을 전부 엄랭 v2 실행 파일에서 처리하는 정적 웹 게임이다. 브라우저 TypeScript는 물리 키·터치·50ms 시계 펄스를 전달하고, 공식 웹 구현을 기준으로 한 v2 호환 VM을 실행하고, 엄랭이 만든 최종 셀과 숫자를 표시할 뿐이다. 백엔드와 네트워크 게임 API는 없다.

실행

Node.js 20 이상이 필요하다.

npm install
npm run generate
npm test
npm run dev

배포용 정적 파일:

npm run build
npm run preview

Cloudflare Pages는 Build command npm run build, Output directory dist로 설정한다. GitHub Pages는 포함된 Actions 워크플로를 사용한다. Vite의 상대 base 설정으로 저장소 하위 경로에서도 동작한다.

조작법

동작	키
이동	← / →
소프트 드롭	↓
시계 방향 회전	↑ / X
반시계 방향 회전	Z
하드 드롭	Space
홀드	C
일시정지	P / Esc
재시작	R

모바일에서는 화면 아래의 DOWN/UP 터치 버튼을 사용한다.

실제 담당 범위

기능	엄랭	브라우저 호스트
보드 상태	O	X
테트로미노 모양	O	X
이동	O	X
회전	O	X
벽차기	O	X
충돌 검사	O	X
줄 삭제	O	X
점수	O	X
레벨	O	X
콤보	O	X
자동 낙하 판단	O	X
키 반복	O	X
락 딜레이	O	X
7-bag	O	X
홀드	O	X
고스트	O	X
게임 오버	O	X
최종 화면 셀 생성	O	X
물리 키 감지	X	O
터치 감지	X	O
고정 시계 펄스 생성	X	O
엄랭 명령 실행	X	O
셀을 픽셀로 표시	X	O
CSS 레이아웃	X	O

게임 규칙의 사람이 읽는 원본은 um/src/tetris.umasm이다. .umasm은 공식 엄랭 문법이 아니라 기호 변수·라벨·매크로를 사용하는 매크로 어셈블리이며, 빌드 시 범용 tools/assembler.ts가 공식 v2 문장만으로 구성된 um/tetris.umm으로 정적 변환한다.

현재 .umasm 원본은 1,628줄이고, 생성된 .umm은 5,843줄·4,341,199바이트다. 생성물 SHA-256은 634AFCB8A64C78EE632DBA374CBBEDC5CFC584210682A24884AB237E765918BD이다. 브라우저 배포 복사본은 src/assets/tetris.umm.txt이며 Vite가 빌드할 때 해시가 붙은 정적 자산으로 만든다.

어셈블러는 기호·정적 배열 접근·반복 산술·호출/계산된 반환을 범용 공식 v2 문장으로 전개한다. 테트로미노 좌표나 점수표 같은 게임 규칙을 계산하거나 JavaScript 게임 로직을 생성하지 않는다.

엄랭과 VM

• 언어/문법: rycont/umjunsik-lang v2
• 조사 기준 저장소 HEAD: e973f9d22b9803ee86b53d8e60f1b65ab08c7547
• 웹 런타임 기반 커밋: f18ccde28ae09e517a288ed927ba571ae34f6e46
• 라이선스: MIT

브라우저 VM은 공식 웹 구현의 변수 인덱싱, 입력, 숫자·문자 출력, 식으로 계산한 반환값, 동탄 뒤의 임의 공식 문장 실행, 절대 줄 점프, Math.imul 32비트 곱셈 의미론을 보존한다. 콘솔 입력이 부족하면 소비한 입력까지 되돌리고 같은 명령에서 대기하며, Web Worker에서 실행된다. 게임 출력은 고정 길이 283개 정수로 프레이밍하고 화면에 넘기기 전에 모든 프로토콜 필드의 형식과 범위를 검사한다.

검증

npm run test:runtime
npm run test:game
npm run test:purity
npm run test:static
npm test

테스트는 별도 TypeScript 테트리스 엔진을 사용하지 않는다. 엄랭 초기 상태와 하드웨어 입력, 고정 SHA-256 골든 리플레이, 패킷 전 필드 범위, VM 및 매크로 어셈블러 동작을 검사한다. 1·2·3·4줄 동시 삭제도 준비된 엄랭 초기 상태에서 실제 엄랭 고정/행 압축 경로로 검증한다. test:static은 실제 브라우저 E2E가 아니라 정적 호스트 구조 검사다.

구조

• um/src/tetris.umasm — 모든 게임 상태·규칙·좌표·점수표를 담은 매크로 어셈블리 원본
• um/tetris.umm — 실제 VM이 실행하는 공식 v2 엄랭
• src/assets/tetris.umm.txt — Vite가 해시 자산화하는 브라우저 배포 복사본
• tools/assembler.ts — 매크로 원본을 공식 v2 문장으로 바꾸는 범용 정적 전개기
• src/runtime — 공식 v2 호환 VM, 입력 대기, Worker, 고정 패킷 전 필드 검사
• src/hardware — 키보드와 50ms 시계
• src/display — 엄랭 출력 셀의 Canvas 표시
• tests — 런타임·어셈블러·프로토콜, 골든 리플레이, 정적 호스트 검사
• docs — 아키텍처, 프로토콜, 변수 지도, 순수성 및 제약

결정론적 리플레이

tests/game/game.test.ts는 고정 시드와 동일한 DOWN/UP/CLOCK 코드 목록을 두 VM에 전송하고 283개 정수로 구성된 모든 패킷을 byte-for-byte 비교한다. 블록 선택에 Math.random()은 사용하지 않는다. 웹 UI는 Web Crypto로 0–127 시드를 만들며 직접 입력하거나 ?seed=42처럼 고정할 수도 있다.

알려진 한계

• 생성된 엄랭 자산은 압축 전 4,341,199바이트이며 현재 Vite 빌드의 gzip 추정치는 약 23KB다. 정적 호스팅의 압축 전송과 장기 캐시를 권장한다.
• 점수는 999,999, 줄 수는 9,999, 레벨과 콤보는 99에서 포화하며 이후 증가분은 버린다.
• 탭이 백그라운드에서 throttling되면 게임 시계도 느려진다.
• 데스크톱·390×844 모바일 브라우저 기능 검증은 완료했지만, 실제 모바일 기기에서의 30분 장기 실행 측정은 별도 확인이 필요하다.

상세 내용은 docs/limitations.md와 docs/purity-audit.md를 참고한다.

원 프로젝트 및 라이선스

엄랭은 rycont/umjunsik-lang을 기반으로 한다. 원 프로젝트와 이 프로젝트의 MIT 라이선스 고지는 LICENSE에 포함되어 있다.