mirror of https://github.com/TemujinCalidius/SurvivorCore.git synced 2026-08-14 00:58:01 +00:00

Files

T

Samuel LisonandClaude Opus 4.8 4256edfd87 feat(plugin): add Survival Stats admin Studio plugin (deltas-only, locked tuning)

A Studio dock widget that lets the experience owner tune the survival stats
through a validated form instead of hand-editing Attributes on the
SurvivalStatsConfig instance — the first slice of the Builder/Admin plugin (#11).

The point is compatibility: edits are LOCKED against engine updates. StatAdmin
(the pure, headlessly-testable logic layer) writes deltas only — it sets an
attribute solely when the owner changes a field from the live engine default,
and removes it on reset / edit-back-to-default. So unset fields keep following
the (improvable) engine defaults across a SurvivorCore release, while explicit
overrides live on the owner's instance, which the engine only ever seeds and
never overwrites. Nothing tuned is lost; nothing left alone is frozen.

Hard guardrail: the plugin can read/write only the seven owner-tunable fields
(STUDIO_ATTR_MAP). A write() assert makes it impossible to ever set the
engine-owned semantics Invert / DangerHigh — re-freezing the affliction
fill-direction bug is structurally unreachable. Runtime-verified in Studio:
every write path exercised (including rejected Invert/DangerHigh attempts) left
zero banned attributes on the instance.

- plugin/StatAdmin.luau     — logic: roster, effective values, deltas-only writes
- plugin/StatAdminUi.luau   — the dock-widget form (per-field reset, override dots)
- plugin/init.server.luau   — toolbar/widget wiring + ChangeHistory undo steps
- plugin.project.json       — separate Rojo tree; build with --plugin to install
- CI: stylua + a plugin-sourcemap luau-lsp pass + a plugin build
- docs/admin-plugin.md + cross-links; fix stale Invert row in the no-code table

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-19 18:22:57 +10:00

3.6 KiB

Raw Permalink Blame History

SurvivorCore — Architecture

Companion to the boundary map in the TheCounterEarth repo (docs/survivorcore-boundary-map.md), which tracks what is being extracted from the production game into this engine.

The shape

SurvivorCore is an engine of mechanics, not content. It exposes two extension layers over a small foundation.

                ┌─────────────────────────────────────────────┐
   Creators →   │  Component layer   (tag + attributes + UI)   │  "I own the object"
                ├─────────────────────────────────────────────┤
   Developers → │  Registry layer    (register() from code)    │  "I own the data"
                ├─────────────────────────────────────────────┤
                │  Foundation: Config · Assets · EventBridge ·  │
                │              Hooks · Registry                 │
                └─────────────────────────────────────────────┘

Foundation

Config — engine ships default tunables per section; games override via deep merge.
Assets — typed asset-id registry; the engine never hardcodes ids.
EventBridge — semantic event bus (fire/onFire); subscribers decouple from sources.
Hooks — lifecycle extension points (Hooks.on("craft:start", ...)).
Registry — the shared register/validate/index/query lifecycle behind every registry.

Registry layer (developers)

Empty registries the game populates at startup: Items, Recipes (crafting + cooking are one registry routed by station), Stats, Achievements, Codex, Appearance, Mobs.

Component layer (creators)

Behaviors bound to a CollectionService tag, configured by per-instance Attributes. Creators tag their own meshes (Gatherable, and later craftable/huntable/farmable/station components) and fill in values — optionally through a builder UI. No engine-side definition required.

Why hooks instead of baked-in behavior

Game-specific flourish stays out of the engine. TheCounterEarth's trees physically fall and segment into logs — SurvivorCore will not ship that. Instead it fires gather:hit / gather:depleted (and similar) hooks; a creator (including TheCounterEarth itself, going forward) implements the felling physics in their own hook handler. The engine stays small and universal; creativity lives at the edges.

Status & roadmap

v0.1.0 is the foundation scaffold. Extraction order (from the boundary map): foundations → pure-core lift → registries → SPLIT server systems (incl. the mob/combat cluster) → UI layer → harvesting/wildlife sub-engine.

Getting Started — install via Rojo + Wally or the drop-in .rbxm.
Extending SurvivorCore — the register() API, the component/attribute model, and Hooks.
Survival Stats + HUD — the stat simulation, no-code tuning, and the designer-editable HUD.
Admin plugin — the Studio dock for tuning stats, and the deltas-only "locked" model that keeps owner edits intact across engine updates.
Design Language — the look the project holds to (UI, palette, icons).
CONTRIBUTING — local dev setup, code style, and the branching model.

3.6 KiB Raw Permalink Blame History