Skip to content

Getting Started

What you'll have at the end: the project open in the S&box editor, tests running, and enough orientation to know where to read next for whatever you're about to do.

Project status. Code/, Assets/, and UnitTests/ are populated through Milestone 10. OfflineTests/ compiles the same source as an ordinary .NET class library and runs the real UnitTests/ suite with dotnet test — so the code compiles and its logic is genuinely tested — but no S&box editor has ever opened this project, and no real client has ever connected. Steps 2 and 5 below (opening the .sbproj, running a live server) are still written against the design, not confirmed. See ROADMAP.md § Verification debt. If a step doesn't match what happens on your machine, you are very likely the first person to find out, and the roadmap's current milestone is the source of truth, not this page. Please raise it.

1. Prerequisites

  • S&box, installed and signed in — see sbox.game for setup. This project targets S&box as of July 2026; see Architecture/00_OVERVIEW.md §4 if you're on a materially different build.
  • A .NET-capable editor — Visual Studio, Rider, or VS Code with the C# extension. S&box projects are ordinary C#; nothing here needs a special toolchain beyond the editor's own.
  • Git.

2. Clone and open

git clone <repository-url> "AppleJackRP's&box"

Open the folder's .sbproj from the S&box editor's project browser (Menu → Projects → Add Existing). The editor compiles Code/ automatically and hot-reloads on save — this is why the framework never wraps engine reload behaviour itself (00_CONSTITUTION.md).

3. Orient yourself

Read in this order:

  1. 00_CONSTITUTION.md — the five-minute version of every rule that governs this codebase.
  2. 01_VISION.md — what "feels like Applejack" means, if you'll be making gameplay judgement calls.
  3. Architecture/00_OVERVIEW.md — the layer diagram.
  4. Architecture/01_PROJECT_LAYOUT.md — where a new file goes, with a worked "where does X go" table.

If you're about to touch a specific module, its Code/<Module>/README.md is the fastest route to "what does this own and what doesn't it" — see Standards/02_DOCUMENTATION_STANDARDS.md §2.

4. Run the tests

Adding UnitTests/ at the project root and restarting the editor once causes S&box to generate an MSTest project automatically (Standards/03_TESTING_STANDARDS.md §2). From then on:

dotnet test

or use your editor's Test Explorer. These tests run with no scene, no host, no player — if a test needs the game running, it's testing the wrong layer; see Standards/03_TESTING_STANDARDS.md §1.

No S&box editor available? OfflineTests/ compiles the same Code//UnitTests/ sources into an ordinary class library — cd OfflineTests && dotnet test runs the real suite with no engine, GPU, or S&box install at all. See that project's own header comment. It's a stand-in for the editor-generated project, not a replacement — delete it once you've verified the real one on a machine with the editor.

5. Run the server

Launch through the S&box editor's play controls, or via the S&box dedicated-server tooling for a headless instance. Both host mode and dedicated servers are supported identically by the framework's authority model — see Architecture/07_NETWORKING.md §8.

6. Configuring your server

Tuning values (prices, cooldowns, need decay rates, ...) live in GameResource configuration assets, not code — see Architecture/05_CONFIGURATION.md. To change a value:

  1. Create your own configuration asset of the relevant type in your addon's Assets/ folder (for example, a .needsconfig to override hunger tuning).
  2. Set the properties you want to change in the S&box inspector.
  3. Restart the server. Configuration is read once at boot, deliberately — see Architecture/05_CONFIGURATION.md §3 for why it isn't hot-swapped mid-session.

No value in this project requires editing source to change. If you find one that does, that's a bug against 01_VISION.md §4, test 5.

7. Configuring persistence

Applejack saves through one of two backends, chosen with a PersistenceConfiguration asset — see Architecture/06_PERSISTENCE.md and ADR-0003.

Single-server, zero infrastructure (the default). Do nothing — Backend defaults to Json, storing everything locally under the game's data directory via FileSystem.Data. Fine for one server, and the saves are plain JSON files you can open and hand-repair.

Multi-server, shared character data. Create your own .persistenceconfig asset, set Backend to Http, and set HttpBaseUrl to your persistence service's base URL. That service must implement the REST contract in Architecture/06_PERSISTENCE.md §3 — this project does not ship that server; you deploy or write it yourself. An asset with Backend: Http and no HttpBaseUrl fails to load, naming the asset, rather than silently falling back to local storage.

Both backends share one migration story — see Architecture/06_PERSISTENCE.md §4 — so switching backends later does not mean re-deriving how your save data upgrades.

8. Where to go next

You want to... Read
Add an item, job, or recipe 02_ADDING_AN_ITEM.md — no C# needed
Build a new gameplay module 01_WRITING_A_MODULE.md
Build a third-party extension 03_EXTENDING_THE_FRAMEWORK.md
Run and administer your fork 04_SERVER_ADMIN_GUIDE.md — becoming an admin, /give, choosing content
Understand a design decision ADR/
Understand what the original did Legacy/
Know what's built and what's next ROADMAP.md

9. Verify this worked

You should be able to: open the project in the S&box editor with no errors, run dotnet test and see it discover and run the UnitTests/ project, and start a local server.

Expect this not to work first time. Nobody has done it yet — see ROADMAP.md § Verification debt. Compilation errors here are far more likely to be genuine defects in this repository than problems with your setup, and the first person to get a clean build should say so in handoverdaily.md and update this section.