Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
kazimuth committed Mar 3, 2025
1 parent 3a2385e commit c4067ac
Showing 1 changed file with 3 additions and 126 deletions.
129 changes: 3 additions & 126 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,136 +1,13 @@
# SpacetimeDB SDK for Unity Engine
# SpacetimeDB C# SDK

## Overview

This repository contains the C# and [Unity](https://unity.com/) SDKs for SpacetimeDB. The SDK allows to interact with the database server and is prepared to work with code generated from a SpacetimeDB backend code.
This repository contains the C# and [Unity](https://unity.com/) client SDKs for SpacetimeDB. These SDKs contain all the tools you need to build native clients for SpacetimeDB modules using C#.

## Documentation

The Unity SDK uses the same code as the C# SDK. You can find the documentation for the C# SDK in the [C# SDK Reference](https://spacetimedb.com/docs/sdks/c-sharp)
The Unity SDK uses the same code as the C# SDK. You can find the documentation for the C# SDK in the [C# SDK Reference](https://spacetimedb.com/docs/sdks/c-sharp). For a guided tutorial, see the [C# SDK Quickstart](https://spacetimedb.com/docs/sdks/c-sharp/quickstart).

There is also a comprehensive Unity tutorial/demo available:
- [Unity Tutorial](https://spacetimedb.com/docs/unity/part-1) Doc
- [Unity Demo](https://github.com/clockworklabs/SpacetimeDBUnityTutorial) Repo

## Installation

### Unity Demo

Download the [.unitypackage release](https://github.com/clockworklabs/SpacetimeDBUnityTutorial/releases) of our [Unity Part 1 tutorial](https://spacetimedb.com/docs/unity/part-1) demo that includes this SDK as a package manfiest requirement.

### Standalone

1. Open the package manager window in Unity.
2. Click the "(+)" button in the top-left corner and select "Add package from git URL".
3. Paste the following URL: `https://github.com/clockworklabs/com.clockworklabs.spacetimedbsdk.git`

## Usage

### SpacetimeDBNetworkManager

The Unity SDK for SpacetimeDB requires that there is a `SpacetimeDBNetworkManager` component attached to a GameObject in the scene. The `UnityNetworkManager` component is responsible for connecting to SpacetimeDB and managing the connection. The `UnityNetworkManager` component is a singleton and there can only be one instance of it in the scene.

### Connecting to SpacetimeDB

To connect to SpacetimeDB, you need to call the `Connect` method on the `SpacetimeDBClient` class. The `Connect` method takes the following parameters:

- `token`: The authentication token to use to connect to SpacetimeDB. This token is generated by the backend code and is used to authenticate the client.
- `hostName`: The hostname of the SpacetimeDB server. This is the same hostname that you use to connect to the SpacetimeDB web interface.
- `moduleAddress`: The address of the module to connect to. This is the same address that you use to connect to the SpacetimeDB web interface.
- `sslEnabled`: Whether to use SSL to connect to SpacetimeDB. This is the same value that you use to connect to the SpacetimeDB web interface.

Example:

```csharp
using SpacetimeDB;

SpacetimeDBClient.instance.Connect(TOKEN, HOST, DBNAME, SSL_ENABLED);
```

### AuthToken

The `AuthToken` class is an optional helper class that can be used to store the local client's authentication token locally in the Unity PlayerPrefs.

Example:

```csharp
using SpacetimeDB;

// called when we receive the client identity from SpacetimeDB
SpacetimeDBClient.instance.onIdentityReceived += (token, identity, address) => {
AuthToken.SaveToken(token);
local_identity = identity;
};

SpacetimeDBClient.instance.Connect(AuthToken.Token, hostName, moduleAddress, sslEnabled);
```

### Subscribing to tables

To subscribe to a table, you need to call the `Subscribe` method on the `SpacetimeDBClient` class. The `Subscribe` method takes a list of queries as a parameter. The queries are the same queries that you use to subscribe to tables in the SpacetimeDB web interface.

### Listening to events

To listen to events, you need to register callbacks on the `SpacetimeDBClient` class. The following callbacks are available:

- `onConnect`: Called when the client connects to SpacetimeDB.
- `onConnectError`: Called when the client fails to connect to SpacetimeDB.
- `onDisconnect`: Called when the client disconnects from SpacetimeDB.
- `onIdentityReceived`: Called when the client receives its identity from SpacetimeDB.
- `onSubscriptionApplied`: Called when the client receives the initial data from SpacetimeDB after subscribing to tables.

You can register for row update events on a table. To do this, you need to register callbacks on the table class. The following callbacks are available:

- `OnInsert`: Called when a row is inserted into the table.
- `OnUpdate`: Called when a row is updated in the table.
- `OnBeforeDelete`: Called before a row is deleted from the table.
- `OnDelete`: Called when a row is deleted from the table.
- `OnRowUpdate`: Called when a row is inserted, updated, or deleted from the table.

Example:

```csharp
using SpacetimeDB.Types;

PlayerComponent.OnInsert += PlayerComponent_OnInsert;
PlayerComponent.OnUpdate += PlayerComponent_OnUpdate;
PlayerComponent.OnDelete += PlayerComponent_OnDelete;
PlayerComponent.OnBeforeDelete += PlayerComponent_OnBeforeDelete;
PlayerComponent.OnRowUpdate += PlayerComponent_OnRowUpdate;
```

You can register for reducer call updates as well.

- `OnREDUCEREvent`: Called when a reducer call is received from SpacetimeDB. (If a) you are subscribed to the table that the reducer modifies or b) You called the reducer and it failed)

Example:

```csharp
using SpacetimeDB.Types;

Reducer.OnMovePlayerEvent += Reducer_OnMovePlayerEvent;
```

### Accessing the client cache

The client cache is a local cache of the data that the client has received from SpacetimeDB. The client cache is automatically updated when the client receives updates from SpacetimeDB.

When you run the CLI generate command, SpacetimeDB will automatically generate a class for each table in your database. These classes are generated in the `SpacetimeDB.Types` namespace. Each class contains a set of static methods that allow you to query the client cache. The following methods are available:

- `int Count()`: Returns the number of rows in the table.
- `IEnumerable<TableRow> Iter()`: Returns an iterator over the table.
- `IEnumerable<TableRow> FilterByCOLUMN(ColumnValue)`: Filters the table by the specified column value.
- `TableRow? FindByCOLUMN(ColumnValue)`: Finds a single item by the specifed column value.
- `IEnumerable<TableRow> Query(Func<TableRow, bool>)`: Filters the table with the specified predicate.

### Calling Reducers

To call a reducer, you need to call the autogenerated method on the `Reducer` class. The autogenerated method takes the reducer arguments as parameters. The reducer arguments are the same arguments that are expected in your server module.

Example:

```csharp
using SpacetimeDB.Types;

Reducer.MovePlayer(new StdbVector2(0.0f, 0.0f), new StdbVector2(1.0f, 1.0f));
```

0 comments on commit c4067ac

Please sign in to comment.