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

# placeholders

StarGenerator has two placeholder contexts:

* Runtime placeholders used in StarGenerator GUI item names and lore.
* PlaceholderAPI expansion placeholders with the identifier `sg`.

## Recipe Icon Placeholders

Use these in `recipe.icon.name` and `recipe.icon.lore`.

| Placeholder                   | Meaning                                                             |
| ----------------------------- | ------------------------------------------------------------------- |
| `%crafting_time%`             | Adjusted craft time formatted as time text.                         |
| `%crafting_time_seconds%`     | Adjusted craft time as seconds.                                     |
| `%raw_crafting_time%`         | Base recipe time formatted as time text.                            |
| `%raw_crafting_time_seconds%` | Base recipe time as seconds.                                        |
| `%energy_cost%`               | Adjusted recipe energy cost.                                        |
| `%raw_energy_cost%`           | Base recipe energy cost.                                            |
| `%energy_base%`               | Adjusted base energy drain for consume modes that use base drain.   |
| `%total_energy%`              | Adjusted recipe energy plus adjusted base drain over adjusted time. |
| `%current_energy%`            | Current stored energy in the open machine.                          |
| `%max_energy%`                | Maximum stored energy for the open machine.                         |
| `%energy_percent%`            | Current stored energy percentage.                                   |
| `%default_detail%`            | Inserts `recipe-icon.default-detail.lore` from `config.yml`.        |

Most placeholders also support brace form, such as `{crafting_time}`.

## Progress Tooltip Placeholders

Use these in:

* `gui.progress-detail.name`
* `gui.progress-detail.lore`
* `energySetting.energy-progress-detail.name`
* `energySetting.energy-progress-detail.lore`
* `upgrade.progress-detail.name`
* `upgrade.progress-detail.lore`

| Placeholder          | Meaning                                                     |
| -------------------- | ----------------------------------------------------------- |
| `%progress_percent%` | Craft or upgrade progress percentage.                       |
| `%energy_progress%`  | Energy progress percentage selected for the bar.            |
| `%current_energy%`   | Current stored energy.                                      |
| `%max_energy%`       | Maximum stored energy.                                      |
| `%energy_percent%`   | Current stored energy percentage.                           |
| `%crafting_time%`    | Adjusted craft time for the current recipe when available.  |
| `%energy_cost%`      | Adjusted energy cost for the current recipe when available. |

## Default Recipe Detail

Configure shared recipe icon detail in `config.yml`:

```yaml
recipe-icon:
  default-detail:
    enabled: true
    apply-when-lore-empty: true
    lore:
      - "&8Recipe Detail"
      - "&7Crafting Time: &f%crafting_time%"
      - "&7Energy Cost: &f%energy_cost%"
      - "&7Total Energy: &f%total_energy%"
```

If `apply-when-lore-empty` is enabled, recipes with empty `icon.lore` automatically use this detail. If you want full control over placement, put `%default_detail%` inside the recipe icon lore.

## PlaceholderAPI Expansion

When PlaceholderAPI is installed, StarGenerator registers the identifier:

```
sg
```

The built-in expansion currently exposes output chance placeholders:

```
%sg_percent_<recipe-id>_<output-id>%
%sg_percent_<recipe-id>_<output-id>:<decimal-places>%
```

For example:

```
%sg_percent_Starter_IceCream:vanilla_scoop.yml_item_1:2%
```

For `INDEPENDENT` reward recipes, the chance is `chance * 100`. For exclusive reward pools, the chance is calculated from the output weight divided by total pool capacity.


---

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