Codebase Architecture & Workflow
This page documents the internal flow of Arnis when a user initiates the "Start Generation" process. It includes backend component interactions, data flow, and transformation steps.
The generation process starts from the frontend and passes through multiple Rust modules in the backend. The diagram below illustrates the full flow, including intermediate data stages and component responsibilities.
Click to expand Sequence Diagram (PlantUML)
@startuml
title Arnis World Generation Workflow (Technical)
actor User
participant "Frontend (Tauri/JS)" as Frontend
participant "gui.rs" as GUI
participant "retrieve_data.rs" as RetrieveData
participant "osm_parser.rs" as OSMParser
participant "ground.rs" as Ground
participant "map_transformation" as MapTransformation
participant "data_processing.rs" as DataProcessing
participant "progress.rs" as Progress
participant "fs" as Filesystem
User -> Frontend : Clicks "Start Generation"
Frontend -> GUI : invoke gui_start_generation(...)
alt New World & Spawn Point
GUI -> GUI : update_player_position(...)\n- Validate spawn point in bbox\n- Write to level.dat
end
GUI -> RetrieveData : fetch_data_from_overpass(bbox, debug, "requests", None)
RetrieveData -> Progress : emit progress (fetching)
RetrieveData -> RetrieveData : Query Overpass API\nReturn OSM XML/JSON
RetrieveData -> GUI : Return raw_data
GUI -> OSMParser : parse_osm_data(raw_data, bbox, scale, debug)
OSMParser -> OSMParser : Parse nodes, ways, relations\nConvert to elements
OSMParser -> GUI : Return (elements, scale_x, scale_z)
GUI -> GUI : Sort elements by priority\n(landuse, buildings, etc.)
GUI -> Ground : generate_ground_data(args)
Ground -> GUI : Return ground
GUI -> MapTransformation : transform_map(elements, xzbbox, ground)
MapTransformation -> MapTransformation : Apply transformations (from JSON ops)
MapTransformation -> GUI : Return transformed elements
GUI -> DataProcessing : generate_world(elements, xzbbox, ground, args)
DataProcessing -> Progress : emit progress (generation)
DataProcessing -> DataProcessing : For each element:\n- Dispatch to element_processing::*\n- Place blocks via WorldEditor
DataProcessing -> Filesystem : Write region files, level.dat, etc.
DataProcessing -> Progress : emit progress (done)
DataProcessing -> GUI : Return success/failure
GUI -> Frontend : Return result (success/error)
note right of DataProcessing
Element processing includes:
- buildings.rs
- highways.rs
- landuse.rs
- water_areas.rs
- etc.
Each calls WorldEditor to place blocks.
end note
@endumlThe raw data obtained from the API includes each element (buildings, walls, fountains, farmlands, etc.) with its respective corner coordinates (nodes) and descriptive tags. When you run Arnis, the following steps are performed automatically to generate a Minecraft world:
The script retrieves geospatial data for the desired bounding box from the Overpass API.
The raw data is parsed to extract essential information like nodes, ways, and relations.
- Nodes are converted into Minecraft coordinates.
- Relations are handled similarly to ways, ensuring all relevant elements are processed correctly.
- Relations and ways cluster several nodes into one specific object.
The elements (nodes, ways, relations) are sorted by priority to establish a layering system, which ensures that certain types of elements (e.g., entrances and buildings) are generated in the correct order to avoid conflicts and overlapping structures.
The Minecraft world is generated using a series of element processors:
generate_buildingsgenerate_highwaysgenerate_landuse- etc.
These processors interpret the tags and nodes of each element to place the appropriate blocks in the Minecraft world. They are documented at the Element Processors Wiki page.
A ground layer is generated based on the provided scale factors, to provide a base for the entire Minecraft world.
This step ensures all areas have an appropriate foundation (e.g., grass and dirt layers).
Finally, all modified chunks are saved back to the Minecraft region files.