Arnis

Arnis is a tool that generates complex and accurate Minecraft Java Edition (1.17+) and Bedrock Edition worlds based on real-world geography, topography, and architecture. It processes geospatial data from OpenStreetMap and elevation data to create detailed representations of terrain and buildings.

Key Features:

• Generates hometowns, cities, and natural landscapes.
• Uses OpenStreetMap (OSM) for architecture and roads.
• Uses elevation data for realistic terrain.
• Supports both GUI and Command Line interfaces.

Note: For mobile generation or larger map sizes, use MapSmith.

Arnis organizes tree packs into size tiers based on their height (measured in blocks). When building, any trees taller than 40 blocks are dropped.

Height Tiers:

• small: $\le$ 6 blocks
• medium: 7-12 blocks
• big: 13-20 blocks
• tall: 21-28 blocks
• giant: 29-40 blocks

Metrics: Counts are provided as SPECIES (distinct species) / SCHEMS (variants).

Rendering Note: Tier toggles are managed via the Meld 'Trees' card. The giant tier is OFF by default and only renders at a 1:1 scale. The tall tier is considered rare.

Arnis can be built and run using cargo. You can choose between a GUI build or a headless command-line build.

GUI Build

To launch the graphical interface:

cargo run --release

Command Line Build

To run a headless generation with specific parameters:

cargo run --release --no-default-features -- --output-dir="C:/YOUR_PATH/.minecraft/saves/worldname" --bbox="min_lat,min_lng,max_lat,max_lng"

Run with Nix

If you are using Nix, you can run the program directly:

nix run github:louis-e/arnis -- --output-dir=YOUR_PATH/.minecraft/saves/worldname --bbox="min_lat,min_lng,max_lat,max_lng"

The Graphical User Interface (GUI) allows for an interactive world generation experience:

1. Select Area: Use the rectangle tool on the map to choose your desired geographic area.
2. Select World: Choose your target Minecraft world.
3. Customize Settings: Adjust parameters such as world scale, spawn point, or building interior generation.
4. Generate: Click Start Generation to begin the process.

Arnis supports three primary world formats. The format is determined by the CLI flags provided:

• Java Edition: The default format. Creates a new world in the specified directory. Supports an optional --disable-height-limit flag to install a tall-world datapack (requires Minecraft 1.21.4+).
• Bedrock Edition: Triggered via --bedrock. Generates a .mcworld file. The output directory defaults to the user's Bedrock output directory if --path is not provided.
• Luanti (formerly Minetest): Triggered via --luanti. Creates a world in the Luanti worlds directory. Supports specific game logic via the --luanti-game option (e.g., Mineclonia).

When selecting an elevation provider, Arnis uses several signals from the ElevationProvider trait:

1. Coverage: The system checks coverage_bboxes() to see if the requested area is supported. If coverage_bboxes() returns None, the provider is treated as a global fallback.
2. Acceptance: The accepts(&LLBBox) method allows a provider to decline a request. This is useful for rate-limited providers that may want to reject oversized bounding boxes, allowing the selector to fall through to the next available candidate.
3. Resolution Ranking: Providers are ranked based on the value returned by native_resolution_m(). A lower value (higher resolution) is preferred.

The compute_water_distance function generates a distance-to-shore field using a multi-source Breadth-First Search (BFS).

This is used for shoreline blending (e.g., assigning sand surfaces to land cells adjacent to water). The resulting grid values are:

• 0: Non-water cell (or unreachable water).
• 1: Water cell on the shore (adjacent to non-water or the grid edge).
• 2+: Water cell $N$ blocks from the nearest shore.

The depth is capped at 15 to prevent excessive computation for large bodies of water.

The SparseBytes struct implements a memory-efficient way to read Parquet files by only storing pre-fetched byte ranges. This is designed for scenarios where you want to download only the file footer and specific row groups (e.g., ~4-5 MB) instead of the entire partition file (e.g., ~580 MB).

Workflow:

1. Initialize with SparseBytes::new(file_size).
2. Use add_range(offset, data) to add fetched chunks.
3. Call finalize() to sort the ranges by offset.
4. The struct implements ChunkReader, allowing it to be used with Parquet readers to access only the cached segments via get_read or get_bytes.

struct SparseBytes {
    file_size: u64,
    ranges: Vec<(u64, bytes::Bytes)>,
}

The 3DMR client uses an on-disk cache for both .json metadata and .glb files. The cache directory is determined as follows:

• It attempts to use the standard system cache directory via the dirs crate, appending the subdirectory arnis/3dmr.
• If a system cache directory cannot be determined, it defaults to ./.arnis_3dmr_cache in the current working directory.