Skip to content

Troubleshooting

Jump to bottom
TheKillerey edited this page Apr 13, 2026 · 2 revisions

Troubleshooting

Common issues and solutions when working with the addon.

Installation Issues

Addon does not appear in Blender preferences

  • Ensure you installed the folder (not a nested zip). The addon root must contain __init__.py.
  • Check the Blender version: the addon requires Blender 4.0+ (tested up to 5.1).
  • Look for error messages in Window → Toggle System Console.

"No module named 'MapgeoAddon'"

The addon folder must be named exactly MapgeoAddon in the addons directory:

%APPDATA%\Blender Foundation\Blender\<version>\scripts\addons\MapgeoAddon\

Auto-updater fails

  • Check internet connectivity.
  • Ensure update_addon.py has write permissions to the addons directory.
  • The updater syncs files to all detected Blender version folders. If a version folder is read-only, the sync will fail silently.

Registration Errors

StringProperty could not register because it starts with '_'

Blender 5.1+ rejects property names starting with underscore. Fixed in addon v0.4.4.

Fix: Update the addon to latest version, or manually rename the property in ui_panel.py:

# Change:
_dialog_phase: bpy.props.StringProperty(...)
# To:
dialog_phase: bpy.props.StringProperty(...)

register_class(...) error

Usually caused by a duplicate class name or incompatible property type. Check the system console for the full traceback.

Project Manager Issues

Map scan finds no files

  • Verify League Path points to the game installation root (containing DATA/ or Game/).
  • Verify Project Folder is set and exists.
  • Ensure WAD hashes are downloaded (League Tools → WAD Archive Tool → Download WAD Hashes).

WAD extraction stalls / never completes

  • Delete the .extraction_done marker file in the WAD cache folder to allow re-extraction: 
    %APPDATA%\Blender Foundation\Blender\<ver>\mapgeo_addon\wad_cache\<MapId>\.extraction_done
  • Check available disk space (WAD extraction can require several GB).

"Hash file not found" warnings

Hash files are large (~180 MB total) and stored in hashes/:

MapgeoAddon/hashes/hashes.game.txt.0
MapgeoAddon/hashes/hashes.game.txt.1

Download them via: League Tools → WAD Archive Tool → Download WAD Hashes.

Import Issues

Mapgeo imports but all meshes are white

  • Materials file not loaded. Load materials via Project Manager or Import Materials.
  • Textures not found on disk. Check that textures are extracted from WAD.
  • Texture paths in materials may use game-relative paths that need resolving.

"Unsupported mapgeo version"

The addon supports mapgeo versions 5–15. Older versions (1–4) may have limited support. Check the system console for the exact version reported.

Import is very slow

  • Large maps (Summoner's Rift) have 2000+ meshes — import takes time.
  • Blender 5.0+ uses foreach_set optimisations for faster mesh creation.
  • Disable Import Materials if you only need geometry.

External mesh import dialog doesn't appear

  • Ensure at least one mesh is selected before clicking Import External Mesh.
  • The operator uses a file browser dialog — check if it opened behind the main window.

Export Issues

Export fails with "No meshes in MapGeometry collection"

Exportable meshes must be in the MapGeometry collection (or a sub-collection). Move your objects there.

Exported mapgeo crashes the game

Common causes:

  1. Missing materials — every mesh must have a material that exists in the materials file.
  2. Invalid vertex data — check for NaN values, zero-area faces, or degenerate geometry.
  3. Bucket grid mismatch — if the map uses bucket grids, they must be present and valid.
  4. Version mismatch — export version must match what the game expects for that map slot.

Materials not exporting correctly

  • Ensure materials are in the scene's material data (not just on mesh slots).
  • Check Project Integrity (League Tools → Project Integrity → Check Project) before export.

Materials Issues

Shader preview shows "Unknown Shader"

The addon includes shader templates for ~50 common shaders. If your material uses an unknown shader hash, it won't have a preview template. The material will still export correctly.

Texture appears black in viewport

  • The texture file may be missing or in an unsupported format.
  • Check that the sampler path resolves to an actual file on disk.
  • DDS textures with BC7 compression may not display in older Blender versions.

Visibility / Layer Issues

Meshes disappear when toggling layers

Dragon layer filtering is working as intended. Meshes are hidden when their layer bit doesn't match the filter. Use the Visibility Filtering controls to adjust which layers are shown.

Baron visibility not working

  • Ensure baron hash meshes have baron_hash custom property set.
  • Visibility controllers must exist in the materials file.
  • Check that controller type and ParentMode values are correct.

Lighting Issues

Lightgrid bake produces all-black cells

  • No light objects in the scene. Place at least one Blender light.
  • All meshes marked as Ignore. Ensure occluder meshes exist for shadow casting.
  • Light scale set to 0. Check scene lightgrid properties.

Lightmap bake fails

  • Requires Cycles renderer (not Eevee).
  • Meshes need LightmapUV layer — run Step 2 first.
  • NO_BAKED_LIGHT macro still present — run Step 3 first.
  • Insufficient memory for large texture resolutions.

Prey Format Issues

Rebuild produces different file size

Small size differences are normal due to JSON serialisation precision. If the difference is large:

  • Check that all 10 .prey.* files are present in the _prey/ folder.
  • Verify no .prey.* files were corrupted by text editors changing line endings.

"Category file not found" error

The rebuild expects all 10 category files. If a category had no entries, it should still exist as an empty-entries file. Re-run Convert to .prey to regenerate.

Map Porter Issues

Ported map has missing textures

The porter copies materials entries but not texture files. You must also copy/extract the source map's textures to the target location.

Character skins wrong on ported map

The porter patches character skin paths in target-only MPC entries. If skins still appear wrong:

  • Check map11.bin patching was enabled.
  • Verify the source map's skin override numbers.

Performance Tips

  • Close system console when not debugging — console output slows Blender.
  • Disable viewport materials (solid mode) when working with large maps.
  • Use Selected Only options when exporting/baking to limit scope.
  • Prey format is faster for iterative edits than full .bin import/export cycles.

Getting Help

  1. Check the system console (Window → Toggle System Console) for detailed error messages.
  2. Run Project Integrity Check to catch common issues.
  3. Enable the Debug System (if available) for verbose logging.
  4. Report issues on GitHub Issues with:
    • Blender version
    • Addon version (shown in preferences)
    • Full error traceback from system console
    • Steps to reproduce

Clone this wiki locally