TL;DR

  • thrl은 PC-98 동방 게임에서 강화학습을 실행하는 프레임워크이며, 유효한 게임 사본과 GNU/Linux, XPU 또는 CUDA GPU가 필요함.
  • 지원 환경은 GNU/Linux이며 WSL2도 사용할 수 있고, GPU에는 최소 4GB VRAM이 필요함.
  • 2,048단계 맵 롤아웃은 약 1.62GiB를 사용하며, 기본 설정의 Intel XPU 공유 메모리 환경에서는 워커 4개로 약 11GB 메모리를 사용함.
  • PC-98 게임을 실행하려면 dosbox-x를 소스에서 빌드하고 Rust, uv, maturin을 설치한 뒤 게임 실행 파일을 패치해야 함.
  • 실험은 연산 자원 부족으로 결과가 확인되지 않았고, 프로젝트는 동료 심사를 거치지 않아 알고리즘에 문제가 없는지 확신할 수 없음.

프로젝트와 인용

  • 프로젝트 이름은 thrl이며, 동방 프로젝트 게임용 강화학습 프레임워크임.
  • 논문 인용 정보는 저자 T. Liu, 제목 A High-Fidelity Reinforcement Learning Environment and Baseline for Multi-Objective Bullet Hell Games, 연도 2026, DOI 10.5281/zenodo.21788472임.
  • 관련 프로젝트:
  • Taisei 헤드리스 시뮬레이션: Taisei Headless Simulation
  • Mystic Square 및 Lotus Land Story 패치: th98patch
  • 강화학습 프레임워크: thrl

요구 사항

  • 지원 운영체제는 GNU/Linux이며, WSL2도 사용 가능함.
  • GPU가 필요하며, 이 저장소에서 지원하는 GPU 백엔드는 XPU와 CUDA임. 명령을 실행하기 전에 make switch로 GPU를 전환해야 함.
  • GPU에는 4GB 이상 VRAM이 필요하며, 통합 GPU의 공유 메모리도 작동할 수 있음.
  • 2,048단계 맵 롤아웃 하나는 약 1.62GiB를 사용함. 프로세스, 프로세스 생성, PyTorch 복제본으로 인해 시스템 메모리 사용량도 매우 커질 수 있음.
  • 기본 설정에서 워커 4개를 사용하는 Intel XPU 공유 메모리 환경은 약 11GB를 사용함. 시간이 문제가 아니라면 기본 설정을 사용할 수 있음.
  • CUDA에서는 GPU VRAM 약 3~6GB, 시스템 메모리 약 7~10GB가 필요할 것으로 추정됨.
  • 가장 안전한 설정은 워커 1개임. VRAM 4GB와 RAM 4GB 조합에서도 실행될 수 있으며, XPU에서는 RAM 8GB가 필요할 수 있음.
  • 언급된 RAM은 필요한 총 메모리이며, 시스템에서 실제로 사용할 수 있는 RAM을 뜻하지 않음. tty1 모드만 사용한다고 가정하면 시스템 오버헤드는 약 1GB로 추정되며, 총 9GB로 실행할 수 있음. 다만 실제로 그런 구성은 없음.
  • MOPPO 업데이트에 걸리는 시간을 측정한 뒤, 처리 속도가 빠르면 워커를 늘려 처리량을 맞추고 그렇지 않으면 워커 수를 줄이는 방식임.

시작하기

  • 실행하려는 게임의 유효한 게임 사본이 필요함.
  • PC-98 시대 게임을 실행하려면 다음 절차를 따름.
  • curl, automake, gcc, g++, make, libncurses-dev, nasm, libsdl-net1.2-dev, libsdl2-net-dev, libpcap-dev, libslirp-dev, fluidsynth, libfluidsynth-dev, libavformat-dev, libavcodec-dev, libavcodec-extra, libswscale-dev, libfreetype-dev, libxkbfile-dev, libxrandr-dev를 설치하고, dosbox-x를 복제해 빌드한 뒤 설치해야 함.
  • 설치 후 sudo setcap -r "$(type -P dosbox-x)"를 실행해야 게임 실행에 루트 권한이 필요하지 않음. 이 설정은 게임이 아닌 네트워크에 영향을 줌. 이후 git pull, ./build, sudo make install을 실행할 때마다 같은 setcap 명령을 다시 실행해야 하며, HM 모드는 예외임.
  • Rust 도구 체인은 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh로 설치함.
  • uv는 curl -LsSf https://astral.sh/uv/install.sh | sh로 설치하고, uv tool install maturin으로 maturin을 설치함.
  • th98patch를 참고해 게임 실행 파일을 패치하고, 패치된 파일을 ./export/에 배치함.
  • make defconfig로 기본 설정을 생성함. 실행 설정은 rrr.toml과 curriculum.json에서 구성하며, 기본 설정을 그대로 사용할 수도 있음.
  • 테스트, 디버깅, 평가, 인간 플레이 모드에는 cp cfg/dosbox-x/test.conf export/default.conf를 사용하고, 일반 학습에는 cp cfg/dosbox-x/headless.conf export/default.conf를 사용함.
  • maturin develop, uv sync, uv run main.py를 실행함.

문서 빌드

  • 문서는 make docs로 빌드함.

실험

  • 연산 자원이 충분하지 않아 실험 결과는 확인되지 않음.
  • 확실히 말할 수 있는 사항은 보상 알고리즘이 문제가 아니며, 이 프로젝트가 시뮬레이터가 아니라는 점임.
  • 학습에 쓸 자금이 충분하지 않음.
  • 프로젝트가 동료 심사를 거치지 않았으므로 알고리즘에 문제가 없는지는 확신할 수 없음.
  • 테스트 결과 무료 등급의 대형 기술 기업 클라우드 컴퓨팅 자원에서는 실행할 수 없음.

특별 감사

  • ReC98: 상세한 역공학 코드와 블로그
  • StableBaseline3: Python 구현 일부
  • PyTorch: Intel 및 CUDA 가속
  • GNU Project: 라이선스와 운영체제
  • Donald E. Knuth 교수: TeX
  • arxiv.org: 훌륭한 논문 제공. arxiv.org에 대한 반감도 있음.
  • Institute of Electrical and Electronics Engineers: 일부 논문 제공.