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

- Skill name: `filament-lifetime`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/google/filament/blob/HEAD/tools/ai/agents/skills/filament_lifetime/SKILL.md
- Repository: google/filament (20,258 GitHub stars when collected)

## SKILL.md

# 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:
        ```cpp
        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);`
        ```cpp
        // 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*:
        ```cpp
        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*:
        ```cpp
        VertexBuffer* vb = VertexBuffer::Builder()
            .vertexCount(count)
            .bufferCount(1)
            .attribute(VertexAttribute::POSITION, 0, VertexBuffer::AttributeType::FLOAT3)
            .build(*engine);
        // ...
        engine->destroy(vb);
        ```

---

Source: https://www.openparable.com/skill/development/filament-lifetime (OpenParable). Cite the canonical URL above.
