Live Spreadsheet Sync: Connect Your Balance Data to Documents

Turn spreadsheets into live data sources for your design docs

Read Time: 12 minutes

§The Problem You Know Too Well#

You have a characters.csv with health values. You mention health in your design doc: "The Warrior has 150 health." Then someone changes the spreadsheet. Now your design doc is wrong, but nobody knows until a confused artist asks "wait, is it 150 or 175?"

This happens constantly:

• —Balance spreadsheets update, but docs don't
• —Copy-paste errors creep in
• —Nobody trusts the numbers in design docs
• —"Check the spreadsheet" becomes a reflex

Gameframe's Spreadsheet Sync fixes this permanently.

§What Is Spreadsheet Sync?#

Instead of copying values from spreadsheets into documents, you reference them. The syntax is simple:

The Warrior has @data:characters/Warrior/health health points.

This displays as: "The Warrior has 150 health points."

But here's the magic: when you update characters.csv and the Warrior's health becomes 175, your document automatically shows 175. No copy-paste. No remembering to update docs. No stale data.

§Part 1: Registering a Data Source#

Step 1: Upload Your Spreadsheet#

First, upload a CSV or Excel file to your vault like any other document:

1. 1.Go to Documents
2. 2.Click Upload or drag-and-drop
3. 3.Upload your characters.csv (or .xlsx)

Step 2: Register It as a Data Source#

Now make it available for references:

1. 1.Open the Data Sources panel (in the sidebar or document settings)
2. 2.Click Add Source
3. 3.Select your uploaded file
4. 4.Give it a short name (e.g., "characters")
5. 5.Set the Primary Column (usually "name" or "id")
6. 6.Click Register

Primary Column explained: This is how you'll identify rows. If your CSV has:

Set "name" as primary. Then you can reference @data:characters/Warrior/health instead of @data:characters/0/health.

Step 3: Wait for Parsing#

Gameframe parses your file immediately (or in the background for files over 5MB). You'll see:

• —✅ Ready - Good to go
• —⏳ Parsing - Processing large file
• —❌ Failed - Check file format

Once ready, you can start using references!

§Part 2: Using @data: References#

Basic Syntax#

@data:sourceName/rowId/column

Examples with a "characters" data source:

In Context#

Write naturally in your design documents:

## Warrior Class

The Warrior is a tank class with @data:characters/Warrior/health health 
and @data:characters/Warrior/armor armor. Their base damage is 
@data:characters/Warrior/damage per hit.

Compared to the Mage's @data:characters/Mage/health health, the Warrior 
can survive approximately twice as long under sustained fire.

This renders with real values that update when your spreadsheet changes.

Multiple Data Sources#

You can register multiple spreadsheets. Common setup:

Then reference across all of them:

The Fire Staff (@data:items/fire_staff/name) deals @data:items/fire_staff/damage 
damage and costs @data:economy/gold/fire_staff_price gold.

§Part 3: Stat Blocks#

For displaying all stats at once, use stat blocks:

[statblock:characters/Warrior]

This renders as a formatted card showing ALL columns for that row:

The stat block includes:

• —Character/entity name as header
• —All numeric values in a grid
• —Text values listed below
• —Boolean values as tags
• —Refresh button to update live
• —Collapse/expand for compact view

When to use stat blocks:

• —Character sheets in design docs
• —Item descriptions
• —Ability breakdowns
• —Quick reference cards

§Part 4: Updating Data#

The Workflow#

1. 1.Someone updates characters.csv (Warrior health → 175)
2. 2.Re-upload the file to your vault (or save if editing in Gameframe)
3. 3.Go to Data Sources → click Refresh on "characters"
4. 4.All documents now show the new value

What Updates Automatically#

When you refresh a data source:

• —All inline @data: references update
• —All stat blocks refresh
• —The version history shows the data changed
• —No need to touch individual documents

What Happens If Data Is Missing#

If you reference a row or column that doesn't exist:

Errors are highlighted so you can spot and fix them. The original reference text is preserved—no silent failures.

§Part 5: Real-World Examples#

Example 1: Character Design Doc#

# Warrior Class Design

## Overview
The Warrior is the game's primary tank class, designed to absorb damage 
and protect allies.

## Base Statistics
[statblock:characters/Warrior]

## Balance Rationale
With @data:characters/Warrior/health health, the Warrior can survive 
approximately @data:calculations/warrior_survival_time seconds under 
focus fire from standard enemies (dealing @data:enemies/grunt/damage DPS).

This gives the team @data:calculations/warrior_survival_time seconds 
to react and provide support.

## Comparison to Other Tanks
| Class | Health | Armor | Effective HP |
|-------|--------|-------|--------------|
| Warrior | @data:characters/Warrior/health | @data:characters/Warrior/armor | @data:calculations/warrior_ehp |
| Paladin | @data:characters/Paladin/health | @data:characters/Paladin/armor | @data:calculations/paladin_ehp |

Example 2: Economy Breakdown#

# Gold Economy - First 10 Hours

Players earn approximately @data:economy/gold_per_hour/average gold per hour.

## Major Purchases

### Weapons
| Item | Price | Hours to Earn |
|------|-------|---------------|
| Iron Sword | @data:items/iron_sword/price | ~@data:calculations/iron_sword_hours |
| Steel Sword | @data:items/steel_sword/price | ~@data:calculations/steel_sword_hours |

### Armor
| Item | Price | Hours to Earn |
|------|-------|---------------|
| Leather Armor | @data:items/leather_armor/price | ~@data:calculations/leather_hours |
| Chain Mail | @data:items/chain_mail/price | ~@data:calculations/chain_hours |

## Pacing Goal
Players should afford their first major upgrade (Iron Sword at 
@data:items/iron_sword/price gold) after approximately 2 hours of play.

§Part 6: Best Practices#

Naming Conventions#

Good data source names:

• —characters (not "character_stats_v2")
• —items (not "ItemDatabase_FINAL")
• —abilities (not "Abilities_ForGameplay")

Good primary column names:

• —name or id
• —Something unique and readable

Organizing Spreadsheets#

One purpose per spreadsheet:

• —✅ characters.csv - All character stats
• —✅ items.csv - All item data
• —❌ game_data.csv - Everything jammed together

Consistent column naming:

• —✅ health, damage, armor (lowercase, single word)
• —❌ Health Points, Base DMG, Armor Rating (spaces, inconsistent)

When to Use Inline vs. Stat Blocks#

Use inline `@data:` for:

• —Mentioning a single value in text
• —Comparison tables
• —Calculations and rationale

Use `[statblock:]` for:

• —Full entity reference
• —Quick lookup cards
• —"Here's everything about X" sections

§Coming Soon: Google Sheets Integration#

We're working on direct Google Sheets integration:

• —Connect your Google account
• —Link sheets without downloading/uploading
• —Auto-sync at configurable intervals (5 min, 15 min, hourly)
• —Changes in Google Sheets appear in your docs automatically

Stay tuned for this update!

§Summary#

Spreadsheet Sync eliminates the gap between your balance data and your design documents:

1. 1.Upload your CSV/Excel to the vault
2. 2.Register it as a data source with a simple name
3. 3.Reference values with @data:source/row/column
4. 4.Update by refreshing the data source when the spreadsheet changes

No more copy-paste errors. No more "is this current?" questions. No more stale design docs.

Your spreadsheets and documents are now a single source of truth.

Continue learning:

• —CSV to Clarity - Managing game balance data professionally
• —The Gameframe Editor - Master all editor features and slash commands
• —Getting Started - Create your first vault in 10 minutes

Ready to sync your data? Start your free trial and connect your spreadsheets today.