factorio-ai-agent/README.md

팩토리오 AI 에이전트

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    ← 행동 로그 (자동 생성)

---

설치

# 외부 라이브러리 불필요! Python 표준 라이브러리만 사용

---

팩토리오 RCON 설정

방법 1: 싱글플레이 (가장 간단)

1. 팩토리오 실행
2. 게임 시작 후 콘솔 열기 (` 키 또는 ~)
3. 아래 입력:

   /rcon-port 25575
   /rcon-password factorio_ai
   

방법 2: 서버 모드 실행 (권장)

# 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

---

실행

# 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)

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 수준