예제 소스

project.md

## 목표

이 프로젝트의 목표는 **레포 내부의 `tetris/`(C++ 테트리스 엔진)** 를 이용해 **강화학습(RL)** 을 수행하고, 학습된 모델을 **`model/` 디렉토리에 저장**하는 것이다.

## 핵심 요구사항

- **로컬 테트리스 엔진 사용**
  - 외부 패키지 기반 환경(`gym-tetris`, `nes-py` 등)을 사용하지 않는다.
  - 반드시 레포 내부의 `tetris/src/tetris_engine.*` 로 게임 로직을 구동한다.

- **파이썬에서 RL 학습 가능**
  - 파이썬 학습 스크립트(`.py`)로 학습을 실행할 수 있어야 한다.
  - 환경은 `gymnasium.Env` 형태로 감싸져 RL 라이브러리에서 사용할 수 있어야 한다.

- **모델 저장 경로**
  - 학습 산출물(모델 파일)은 기본적으로 `model/` 디렉토리에 저장되어야 한다.
  - `model/`이 없으면 자동으로 생성한다.

## 구현/구조 요구사항

- **엔진 브릿지**
  - `tetris_engine`를 “헤드리스(렌더링 없이)”로 `reset()`/`step()` 가능한 형태로 호출할 수 있어야 한다.
  - 파이썬에서 호출 가능한 형태로 노출한다(예: C API + `ctypes`, 또는 pybind11 등).

- **환경 API**
  - `reset()` / `step(action)` / `observation` / `reward` / `done(terminated)`가 일관되게 제공되어야 한다.
  - Action space는 엔진의 `TetrisAction`에 대응하는 이산 행동(예: `Discrete(7)`)이어야 한다.

- **관측(Observation)**
  - 보드 상태(locked + active piece 포함)를 관측으로 제공한다.
  - 엔진 설정의 `hidden_rows`를 고려해 “보이는 영역”을 학습 입력으로 사용할 수 있어야 한다.

## 실행 요구사항

- **빌드**
  - 로컬 엔진을 파이썬에서 쓰기 위해 필요한 네이티브 빌드가 가능해야 한다.
  - Qt6 GUI는 RL 학습에 필수가 아니며(선택), 브릿지 빌드는 Qt 없이도 가능해야 한다.

- **학습 실행**
  - 하나의 커맨드(예: `python train_tetris_rl.py ...`)로 학습을 시작할 수 있어야 한다.

## 비범위(Out of scope)

- 외부 Tetris Gym 환경을 이용한 학습
- NES ROM 기반 테트리스 환경 의존(ROM/에뮬레이터 등)