Filament Lifetime
Developmentfilament-lifetimeFilament Lifetime is an Agent Skill for development published in the google/filament repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Enforce correct Filament object creation and destruction lifecycles. Use this skill when initializing rendering pipelines or allocating/deallocating GPU buffers and entities.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/google/filament/blob/HEAD/tools/ai/agents/skills/filament_lifetime/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/filament-lifetime, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Filament object creation and destruction lifecycles
Filament manages its own native allocations. To prevent segmentation faults and memory leaks, follow these rules:
1. ECS Entities & Components
Getting the Entity Manager
- Preferred Method: Retrieve the
EntityManagerdirectly from theEngineinstance:utils::EntityManager& em = engine->getEntityManager(); - Alternative (Avoid if engine is available): Only use the global singleton if the
Enginepointer is inaccessible:utils::EntityManager& em = utils::EntityManager::get();
Entities
- Create: Create Entity IDs using the entity manager:
utils::Entity entity = engine->getEntityManager().create(); - Destroy: Free the Entity ID from the entity manager:
engine->getEntityManager().destroy(entity);
Components
- Create: Attach components to an existing entity using manager builders:
- Renderables/Lights: Use
RenderableManager::BuilderorLightManager::Builderon the entity:RenderableManager::Builder(1) .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vb, ib) .material(0, matInstance) .build(*engine, entity); - Cameras: Attach a Camera component to the entity:
Camera* camera = engine->createCamera(entity);
- Renderables/Lights: Use
- Destroy (CRITICAL):
- To clean up the entire entity:
First, destroy all Filament-managed components on the entity:
engine->destroy(entity);Second, free the Entity ID:engine->getEntityManager().destroy(entity);// Correct Entity Cleanup engine->destroy(myEntity); engine->getEntityManager().destroy(myEntity); - To remove a single component from the entity:
You can destroy specific components individually without deleting the entity:
- Cameras:
engine->destroyCameraComponent(entity); - Transforms:
engine->getTransformManager().destroy(entity); - Renderables:
engine->getRenderableManager().destroy(entity);
- Cameras:
- To clean up the entire entity:
First, destroy all Filament-managed components on the entity:
2. Engine-Managed Native Objects
Native GPU objects are created using the Engine factory or nested Builder patterns.
- NO
delete: Never call standard C++deleteon pointers returned byEngine. - Direct Factories: Instantiated directly from the
Engineinstance.- Objects:
View,Scene,Renderer,SwapChain. - Pattern:
View* view = engine->createView(); // ... engine->destroy(view);
- Objects:
- Builder Pattern: Instantiated using a nested
Builderclass, passing the engine instance tobuild(*engine).- Objects:
VertexBuffer,IndexBuffer,Texture,Material,IndirectLight,Skybox,RenderTarget. - Pattern:
VertexBuffer* vb = VertexBuffer::Builder() .vertexCount(count) .bufferCount(1) .attribute(VertexAttribute::POSITION, 0, VertexBuffer::AttributeType::FLOAT3) .build(*engine); // ... engine->destroy(vb);
- Objects: