Particles & Map Objects

Particles & Map Objects

The addon imports and exports two types of placement data from .materials.bin files:

• MapParticle placements — VFX particle emitters placed on the map
• GdsMapObject items — static prop placements (shopkeepers, structures, etc.)

Both are imported as Blender empties with transform data, and changes can be exported back.

---

MapParticle Placements

What They Are

MapPlaceableContainer entries in the materials file hold lists of MapParticle items. Each MapParticle defines:

• Position, rotation, scale (via transform matrix)
• VFX system link — which VfxSystemDefinitionData to play
• Container hash — which MPC owns this placement

Import

Automatic (via Project Manager Load Map): When importing a map, particle placements are automatically extracted and created in the scene.

Manual:

1. Utilities → Import Particles from Map
2. Select the materials file
3. Particle empties are created in collections

What Gets Created

Each particle placement becomes a Blender empty:

• Name: Based on VFX definition name or hash
• Transform: Position/rotation/scale from the transform matrix
• Collection: Grouped by MapPlaceableContainer
• Custom Properties:
  • vfx_link — linked VFX definition hash
  • container_hash — owning MPC path hash
  • item_key — stable identity key for round-trip matching

Editing Particles

1. Select a particle empty in the viewport.
2. Move, rotate, or scale it using Blender's standard tools.
3. The addon tracks transform changes for export.

Edit Specific Properties:

• Edit MapParticle — edit placement properties (link, flags)
• Edit VFX Definition — edit the VFX system parameters

Export

Particle changes are written back to materials during export:

• Export Materials (merge mode) updates MPC entries with new transforms
• Save All to .prey writes particles to the .prey.particles category

Only modified particles are flagged for update. Unmodified placements are preserved exactly.

---

VFX System Definitions

VfxSystemDefinitionData entries (type 0x45cd899f) define particle effects used by MapParticle placements. These are the actual effect definitions — particles, trails, beams, etc.

The addon imports these as reference data. They can be viewed and edited through the material editor or prey format.

---

GdsMapObject Items

What They Are

GlobalDataStorage entries contain map object placements — static props like shopkeepers, turret models, nexus structures, etc. Each has:

• Position, rotation, scale
• Object type/class reference
• Stable item key for safe round-trip updates

Import

Automatic (via Project Manager Load Map): GdsMapObject items are imported alongside particles when loading a map.

What Gets Created: Each map object becomes a Blender empty:

• Name: Based on object type or hash
• Transform: From stored transform matrix
• Collection: Grouped by container
• Custom Properties:
  • gds_type — object type hash
  • item_key — stable identity for matching during export
  • container_hash — owning container path hash

Editing Map Objects

1. Select a map object empty.
2. Move/rotate/scale using Blender tools.
3. Do not rename — the item_key custom property is used for matching.

Export

Map object transforms are updated in the materials file during export:

• Matching uses the item_key property (not object name)
• Only changed transforms are written
• New objects or deleted objects are reflected

---

Collections Structure

After import, the scene hierarchy looks like:

Scene Collection/
├── MapGeometry/           ← Imported meshes
├── Particles/
│   ├── MPC_A1B2C3D4/     ← MapPlaceableContainer group
│   │   ├── Particle_001  ← MapParticle empty
│   │   ├── Particle_002
│   │   └── ...
│   └── MPC_E5F6G7H8/
│       └── ...
├── MapObjects/
│   ├── Container_001/
│   │   ├── Object_001    ← GdsMapObject empty
│   │   └── Object_002
│   └── ...
└── BucketGrids/           ← Spatial grids (if imported)

---

Round-Trip Workflow

Full Binary Mode

1. Load Map (imports mapgeo + materials + particles + objects)
2. Edit transforms in Blender
3. Export Materials (merge mode)
   → Particles and objects updated in .materials.bin
4. Export Mapgeo
   → Geometry written to .mapgeo
5. Test in game

Prey Split Mode

1. Load Map
2. Convert to .prey (splits materials into categories)
3. Edit transforms in Blender
4. Save All to .prey
   → Particles written to .prey.particles
   → VFX defs written to .prey.vfx
   → Objects written to .prey.particles (MPC entries)
5. Rebuild .bin from .prey
6. Test in game

---

Code Example

Particle entry structure (from materials.bin)

# MapPlaceableContainer (type 0xb25c0a3f) holds particle placements
mpc_entry = {
    "path_hash": "0xa1b2c3d4",
    "type_hash": "0xb25c0a3f",
    "fields": [{
        "name_hash": "0x...",
        "type": 134,  # map type
        "pairs": [
            {
                "key": {"type": 18, "value": "0x11223344"},
                "value": {
                    "class_hash": "0x24a31b3e",  # MapParticle
                    "fields": [
                        {"name_hash": "0x...", "type": 22, "value": [
                            1.0, 0.0, 0.0, 100.0,  # transform row 1
                            0.0, 1.0, 0.0, 200.0,  # transform row 2
                            0.0, 0.0, 1.0, 50.0     # transform row 3
                        ]},
                        {"name_hash": "0x...", "type": 17, "value": "0xvfx_link"}
                    ]
                }
            }
        ]
    }]
}

Collecting particle empties from scene

from MapgeoAddon import particles_materials

# Find all particle empties
particle_objects = particles_materials.collect_particle_objects()
for obj in particle_objects:
    print(f"{obj.name}: pos={obj.location}, vfx={obj.get('vfx_link', 'N/A')}")