OpenParable
Skip to content
← Back to skills

Filament Lifetime

Development
filament-lifetime

Filament 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. 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 EntityManager directly from the Engine instance: utils::EntityManager& em = engine->getEntityManager();
  • Alternative (Avoid if engine is available): Only use the global singleton if the Engine pointer 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::Builder or LightManager::Builder on 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);
  • Destroy (CRITICAL):
    1. 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);
      
    2. 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);

2. Engine-Managed Native Objects

Native GPU objects are created using the Engine factory or nested Builder patterns.

  • NO delete: Never call standard C++ delete on pointers returned by Engine.
  • Direct Factories: Instantiated directly from the Engine instance.
    • Objects: View, Scene, Renderer, SwapChain.
    • Pattern:
      View* view = engine->createView();
      // ...
      engine->destroy(view);
      
  • Builder Pattern: Instantiated using a nested Builder class, passing the engine instance to build(*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);