Setting Up the s&box Library

# Setting Up the s&box Library

The fastest way to integrate Network Storage into your s&box game is with the official library. It handles authentication, API versioning, response parsing, and error logging so you can focus on game logic.

Network Storage is designed as the no-boilerplate alternative for s&box backend storage. Instead of hand-writing HTTP calls, token exchange, Facepunch auth verification, and a separate backend service, your game calls one library method and your `.yml` endpoint handles the server-authoritative transaction.

**Install from the s&box Library Manager:**
[https://sbox.game/sboxcool/network-storage](https://sbox.game/sboxcool/network-storage)

Or search for **Network Storage by sboxcool.com** in Editor > Library Manager inside the s&box editor. Source: [github.com/sbox-cool/sbox-network-storage](https://github.com/sbox-cool/sbox-network-storage).

## 1. Install

Open the s&box editor and go to **Editor > Library Manager**. Search for `Network Storage by sboxcool.com` and click **Install**.

Once installed, the library adds:
- `NetworkStorage` -- the C# API client for your game code
- `SaveStateTracker` -- UI-friendly save state tracking
- `JsonHelpers` + extension methods -- parsing helpers
- `NetLog` -- debug event logger
- **Sync Tool** -- editor window for managing endpoints and collections

## 2. Configure

Use the **Setup Tool** to connect the library to your project — no code changes needed.

1. Open **Editor → Network Storage → Setup**
2. Enter your **Project ID**, **Public Key**, and **Secret Key** from the [dashboard](/tools/network-storage)
3. Click **Save Configuration**, then **Test Connection**

At runtime, your game uses the **Project ID + Public Key**. The **Secret Key** is only for the Sync Tool / Management API and stays editor-only, so it is never exported with published game files.

This writes `Assets/network-storage.credentials.json` to your project. The library auto-loads it on first use — your game code needs no `Configure()` call.

**Settings window** (Editor → Network Storage → Settings):
- Toggle **Proxy Mode** for dedicated server setups
- Project-level settings managed from the editor

**Code Generator** (Editor → Network Storage → Generate Code):
- Generates strongly-typed C# classes from your schemas
- Creates `NSConfig` static class that the library uses as a fallback when credentials JSON isn't available
- Published games use `NSConfig` instead of the credentials file

**Manual configure (optional override):**

If you prefer to configure in code (e.g., for custom base URLs), call `Configure()` once at startup:

```csharp
NetworkStorage.Configure( "YOUR_PROJECT_ID", "sbox_ns_YOUR_KEY" );
```

The library defaults to `https://api.sboxcool.com` and API version `v3`. You can override these if needed:

```csharp
NetworkStorage.Configure( ProjectId, ApiKey, "https://api.sboxcool.com", "v3" );
```

## 3. Call an Endpoint

Once configured, call endpoints from anywhere in your game:

```csharp
// Secure transaction: one call from game code
var purchase = await NetworkStorage.CallEndpoint( "purchase-item", new
{
    item_id = "sports_car"
} );
```

The library attaches the auth context automatically. The sboxcool.com backend verifies the player before the endpoint reads protected data or writes to endpoint-controlled collections.

```csharp
// Report a kill -- the endpoint handles XP, gold, and stats server-side
var result = await NetworkStorage.CallEndpoint( "report-kill", new
{
    target_type = "goblin_warrior"
} );

if ( result.HasValue )
{
    int xp = result.Value.Int( "xp_earned" );
    int gold = result.Value.Int( "gold_earned" );
    Log.Info( $"Kill rewarded! +{xp} XP, +{gold} gold" );
}
```

```csharp
// Purchase an item
var result = await NetworkStorage.CallEndpoint( "purchase-item", new
{
    item_id = "iron_sword"
} );

if ( result.HasValue && result.Value.Bool( "success" ) )
{
    int gold = result.Value.Int( "gold_remaining" );
    Log.Info( $"Purchased! Gold remaining: {gold}" );
}
```

## 4. Read Player Data

Read player data through a controlled endpoint or query:

```csharp
var data = await NetworkStorage.CallEndpoint( "get-player-profile", new { } );

if ( data.HasValue )
{
    string name = data.Value.Str( "playerName", "Unknown" );
    int xp = data.Value.Int( "xp" );
    int gold = data.Value.Int( "gold" );
    Log.Info( $"{name}: {xp} XP, {gold} gold" );
}
```

For **Endpoint controlled** collections, use `CallEndpoint` from clients. Dedicated servers can use secret-key runtime access for protected endpoints, queries, and direct collection rows; see [Dedicated Server Runtime](/wiki/network-storage-v3/dedicated-server-runtime).

## 5. Load Game Values

Fetch server-authoritative constants on game startup:

```csharp
var values = await NetworkStorage.GetGameValues();

if ( values.HasValue )
{
    // Groups -- simple key-value constants
    var combat = values.Value.GetProperty( "groups" ).GetProperty( "combat" );
    int xpPerKill = combat.GetProperty( "xp_per_kill" ).GetInt32();

    // Tables -- structured data with rows
    var shop = values.Value.GetProperty( "tables" ).GetProperty( "shop_items" );
    foreach ( var row in shop.GetProperty( "rows" ).EnumerateArray() )
    {
        string name = row.GetProperty( "name" ).GetString();
        int cost = row.GetProperty( "cost" ).GetInt32();
        Log.Info( $"Shop: {name} costs {cost} gold" );
    }
}
```

## 6. Save State Tracking

Use `SaveStateTracker` to show saving indicators in your UI:

```csharp
public class PlayerManager : Component
{
    private SaveStateTracker _tracker = new();

    public bool IsSaving => _tracker.IsBusy;
    public string LastError => _tracker.LastError;

    public async Task ReportKill( string targetType )
    {
        var result = await _tracker.Call( "report-kill", new { target_type = targetType } );
        if ( result.HasValue )
        {
            // Update local UI with server response
            int xp = result.Value.Int( "xp_earned" );
            Log.Info( $"+{xp} XP" );
        }
    }
}
```

## 7. Editor Sync Tool

The Setup Tool (configured in step 2) also lets you manage your project data without opening the web dashboard.

From the sync tool you can:
- **Push** local endpoint/collection definitions to the server
- **Pull** server data into local YAML Source files
- **Diff** local vs remote to see changes
- Edit endpoints and collections as YAML Source files in your project
- Push Game Values used by both your client UI and backend validators

YAML Source is the standard for synced definitions. Prefer `.yml` filenames for new YAML Source files. `.yaml` files still work and are treated the same.

### Predictive Values

Game Values are especially useful for shop prices, weapon stats, XP curves, and balance constants. Keep the same value files in your project, push them to the cloud with the Sync Tool, and ship them with your game bundle. Your client UI can show the predicted price locally while the backend endpoint validates against the synced server value.

That means fewer desync failures like "the shop UI said 500 gold, but the server validator expected 750." The same source data drives both sides.

### File Structure

```
Editor/Network Storage/
  config/
    public/projectConfig.json   # Project ID, public key, base URL
    secret/secret_key.json      # Secret key only (gitignored)
  endpoints/
    report-kill.endpoint.yml    # One YAML Source file per endpoint
    purchase-item.endpoint.yml
  collections/
    player_data.collection.yml  # One YAML Source file per collection
```

The secret key stays in `Editor/Network Storage/config/secret/`, which is editor-only and never published with your game. Runtime requests use the Project ID + Public Key instead.

## Properties Reference

| Property | Type | Description |
|----------|------|-------------|
| `NetworkStorage.IsConfigured` | `bool` | True after `Configure()` is called or credentials file is auto-loaded |
| `NetworkStorage.ProjectId` | `string` | Current project ID |
| `NetworkStorage.ApiKey` | `string` | Current public API key |
| `NetworkStorage.BaseUrl` | `string` | Base URL (default: `https://api.sboxcool.com`) |
| `NetworkStorage.ApiVersion` | `string` | API version (default: `v3`) |
| `NetworkStorage.ApiRoot` | `string` | Full versioned URL (e.g. `https://api.sboxcool.com/v3`) |
| `NetworkStorage.IsHost` | `bool` | True if this machine is the network host (or single-player) |
| `NetworkStorage.ProxyEnabled` | `bool` | Enable/disable proxy mode for dedicated servers (default: `true`) |

## Next Steps

- [Quick Start](/wiki/network-storage-v3/quick-start) -- 5-minute end-to-end setup
- [Endpoints](/wiki/network-storage-v3/endpoints) -- building server-side logic pipelines
- [Collections](/wiki/network-storage-v3/collections) -- schemas, access model, save slots
- [Agent Discovery](/wiki/network-storage-v3/agent-discovery) -- machine-friendly endpoint and auth manifest
- [Library Reference](/wiki/network-storage-v3/library-reference) -- full API docs for all classes and methods