예제 소스

CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Reinforcement Learning project training a DQN agent to play Tetris. Uses a C++17 Tetris engine with a C API bridge (ctypes) to Python/Gymnasium, with an optional Qt6 GUI for visualization. All documentation and comments are in Korean.

## Build Commands

### C++ engine + C API bridge (headless, no Qt required)
```bash
cd tetris
cmake -S . -B build -DBUILD_PY_BRIDGE=ON -DBUILD_QT_APP=OFF
cmake --build build -j
```

### C++ engine with Qt6 GUI (requires Qt6)
```bash
cd tetris
cmake -S . -B build   # both BUILD_PY_BRIDGE and BUILD_QT_APP default ON
cmake --build build -j
```

On macOS, CMake auto-searches Homebrew Qt6 paths (`/opt/homebrew/opt/qt@6`, `/usr/local/opt/qt@6`).

## Training & Running

### Headless DQN training
```bash
python train_tetris_rl.py --env-id tetris/build/libtetris_c_api.dylib --timesteps 300000
```
On Linux, use `.so` instead of `.dylib`. Supports `--load-model <path>` to resume and `--checkpoint-freq <steps>` for periodic saves.

### Qt GUI with RL TCP server
```bash
./tetris/build/tetris_rl --rl-port 5555
```

### Connect trained model to Qt GUI
```bash
python qt_rl_client.py --port 5555 --model model/<model_name>.zip --deterministic --auto-reset
```

### Combined live training + visualization
```bash
python train_qt_live.py --env-id tetris/build/libtetris_c_api.dylib --port 5555 --timesteps 300000
```

## Architecture

```
tetris_engine.cpp  ──core game logic──►  TetrisEngine class
       │
       ├──► tetris_c_api.cpp (extern "C" bridge)
       │         │
       │         └──► ctypes ──► local_tetris_env.py (Gymnasium Env)
       │                              │
       │                              └──► train_tetris_rl.py (DQN headless training)
       │
       └──► Qt GUI (main_window.cpp, tetris_widget.cpp)
                  │
                  └──► TCP socket (line-delimited JSON)
                            │
                            └──► qt_rl_client.py / train_qt_live.py
```

### Key design decisions
- **Action space**: `Discrete(7)` — Noop, Left, Right, RotateCW, RotateCCW, SoftDrop, HardDrop
- **Observation**: `(22, 10, 1)` uint8 grid (visible rows only; 4 hidden spawn rows stripped). Cell values: 0=empty, 1-7=tetromino type
- **Reward**: `line_reward * (lines_cleared)^2 - step_penalty` — squared line count incentivizes multi-line clears
- **Piece randomizer**: 7-bag for fair distribution
- **Rotation**: SRS-like with kick tables
- **C API**: Opaque handle pattern (`TetrisHandle*`) with functions prefixed `tetris_`
- **Qt TCP protocol**: Line-delimited JSON for state, line-delimited integers/commands for actions

### SimpleTetrisEnv (fallback)
`simple_tetris_env.py` is a pure-Python Gymnasium env with only 5 actions and flat `(H*W,)` float32 observation. Used when the C++ engine is not built. Different observation/action format from the C API env — not interchangeable with trained models.

## Dependencies

- Python 3.14 (`.venv/`), `gymnasium`, `stable-baselines3`, `opencv-python`, `numpy`
- C++17, CMake 3.16+, Qt6 (optional for GUI)
- Trained models saved to `model/` directory (auto-created)