Skip to content

Mapgeo Import & Export

Jump to bottom
TheKillerey edited this page Apr 13, 2026 · 1 revision

Mapgeo Import & Export

The .mapgeo format is League of Legends' binary mesh container. It stores geometry, vertex attributes, materials references, bucket grids, and per-mesh metadata.

Import

Location: LoL Mapgeo tab → Import Map

Import Options

Option Default Description
Import Materials On Load material data and create Blender shader nodes
Import Vertex Colors On Load vertex color attributes
Import UVs On Load UV coordinate channels
Import Normals On Load custom vertex normals
Import Lightmaps On Load baked lightmap data
Import Bucket Grid Off Import spatial partitioning grid as collections
Merge Vertices Off Deduplicate coincident vertices
Debug Logging Off Verbose console output during import
Execution Mode Foreground Foreground (freeze UI) or Background (responsive)

What Gets Imported

Each mesh in the mapgeo becomes a Blender object with:

  • Geometry: Triangulated mesh with positions and normals
  • UV Channels: Up to 8 UV layers (TEXCOORD0–TEXCOORD7)
  • Vertex Colors: COLOR0 attribute (RGBA per-vertex)
  • Materials: Blender material assigned per-primitive (when materials are loaded)
  • Custom Properties: All mapgeo-specific metadata stored on the object

Per-Mesh Custom Properties

After import, each mesh object carries these properties:

Property Type Description
visibility_layer int Dragon layer bitmask (bits 0–7)
quality int Quality level bitmask (bits 0–4)
is_bush bool Whether this mesh is bush/vegetation
baron_hash string Baron visibility controller hash (hex)
render_region_hash string Render region controller hash
path_hash string Mapgeo path hash identifier
unknown_v18_float float Version 18+ float field
point_light_* various Custom point light data (if present)

Filtered Imports

The Utilities panel offers specialised import modes:

Operator What it imports
Import Bushes Only meshes with is_bush=True
Import Render Regions Only meshes with a render region hash
Import Bucket Grid Only the bucket grid spatial data
Import External Mesh glTF/FBX/OBJ with automatic mapgeo property initialisation

Mesh Properties Panel

Location: LoL Mapgeo tab → Mesh Properties

Select any imported mesh to view and edit its properties:

  • Visibility Layer: Toggle individual dragon layers (Base, Inferno, Mountain, Ocean, Cloud, Hextech, Chemtech, Void)
  • Quality: Set quality bitmask
  • Bush: Toggle bush flag
  • Baron Hash: Assign or edit baron visibility controller
  • Render Region: Assign render region hash
  • Material: View/change the assigned material name
  • Diffuse Texture: Quick-change the diffuse texture path

Setup Wizard

For new or external meshes, use Mapgeo Setup Wizard to configure all properties at once:

  1. Select meshes
  2. Click "Mapgeo Setup Wizard" in Utilities
  3. Set visibility layer, quality, bush flag, hashes
  4. Click OK

Initialize for Mapgeo

Quick one-click initialiser that assigns default mapgeo properties to selected meshes (visibility=255, quality=31).

Export

Location: LoL Mapgeo tab → Export Settings

Export Settings

Setting Options Description
Version 13–18 Mapgeo format version to write
Optimize Meshes On/Off Optimize vertex/index buffers during export

Export Pipeline

Blender scene objects
  ↓ validate geometry (triangulated, has UVs)
  ↓ encode vertex streams (position, normal, UV, color)
  ↓ encode index buffer
  ↓ collect bucket grid data from collections
  ↓ gather per-mesh metadata from custom properties
  ↓ write .mapgeo binary

What Gets Exported

  • All mesh objects in the scene (excluding helpers/empties)
  • Vertex positions, normals, UVs, vertex colors
  • Material name references per-primitive
  • Bucket grid spatial partitioning data
  • Bounding spheres and bounding boxes
  • All custom properties (visibility, quality, hashes, etc.)

Validation

Before export, the addon validates:

  • All meshes are triangulated
  • UV channels exist
  • Material names are assigned
  • No degenerate faces

Errors appear in the console and as Blender info-bar messages.

File Format Reference

Mapgeo Structure

MapgeoFile
├── magic: "OEGM" (4 bytes)
├── version: u32 (13–18)
├── meshes[]: array
│   ├── name: string
│   ├── vertex_buffers[]: VertexBuffer
│   │   ├── description: VertexBufferDescription
│   │   │   └── elements[]: (name, format, offset)
│   │   └── data: raw bytes
│   ├── index_buffer: IndexBuffer
│   ├── primitives[]: MeshPrimitive
│   │   ├── material: string (name reference)
│   │   ├── start_index, index_count
│   │   └── start_vertex, vertex_count
│   ├── bounding_sphere: (x, y, z, radius)
│   ├── bounding_box: (min, max)
│   ├── visibility_layer: u32
│   ├── quality: u8
│   ├── is_bush: bool
│   ├── baron_hash: u32
│   ├── render_region_hash: u32
│   └── path_hash: u32
├── bucket_grids[]: BucketGrid
│   ├── min_x, min_z, max_x, max_z
│   ├── bucket_size_x, bucket_size_z
│   ├── count_x, count_z
│   ├── height_range_min, height_range_max
│   └── buckets[]: GeometryBucket
│       ├── mesh_indices[]
│       └── face_visibility_flags[]
└── texture_overrides[]: (optional, v15+)

Vertex Element Names

Name Usage
POSITION Vertex position (xyz)
NORMAL Vertex normal
TEXCOORD0–TEXCOORD7 UV channels
COLOR0 Vertex colour (RGBA)
BLEND_WEIGHT Skinning weights
BLEND_INDEX Skinning indices

Vertex Element Formats

Format Size Description
FLOAT3 12 bytes 3× 32-bit float (positions, normals)
FLOAT2 8 bytes 2× 32-bit float (UVs)
BYTE4N 4 bytes 4× 8-bit normalised (colours)
SHORT2N 4 bytes 2× 16-bit normalised (compressed UVs)
FLOAT4 16 bytes 4× 32-bit float

External Mesh Import

To add custom geometry (from glTF, FBX, or OBJ):

  1. Utilities → Import External Mesh (or use Blender's native importer)
  2. Select the imported mesh(es)
  3. Run Initialize for Mapgeo or Mapgeo Setup Wizard
  4. Assign a material name that exists in your materials file
  5. Set visibility layer, quality, and other properties
  6. Rebuild bucket grids (see Bucket Grids)
  7. Export

Ensure all faces are triangulated before export. Use Blender's Triangulate Faces (Ctrl+T in Edit Mode).

Debug & Comparison

JSON Debug Export

Export a mapgeo file to JSON for inspection or comparison:

  1. Use debug_system.py to export the original mapgeo as JSON
  2. Export your modified mapgeo as JSON
  3. Compare bucket grid counts, mesh hashes, vertex counts
  4. Identify discrepancies with any diff tool

Import Statistics

After import, the debug system reports:

  • Meshes imported / failed
  • Materials loaded / missing
  • Textures loaded / missing / failed
  • Lights created (if point lights present)

Clone this wiki locally