> 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/scene.md).

# Scene Management

The scene API lets plugins save the current scene, spawn new entities from assets, and delete existing ones. All functions are available as function pointers on `PluginContext`.

## The Scene Object

`ctx->scene` is a pointer to the current scene state owned by the host. It is available for the duration of the callback but should not be stored beyond it.

```cpp
Scene* scene;
```

## Functions

### Save

Serializes the current scene to disk using the host's default save path. Equivalent to the user pressing Ctrl-S.

```cpp
ctx->scene_save();
```

```cpp
void (*scene_save)();
```

### Spawn

Instantiates an asset by name and adds it to the scene. Returns the new entity's index on success, or `-1` if the asset name is not found in the host's asset registry.

```cpp
int index = ctx->scene_spawn("crate_01");
if (index >= 0) {
    ctx->entity_set_position(index, 0.0f, 0.0f, 0.0f);
}
```

```cpp
int (*scene_spawn)(const char* asset_name);
```

### Delete

Permanently removes an entity from the scene by index.

```cpp
ctx->scene_delete(index);
```

```cpp
void (*scene_delete)(int index);
```

> **Warning:** After `scene_delete()`, indices for all entities above the deleted index may shift. Treat any cached index as invalid and re-query `entity_count` before accessing entities again.

## Common Patterns

### Spawn and configure in one step

```cpp
int index = ctx->scene_spawn("point_light");
if (index >= 0) {
    ctx->entity_set_position(index, 0.0f, 5.0f, 0.0f);
    ctx->entity_set_name(index, "Key Light");
}
```

### Delete the selected entity

```cpp
if (ctx->selected) {
    int i = *ctx->selected;
    ctx->scene_delete(i);
    // Do not dereference ctx->selected or use i after this point.
}
```

### Auto-save on a condition

```cpp
void on_update(PluginContext* ctx) {
    if (should_autosave()) {
        ctx->scene_save();
    }
}
```

## Related Docs

* [Plugin Overview](https://github.com/Quark-Engine/quark-engine.github.io/blob/main/docs/api/api/plugins.md)
* [Plugin Lifecycle](https://github.com/Quark-Engine/quark-engine.github.io/blob/main/docs/api/api/lifecycle.md)
* [UI System](https://github.com/Quark-Engine/quark-engine.github.io/blob/main/docs/api/api/ui.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/scene.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.