Arnis: 현실 세계를 통째로 Minecraft로 옮기는 오픈소스, 내부 구조까지 뜯어보기

AI 시대에는 텍스트를 코드로 바꾸는 도구가 넘쳐난다. 그런데 어떤 프로젝트는 그 반대 방향에서 더 강한 인상을 준다. 현실 세계의 지리 데이터, 건물 정보, 지형 높이 데이터를 읽어 Minecraft 월드로 바꿔버리는 도구라면 어떨까.

Arnis는 단순한 “맵 변환기”가 아니다. 이 프로젝트는 OpenStreetMap과 고도 데이터를 받아서, 이를 Minecraft Java Edition과 Bedrock Edition이 이해할 수 있는 월드 포맷으로 재구성하는 지리 데이터 파이프라인 + 월드 생성 엔진에 가깝다. 저장소 설명 그대로, 실제 지리·지형·건축 정보를 반영한 Minecraft 월드를 생성하는 것이 목표이며, 현재 GUI와 CLI를 함께 제공하고, Rust 기반 모듈 구조 위에 Tauri GUI를 얹은 형태로 발전해왔다. 저장소 메타데이터 기준으로 이 프로젝트는 2026년 2월 기준 v2.5.0 릴리스를 공개했고, 저장소는 1만 개가 넘는 스타를 받고 있다. (GitHub)

 

GitHub - louis-e/arnis: Generate any location from the real world in Minecraft with a high level of detail.

 

프로젝트 소개

Arnis는 현실의 특정 지역을 Minecraft 월드로 생성하는 데스크톱 애플리케이션이다. 사용자는 지도에서 영역을 선택하고, 스케일이나 스폰 지점, 건물 내부 생성 같은 옵션을 지정한 뒤 월드 생성을 시작할 수 있다. 내부적으로는 OpenStreetMap 데이터를 가져오고, 필요하면 실제 고도 데이터를 더해 지형까지 반영한 뒤, 이를 Minecraft 월드 파일로 저장한다. Java Edition 1.17+뿐 아니라 Bedrock Edition도 지원한다. (GitHub)

이 프로젝트를 만든 사람은 저장소 소유자 Louis Erbkamm이며, 저장소와 공식 사이트 모두 무료·오픈소스 데스크톱 앱임을 강조한다. 라이선스는 Apache-2.0이다. 또한 README와 위키를 보면, 이 프로젝트는 “모듈성”, “성능 최적화”, “사용자 친화성”, “크로스 플랫폼”을 핵심 목표로 삼고 있다. (GitHub)

기술 스택도 꽤 흥미롭다. 핵심 생성 엔진은 Rust로 작성됐고, GUI는 Tauri 기반이다. Cargo 설정에는 geo, rayon, reqwest, fastanvil, fastnbt, tauri 등이 포함되어 있으며, Bedrock 지원을 위한 별도 feature와 관련 크레이트들도 존재한다. 즉, 이 프로젝트는 단순히 “지도 API를 부르는 앱”이 아니라, 지리 데이터 처리 + 병렬 처리 + Minecraft 포맷 직렬화를 한데 묶은 시스템이다. (GitHub)

왜 이 프로젝트가 등장했을까

이 프로젝트가 재미있는 이유는, Minecraft를 그냥 게임이 아니라 범용 3D 그리드 플랫폼처럼 다루고 있기 때문이다.

보통 현실 지도를 게임 월드로 가져오는 일은 생각보다 어렵다. 도로, 건물, 공원, 강처럼 서로 성격이 다른 데이터를 한 좌표계 안에서 정리해야 하고, 평면 지도 정보만으로는 Minecraft의 블록 월드를 만들 수 없기 때문이다. 게다가 Minecraft는 단순한 메쉬 엔진이 아니라, 청크·리전·NBT 같은 자체 저장 구조를 가진다. Arnis는 이 간극을 메우기 위해 OpenStreetMap 데이터 파싱, 좌표 변환, 레이어 우선순위 정렬, 지형 보정, 블록 배치, 월드 저장을 하나의 파이프라인으로 묶었다. 위키에서도 코드베이스 구조가 모듈식으로 설계되어 유지보수와 기능 추가를 쉽게 하려 했다고 설명한다. (GitHub)

특히 최근 버전의 발전 방향을 보면 문제의식이 더 선명해진다. Bedrock 지원은 2025년 12월 공개된 v2.4.0에서 큰 기능으로 추가됐고, 이어진 v2.4.1에서는 AWS Terrain Tiles 다운로드 병렬화, OSM 파싱 스트리밍, 메모리 절감, 보다 현실적인 지형 생성 같은 성능·품질 개선이 포함됐다. 즉, Arnis는 “한 번 데모로 만들어본 프로젝트”가 아니라, 실사용 과정에서 병목과 품질 문제를 계속 다듬고 있는 생성 엔진이다. (GitHub)

핵심 기능

1. 실제 지리 데이터를 Minecraft 오브젝트로 변환한다

Arnis의 시작점은 OSM 데이터다. 사용자가 지정한 bounding box를 기준으로 Overpass API에서 데이터를 가져오고, 이를 파싱해 노드·웨이·릴레이션을 Minecraft 좌표계로 옮긴다. 그런 다음 건물, 도로, 수역, 녹지, 철도, 관광 시설 같은 요소별 processor가 각자 블록 배치 로직을 수행한다. (GitHub)

이 말은 곧, Arnis가 단일 렌더러가 아니라 도메인별 렌더링 규칙 모음이라는 뜻이다. 건물은 높이와 재질 태그를 보고 해석하고, 도로는 highway 타입에 따라 폭과 재질을 달리하고, 물은 면과 선을 다르게 처리한다. 그래서 결과물도 단순 픽셀 맵이 아니라 “걷고 볼 수 있는 도시”에 가깝다. (GitHub)

2. 지형 고도까지 반영한다

평면 OSM만으로는 “지도를 블록 위에 칠한” 느낌이 날 수 있다. Arnis는 이를 해결하기 위해 AWS Terrain Tiles를 이용해 실제 고도 데이터를 가져온다. 위키에 따르면 이 시스템은 AWS S3의 Terrarium 포맷 PNG 타일을 내려받아 RGB 값을 높이 값으로 디코딩하고, 결측치 보정, 이상치 제거, adaptive Gaussian blur, Minecraft 높이 범위에 맞는 스케일링을 수행한다. 또한 타일 캐싱도 지원한다. (GitHub)

이 부분이 꽤 인상적이다. 보통 오픈소스 프로젝트에서 “지형 지원”은 옵션 수준으로 들어가지만, Arnis는 이 레이어를 별도 시스템으로 분리하고, 성능과 비용까지 고려해 무료 S3 접근 방식으로 옮겼다. 위키는 현재 구현이 고품질 데이터, 비용 0, API 키 불필요, 좌표 정렬 개선이라는 장점을 제공한다고 정리한다. (GitHub)

3. Java와 Bedrock 양쪽을 겨냥한다

Minecraft 생태계에서 Java와 Bedrock은 사용자층이 다르고 파일 포맷도 다르다. Arnis는 Java Anvil 포맷과 Bedrock .mcworld 출력 경로를 분기 처리하며, Cargo feature에서도 Bedrock 관련 의존성을 별도로 관리한다. main.rs를 보면 실행 시 --bedrock 여부에 따라 출력 포맷과 파일 생성 경로를 다르게 잡는다. Bedrock 지원 자체도 v2.4.0의 핵심 릴리스 항목이었다. (GitHub)

개발자 관점에서 이것은 중요하다. 이 프로젝트가 단순히 “한 에디션 전용 툴”이 아니라, 월드 생성 로직과 출력 포맷을 분리하는 방향으로 설계되어 있다는 뜻이기 때문이다.

4. 저장 엔진까지 직접 다룬다

Arnis는 최종 결과를 단순 export 이미지로 내보내지 않는다. 실제 Minecraft 월드 구조를 다룬다. WorldEditor 시스템 문서에 따르면, 이 레이어는 수정된 리전을 병렬로 저장하고, 각 청크에 대해 기존 데이터를 읽어 머지하며, 블록 엔티티를 보존하고, 필요한 기본 청크를 생성한다. 내부적으로는 Anvil/NBT 구조를 직접 다루며, 메모리 최적화를 위해 FnvHashMap, lazy chunk creation, bit packing, rayon 병렬 저장을 사용한다. (GitHub)

이건 말 그대로 게임 월드 직렬화 엔진이다. 그래서 Arnis를 보면 “지도 데이터를 블록으로 바꾼다”보다 “지리 데이터를 Minecraft 저장소 구조에 매핑한다”가 더 정확한 표현이다.

프로젝트 아키텍처 분석

위키의 설명과 main.rs 흐름을 합치면 Arnis의 핵심 파이프라인은 꽤 명확하다. 사용자는 GUI 혹은 CLI로 generation을 시작하고, 백엔드는 OSM 데이터를 가져와 파싱한 뒤, 우선순위 정렬과 변환 단계를 거쳐 각 processor가 블록을 배치한다. 마지막에는 WorldEditor가 이를 실제 월드 파일로 저장한다. (GitHub)

이 구조를 좀 더 개발자스럽게 해석해보면 다음과 같다.

1단계: 입력 계층

입력은 크게 두 종류다.
하나는 OSM 기반의 평면 지리 정보, 다른 하나는 선택적으로 활성화되는 고도 데이터다.

main.rs를 보면 OSM 데이터는 파일에서 읽거나 Overpass API에서 가져오고, 이후 osm_parser::parse_osm_data로 넘긴다. 지형은 ground::generate_ground_data에서 준비된다. (GitHub)

2단계: 좌표계 정규화

현실 세계 좌표는 위도/경도고, Minecraft는 X/Y/Z 블록 좌표다. 이 사이를 그대로 잇는 것은 불가능하므로, Arnis는 중간 단계로 Cartesian XZ 좌표계를 두고 변환한다. 위키에 따르면 geographic → Cartesian → region/chunk/block 순서로 변환되며, OSM 파서가 전자의 역할을, WorldEditor가 후자의 역할을 맡는다. (GitHub)

이 설계가 좋은 이유는, 좌표 변환을 건물/도로 로직에 섞지 않았기 때문이다. processor는 “이미 Minecraft 친화적으로 정규화된 2D 좌표”만 받아 처리할 수 있다. 좌표계 분리가 잘 된 프로젝트에서 흔히 보이는 장점이다.

3단계: 도메인별 생성기

Arnis의 진짜 핵심은 element processors다.
위키 문서상 대표 processor만 봐도 buildings.rs, highways.rs, landuse.rs, water_areas.rs, waterways.rs, railways.rs, natural.rs, tree.rs, bridges.rs 등으로 나뉜다. 각 processor는 OSM 태그를 해석하고, 필요한 기하 계산을 수행한 뒤, WorldEditor를 통해 블록을 배치한다. 보조 알고리즘으로는 선형 요소를 위한 Bresenham, 면 채우기를 위한 flood fill 등이 등장한다. (GitHub)

즉, Arnis는 “큰 generate() 하나가 모든 걸 처리하는 앱”이 아니라, 지리 요소 타입마다 렌더링 책임을 나눠 가진 규칙 엔진이다.

4단계: 월드 저장 계층

마지막 저장 단계는 생각보다 어렵다. Minecraft 월드는 아무 파일이나 써 넣는다고 되는 구조가 아니기 때문이다. Arnis는 수정된 청크만 추적하고, 필요한 기본 청크를 생성하며, NBT 구조에 맞게 섹션과 palette를 구성해 저장한다. 저장은 병렬로 이루어지고, 기존 청크 데이터와의 병합 및 block entity 유지도 고려한다. (GitHub)

이 덕분에 Arnis는 “월드 프리뷰 생성기”가 아니라 실제로 플레이 가능한 월드 아티팩트를 만든다.

코드 흐름으로 보는 Arnis

main.rs를 단순화하면 대략 이런 흐름이다. 원본 코드는 더 길지만, 핵심 구조는 아래와 같다. (GitHub)

fn run_generation(args: Args) -> Result<(), String> {
    let raw_data = match &args.file {
        Some(file) => retrieve_data::fetch_data_from_file(file)?,
        None => retrieve_data::fetch_data_from_overpass(
            args.bbox,
            args.debug,
            args.downloader.as_str(),
            args.save_json_file.as_deref(),
        )?,
    };

    let mut ground = ground::generate_ground_data(&args);

    let (mut elements, mut xzbbox) =
        osm_parser::parse_osm_data(raw_data, args.bbox, args.scale, args.debug);

    elements.sort_by_key(|e| osm_parser::get_priority(e));

    map_transformation::transform_map(&mut elements, &mut xzbbox, &mut ground);

    data_processing::generate_world_with_options(
        elements,
        xzbbox,
        args.bbox,
        ground,
        &args,
        generation_options,
    )?;

    Ok(())
}

이 코드에서 눈여겨볼 점은 세 가지다.

첫째, 파이프라인이 선형적이다.
데이터 수집 → 지형 준비 → 파싱 → 정렬 → 변환 → 생성 순서가 명확해서, 디버깅 포인트를 찾기 쉽다.

둘째, 생성 로직 진입 전까지는 최대한 도메인 데이터 처리에 집중한다.
월드 파일 쓰기는 마지막에 몰려 있다. 덕분에 중간 단계의 테스트와 교체가 상대적으로 쉽다.

셋째, GUI와 CLI가 같은 엔진을 공유한다.
main.rs는 인자가 없으면 GUI를 띄우고, 있으면 CLI로 실행한다. 즉, 인터페이스는 다르지만 생성 엔진은 하나다. (GitHub)

개발자가 배울 만한 설계 포인트

1. 좌표계와 도메인 로직을 분리했다

많은 지도 기반 프로젝트는 위도/경도 계산이 도메인 로직 전체에 스며들어 코드가 금방 복잡해진다. Arnis는 coordinate system을 별도 모듈로 두고, geographic 좌표를 XZ 공간으로 먼저 정리한다. 덕분에 나중 단계는 Minecraft 친화적인 좌표만 생각하면 된다. (GitHub)

2. 기능이 아니라 “처리 단위”로 모듈을 자른다

Arnis의 구조는 프레임워크식 계층 분리보다, 데이터 처리 단계를 기준으로 잘려 있다.
예를 들어 retrieve_data, osm_parser, ground, map_transformation, element_processing, world_editor처럼 흐름 기반으로 나뉜다. 이런 구조는 배치성 파이프라인에 특히 잘 맞는다. (GitHub)

3. 성능 최적화가 아키텍처에 녹아 있다

이 프로젝트는 Rust를 쓰는 것만으로 끝나지 않는다. 위키와 릴리스 노트를 보면 rayon 기반 병렬 저장, AWS terrain tile 병렬 다운로드, OSM 파싱 스트리밍, 메모리 절감, lazy chunk creation, bit packing 같은 개선이 반복적으로 들어간다. 즉, 성능을 나중에 붙이는 게 아니라 아예 저장 계층과 데이터 흐름 설계에 포함하고 있다. (GitHub)

언제 사용하면 좋은가

Arnis는 다음 같은 상황에서 특히 매력적이다.

현실 공간을 게임 환경으로 옮기고 싶은 경우다.
예를 들어 학교 주변, 도심 일부, 관광지, 하천 인근을 Minecraft로 가져와 교육용·시뮬레이션용·커뮤니티 이벤트용으로 활용할 수 있다. 실제로 README에는 학술 및 언론 인용 사례도 소개되어 있다. (GitHub)

지리 데이터 처리 파이프라인을 공부하고 싶은 경우다.
OSM을 단순 시각화가 아니라 “게임 월드”로 바꾸는 과정은, ETL·좌표계 변환·도메인별 렌더링·직렬화가 모두 들어간다. 지리정보 시스템과 게임 데이터 구조 사이를 잇는 사례로 보기 좋다. (GitHub)

Rust로 작성된 실전형 오픈소스 아키텍처를 보고 싶은 경우다.
GUI 앱, CLI, 멀티 포맷 출력, 병렬 처리, 외부 데이터 연동, 자체 포맷 저장 엔진이 한 저장소 안에 공존한다. 학습용 소재로 꽤 훌륭하다. (GitHub)

실제 사용 예시

CLI 예시는 README에도 제공된다. 이런 식으로 특정 bounding box를 지정해 생성할 수 있다. (GitHub)

cargo run --no-default-features -- \
  --terrain \
  --path="C:/YOUR_PATH/.minecraft/saves/worldname" \
  --bbox="min_lat,min_lng,max_lat,max_lng"

개념적으로는 이런 활용이 가능하다.

1. 서울 특정 구역의 bbox를 지정한다.
2. OSM에서 도로/건물/공원 데이터를 가져온다.
3. 고도 데이터를 함께 받아 언덕과 경사를 반영한다.
4. Java 또는 Bedrock 월드로 출력한다.
5. 플레이어는 실제 도시 구조와 유사한 Minecraft 월드에 접속한다.

조금 더 개발자스럽게 응용하면, Arnis는 “현실 데이터 기반 월드 생성 백엔드”로도 볼 수 있다. 예를 들어 교육용 도시 시뮬레이션, 재난 대응 시각화, 로컬 커뮤니티 프로젝트, 혹은 특정 지역 기반 이벤트 서버 초기 맵 생성 등에 어울린다.

한계도 분명하다

좋은 프로젝트일수록 한계를 같이 봐야 한다.

위키에 따르면 지형 시스템은 현재 큰 영역에서 메모리 사용량이 커질 수 있고, AWS Terrain Tiles에 대한 단일 provider 의존성이 있다. fallback 소스는 아직 없다. 또한 현실 세계 OSM 데이터 품질 자체가 지역마다 다르기 때문에, 생성 결과의 정밀도도 결국 입력 데이터 품질 영향을 받는다. (GitHub)

또 하나는 이 프로젝트가 결국 정교한 규칙 기반 생성기라는 점이다. 즉, 모든 건축 디테일을 완벽한 3D 복원 수준으로 재현하는 도구는 아니다. 하지만 그것은 단점이라기보다 의도된 설계 선택에 가깝다. Arnis의 목표는 photorealistic 재현이 아니라, 현실 지리 구조를 Minecraft 문법으로 잘 번역하는 것에 있다. (GitHub)

마무리

Arnis를 한 줄로 요약하면 이렇다.

현실의 지리 데이터를 Minecraft 월드로 바꾸는, 생각보다 훨씬 진지한 지오메트리/직렬화 엔진이다.

겉으로 보면 “우리 동네를 Minecraft로 만드는 재미있는 툴”처럼 보인다. 그런데 저장소를 자세히 보면, 그 안에는 OSM 수집, 좌표 변환, 지형 보정, 요소별 생성기, 청크 저장 엔진, Java/Bedrock 포맷 분기, 병렬 처리까지 들어 있다. 이 프로젝트가 인상적인 이유는 결과물이 신기해서가 아니라, 그 결과물을 만들기 위한 아키텍처가 꽤 정교하기 때문이다. (GitHub)

개발자 입장에서 Arnis는 두 가지 의미가 있다.
하나는 실제로 재미있고 유용한 도구라는 점, 다른 하나는 복잡한 현실 데이터를 게임 세계의 규칙으로 번역하는 방법을 배울 수 있는 아주 좋은 오픈소스 사례라는 점이다.