Bucket Grids

Bucket Grids

Bucket grids are spatial partitioning structures that League uses for visibility culling and level-of-detail (LOD). Each grid divides the map into rectangular cells ("buckets"), and each bucket knows which mesh faces it contains.

Location: LoL Mapgeo tab → Layer Management (for controls) and Utilities (for import)

---

Concepts

What is a Bucket Grid?

A bucket grid is an axis-aligned 2D grid (X/Z plane) that covers a portion of the map. Each cell stores:

• Mesh indices — which meshes have geometry in this cell
• Face visibility flags — per-face visibility within each mesh (bitfield)

The game engine uses this to quickly determine which faces to render based on the camera position.

Grid Types

Meshes are grouped into separate grids based on their metadata:

Grid Type	Grouping Key	path_hash	unknown_v18_float
Master Grid	No special hash	0	0
Render Region Grid	render_region_hash	0	render region hash
Baron/Visibility Grid	baron_hash	hash	0

Hash Field Placement Rules

Render region grid:   path_hash = 0,       unknown_v18_float = region hash
Baron/visibility:     path_hash = hash,    unknown_v18_float = 0
Master grid:          path_hash = 0,       unknown_v18_float = 0

---

Creating Bucket Grids

Create Custom Bucket Grid

1. Import or build your map geometry.
2. In Layer Management → Bucket Grid, click Create Bucket Grid.
3. Configure options:

Option	Default	Description
Height Range Z Min	-120	Minimum Z for bucket sampling
Height Range Z Max	5000	Maximum Z for bucket sampling
Use Selected Only	Off	Only process selected meshes
Include Render Regions	On	Generate separate grids for render region meshes

4. Click OK.

What Happens

The operator:

1. Groups meshes by render_region_hash, baron_hash, and visibility_layer.
2. For each group, computes the bounding box on the X/Z plane.
3. Determines dynamic grid resolution based on bounds size.
4. Assigns each mesh face to the bucket(s) it overlaps.
5. Creates:
   • Display mesh — visual representation of the grid
   • Bounding box — wireframe outline
   • Collection — containing grid objects with JSON metadata

Collection Structure

BucketGrids/
├── BucketGrid_Master/
│   ├── BG_Master_Grid (display mesh)
│   └── BG_Master_Bounds (wireframe)
├── BucketGrid_RenderRegion_A1B2C3D4/
│   ├── BG_RR_A1B2C3D4_Grid
│   └── BG_RR_A1B2C3D4_Bounds
└── BucketGrid_Baron_5E652742/
    ├── BG_Baron_5E652742_Grid
    └── BG_Baron_5E652742_Bounds

Each grid collection stores metadata as a JSON string in custom properties:

• bucket_grid_data: Full grid definition (bounds, resolution, buckets)
• bucket_grid_type: "master", "render_region", or "baron"
• bucket_grid_hash: The associated hash value

---

Managing Bucket Grids

Controls

Button	Action
Create Bucket Grid	Generate new grids from scene meshes
Clear All Bucket Grids	Delete all bucket grid collections
Toggle Selectable	Lock/unlock grid objects to prevent accidental selection
Show/Hide	Toggle bucket grid visibility in viewport

When to Rebuild

Rebuild bucket grids whenever you:

• Add, remove, or move meshes
• Change mesh geometry (vertices, faces)
• Modify visibility layers or baron hashes
• Change render region assignments

Clean Before Rebuild

Always click Clear All Bucket Grids before creating new ones to avoid stale data.

---

Import Bucket Grid

Import and visualise bucket grids from an existing .mapgeo file:

1. Utilities → Import Bucket Grid from mapgeo
2. Select a .mapgeo file
3. Grid collections are created with visual representations

This is useful for inspecting the original game's spatial partitioning.

---

Export

Bucket grids are automatically included when exporting a .mapgeo file. The export process:

1. Reads metadata from each bucket grid collection.
2. Encodes the grid structure (bounds, resolution, bucket data).
3. Writes to the mapgeo binary.

If no bucket grid collections exist in the scene, the exported mapgeo will have no bucket grids — which may cause rendering issues in-game.

---

Validation Tips

• Ensure at least one master grid exists (covers all regular meshes).
• Verify face visibility flags are present for all meshes in each grid.
• Use JSON debug export to compare your grids against the original mapgeo.
• Check that hash field placement follows the rules above.

---

Code Example

Bucket grid structure (from mapgeo export)

bucket_grid = {
    "min_x": -8000.0,
    "min_z": -8000.0,
    "max_x": 8000.0,
    "max_z": 8000.0,
    "bucket_size_x": 500.0,
    "bucket_size_z": 500.0,
    "count_x": 32,
    "count_z": 32,
    "height_range_min": -120.0,
    "height_range_max": 5000.0,
    "path_hash": 0,            # 0 for master grid
    "unknown_v18_float": 0.0,  # 0 for master grid
    "buckets": [
        {
            "mesh_indices": [0, 5, 12, 47],
            "face_visibility_flags": [0xFFFFFFFF, 0x0000FFFF, ...]
        },
        ...
    ]
}

Dynamic grid resolution

The addon computes resolution based on the group's bounding area:

• Smaller areas get fewer buckets (minimum: 4×4)
• Larger areas get more buckets (scales with extent)
• Each bucket is approximately 500×500 world units