> For the complete documentation index, see [llms.txt](https://quark-engine.gitbook.io/quark-engine-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quark-engine.gitbook.io/quark-engine-docs/plugins/lifecycle.md).

# Plugin Lifecycle

This page explains when each plugin callback is called and what each callback should be used for.

## Load Order

```
Load library
→ call get_plugin()
→ call on_load()
→ call on_update() every frame
→ call on_draw_ui() every UI frame
→ call on_unload()
→ unload library
```

If `get_plugin()` returns `nullptr`, or if required fields in `Plugin` are missing, the engine should treat the load as failed.

## on\_load

`on_load(PluginContext* ctx)` is called once after the library is loaded. Use it for initialization, resource setup, and registering callbacks.

```cpp
static void on_load(PluginContext* ctx) {
    ctx->register_ui_callback(UI_INSPECTOR, my_ui);
}
```

## on\_update

`on_update(PluginContext* ctx)` is called every simulation frame. Use it for time-based logic, animation, and non-UI plugin behavior.

```cpp
static void on_update(PluginContext* ctx) {
    float dt = ctx->delta_time;
    (void)dt;
}
```

## on\_draw\_ui

`on_draw_ui(PluginContext* ctx)` is called every UI pass. Use the `ui_*` functions on `ctx` to draw controls.

```cpp
static void on_draw_ui(PluginContext* ctx) {
    if (ctx->ui_begin("My Plugin")) {
        ctx->ui_text("Hello from plugin");
        ctx->ui_end();
    }
}
```

## on\_unload

`on_unload()` is called once before the library is unloaded. Free heap allocations and release external resources here.

```cpp
static void on_unload() {
    // cleanup
}
```

## Rules

* Keep callbacks fast.
* Do not block the main thread.
* Do not keep `PluginContext*` after the call ends.
* Make sure every `ui_begin()` has a matching `ui_end()`.

## Related Docs

* [Plugins](https://github.com/Quark-Engine/quark-engine.github.io/blob/main/docs/api/api/plugins.md)
* [UI System](https://github.com/Quark-Engine/quark-engine.github.io/blob/main/docs/api/api/ui.md)
* [Scene Management](https://github.com/Quark-Engine/quark-engine.github.io/blob/main/docs/api/api/scene.md)
* [Entities](https://github.com/Quark-Engine/quark-engine.github.io/blob/main/docs/api/api/entities.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quark-engine.gitbook.io/quark-engine-docs/plugins/lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.