> For the complete documentation index, see [llms.txt](https://star-generator.gitbook.io/star-generator-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://star-generator.gitbook.io/star-generator-docs/features/runtime-cache-recovery.md).

# runtime cache recovery

StarGenerator stores placed table runtime state under:

```
plugins/StarGenerator/cache/
```

This cache is separate from table YAML templates. Table YAML defines what a machine type is. Runtime cache stores placed machines, their locations, energy, pending outputs, active queues, and recovery metadata.

## Cache Files

Typical files include:

| File                 | Purpose                                             |
| -------------------- | --------------------------------------------------- |
| `models.yml`         | Placed table state.                                 |
| `everyTime.yml`      | Tables in recurring energy queues.                  |
| `fully.yml`          | Tables in `FULLY` refill queues.                    |
| `craftOrder.yml`     | Active craft orders.                                |
| `upgradeOrder.yml`   | Active upgrade orders.                              |
| `cache-state.yml`    | Last known complete entry counts.                   |
| `deleted-tables.yml` | Tombstones for intentionally broken tables.         |
| `backups/`           | Timestamped cache backups.                          |
| `bad/`               | Suspicious cache files copied aside for inspection. |

## Save Strategy

When runtime cache is saved, StarGenerator writes through a temp file, keeps a `.bak`, and also writes timestamped backups. The number of timestamped backups is controlled by:

```yaml
runtime-cache:
  backup-retention: 20
```

## Suspicious Cache Guard

If the primary cache restores far fewer tables than the last complete save, StarGenerator treats it as suspicious and tries older backups first.

```yaml
runtime-cache:
  suspicious-drop-ratio: 0.10
```

If a cache file is suspicious, StarGenerator copies it into:

```
plugins/StarGenerator/cache/bad/
```

## Deleted Table Tombstones

When a player intentionally breaks a table, StarGenerator records a tombstone in:

```
plugins/StarGenerator/cache/deleted-tables.yml
```

This prevents old backups from reviving a table that was intentionally removed.

```yaml
runtime-cache:
  deleted-table-tombstones: true
```

## Deleted Table Templates

If a table template YAML was removed from a pack, StarGenerator can purge runtime cache entries and backup entries that still reference that deleted template:

```yaml
runtime-cache:
  purge-deleted-table-templates: true
```

This prevents removed pack content from coming back through cache recovery.

## Read-Only Protection

If StarGenerator cannot safely load runtime cache, it can temporarily avoid writing runtime cache back to disk. This protects existing backups from being overwritten by a bad or incomplete state.

Check the console for warnings before manually deleting cache files.


---

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

```
GET https://star-generator.gitbook.io/star-generator-docs/features/runtime-cache-recovery.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.