SurvivorCore/docs/admin-plugin.md

# SurvivorCore Studio (the admin plugin)

A **Studio plugin** that gives the experience owner friendly forms instead of hand-editing
Attributes in the Explorer. One **SurvivorCore › Studio** toolbar button opens one **floating
window** (drag-dock it anywhere) with a sidebar of editors:

- **Overview** — is the engine synced, what content exists (click through), how the model works.
- **Survival Stats** — tune the survival-stat rates/thresholds/HUD on the `SurvivalStatsConfig`
  instance (the deltas-only, locked model below), with an Edit-mode **HUD preview**.
- **Engine Config** — every engine Config section (issue #21): Movement (speeds, energy, audio,
  feedback **asset ids**), Combat + Bow, Mobs & AI, Harvesting, Crafting, Inventory, Consequences,
  Loot bags, Quests, Achievements, and **UI & theme** (keybinds, chat placement, layout — and the
  full **Theme**: colors edited as `R, G, B` with a live swatch, fonts by name). Same deltas-only
  model, persisted on **`SurvivorCoreEngineConfig`**; edits apply on the **next Play**.
- **Content** — create/edit/delete **items**, **weapons**, **arrows**, **gatherable resources**,
  **mobs**, **quests** and **achievements** with no code, one page per category with entry counts —
  plus **Overrides** that tune defs registered *from code* (issue #40, below). Gatherables/mobs get
  **+ Add to World**, weapons **+ Tool model**, quests **+ Quest giver**. See
  [content-authoring.md](content-authoring.md).

The **search box** at the top of the sidebar finds any content entry by id or name across every
category and shows fully **editable** results in place. The window remembers your last-open page.
Every edit is one Studio **undo** step (and undo/redo refreshes the forms).

This is the [Builder / Admin plugin](https://github.com/TemujinCalidius/SurvivorCore/issues/11).

> **Upgrading from the tabbed panel?** The window identity changed (`SurvivorCore Studio`), so
> Studio forgets the old panel's dock position **once** — the new window opens floating; dock it
> wherever you like and Studio remembers from then on.

> 📹 **Demos:** [HUD, survival stats & the admin plugin](https://makertube.net/w/xqX7wfRpTqd9L9BkozCS1P) · [no-code item & gatherable creation](https://makertube.net/w/mCneurjoY3Av6yi48VsGQE) · [no-code weapon, ammo & mob creation](https://makertube.net/w/tyn8JEMG3CaMbTXid8osdU) · [no-code quest & achievement creation](https://makertube.net/w/uSGJ2MHEFjSSKxMiJBJ6Y5) · [SurvivorCore Studio — the no-code admin window](https://makertube.net/w/g4oySJeXD4Th7f1zYEu9Bz)

## Install

> **This is a Studio editor tool, not game content — so syncing the engine does _not_ install it.**
> A Rojo sync (or the drop-in `SurvivorCore.rbxm`) populates a *place's* `ReplicatedStorage`. The
> plugin is different: it lives in Studio's **local plugins folder** and runs in the editor across
> every place you open. You install it **once**, separately from any place.

Build it straight into your local plugins folder:

```bash
rojo build plugin.project.json --plugin SurvivorCoreStatAdmin.rbxm
```

The `--plugin` flag writes the built model into Studio's plugins folder for you:

| OS | Plugins folder |
|---|---|
| macOS | `~/Documents/Roblox/Plugins/` |
| Windows | `%LOCALAPPDATA%\Roblox\Plugins\` |

(Prefer to place it by hand? Build to a file instead — `rojo build plugin.project.json -o
SurvivorCoreStatAdmin.rbxm` — and drop it into that folder, or open it from Studio → **Plugins** tab
→ **Plugins Folder**.)

Then **restart Studio** — a brand-new plugin's toolbar only registers when Studio loads it. (After
this first install, re-running the `--plugin` build hot-reloads the plugin live, no restart needed.)
A **SurvivorCore › Studio** button then appears on the **Plugins** ribbon tab; click it to toggle
the window.

> **Open a place that has the engine in it.** The plugin edits whatever place is open, reading the
> stat roster and the Engine Config schema live from `ReplicatedStorage.SurvivorCore` — so sync the
> engine (or drop in `SurvivorCore.rbxm`) first. With no engine present it opens to an
> instructional empty state and writes nothing. Note that restarting Studio drops an *unsaved*
> Rojo-synced place, so reconnect Rojo and re-sync (or save the place before restarting) to bring
> the engine back.

## Survival Stats

Each stat shows the seven tunable fields, each displaying its **effective** value (your override if
you've set one, otherwise the live engine default):

- **Rate / second** — how fast the stat drifts (the headline knob).
- **Max**, **Start**, **Warn at %** — range, spawn value, warning threshold.
- **Display** — whether it shows on the HUD.
- **Icon** — the HUD icon asset id.
- **Value format** — `fraction` (`99/100`) · `percent` · `value` · `none`.

Edit a field (type a number / click to toggle or cycle) and it's applied immediately — stats apply
**live**, no restart. The dot at the left of a row is **filled + blue when that field is
overridden**, hollow when it's following the engine default. Click the dot to **reset** the field.

The plugin can tune **only** the seven owner-facing fields above. It deliberately **cannot** touch
`Invert` or `DangerHigh` — those are engine-owned stat *semantics*; a guardrail makes them
impossible to write.

### Preview the HUD in Edit mode

Roblox doesn't run the HUD's client binder in Studio's **Edit** view, so an authored `SurvivalHud`
normally shows its static template there. The footer's **Preview HUD** button paints, in Edit, what
the running game *would* render: each bar's resolved icon (including your overrides), a sample
partial fill, and a sample value readout — so you can tune and **see the result without pressing
Play**. **Clear** restores the HUD; both are a single **undo** step.

## Engine Config

Every page under **Engine Config** edits one engine Config section with the exact same row model as
the stats editor (override dot, engine-default placeholder, blue = overridden). Differences worth
knowing:

- **Persisted on `SurvivorCoreEngineConfig`** (a Configuration in ReplicatedStorage, one child per
  section, one grandchild per group) — created on your first real override, deltas-only, never
  seeded, never overwritten by the engine.
- **Applies on the next Play / server start.** The engine layers the instance over its defaults as
  the very first step of `start()`/`startClient()` — before any system boots — so live-reading and
  boot-caching systems all agree. (Survival Stats stay live-applied; everything else is
  boot-applied. The footer reminds you.)
- **Theme colors** are edited as `R, G, B` (0–255) with a live **swatch**; **fonts** by
  `Enum.Font` name (the ↻ button cycles common ones; any valid name can be typed). Invalid values
  are rejected in the form, and a hand-authored bad attribute is **warned about and skipped at
  boot** — never fatal.
- **Reset section** (footer) removes every override on that page in one undo step.
- The two Inventory **lists** (equip slots, auto-hotbar categories) are code-managed — set them
  via `Config.override("Inventory", …)`.
- **After re-syncing an UPDATED engine** (one whose config fields/defaults changed), restart
  Studio — Studio caches required modules per session, so the plugin keeps seeing the old schema
  until it reloads.

Resolution order everywhere: **engine default → `Config.override(...)` in your game code → the
instance (highest)**. Fields you never touched keep following engine defaults across updates —
that's the locked model.

## Content: authored entries & overrides

Each category page lists the **merged roster**:

- **Authored entries** — full defs this plugin created under `SurvivorCoreContent/<Category>`;
  every field editable, **Delete** removes the def.
- **Override entries** (blue *override* pill) — **deltas over a def registered from code** (e.g. a
  starter kit's `SurvivorCore.Items.register{...}`). Code-registered defs can't be listed here in
  Edit mode (registries fill at runtime), so: type the id, click **+ Override**, and set **only the
  fields you want to change** — **blank = inherit** the code value (booleans cycle
  `(inherit) → true → false`). **Remove** deletes the override and the pristine code def returns on
  the next Play. A typo'd id can only be caught at runtime: the engine **warns in Output on Play**
  (`override 'x' matches no registered def`).

Overrides live under `SurvivorCoreContent/Overrides/<Category>` and are field-merged onto the
registered defs at `start()` — before anything caches or replicates, so tooltips, recipes and
gatherables all see the merged values. One caveat: on a **code-registered quest** with nested
objective/reward tables, the flat `objective*`/`reward*` override fields are ignored (name/
description/autoStart/requires/turnIn still merge); overrides of no-code quests merge fully.

## Why your tuning is "locked" — it survives re-syncs and engine updates

The engine resolves configuration as **engine default → `Config.override` → your instance
(highest priority)**, and it never overwrites your instances. The plugin builds on that with the
**deltas-only** rule:

- It **writes an attribute only when you change a field from the engine default.**
- **Resetting** a field (or typing the default back in) **removes** the attribute, so the field
  goes back to following the engine default.

So two good things hold across a SurvivorCore update:

1. **Your explicit overrides are never lost** — they live on your instances, which the engine never
   overwrites.
2. **Fields you didn't touch keep following engine defaults** — so a future release that improves a
   default reaches your game, instead of being frozen at today's value.

> **Caveat — the engine's own demo.** In this repo's demo, config instances are *Rojo-mounted*, so
> a `rojo serve` re-sync reverts plugin edits there. That's a demo artifact: a **real** game keeps
> its instances in the place file, so plugin edits persist across engine updates — which is the
> whole point.

---

See also: [Survival Stats + HUD](survival-stats.md) · [Content authoring](content-authoring.md) ·
[Design Language](design-language.md).