From 7288976a99556b91ecd4a558cba35f7637ed3be9 Mon Sep 17 00:00:00 2001
From: gihyeon <gihyeon@gihyeon.com>
Date: Wed, 25 Mar 2026 10:26:57 +0900
Subject: [PATCH] =?UTF-8?q?Update=20README.md=20-=20=EC=A0=84=EC=B2=B4=20?=
 =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 106 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ccb8604..5c83586 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,107 @@
-# factorio-ai-agent
+# 팩토리오 AI 에이전트
 
-팩토리오 완전 자율 AI 에이전트
\ No newline at end of file
+Claude API를 이용해 팩토리오를 자율적으로 플레이하는 에이전트입니다.
+캐릭터 이동, 채굴기 배치, 제련소 건설, 벨트 연결까지 AI가 직접 판단하고 실행합니다.
+
+---
+
+## 파일 구조
+
+```
+factorio_ai/
+├── main.py            ← 메인 루프 (여기서 실행)
+├── factorio_rcon.py   ← RCON 연결 (게임과 통신)
+├── state_reader.py    ← 게임 상태 읽기 (자원, 인벤토리, 건물)
+├── ai_planner.py      ← Claude AI 행동 계획
+├── action_executor.py ← 실제 게임 조작 (이동, 건설, 채굴)
+└── agent_log.jsonl    ← 행동 로그 (자동 생성)
+```
+
+---
+
+## 설치
+
+```bash
+# 외부 라이브러리 불필요! Python 표준 라이브러리만 사용
+```
+
+---
+
+## 팩토리오 RCON 설정
+
+### 방법 1: 싱글플레이 (가장 간단)
+1. 팩토리오 실행
+2. 게임 시작 후 콘솔 열기 (` 키 또는 ~)
+3. 아래 입력:
+   ```
+   /rcon-port 25575
+   /rcon-password factorio_ai
+   ```
+
+### 방법 2: 서버 모드 실행 (권장)
+```bash
+# Windows
+factorio.exe --start-server saves/mysave.zip --rcon-port 25575 --rcon-password factorio_ai
+
+# Linux/Mac
+./factorio --start-server saves/mysave.zip --rcon-port 25575 --rcon-password factorio_ai
+```
+
+---
+
+## 실행
+
+```bash
+# Z.ai API 키 설정 (https://z.ai 에서 Coding Plan 구독 후 발급)
+export ZAI_API_KEY="your-key-here"
+
+# 기본 실행
+python main.py
+
+# 커스텀 서버 연결
+FACTORIO_HOST=192.168.1.10 FACTORIO_PORT=25575 FACTORIO_PASSWORD=mypass python main.py
+```
+
+---
+
+## AI 목표 변경 (main.py)
+
+```python
+planner.set_goal(
+    "전력 인프라 구축: offshore-pump → boiler → steam-engine → 전선 연결"
+)
+```
+
+다른 목표 예시:
+- `"구리 채굴 + 전선 생산 자동화"`
+- `"자동화 연구 달성을 위한 빨간 과학팩 생산"`
+- `"방어선 구축: 포탑 배치 + 탄약 보급"`
+
+---
+
+## 동작 원리
+
+```
+매 2초마다:
+  1. RCON → 팩토리오에서 현재 상태 읽기
+     (플레이어 위치, 인벤토리, 자원 패치, 건물 목록)
+  
+  2. 상태 → Claude API로 전송
+     "다음에 뭘 해야 하나요?" 질문
+  
+  3. Claude → JSON 행동 반환
+     {"action": "place_mining_drill", "params": {"x": 10, "y": 20, ...}}
+  
+  4. RCON → 팩토리오에서 Lua 명령으로 실행
+     (실제로 게임 내에서 채굴기가 배치됨)
+```
+
+---
+
+## 주의사항
+
+- RCON을 통한 Lua 명령은 **치트 없이는 불가능한 것도 실행 가능** (텔레포트 등)
+  - 순수 AI 플레이를 원한다면 `move()` 함수를 텔레포트 대신 실제 걷기로 교체
+- `agent_log.jsonl`에 모든 행동이 기록됩니다
+- Claude API 비용: 스텝당 약 $0.001 (Sonnet 기준)
+  - 하루 8시간 실행 시 약 $14 수준