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.
• Build — select a Part or Model in the viewport, answer "what is this object?", and fill a form: it becomes a gatherable node, a mob, or a quest giver. No tags to memorise, no attribute names to type. See Build: world objects below.
• 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.

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.

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 · no-code item & gatherable creation · no-code weapon, ammo & mob creation · no-code quest & achievement creation · SurvivorCore Studio — the no-code admin window · Build — a plain Part into a working iron node

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:

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.

Build: world objects

The Build page is how a creator turns their own geometry into engine content. Select a Part or Model and it asks "What is this object?" — pick Gatherable, Mob (creature) or Quest giver and the plugin applies the tag for you, then renders that component's setup form.

The form is generated from the engine's own component schema (src/components/Schema.luau) — the same source the engine binds from — so the fields, their defaults and their help text can never drift from what actually runs. Any component that declares a schema gets a form here automatically; there is no per-component UI code.

Your first tree, in 60 seconds

1. Author the resource. Content › Gatherables › + Create → id oak_tree, yields item wood, HP 4.
2. Build the mesh. Insert a Part (or your own tree model) and select it.
3. Say what it is. Open Build → click the Gatherable card.
4. Point it at the resource. In the form, click the ⌄ next to Resource until it reads oak_tree — that's it; item, HP, tool and yield all follow the entry.
5. Play. Walk up and hold E. Wood lands in your inventory.

Change your mind later: Change type swaps the component (clearing the old one's settings), and Clear removes the tag and every attribute the engine added.

How it behaves

• Deltas only. Applying a component writes no attributes — the object follows every default until you change something, and a changed field that you set back to its default is removed again. The ○/● dot next to each field tells you which is which.
• Pickers, not memory. Fields that reference authored content (a resource, a mob type, a quest) offer a ⌄ that cycles the ids you've created in Content.
• Eligibility is enforced. Mob needs a Model (Humanoid + PrimaryPart), so it's dimmed with the reason when a plain Part is selected.
• Multi-select applies to every eligible object at once, as one undo step.
• Undo — every apply, clear and field edit is a single Studio undo step.
• Needs SurvivorCore ≥ 0.9. Against an older engine the page explains that instead of failing.

Components a game defines at runtime (in its own code) can't appear here — the plugin reads a static module in Edit mode, where your server scripts haven't run. Tag those by hand as before.

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 · Content authoring · Design Language.