Dwarf Fortress를 플레이하는 LLM 에이전트 구축

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

이 글은 DFHack와 quickfort를 중심으로 LLM을 이용해 Dwarf Fortress를 단계별로 자동화한 구현을 정리한다. 아키텍처는 Knowledge·Decision·Execution·Feedback 네 계층으로 구성되며 LLM은 현재 상태와 단계별 지식을 받아 구조화된 Action JSON을 출력하고, dfhack-run과 quickfort가 이를 실행해 상태를 갱신한다. 핵심 구현 결정으로는 headless PTY 실행과 dfhack-run 선택, 파일시스템을 상태 오라클로 활용한 점이 있으며 Phase 1에서 식량·주거 확보를 성공적으로 달성해 다음 생산·방어 단계로 확장할 계획이 있다.

섹션별 상세

Dwarf Fortress를 선택한 이유는 게임이 픽셀 대신 구조화된 텍스트와 파일 상태를 제공해 LLM이 직접 읽고 판단하기에 적합했기 때문이다. 글은 DF의 인터페이스가 ASCII 터미널과 제한된 명령어 집합으로 구성되어 있어 시각 모델이나 복잡한 프레임처리 없이도 상태·행동·피드백 루프를 만들 수 있다고 기술한다. 이 접근은 에이전트가 환경을 '이해'해야 할 필요성을 유지하면서도 감지·해석 단계의 불확실성을 줄여 연구·개발 효율을 높인다.

시스템 아키텍처는 네 계층으로 나뉘며 각 계층은 입력부터 실행·피드백까지 역할을 분리한다. Knowledge Layer는 단계별 전략과 블루프린트를 LLM 프롬프트로 주입해 문맥을 제공하고, Decision Layer는 현재 상태와 역사 로그를 받아 구조화된 Action JSON을 출력하며 Execution Layer는 dfhack-run·xdotool·Lua로 명령을 실행한 뒤 JSONL 로그로 결과를 기록한다. Feedback Layer는 우선적으로 DFHack Lua 쿼리로 상태를 확인하고 불가능할 때는 스크린샷+Vision API를 대체 수단으로 활용해 신속한 이벤트 대응을 가능하게 만든다.

근거

Lua RPC 채널은 headless 환경에서 불안정하므로 dfhack-run 명령 파이프를 사용했다 — 글 본문 'dfhack-run command pipe, not Lua RPC. The Lua RPC channel is unstable headless.' 부분과 Implementation decisions 섹션

Decision Layer에서 출력되는 Action JSON은 dfhack, keystroke, query, wait, done 같은 유형으로 구분되어 실행 레이어에서 직접 매핑되게 설계됐다. 에이전트는 dfhack 명령으로 quickfort나 dig-now 같은 직접적 조작을 호출하거나 keystroke로 UI 네비게이션을 수행하도록 지시할 수 있으며 query 타입은 Lua를 통해 추가 상태를 조사하는 역할을 한다. 이 구조는 LLM의 자연어 추론 결과를 기계가 해석 가능한 정형화된 명령으로 변환해 실행 안정성과 디버깅 편의성을 동시에 확보한다.

핵심 구현 결정은 headless 환경에서의 안정성을 최우선으로 한 점이다. 글에서는 PRINT_MODE:TEXT로 ncurses TUI를 사용해 Xvfb 없이 PTY에서 게임을 구동하고, 불안정한 Lua RPC 대신 dfhack-run 명령 파이프를 채택해 명령 실행 신뢰도를 확보했다고 적었다. 또한 파일시스템(저장 파일, region_snapshot 등)을 상태 오라클로 사용해 내부 쿼리 없이도 '요새가 실행 중인지'와 같은 기본 상태를 확인하도록 설계했다.

Phase 1은 생존 기반의 단계 목표를 갖고 dreamfort 블루프린트 시퀀스를 실행해 식량·음료·주거를 확보하는 것을 목표로 했다. 에이전트는 블루프린트를 순서대로 적용하고 상태를 읽어 검증했으며, 시간 시스템 관련 디버깅으로 cur_year_tick와 cur_season_tick의 차이를 파악해 계절 진행을 제어해 수확 시점을 맞추었다. 실행 결과로 건물 수가 단계별로 증가하고 일부 건물은 자재 대기 상태로 suspended 되었으며 로그상으로 계획 완료가 확인되었다.

향후 계획은 단계별 목표를 이어받아 생산 체인과 방어 체계를 구현하고 장기적으로는 세션 간 메모리를 도입하는 것이다. 글에서는 gamelog.txt를 에피소드 메모리로 활용해 요새 실패 원인을 기록하고 다음 로드 시 LLM 프롬프트에 주입해 경험 누적을 가능하게 한다고 적었다. 이 방식은 단순한 현재상황 계획자를 넘어 반복 실험에서 학습 신호로 작용하는 경험 축적기를 만들겠다는 의도를 담고 있다.

이미지 분석

Screenshot
스샷은 ncurses 기반의 텍스트 UI에서 요새 상태와 메뉴를 동시에 보여 주며, 글에서 설명한 'UI를 직접 조작하지 않고 DFHack로만 상호작용' 설계 의도를 시각적으로 확인할 수 있다. 화면 왼쪽에 지형과 건설 현황이 보이고 중앙에 메뉴가 있어 quickfort 같은 도구로 좌표 기반 작업을 적용하면 UI 네비게이션이 최소화된다는 점을 직관적으로 이해할 수 있다.
Dwarf Fortress의 텍스트 모드 실행 화면 스크린샷

Diagram
다이어그램은 입력으로 단계별 전략·경험 로그·현재 상태가 Decision Layer로 들어가고, 실행 후 JSONL 로그와 DFHack 쿼리로 피드백이 돌아오는 전체 파이프라인을 명확히 보여 준다. 이 시각 자료는 각 계층의 경계와 정보 흐름, 특히 Action JSON이 어떻게 실행 레이어로 매핑되는지 구조적으로 이해하는 데 도움이 된다.
글에서 제시한 시스템 아키텍처 다이어그램: Knowledge, Decision, Execution, Feedback 계층

Screenshot
이미지는 에이전트가 시간 관련 버그를 찾아낸 디버깅 장면을 보여 주며, cur_year_tick(연중 전체 tick)과 cur_season_tick(계절 내 tick)을 구분해 계절 진행을 제어해야 함을 시사한다. 이 사례는 상태 해석에서 내부 변수의 의미를 파악하는 과정이 에이전트의 올바른 행동 결정에 직접적인 영향을 미친다는 점을 증명한다.
시간 시스템 분석 스니펫: season_tick과 cur_year_tick의 차이를 보여 주는 로그 캡처

Screenshot
이 이미지는 블루프린트 실행 결과로 건물 수가 증가하고 플랜 완료 메시지가 발생한 장면을 캡처해 실제 자동화가 목표를 달성했음을 시각적으로 확인하게 한다. 화면과 함께 본문 로그를 대조하면 suspended 상태와 자재 대기 현상도 함께 관찰되어 실행·피드백 루프가 제대로 작동했음을 뒷받침한다.
Phase 1 완료 상황을 보여 주는 스크린샷: 건물 수 증가와 'Plan complete' 상태

용어 해설

DFHack 툴킷(DFHack): — DFHack은 Dwarf Fortress의 런타임을 확장해 Lua 스크립트와 명령 파이프를 통해 게임 상태를 읽고 조작할 수 있게 해 주는 도구이다. 글에서는 DFHack을 통해 Lua 쿼리와 dfhack-run 명령 파이프를 활용해 상태를 확인하고 액션을 실행하는 방식으로 에이전트를 제어한다고 밝힌다. DFHack은 텍스트 모드 서버 환경에서 직접 게임 파일과 명령 파이프를 이용해 안정적으로 동작하도록 선택된 핵심 인터페이스다.
Quickfort 청사진 도구(quickfort): — quickfort는 CSV 형태의 blueprint를 받아 커서 좌표 기반으로 건물이나 굴착을 자동으로 실행하는 도구다. 글에서는 메뉴 내비게이션 없이 quickfort run blueprint.csv --cursor x,y,z 같은 명령으로 작업을 수행해 에이전트가 좌표만 제공하면 되도록 설계했다고 적었다. 이 방식은 UI 조작 능력 대신 좌표와 파일 I/O를 상태 오라클로 삼는 단순한 실행 경로를 만든다.
dfhack-run 명령 파이프(dfhack-run): — dfhack-run은 DFHack 명령을 별도 프로세스에서 실행하도록 파이프 방식으로 호출하는 인터페이스다. 기사에서는 headless 환경에서 Lua RPC가 불안정해 dfhack-run 명령 파이프가 더 신뢰할 수 있는 실행 경로였다고 기술한다. 실행 레이어는 각 단계 호출 후 JSONL 로그를 기록하고 상태를 갱신하기 위해 이 파이프 방식을 사용한다.
텍스트 모드 실행(PRINT_MODE:TEXT): — PRINT_MODE:TEXT는 Dwarf Fortress를 ncurses 기반 TUI로 렌더링하는 설정으로 Xvfb가 필요 없는 headless 실행을 가능하게 한다. 글에서는 이를 이용해 VPS에서 GUI 없이 터미널 PTY로 게임을 돌리고, 화면 캡처 대신 파일시스템·DFHack 쿼리로 상태를 읽어 자동화를 단순화했다고 적었다. 이 선택은 비전 모델이나 가상 디스플레이 의존도를 줄여 안정성을 높인다.

코드 예제

bash

quickfort run blueprint.csv --cursor x,y,z

굴착이나 건물 배치를 위해 quickfort를 사용하는 실행 예시다. 에이전트는 UI 내비게이션 대신 블루프린트 파일과 좌표를 출력으로 생성해 quickfort에 전달한다. 이로써 복잡한 키스트로크 시퀀스 없이 정확한 영역에 작업을 적용할 수 있다.

bash

dfhack-run <command>

headless 환경에서 안정적으로 DFHack 명령을 실행하기 위해 dfhack-run 파이프 방식을 사용한다. 글에서는 Lua RPC 채널이 불안정하므로 dfhack-run이 더 신뢰성이 높다고 보고한다. 실행 레이어는 이 방식으로 명령을 호출한 뒤 JSONL 로그를 남기고 상태를 갱신한다.

python

python3 -c "from df_ai.dfhack import run_dfhack; import time; ..."

에이전트를 실행하는 간단한 호출 예시로, 파이썬에서 df_ai.dfhack 모듈을 통해 dfhack 인터페이스를 감싼 런타임을 호출한다. 글 본문에는 테스트와 디버깅을 위해 직접 파이썬 명령으로 에이전트를 실행한 로그가 포함되어 있다. 이 패턴은 LLM이 출력한 Action JSON을 실행 레이어로 전달하는 데 쓰인다.

기술

DFHack Lua 쿼리와 dfhack-run 명령 파이프를 통해 게임 상태를 읽고 명령을 실행한다. 글에서는 Lua RPC 대신 파이프 방식을 채택해 headless 안정성을 확보했다고 명시한다. 이 조합은 Decision Layer의 Action JSON을 실환경 명령으로 안전하게 연결하는 역할을 한다.
quickfort는 CSV 블루프린트 기반 자동 건설 도구로, 에이전트는 좌표만 제공해 복잡한 UI 입력 없이 굴착·건물 배치를 수행할 수 있다. 이 도구 사용은 에이전트 설계에서 UI 제어 필요성을 줄이고 실행 신뢰도를 높이는 핵심 선택이었다. 결과적으로 에이전트는 좌표 중심의 계획을 출력하면 quickfort가 정확하게 이를 적용한다.
PRINT_MODE:TEXT와 PTY 기반 headless 실행은 X 서버 없이 ncurses TUI로 게임을 돌리는 환경을 만든다. 글에서는 이 설정 덕분에 VPS에서 GUI를 띄우지 않아도 게임을 안정적으로 운영할 수 있었다고 밝힌다. 이 접근은 비전 모델 의존도를 줄이고 파일·DFHack 쿼리로 상태를 확보하는 설계를 가능하게 한다.

활용 사례

단계별 자동화 에이전트로 초기 생존·생산·방어 목표를 순차적으로 달성하는 게임 플레이 자동화 사례다. 글에서는 Phase 1로 식량·음료·주거를 확보하고 이후 생산 체인과 방어를 확장하는 구체적 계획을 제시했다. 이런 단계화된 목표와 검증 가능 조건은 에이전트의 성공 판정과 디버깅을 용이하게 한다.
gamelog.txt를 에피소드 메모리로 사용해 세션 간 경험을 누적하는 장기 학습 사례다. 요새가 실패한 원인을 기록하고 다음 로드 시 LLM에게 해당 로그를 주입해 의사결정에 반영하도록 설계했다. 이 방식은 반복적 실패를 학습 신호로 삼아 점진적 개선을 도모하는 워크플로우에 적합하다.
텍스트 기반 시뮬레이션을 연구 플랫폼으로 삼아 LLM의 플래닝·실행·모니터링 능력을 시험하는 연구용 벤치마크로 활용할 수 있다. 글의 설계는 시각 입력을 배제하고 구조화된 상태와 이벤트 로그를 중심으로 에이전트를 구성하므로 실험 재현성과 해석 가능성이 높다. 학술적 실험이나 에이전트 아키텍처 비교 연구에 적합한 설정이다.