mirror of
https://github.com/TemujinCalidius/SurvivorCore.git
synced 2026-08-14 00:58:01 +00:00
Samuel LisonandClaude Opus 4.8
4256edfd87
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>
65 lines
3.6 KiB
Markdown
65 lines
3.6 KiB
Markdown
# 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.
|
|
|
|
## Related docs
|
|
|
|
- [Getting Started](getting-started.md) — install via Rojo + Wally or the drop-in `.rbxm`.
|
|
- [Extending SurvivorCore](extending.md) — the `register()` API, the component/attribute
|
|
model, and Hooks.
|
|
- [Survival Stats + HUD](survival-stats.md) — the stat simulation, no-code tuning, and the
|
|
designer-editable HUD.
|
|
- [Admin plugin](admin-plugin.md) — the Studio dock for tuning stats, and the deltas-only "locked"
|
|
model that keeps owner edits intact across engine updates.
|
|
- [Design Language](design-language.md) — the look the project holds to (UI, palette, icons).
|
|
- [CONTRIBUTING](../CONTRIBUTING.md) — local dev setup, code style, and the branching model.
|