숫자 퍼즐 뚱이 게임과, 그 위에서 학습된 강화학습 에이전트를 함께 담은 프로젝트입니다.
사람 플레이, PPO/DQN/MC 에이전트 학습·실행, 사람 vs PPO 대결까지 지원합니다.
- Python 3.10 이상 (3.12 환경에서 확인)
- 의존성:
requirements.txt
pip install -r requirements.txtpython applegame.py- 마우스로 타일을 직사각형으로 드래그해 선택합니다.
- 선택 영역 안 0이 아닌 타일들의 합이 10이면 제거되고, 제거한 타일 수만큼 점수가 올라갑니다.
- 제한 시간 120초 동안 점수를 최대한 많이 획득하는 것이 목표입니다.
- 시간이 끝나면 스페이스바로 다시 시작할 수 있습니다.
동일한 Gymnasium 환경(DdungEnv)에서 PPO, DQN, Monte Carlo(REINFORCE) 세 가지 알고리즘을 사용할 수 있습니다.
- 관측: 숫자 그리드(정규화) + 남은 시간 비율 + 점수 스케일
- 행동: 현재 그리드에서 가능한 직사각형 선택 중 하나 (액션 마스킹 지원)
- 보상: 제거한 타일 수 + 9+1/8+2/7+3 조합 보너스 − 시간 패널티 − 남은 타일 패널티 + 클리어 보너스
자세한 보상 설계·실험 결과는 docs/experiment_summary.md 에 정리되어 있습니다.
| 항목 | 내용 |
|---|---|
| 학습 | python train_ppo.py → models/ddung_ppo.zip (20만 스텝, tqdm, TensorBoard logs/ppo) |
| 텍스트 실행 | python run_agent.py [--model ...] [--episodes 5] |
| 시각화 | python run_agent_visual.py [--model ...] [--episodes 5] |
- DQN은 액션 마스킹을 지원하지 않으므로, DdungEnvDQNWrapper로 유효 액션만 실행하도록 클램핑합니다.
| 항목 | 내용 |
|---|---|
| 학습 | python train_dqn.py → models/ddung_dqn.zip (20만 스텝, tqdm, TensorBoard logs/dqn) |
| 텍스트 실행 | python run_agent_dqn.py [--model ...] [--episodes 5] |
| 시각화 | python run_agent_dqn_visual.py [--model ...] [--episodes 5] |
| 항목 | 내용 |
|---|---|
| 학습 | python train_mc.py → models/ddung_mc_policy.pt (3,000 에피소드, tqdm) |
| 텍스트 실행 | python run_agent_mc.py [--model ...] [--episodes 5] |
| 시각화 | python run_agent_mc_visual.py [--model ...] [--episodes 5] |
정책 네트워크·액션 선택 로직은 mc_policy.py 에서 공유합니다.
같은 초기 보드(seed)로 사람이 먼저 1판 플레이한 뒤, PPO가 같은 seed로 1판 플레이하는 모습을 시각화하고, 두 점수를 비교합니다.
python human_vs_ppo.py [--model models/ddung_ppo.zip] [--seed 1234]- 사람 턴: 120초 제한. 시간 종료 시 점수 화면 + 3, 2, 1 카운트다운 후 창이 자동으로 닫힙니다.
- PPO 턴: 같은 seed로 환경을 초기화한 뒤, PPO 에이전트 플레이를 pygame 창으로 보여줍니다.
- 터미널에 사람 점수·PPO 점수·승패(사람 승 / PPO 승 / 무승부)를 출력합니다.
PPO·DQN 학습 시 tensorboard_log 로 로그가 쌓입니다. 실시간으로 손실·보상을 보려면:
tensorboard --logdir logs브라우저에서 http://localhost:6006/ 를 엽니다. 사용 방법은 docs/tensorboard.md 를 참고하세요.
| 파일 | 설명 |
|---|---|
applegame.py |
사람용 메인 게임 (pygame GUI). seed, auto_exit_on_timeup 옵션 지원. |
game_logic.py |
게임 규칙·그리드·유효 행동 (GUI/RL 공용) |
ddung_env.py |
Gymnasium 환경 DdungEnv + DQN용 DdungEnvDQNWrapper |
train_ppo.py |
PPO(MaskablePPO) 학습 |
run_agent.py |
PPO 텍스트 실행 |
run_agent_visual.py |
PPO 플레이 시각화 |
train_dqn.py |
DQN 학습 |
run_agent_dqn.py |
DQN 텍스트 실행 |
run_agent_dqn_visual.py |
DQN 플레이 시각화 |
mc_policy.py |
MC(REINFORCE) 정책 네트워크·액션 선택 (공유) |
train_mc.py |
MC(REINFORCE) 학습 |
run_agent_mc.py |
MC 텍스트 실행 |
run_agent_mc_visual.py |
MC 플레이 시각화 |
human_vs_ppo.py |
사람 vs PPO 대결 (동일 seed, 사람 → PPO 순서) |
requirements.txt |
게임·강화학습·TensorBoard 의존성 |
| 파일 | 설명 |
|---|---|
docs/USAGE.md |
사용 방법 요약 (PPO, DQN 등) |
docs/tensorboard.md |
TensorBoard 사용 방법 |
docs/experiment_summary.md |
보상 설계·실험 결과 정리 |
- 랜덤성
- 학습·대결 시 seed를 지정하면 같은 초기 보드를 재현할 수 있습니다.
run_agent_visual.py등은 seed 없이 실행 시 매번 다른 초기 그리드가 나오도록make_grid에서 독립 RNG를 사용합니다.
- 윈도우 한글 폰트
- 한글이 깨지면 시스템에 맑은 고딕(Malgun Gothic) 등 한글 폰트 설치 여부를 확인하세요.