b3dFreeEntity

Destroys an entity and all its children, freeing associated resources. Takes entity (handle to any 3D entity type). Returns nothing. Validates entity exists in g_entities map - silently returns if not found. Recursively frees all children first (processes children.back() repeatedly until children empty). Removes entity from parent's children list if parented. Frees type-specific data based on entity.type: ENTITY_MESH (mesh shared/cached, not deleted), ENTITY_CAMERA (deletes camera struct), ENTITY_LIGHT (deletes light struct), ENTITY_BILLBOARD (deletes billboard struct), ENTITY_TERRAIN (calls FreeTerrain3D for heightmap/splatmap/GPU resources), ENTITY_PIVOT (no data to free). Erases entity from g_entities map. Does not free mesh data (shared via caching - use b3dCopyMesh for unique copies if needed). Silently ignores invalid handles (safe to call multiple times).

This function performs hierarchical cleanup with automatic child destruction. Recursive child freeing prevents orphaned entities - parent deletion cascades to entire subtree. Use before application exit or when removing scene elements. Common workflows: (1) Level cleanup (For Each entity In levelEntities: b3dFreeEntity(entity)), (2) Dynamic object removal (bullet hits target: b3dFreeEntity(targetEntity)), (3) Memory management (delete old LOD models when camera moves). Mesh caching caveat: loaded meshes (b3dLoadMesh with unique=0) share GPU buffers - freeing entity doesn't free mesh, only entity instance. For truly unique meshes, use b3dCopyMesh first. Terrain resources freed properly (heightmap vertex buffer, texture splatmaps, GPU resources). No dangling pointers - all references removed from scene graph. Safe to free during iteration if careful (iterate backwards or collect handles first). No undo - entity data unrecoverable after free. Active camera deletion: if entity is g_activeCamera, consider setting different camera active first to avoid rendering errors. Physics bodies detached automatically (implementation should unregister from Jolt Physics). Performance: O(N) where N = total descendants. Massive hierarchies (thousands of children) may cause stack overflow - use iterative freeing for very deep trees.