SurvivorCore/docs/getting-started.md

Getting Started

SurvivorCore is the mechanics of a survival game — stats, inventory, crafting, harvesting, mobs, and more — without dictating your content. There are two ways to bring it into your place: as source (via Rojo + Wally, the recommended path for active development) or as a drop-in model (SurvivorCore.rbxm, the fastest way to try it).

Status: early scaffold (v0.1.0). APIs will change. See the README for what's implemented today.

Option A — Rojo + Wally (recommended)

Best if you're actively developing and want source, types, and live sync into Studio.

1. Install the toolchain

SurvivorCore pins its tools with Rokit. In your game's repo, add SurvivorCore's tools to your rokit.toml (or copy the pins) and run:

rokit install

This gets you rojo (7.6.1) and wally, among others. In Studio, install the Rojo plugin version 7.6.1 to match.

2. Add SurvivorCore as a Wally dependency

Wally publishing is planned for a later release. Until then, use the Git submodule / source approach below, or the drop-in model.

Once published, add it to your game's wally.toml:

[dependencies]
SurvivorCore = "temujincalidius/survivorcore@0.1.0"

Then:

wally install

…and map the Packages folder into ReplicatedStorage in your *.project.json.

3. …or vendor the source

Clone or submodule this repo and point your Rojo project at it:

// your.project.json
{
  "tree": {
    "ReplicatedStorage": {
      "SurvivorCore": { "$path": "path/to/SurvivorCore/src" }
    }
  }
}

4. Boot it from a server script

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local SurvivorCore = require(ReplicatedStorage:WaitForChild("SurvivorCore"))

-- Register your content (see "Extending SurvivorCore")…
SurvivorCore.Items.register({ id = "reed", name = "Reed", stack = 20 })

-- …then start the engine. Call once, from the server, after registering.
SurvivorCore.start()

Option B — Drop-in model (SurvivorCore.rbxm)

Best for a quick look with no toolchain.

1. Download SurvivorCore.rbxm from the latest Release (it's built from source by CI on every version tag).

2. In Studio, right-click ReplicatedStorage → Insert from File… → pick the .rbxm. You'll get a SurvivorCore ModuleScript.

3. Add a Script in ServerScriptService:

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   local SurvivorCore = require(ReplicatedStorage:WaitForChild("SurvivorCore"))
   
   SurvivorCore.Items.register({ id = "reed", name = "Reed", stack = 20 })
   SurvivorCore.start()
   

4. Press Play.

Try the demo

This repo ships a runnable demo that exercises both extension layers:

rojo serve demo.project.json

Connect the Rojo plugin, press Play, then add a Part to the Workspace, tag it Gatherable (CollectionService), and set the attributes ItemId="reed", Yield=2, HP=3. Interact with the prompt to see the component + hook flow. The boot script is demo/server/Boot.server.luau.

Next steps

• Survival Stats + HUD — the built-in stat simulation and HUD, and how to tune it with no code.
• Survival Stats admin plugin — a Studio form for tuning the stats. It's editor tooling, so it installs separately from the engine sync (build it once into your Studio plugins folder) — see its Install section.
• Extending SurvivorCore — the register() API, the component/attribute model, and Hooks.
• Architecture — how the layers fit together.