Overview
Rust & Roots has three balance workflows, all accessible from the Card Editor (Admin → Card Editor):
CSV Sandbox Safe
Upload a CSV → activate sandbox → play Rumble with modified cards
- Creates a temporary session (2 hours)
- Full Rumble works: shop, combat, AI opponents
- Open the game normally — sandbox auto-activates
- Nothing is saved permanently
Draft Sandbox Safe
Edit cards in the Card Editor → sandbox your pending drafts
- Test changes made via the Card Editor UI
- Includes stat, effect, keyword, and art changes
- Click “Sandbox” in the Pending Changes panel
- Playtest before deciding to publish
CSV Import Live
Upload a CSV → review changes → apply to live game
- Shows diff preview before applying
- Can route through draft system for review
- Auto-generates detailed changelog entries
- Auto-bumps version
Spreadsheet Format
The system accepts CSV files exported from Google Sheets, Excel, or any spreadsheet app. Column names are flexible — case-insensitive with common aliases supported:
| Your Column | Maps To | Required? | Notes |
|---|---|---|---|
| ID / id | id | Yes | Must match a card in the database (e.g., feral_001) |
| Type / type | type | No | unit / spell / token |
| Name / name | name | No | Changing this renames the card |
| Faction / faction | faction | No | e.g., The Pack, Syndicate, Rigs |
| Tier / tier | tier | No | 1–6 |
| Attack / ATK / atk | attack | No | Base attack value |
| Health / HP / hp | health | No | Base health value |
| Cost / cost | cost | No | Scrap cost (spells) |
| Keywords / Keyword(s) | keywords | No | Semicolon-separated: Guard;Plating |
| Current ability / Ability / Ability Text | ability_text | No | Display text only — does not change what the card actually does |
What You Can Change via CSV
CAN change
- Attack / Health / Tier / Cost
- Keywords (add/remove Guard, Plating, etc.)
- Faction assignment
- Card name
- Ability text (display only)
CANNOT change
- Effect triggers (on_death, on_attack, surge)
- Effect actions (damage, buff, summon)
- Effect conditions (if_kills, etc.)
- Target selectors or amounts
- Card art
Effect/ability changes require the Card Editor's effect builder UI. The CSV is designed for stat balance passes — tuning numbers, moving cards between tiers, adjusting keywords.
Sandbox Workflow Safe
Test balance changes without affecting the live game. Creates a temporary copy of the card database with your modifications applied.
Step 1 — Prepare Your Spreadsheet
Export the current cards from the Card Editor (Export button) or start from your own spreadsheet. Edit the stat columns to the new values you want to test. Make sure you have an ID column.
Step 2 — Upload to Sandbox
In the Card Editor toolbar, click the green Sandbox button. Select your CSV file. A diff preview shows exactly what will change — card name, field, old value, new value.
Step 3 — Activate Sandbox & Play
Click Create Sandbox & Play. The server activates sandbox mode for your account. Open the game normally (click the link in the modal, or just go to Play) and start a Rumble — the server automatically uses your sandbox card data for that game. Shop rolls, AI opponents, and combat all use the modified stats.
Step 4 — Deactivate When Done
Click Deactivate Sandbox in the modal, or it expires automatically after 2 hours. Your next game will use normal live data.
Draft Sandbox Workflow Safe
Made changes directly in the Card Editor? Playtest them before publishing. This works with any kind of edit — stats, effects, keywords, faction changes, even art uploads.
Step 1 — Make Edits in the Card Editor
Edit cards normally using the Card Editor UI — change stats, modify effects, adjust keywords, upload art. All changes save as drafts automatically and appear in the Pending Changes panel.
Step 2 — Click Sandbox in the Pending Panel
In the Pending Changes panel (next to Publish All and Discard), click the green Sandbox button. This snapshots the current card database — including all your unpublished draft changes — and activates sandbox mode on your account.
Step 3 — Play & Test
Open the game normally and start a Rumble. The server detects your active sandbox session and uses the modified card data for that game. Shop, AI, and combat all use your draft changes.
Step 4 — Publish or Discard
If the changes feel right, go back to the Card Editor and click Publish All to push them live. If not, click Discard — this reverts all edited cards back to their pre-edit stats, clears the draft queue, and deactivates the sandbox.
You can also revert individual cards using the green Revert button on each card’s action bar (next to Rename and Archive).
CSV Import Workflow Live
Apply balance changes to the live game with full audit trail and changelog.
Step 1 — Upload CSV
In the Card Editor toolbar, click Import. Select your CSV file.
Step 2 — Review Diff
A preview table shows every change that will be applied: card name, which field changed, old value, new value. Cards with no changes are skipped. Unrecognized card IDs are flagged.
Step 3 — Choose How to Apply
- Import as Drafts — Changes queue in the Pending Changes panel. Review them alongside any other edits, then hit Publish All when ready. One version bump, one changelog entry.
- Import & Publish Now — Applies immediately. Bumps the version, creates a detailed changelog entry, reloads the game engine. Web clients auto-refresh within 2 minutes.
What Happens on Publish
- Version bumps automatically (e.g., 0.91 → 0.91.1)
- Changelog entry is created with per-card detail: "Daisy-Cutter Hound: attack 2 → 3, health 1 → 2"
- Game engine reloads with new card data
- Web clients auto-refresh when they detect the new version
- Audit log records who made the change and when
Recommended Balance Pass Flows
Spreadsheet Flow (bulk stat changes)
- Make your balance changes in Google Sheets / Excel
- Export as CSV
- Use Sandbox button in toolbar to playtest — iterate until happy
- When ready, use Import → Import as Drafts
- Review in the Pending Changes panel
- Click Publish All to push live
Card Editor Flow (individual card edits, effects, art)
- Edit cards directly in the Card Editor (stats, effects, keywords, art)
- Changes auto-save as drafts in the Pending Changes panel
- Click Sandbox in the Pending panel to playtest
- Iterate — make more edits, sandbox again
- Click Publish All to push live
Technical Details
How Sandbox Works Under the Hood
- You activate sandbox from the Card Editor (CSV upload or draft sandbox button)
- The server creates a full copy of the card database in memory with your changes merged in
- Your account (discord_id) is mapped to that sandbox session
- When you create a Rumble room, the server detects your active sandbox session and tags the room with the modified card data
- Shop generation, AI shop/scoring, and combat resolution all use the sandbox data for that room
- Other players’ rooms are completely unaffected — the sandbox only applies to rooms you create while it’s active
Safety Guarantees
- Sandbox data lives in server memory only — never written to disk
- Production code paths are untouched when no sandbox is active (rooms without sandbox data fall through to normal behavior)
- The game engine uses a swap-and-restore pattern protected by
try/finally— production card data is always restored even if an error occurs - Node.js single-threaded execution guarantees no concurrent request can see the swapped data
- Discard button reverts all draft changes to pre-edit values and deactivates sandbox
Limitations
- Sandbox is admin-only — requires Card Editor access to activate
- Sessions expire after 2 hours or on server restart
- Effect/ability changes (triggers, actions, conditions) cannot be tested via CSV — only stat changes, keywords, tier, and cost. Use the Card Editor + Draft Sandbox for effect changes.
- The “SANDBOX TESTING MODE” banner on the game screen requires a Godot web export with the latest code