Forge 딥다이브
— 카드 텍스트 3만 장을 "읽어서 그대로 작동시키는" 매직 더 개더링 규칙 엔진

Card-Forge/forge. 세계에서 가장 유명한 카드 게임 매직 더 개더링(MTG)의 복잡한 규칙을 통째로 코드로 구현한 오픈소스 규칙 엔진이다. 핵심은 카드 한 장 한 장의 효과를 자바 코드가 아니라 사람이 읽을 수 있는 텍스트 스크립트로 적어두고, 엔진이 그 텍스트를 읽어 실제 게임으로 작동시킨다는 점. 카드 스크립트만 33,000장 이상, 누적 커밋 약 74,000건의 20년 묵은 커뮤니티 프로젝트이며, AI 상대·온라인 대전·RPG(Adventure) 모드까지 한 채에 들어 있다. (저장소: Card-Forge/forge · 언어 Java 17 · ★2.4k · 라이선스 GPL-3.0 · 크로스플랫폼 Windows·Mac·Linux·Android · TrendShift 라이브 멘션 등재)

1프로젝트 한줄 요약

"규칙을 코드에 박는 대신, 카드 한 장을 '텍스트 한 장'으로 적어두고 엔진이 읽게 했다."

구체적으로 보면 Forge는 비공식 프로젝트다(매직 더 개더링의 저작권자 Wizards of the Coast와 무관한 커뮤니티 팬 프로젝트). 자바(Java)로 짜였고, 누적 커밋 약 74,000건에 달하는 20년 가까운 역사를 가진, 오픈소스 게임치고는 보기 드물게 거대하고 오래 살아남은 코드베이스다. 데스크톱(Windows·Mac·Linux)뿐 아니라 안드로이드에서도 돌고, 혼자 AI와 두는 모드부터 온라인 대전, 심지어 카드를 모으며 맵을 탐험하는 RPG(Adventure) 모드까지 들어 있다.

이 문서가 주목하는 건 게임 자체가 아니라 그 안의 설계다. "수만 가지 예외 규칙을 어떻게 코드로 감당하는가", "AI는 어떻게 다음 수를 고르는가", "하나의 게임 로직을 데스크톱과 모바일에서 어떻게 같이 쓰는가" — 소프트웨어 엔지니어가 배울 게 가득한, 살아있는 교과서다.

2왜 주목받는가

게임이 재미있어서가 아니라, "이걸 코드로 어떻게 해냈지?"가 놀라워서.

매직 더 개더링을 디지털로 옮긴 시도는 많았다. 하지만 Forge가 개발자들 사이에서 오래 회자되는 이유는 따로 있다.

① 데이터 주도 설계 — 카드는 코드가 아니라 텍스트다

Forge의 카드는 forge-gui/res/cardsfolder/ 아래에 알파벳 폴더로 나뉜 텍스트 파일 33,289개로 들어 있다. 새 카드를 추가할 때 자바 코드를 짜고 다시 컴파일할 필요가 없다 — 텍스트 한 장만 적으면 끝이다. 덕분에 프로그래머가 아닌 자원봉사자도 카드를 기여할 수 있고, 3만 장이라는 규모가 가능해졌다.

② 정식 규칙을 진짜로 구현했다

턴의 11단계(언탭→유지→뽑기→메인1→전투 5단계→메인2→종료→정리), 스택(stack) 기반 주문 해결, 상태 기반 행동(state-based action), 유발·대체·정적 능력의 우선순위 처리까지 — MTG 종합 규칙서에 적힌 흐름을 코드로 재현한다. 단순한 "카드 대결"이 아니라 규칙 처리기를 통째로 만든 것이다.

③ 게임 한 채를 통째로 — AI·온라인·RPG

휴리스틱 기반 AI 상대, 자체 서버를 통한 온라인 대전, 그리고 카드를 모으며 오버월드를 탐험하는 Adventure 모드(고전 게임 '섄달라' 풍의 RPG)까지 들어 있다. 헤드리스로 AI끼리 수천 판을 자동 대전시켜 밸런스를 측정하는 CLI 도구도 있다.

④ 하나의 로직, 여러 플랫폼

게임 규칙(forge-game)은 화면과 완전히 분리돼 있어서, 데스크톱(자바 Swing)과 모바일(libGDX)이 같은 엔진을 공유한다. "UI는 갈아끼우되 핵심은 한 번만 만든다"는 교과서적 분리를 대규모로 실천한 사례다.

경쟁 구도 한눈에

3기술 스택 전체 지도

"자바 한 언어로, 파서·게임 엔진·AI·데스크톱 GUI·모바일 게임 엔진까지 전부."

Forge는 98%가 자바인 Maven 멀티모듈 프로젝트다. 웹의 "프론트엔드/백엔드" 구분 대신, 코어 데이터 · 규칙 엔진 · AI · 공유 GUI · 플랫폼별 화면으로 나뉜다. 루트 pom.xml이 12개 모듈을 묶는 지도 역할을 한다.

핵심 4대 모듈 (게임의 두뇌)

플랫폼별 화면 (게임의 얼굴)

주요 라이브러리

4아키텍처 심화 분석 — 카드 텍스트가 게임이 되기까지

"내가 라이트닝 볼트를 시전하면, 그 텍스트 한 장이 화면 속 3 데미지가 되기까지 Forge 안에서 무슨 일이 벌어지나."

Forge를 이해하는 가장 좋은 방법은 카드 한 장이 살아 움직이는 길을 끝까지 따라가는 것이다. 먼저 전체 그림을 한 장으로 보자 — 디스크의 텍스트 파일이 어떤 단계를 거쳐 실제 게임 동작이 되는지다.

핵심 설계 1 — 카드 DSL: 파이프(|)와 달러($)로 짠 미니 언어

Forge의 심장은 카드 스크립트 언어(DSL)다. 카드 효과를 적는 작은 전용 언어로, 자바를 몰라도 읽고 쓸 수 있게 설계됐다. 실제 파일 세 장을 보자.

# g/grizzly_bears.txt — 능력 없는 평범한 크리처(바닐라)
Name:Grizzly Bears
ManaCost:1 G
Types:Creature Bear
PT:2/2
Oracle:

# l/lightning_bolt.txt — "아무 대상에게 3 데미지" 순간마법
Name:Lightning Bolt
ManaCost:R
Types:Instant
A:SP$ DealDamage | ValidTgts$ Any | NumDmg$ 3 | SpellDescription$ CARDNAME deals 3 damage to any target.
Oracle:Lightning Bolt deals 3 damage to any target.

# e/elvish_visionary.txt — "전장에 나오면 카드 1장 뽑기" 유발 능력
Name:Elvish Visionary
ManaCost:1 G
Types:Creature Elf Shaman
PT:1/1
T:Mode$ ChangesZone | Destination$ Battlefield | ValidCard$ Card.Self | Execute$ TrigDraw
SVar:TrigDraw:DB$ Draw | Defined$ You | NumCards$ 1
Oracle:When Elvish Visionary enters, draw a card.

읽는 법은 의외로 쉽다. 각 줄은 키:값 꼴이고, 능력 줄은 파이프(|)로 항목을 나누고, 각 항목 안에서 달러($)로 이름과 값을 가른다. 그래서 A:SP$ DealDamage | NumDmg$ 3은 "이건 주문(SP) 능력이고, 종류는 DealDamage, 데미지 수치(NumDmg)는 3"이라는 뜻이다. CARDNAME은 출력할 때 카드 이름으로 치환된다.

능력 줄 앞머리(prefix)가 능력의 '종류'를 정한다

파싱은 두 클래스가 맡는다. CardRules.Reader가 줄의 첫 글자를 보고 Name·ManaCost·Types·PT·A·T·SVar로 분기하고, 능력 줄(A:·T:)은 AbilityFactory가 받아 실제 능력 객체(SpellAbility)로 바꾼다. 이때 DealDamage 같은 값이 ApiType이라는 enum으로 매핑되고, 그 enum이 forge/game/ability/effects/ 폴더의 Effect 클래스 205종 중 하나(DealDamageEffect)에 연결된다.

핵심 설계 2 — 스택과 페이즈: MTG 규칙을 그대로 코드로

카드를 시전하면 즉시 효과가 나는 게 아니라, 먼저 스택(stack)에 쌓인다. 상대가 대응할 기회를 준 뒤, 맨 위(나중에 쌓인 것)부터 차례로 해결된다. Forge에서 이건 forge.game.zone.MagicStack이 담당하고, 내부적으로 양쪽에서 넣고 뺄 수 있는 큐(Deque)로 구현돼 있다. resolveStack()이 맨 위 항목을 꺼내 그 능력의 resolve()를 호출한다.

턴 진행은 PhaseHandler가 맡는다. PhaseType enum이 MTG 정식 11단계(언탭·유지·뽑기·메인1·전투 5단계·메인2·종료·정리)를 그대로 정의하고, 단계마다 누구에게 우선권(priority)을 줄지 관리한다. 여기에 유발 능력(TriggerHandler), 대체 효과(ReplacementHandler), 정적 능력(StaticEffects) 세 핸들러가 스택 해결 사이사이에 끼어들어, 진짜 MTG 규칙의 복잡한 흐름을 재현한다.

핵심 설계 3 — 흐름 한 줄기: 라이트닝 볼트의 일생

위 부품들이 어떻게 맞물리는지, 가장 단순한 흐름 하나(엣지 케이스는 생략한 '해피 패스')로 따라가 보자.

// "라이트닝 볼트로 상대 얼굴에 3 데미지" 한 판의 내부 순서 (개념 단순화)
① 게임 시작 전: CardStorageReader 가 lightning_bolt.txt 를 읽어
   CardRules 로 만들어 둔다 (3만 장 전부 메모리에)
② 내가 카드를 손에서 시전 → AbilityFactory 가 만든 SpellAbility 발동
③ 대상 선택: ValidTgts$ Any → 상대 플레이어를 타깃으로 지정
④ MagicStack.add(...) — 볼트가 스택에 올라간다 (아직 데미지 없음)
⑤ 양쪽이 더 안 하면 → resolveStack() 이 맨 위(볼트)를 꺼냄
⑥ DealDamageEffect.resolve() 실행 — 상대 생명점 -3
⑦ GameAction.checkStateEffects() — "생명점 0 이하인 사람 있나?" 검사
⑧ 있으면 checkGameOverCondition() 으로 승패 판정 → 없으면 다음 우선권

여기서 배울 핵심은 "데이터(텍스트)와 실행(엔진)이 깔끔히 갈려 있다"는 점이다. 볼트의 "3"이라는 숫자는 텍스트에서 왔지만, "스택에 올리고·해결하고·생명점을 깎고·승패를 검사하는" 흐름은 카드와 무관한 엔진의 일반 규칙이다. 그래서 카드가 3만 장이어도 이 흐름 코드는 한 벌이면 된다.

5디렉토리 구조 해부

"모듈 12개가 무섭지만, 사실 '두뇌 4개 + 얼굴 여럿 + 리소스'로 묶인다."

루트에는 부모 pom.xml과 모듈 폴더들이 있다. 코드의 대부분은 4대 핵심 모듈에, 카드 텍스트 같은 리소스는 forge-gui/res/에 모여 있다.

처음 읽는다면 길잡이는 이렇다. 카드가 궁금하면 forge-gui/res/cardsfolder/의 텍스트 몇 장 → forge-core의 CardRules → forge-game의 AbilityFactory 순으로. 게임 흐름이 궁금하면 forge-game의 Game.java(전체 뼈대) → PhaseHandler(턴) → MagicStack(스택) 순으로 따라가면 된다.

6학습 포인트 (기술별)

"Forge 한 채에 '데이터 주도 설계·규칙 엔진·게임 AI·크로스플랫폼'이 다 들어 있다."

Forge는 게임을 안 좋아해도 배울 게 많다. 분야별로 무엇을 배울지 + 작게 실습할 아이디어를 정리했다.

7시스템 요구사항

"플레이는 가볍지만, 3만 장을 메모리에 올리고 소스에서 빌드하는 건 묵직하다."

그냥 플레이하기 (설치본)

소스에서 빌드하기 (개발자)

개발하려면 JDK 17과 Maven이 필요하다. 멀티모듈이라 루트에서 한 번에 빌드하고, 데스크톱 모듈을 실행한다.

# 소스에서 Forge 데스크톱 빌드·실행
git clone https://github.com/Card-Forge/forge
cd forge
mvn -U -B clean install -DskipTests   # 12개 모듈 전체 빌드 (첫 빌드는 길다)

# 데스크톱 GUI 실행 (빌드 후 forge-gui-desktop 산출물)
cd forge-gui-desktop/target
java -jar forge-gui-desktop-*-jar-with-dependencies.jar

# 화면 없이 AI끼리 자동 대전(밸런스 측정) — docs/AI.md
sim -d deck1.dck deck2.dck -n 3      # 두 덱을 3판 시뮬레이션

복사해서 그대로 쳐도 된다. 핵심은 mvn clean install 한 번이면 12개 모듈이 통째로 빌드된다는 것 — 다만 부품이 많고 카드 리소스가 커서 첫 빌드는 시간이 걸린다. sim 명령은 화면 없이 AI 대 AI를 돌려 결과만 뽑는, "성능·밸런스를 데이터로 본다"는 이 프로젝트의 성격이 드러나는 도구다.

8직접 해볼 수 있는 실습 과제

"읽기만 하면 안 남는다 — 난이도별로 손을 움직여 보자."

9관련 기술 심화 학습 로드맵

"자바 기초에서 Forge에 카드를 기여하기까지 — 7주 코스 예시."

아래는 "자바를 좀 아는 사람이 Forge 코드를 읽고 작게 기여할 수 있는 수준"까지의 한 가지 길이다. 본인 속도에 맞춰 늘리거나 줄여도 된다.

10핵심 키워드 사전

"이 문서와 Forge 코드에서 거듭 나오는 용어들 — 한 곳에 모아 풀었다."

11참고 링크

공식 저장소·문서·커뮤니티.