ludovic111/horizon 딥다이브
— Minecraft를 Rust로 다시 쓰고, 원본과 숫자 단위로 대조하는 법

1프로젝트 한줄 요약

Horizon은 Minecraft Java 26.3과 같은 월드·규칙·지형을 내도록 Rust로 처음부터 다시 쓴 게임이며, 게임 파일은 한 줄도 들어 있지 않고 사용자가 가진 정품 파일에서 리소스를 만들어 씁니다. README는 무료·오픈소스·비공식이며 Mojang이나 Microsoft과 관련이 없다고 밝힙니다. 라이선스는 MIT(프로젝트 고유 코드에 한함)입니다.

저장소는 게임 하나가 아니라 네 갈래입니다. 게임 클라이언트(crates/horizon-client), 전용 서버(horizon-server), 설치와 업데이트를 맡는 런처(launcher/), 그리고 모드·모드팩·에이전트 조작 같은 확장입니다.

1-1. 한눈에 보는 구성 요소

이 저장소에서 배울 핵심은 “큰 시스템을 다시 쓸 때 원본을 정답지로 삼아 기계적으로 대조하는 작업 방식”입니다.

2왜 주목받는가

2026-10-25 GitHub 기준 스타 1,328개, 포크 90개이며 TrendShift 순위 8위로 잡혔습니다. 저장소는 2026-10-03에 만들어졌고 최신 릴리스는 게임 v0.2.50, 런처 launcher@0.2.6입니다. 만든 지 22일 만에 이 규모라는 점, 최근 푸시가 분석 당일 아침이라는 점에서 개발 속도가 매우 빠릅니다. 스타 수는 관심도일 뿐 품질 지표가 아닙니다.

2-1. 주목받는 이유를 코드에서 확인한 것

• 검증 방식이 공개돼 있다. README의 “Java parity 100%” 표는 12개 하위 시스템마다 어떤 하네스가 몇 건을 비교하는지 적습니다(예: 월드 생성은 225개 구조물 위치의 청크 2,352개가 원본과 동일). 저장소에 하네스 스크립트 tools/test_*_parity.py가 실제로 326개 있습니다.
• 수치 재현이 집요하다. 플랫폼마다 달라지는 부동소수점 결과까지 맞추려고 jmath.rs를 따로 둡니다(4장).
• 제품이 완결돼 있다. 게임만이 아니라 런처, 서버 호스팅, 모드, 모드팩 가져오기, 에이전트 조작까지 있고 Linux·macOS(Apple Silicon)·Windows 빌드를 배포합니다.
• 대부분을 AI 에이전트가 작성한다. CLAUDE.md와 docs/security.md는 Claude 세션이 PR을 쓰고 리뷰·병합까지 한다고 적습니다. 그래서 문서가 에이전트용 지도(“A map for agents”) 형태로 매우 자세합니다.

AI가 코드를 쏟아내는 시대에 “원본과 대조하는 자동 심판”을 먼저 세우는 것이 이 프로젝트를 가능하게 한 설계로 보입니다.

3기술 스택 전체 지도

CLAUDE.md의 규칙은 “플레이어가 실행하는 것은 모두 Rust, Python/Java는 tools/의 개발 도구와 하네스 드라이버에만”입니다. 추적 파일 3,110개 중 확장자별로 Rust 1,548개, Python 474개, JSON 358개, Java 304개입니다.

3-1. 코드 규모 (커밋 00705d8, 물리 줄 수)

3-2. 영역별 스택

워크스페이스는 edition 2024, 릴리스 프로파일은 lto = "thin", codegen-units = 1입니다. 빠른 반복용 fast 프로파일(LTO 없음, 코드 생성 단위 16)이 따로 있습니다. 또 third_party/wgpu-hal은 특정 Intel 윈도우 드라이버 크래시를 피하려고 wgpu-hal 30.0.1을 패치해 넣은 사본이며, 업스트림 수정이 나오면 지우라는 주석이 있습니다.

4아키텍처 심화 분석

4-1. 전체 구조

한 가지 특이점은 클라이언트가 Game 구조체 하나(필드 약 290개, 비공개)에 모든 상태를 두고, 메서드를 game/<기능>.rs 파일 약 180개에 impl Game 블록으로 나눠 놓는다는 점입니다(CLAUDE.md). 기능을 찾을 때는 fn tick_<기능>을 검색하라고 안내합니다. 라이브러리 쪽은 Game을 볼 수 없고, 바이너리가 horizon_client::<모듈>으로 가져다 씁니다.

4-2. 핵심 설계 패턴

4-3. 같은 수식을 같은 비트로: jmath.rs

Rust의 f64::sin은 플랫폼의 libm을 부르고, 거기서는 마지막 비트가 달라지는 경우가 있습니다. 원본 Java는 HotSpot이 일부 Math 메서드를 CPU별 intrinsic으로 바꿔서, 이 결과도 머신마다 다릅니다. 파일 머리말은 이를 이렇게 정리합니다.

• atan2, atan, asin, acos, hypot은 어디서나 StrictMath(fdlibm)
• x86-64에서는 sin·cos·tan·exp·log·log10·pow가 Intel libm stub이라 플랫폼 libm과 거의 같음
• AArch64에서는 sin·cos만 intrinsic(곱셈-덧셈 융합을 쓰는 fdlibm 커널), 나머지는 StrictMath

// crates/horizon-core/src/jmath.rs (발췌)
pub fn sin(x: f64) -> f64 {
    if cfg!(target_arch = "aarch64") {
        aarch64::sin(x)      // HotSpot의 AArch64 intrinsic과 같은 계산
    } else {
        x.sin()              // x86-64: 플랫폼 libm
    }
}

그래서 규칙은 “원본의 Math 호출은 horizon_core::jmath로, 난수는 horizon_core::random으로, 난수는 원본과 같은 순서로 뽑는다”입니다(CLAUDE.md). 월드 생성이 시드 하나로 원본과 같은 지형을 내려면 이 수준이 필요합니다.

“비슷하게 동작”과 “비트 단위로 같은 결과”는 전혀 다른 난이도이며, Horizon은 후자를 목표로 비용을 치릅니다.

4-4. 하네스 한 개는 어떻게 생겼나

tools/test_composter_parity.py는 퇴비통이 설계 목적인 하네스입니다. 무작위 채움 레벨의 퇴비통에 대해 네 가지 동작(플레이어 우클릭, 위 호퍼가 넣기, 아래 호퍼가 꺼내기, 드로퍼가 투입)을 만들고, 양쪽이 블록 변화·컨테이너 내용·생성된 아이템·소리·게임 이벤트·플레이어 통계·레벨 난수 상태까지 출력해 비교합니다. 케이스 생성부는 시드를 받는 random.Random이라 재현할 수 있습니다.

def cases(facts, items, count, seed):
    rng = random.Random(seed)
    modes = ['use', 'use', 'hopper_in', 'hopper_out', 'dispense']
    for n in range(count):
        mode = modes[n % len(modes)]
        ...

4-5. 모드: 인터페이스는 WIT 한 파일

horizon.wit의 패키지는 horizon:mods@0.1.0입니다. 인터페이스 log는 항상 허용되고, 나머지(game, chat, hud 등)는 매니페스트에 선언해야 하는 권한입니다. 예제 모드 coords-hud의 매니페스트는 다음과 같이 세 가지만 요청합니다.

id = "coords_hud"
api = "0.1"
side = "client"
capabilities = ["game-read", "hud", "chat"]

5디렉토리 구조 해부

5-1. 처음 열어볼 파일 순서

5-2. 이식할 때 쓰는 이름 규칙

docs/architecture.md는 영역을 L/(crates/horizon-client/src/), G/(…/src/game/), W/(crates/horizon-world/src/)로 줄여 부릅니다. 예를 들어 월드 생성은 W/worldgen/과 L/vanillagen.rs, 이를 검사하는 하네스는 chunk_generation, feature_graph 등입니다. 하네스 이름은 tools/test_<이름>_parity.py로 대응됩니다.

6학습 포인트 (기술별)

6-1. 기술별로 배울 것

6-2. 에이전트 조작: 같은 명령을 CLI와 MCP로

docs/horizon-ctl-commands.md는 명령표에서 자동 생성된 문서라고 첫 줄에 적혀 있습니다. 한 표에서 CLI 명령, MCP 도구 이름(find-block → find_block), 인자 설명이 함께 나옵니다. README의 예시는 다음과 같습니다.

horizon-ctl launch --world Survival --seed 5 --wait
horizon-ctl state                       # 위치, 체력, 허기, 바라보는 대상, 화면...
horizon-ctl find-block birch_log
horizon-ctl goto -0.5 65 -2.5 --near 2.5
horizon-ctl break -1 65 -3              # 캐고, 떨어진 아이템을 응답으로 돌려줌

명령은 동작이 끝날 때까지 기다렸다가 결과를 JSON으로 돌려주고, 오류는 종류별 종료 코드로 구분됩니다(README). 리눅스·macOS는 Unix 소켓, Windows는 토큰이 있는 localhost 포트로 통신합니다.

6-3. 실습 아이디어

• jmath.rs의 sin이 x86-64와 AArch64에서 왜 다른 분기를 타는지 머리말을 읽고 직접 설명해 보기
• 임의의 하네스 하나를 골라 “입력 생성 → 오라클 → probe → 비교” 단계를 그림으로 그리기
• 작은 WIT 인터페이스를 직접 정의하고, 선언하지 않은 권한을 호출하면 어떤 일이 생겨야 하는지 설계해 보기

7하드웨어 / 시스템 요구사항

7-1. 플레이(런처 설치)

7-2. 소스 빌드(개발자)

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

git clone https://github.com/ludovic111/horizon.git
cd horizon
ls crates tools | head -50
git ls-files 'tools/test_*_parity.py' | wc -l

python3 tools/check_public_tree.py
python3 tools/check_public_tree.py --history

printf '%s\n' crates/horizon-core/src/jmath.rs > paths.txt
python3 tools/parity.py --changed-files paths.txt --list

cargo run --release -p horizon-prepare -- --prepare --server-jar ~/Downloads/server.jar
cargo run --release -p horizon-client

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

10핵심 키워드 사전

11참고 링크

• ludovic111/horizon — 저장소
• playhorizon.dev · 문서 — 설치와 사용 안내
• 릴리스 노트 — 게임 v0.2.x와 런처 launcher@0.2.x
• CLAUDE.md · docs/architecture.md · docs/parity-workflow.md — 구조와 검증 흐름
• docs/security.md — 에이전트 중심 개발의 보안 설계
• wgpu · WebAssembly 컴포넌트 모델 · MCP 입문 — 외부 개념 자료
• Minecraft EULA — README가 안내하는 약관

외부 문서는 시간이 지나며 바뀔 수 있습니다. 이 글의 파일·수치 설명은 커밋 00705d8에 맞췄습니다. 하네스를 실제로 실행한 결과, 성능, 정확도의 독립 검증은 이 글에 포함되지 않습니다.

현재 상태 (2026-10-25 확인)