FireMaze — Usage & Management

1. Object Categories & Material Slots

When generated, the addon creates separate objects based on your merge configuration. Each object carries a fire_maze custom property tag for reliable cleanup.

Material Notes

• All materials are auto-generated with a simple principled BSDF shader using a unique color per category.
• You can replace or modify materials after generation — the addon does not overwrite existing materials on rebuild.

2. Collection Structure

Maze Collection

Each maze generation creates a new top-level collection (e.g. FireMaze, FireMaze.001, FireMaze.002, etc.) containing all generated objects. The naming auto-increments to avoid conflicts.

The collection stores a serialized JSON custom property named fire_maze_data containing:

• Grid dimensions (width, depth, rings)
• 3D cell states (wall flags, mesh indices per direction, floor/roof/stair indices)
• Entrance and exit coordinates with side orientations
• Wall mode and grid type
• Shape boundary and smooth edge settings
• Schema version

This data property is the single source of truth for interactive editing and session management. The viewport editor and rebuild operators read it directly, ensuring seamless operation across file loads and session restores.

Prop Sub-Collections

Prop and decor objects are grouped under a scoped sub-collection named FireMaze_Props_{parent_name} (e.g. FireMaze_Props_FireMaze). This sub-collection is:

• Linked as a child of the main maze collection.
• Tagged with a fire_maze_data custom property so it is included in Clear Maze operations.

Active Collection Detection

The addon resolves the active maze collection through _get_active_maze_collection():

1. First checks scene.fire_maze.fire_maze_collection_name for a stored collection name.
2. Falls back to scanning bpy.data.collections for any collection with a fire_maze_data custom property.
3. If exactly one candidate is found, it is used as the active collection.

3. Session Management

FireMaze supports full session serialization to .json files, allowing you to save and reload complete maze configurations.

Save Session

Operator: MAZE_OT_save_session — fire_maze.save_session (ExportHelper, .json extension)

Exports the following to a JSON file via a file dialog:

• All scalar properties — Every property in PROP_NAMES (integers, floats, strings, booleans, and vector tuples) is serialized by value.
• Pointer references — Mesh, collection, image, and object pointers are stored by name (not packed into the JSON). This includes:
  • custom_floor_mesh, custom_wall_mesh, custom_roof_mesh (Mesh datablocks)
  • custom_floor_collection, custom_wall_collection, custom_roof_collection (Collections)
  • custom_stair_mesh, custom_ramp_mesh (Object pointers)
  • prop_torch_mesh, prop_chest_mesh, prop_door_mesh (Object pointers)
  • mask_image (Image datablock)
• Full maze layout data — The serialized cell grid (fire_maze_data JSON from the maze collection).

Load Session

Operator: MAZE_OT_load_session — fire_maze.load_session (ImportHelper, .json extension)

Opens a .json session file and:

1. Reads the schema version for forward-compatibility handling.
2. Restores all scalar properties from the properties dict.
3. Re-links pointer references by looking up datablock names with bpy.data.images.get(), bpy.data.collections.get(), bpy.data.meshes.get(), and bpy.data.objects.get().
4. Recreates the maze collection, applies the serialized cell data, and triggers a full rebuild of all mesh objects.
5. Clears the autosave recovery warning if one was present.

If a referenced datablock no longer exists, the corresponding property is set to None rather than failing the entire load.

Serialization Format

{
  "schema_version": 1,
  "properties": {
    "width": 10,
    "depth": 10,
    "algorithm": "dfs",
    "custom_wall_collection": "MyWalls",
    "mask_image": "my_mask.png",
    ...
  },
  "maze_data": "{...serialized cell JSON...}"
}

4. Autosave & Crash Recovery

The addon automatically saves the current session to a temporary file every time a maze is generated, providing crash recovery.

Autosave File

• Location: System temp directory — {tempdir}/firemaze_autosave.json
• Trigger: Written at the end of every successful maze generation.
• Content: Same format as a manual session save (all properties + cell data).
• Threading: Written on a background thread using atomic file replacement to avoid corruption.

Recovery Flow

1. On addon registration, has_autosave() checks for the existence of firemaze_autosave.json in the temp directory.
2. If found, a warning box appears in the Session & Image Management panel with two buttons:
   • Restore Session — Loads the autosave file, deserializes all properties and cell data, rebuilds the maze, and writes an acknowledgement file.
   • Discard — Deletes the autosave file and acknowledgement file from disk.
3. An acknowledgement sidecar file (firemaze_autosave_ack.json) is written on successful restore to prevent the recovery prompt from reappearing on subsequent Blender restarts.

Acknowledgement File

• Location: {tempdir}/firemaze_autosave_ack.json
• Purpose: Persists the fact that the user has acknowledged/restored the autosave. On addon startup, if this file exists, the recovery warning is suppressed.

5. Image Export

Export the maze layout as a black-and-white image showing walls as black and walkable cells as white.

Create Blender Image

Operator: MAZE_OT_save_as_image — fire_maze.save_as_image

Generates an in-memory Blender Image datablock named FireMaze_Layout. Useful as a reference minimap or for external editing in the Image Editor.

• Cube Mode: 1 pixel per cell (width × depth resolution).
• Thin Mode: 3× upscaled (width × 3 by depth × 3 resolution) to render individual wall segments at pixel resolution.
• Only available for Rectangular grids. Returns an error for Polar grids.

Save PNG to Disk

Operator: MAZE_OT_save_image_file — fire_maze.save_image_file (ExportHelper, .png extension)

Same rendering logic as Create Blender Image, but saves directly to a PNG file on disk via a file dialog. A temporary Image datablock is created, saved, and immediately removed from the database.

6. Clear Maze

Operator: MAZE_OT_clear — fire_maze.clear

Completely removes all maze-generated content from the scene:

1. Object removal — Scans bpy.data.objects for any object with a fire_maze custom property tag, removes each object, and cleans up orphaned mesh and curve datablocks (those with zero users whose name starts with FireMaze).
2. Collection removal — Iterates bpy.data.collections and removes any collection that carries a fire_maze_data custom property. Handles parent-child unlinking to avoid RuntimeErrors.
3. State reset — Clears fire_maze_collection_name on the scene properties.
4. Memory sweep — Orphaned datablocks (meshes, curves) that were left with zero users are purged from the database to prevent memory leaks.

7. Session & Image Management Panel

UI Location: VIEW3D_PT_fire_maze_session — Session & Image Management

The panel is divided into two sections:

Session Management Box

• Save Session... / Load Session... — Side-by-side buttons for manual session file operations.
• Conditional Crash Recovery — Only visible when a leftover autosave file exists:
  • Warning alert box with info icon.
  • Restore Session button — Triggers fire_maze.restore_autosave.
  • Discard button — Triggers fire_maze.discard_autosave.

Masking & Image Export Box

• Load Mask from Disk... — Opens file browser for PNG, JPG, BMP, or TGA images. Assigns the loaded image to the mask property.
• Selected Mask — Dropdown to pick an existing Blender Image datablock.
• Invert Mask Colors — Toggle.
• (Masking controls are hidden when grid type is Polar, with a label explaining the restriction.)
• Save PNG to Disk... — Exports layout to .png.
• Create Blender Image — Creates FireMaze_Layout datablock.

8. Best Practices

Custom Assets Across Machines

Pointer references (meshes, collections, images) are stored by name only. To reliably share sessions:

• Use consistent datablock naming across .blend files.
• Consider appending or linking common asset libraries before loading a session.
• External image files for masking should be available at the same relative paths or re-assigned after loading.

Scene Cleanup

• Use Clear Maze before generating a new maze in the same scene to prevent collection name collisions.
• The fire_maze object tag and fire_maze_data collection property are the authoritative markers. Manually renaming maze collections or objects may cause the addon to lose track of them.

Autosave

• The autosave file is stored in the system temp directory — it may be cleared by temporary file cleanup utilities or disk space management. Save important work as a named .json session file.
• Only the most recent generation is autosaved. Each generation overwrites the previous autosave.