diff --git a/STYLE.md b/STYLE.md index d8b8be85..81de954f 100644 --- a/STYLE.md +++ b/STYLE.md @@ -311,9 +311,9 @@ For example: > > You can supply your users with authorization tokens in several different ways; which one is best for you will depend on the needs of your app. [...] (I don't actually want to write a real answer to this question - pgoldman 2024-11-19.) > -> #### Can my client connect to multiple modules at the same time? +> #### Can my client connect to multiple databases at the same time? > -> Yes! Your client can construct as many `DbConnection`s simultaneously as it wants to, each of which will operate independently. If you want to connect to two modules with different schemas, use `spacetime generate` to include bindings for both of them in your client project. Note that SpacetimeDB may reject multiple concurrent connections to the same module by a single client. +> Yes! Your client can construct as many `DbConnection`s simultaneously as it wants to, each of which will operate independently. If you want to connect to two databases with different schemas, use `spacetime generate` to include bindings for both of them in your client project. Note that SpacetimeDB may reject multiple concurrent connections to the same database by a single client. ## Tutorial pages @@ -341,7 +341,7 @@ The first time a tutorial or series introduces a new type / function / method / ### Tutorial code -If the tutorial involves writing code, e.g. for a module or client, the tutorial should include the complete result code within its text. Ideally, it should be possible for a reader to copy and paste all the code blocks in the document into a file, effectively concatentating them together, and wind up with a coherent and runnable program. Sometimes this is not possible, e.g. because C# requires wrapping your whole file in a bunch of scopes. In this case, precede each code block with a sentence that describes where the reader is going to paste it. +If the tutorial involves writing code, e.g. for a module or client, the tutorial should include the complete result code within its text. Ideally, it should be possible for a reader to copy and paste all the code blocks in the document into a file, effectively concatenating them together, and wind up with a coherent and runnable program. Sometimes this is not possible, e.g. because C# requires wrapping your whole file in a bunch of scopes. In this case, precede each code block with a sentence that describes where the reader is going to paste it. Include even uninteresting code, like imports! You can rush through these without spending too much time on them, but make sure that every line of code required to make the project work appears in the tutorial. diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 69ebbbd5..4da30b2c 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -54,7 +54,7 @@ This document contains the help content for the `spacetime` command-line program * `logout` — * `init` — Initializes a new spacetime project. WARNING: This command is UNSTABLE and subject to breaking changes. * `build` — Builds a spacetime module. -* `server` — Manage the connection to the SpacetimeDB server. WARNING: This command is UNSTABLE and subject to breaking changes. +* `server` — Manage the connection to the SpacetimeDB database server. WARNING: This command is UNSTABLE and subject to breaking changes. * `subscribe` — Subscribe to SQL queries on the database. WARNING: This command is UNSTABLE and subject to breaking changes. * `start` — Start a local SpacetimeDB instance * `version` — Manage installed spacetime versions @@ -83,7 +83,7 @@ Run `spacetime help publish` for more detailed information. ###### Options: -* `-c`, `--delete-data` — When publishing to an existing database identity, first DESTROY all data associated with the module +* `-c`, `--delete-data` — When publishing to an existing database identity, first DESTROY all data associated with the database * `--build-options ` — Options to pass to the build command, for example --build-options='--lint-dir=' Default value: `` @@ -391,7 +391,7 @@ Builds a spacetime module. ## spacetime server -Manage the connection to the SpacetimeDB server. WARNING: This command is UNSTABLE and subject to breaking changes. +Manage the connection to the SpacetimeDB database server. WARNING: This command is UNSTABLE and subject to breaking changes. **Usage:** `spacetime server server ` diff --git a/docs/deploying/spacetimedb-standalone.md b/docs/deploying/spacetimedb-standalone.md index 34cb8ccf..49b92c27 100644 --- a/docs/deploying/spacetimedb-standalone.md +++ b/docs/deploying/spacetimedb-standalone.md @@ -168,7 +168,7 @@ If you have uncommented the `/v1/publish` restriction in Step 3 then you won't b ```bash spacetime build scp target/wasm32-unknown-unknown/release/spacetime_module.wasm ubuntu@:/home/ubuntu/ -ssh ubuntu@ spacetime publish -s local --bin-path spacetime_module.wasm +ssh ubuntu@ spacetime publish -s local --bin-path spacetime_module.wasm ``` You could put the above commands into a shell script to make publishing to your server easier and faster. It's also possible to integrate a script like this into Github Actions to publish on some event (like a PR merging into master). diff --git a/docs/http/database.md b/docs/http/database.md index 0ac41070..de495511 100644 --- a/docs/http/database.md +++ b/docs/http/database.md @@ -127,7 +127,7 @@ Accessible through the CLI as `spacetime delete `. ## `GET /v1/database/:name_or_identity/names` -Get the names this datbase can be identified by. +Get the names this database can be identified by. #### Returns diff --git a/docs/index.md b/docs/index.md index 6e4a0b65..a8b671c0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -229,7 +229,7 @@ Clients are regular software applications that developers can choose how to depl ### Identity -A SpacetimeDB `Identity` identifies someone interacting with a module. It is a long lived, public, globally valid identifier that will always refer to the same end user, even across different connections. +A SpacetimeDB `Identity` identifies someone interacting with a database. It is a long lived, public, globally valid identifier that will always refer to the same end user, even across different connections. A user's `Identity` is attached to every [reducer call](#reducer) they make, and you can use this to decide what they are allowed to do. @@ -261,9 +261,9 @@ def identity_from_claims(issuer: str, subject: str) -> [u8; 32]: ### ConnectionId -A `ConnectionId` identifies client connections to a SpacetimeDB module. +A `ConnectionId` identifies client connections to a SpacetimeDB database. -A user has a single [`Identity`](#identity), but may open multiple connections to your module. Each of these will receive a unique `ConnectionId`. +A user has a single [`Identity`](#identity), but may open multiple connections to your database. Each of these will receive a unique `ConnectionId`. ### Energy **Energy** is the currency used to pay for data storage and compute operations in a SpacetimeDB host. diff --git a/docs/modules/c-sharp/index.md b/docs/modules/c-sharp/index.md index fc2acc95..9074bf67 100644 --- a/docs/modules/c-sharp/index.md +++ b/docs/modules/c-sharp/index.md @@ -830,13 +830,13 @@ This reducer can be used to configure any static data tables used by your module ### The `ClientConnected` reducer -This reducer is marked with `[SpacetimeDB.Reducer(ReducerKind.ClientConnected)]`. It is run when a client connects to the SpacetimeDB module. Their identity can be found in the sender value of the `ReducerContext`. +This reducer is marked with `[SpacetimeDB.Reducer(ReducerKind.ClientConnected)]`. It is run when a client connects to the SpacetimeDB database. Their identity can be found in the sender value of the `ReducerContext`. If an error occurs in the reducer, the client will be disconnected. ### The `ClientDisconnected` reducer -This reducer is marked with `[SpacetimeDB.Reducer(ReducerKind.ClientDisconnected)]`. It is run when a client disconnects from the SpacetimeDB module. Their identity can be found in the sender value of the `ReducerContext`. +This reducer is marked with `[SpacetimeDB.Reducer(ReducerKind.ClientDisconnected)]`. It is run when a client disconnects from the SpacetimeDB database. Their identity can be found in the sender value of the `ReducerContext`. If an error occurs in the disconnect reducer, the client is still recorded as disconnected. @@ -1002,7 +1002,7 @@ namespace SpacetimeDB Methods for writing to a private debug log. Log messages will include file and line numbers. -Log outputs of a running module can be inspected using the `spacetime logs` command: +Log outputs of a running database can be inspected using the `spacetime logs` command: ```text spacetime logs diff --git a/docs/modules/c-sharp/quickstart.md b/docs/modules/c-sharp/quickstart.md index 9bdb78c9..72d907e3 100644 --- a/docs/modules/c-sharp/quickstart.md +++ b/docs/modules/c-sharp/quickstart.md @@ -233,7 +233,7 @@ public static void ClientConnected(ReducerContext ctx) } ``` -Similarly, whenever a client disconnects, the module will execute the `OnDisconnect` event if it's registered with `ReducerKind.ClientDisconnected`. We'll use it to un-set the `Online` status of the `User` for the disconnected client. +Similarly, whenever a client disconnects, the database will execute the `OnDisconnect` event if it's registered with `ReducerKind.ClientDisconnected`. We'll use it to un-set the `Online` status of the `User` for the disconnected client. Add the following code after the `OnConnect` handler: @@ -311,6 +311,6 @@ spacetime sql quickstart-chat "SELECT * FROM message" You've just set up your first database in SpacetimeDB! You can find the full code for this client [in the C# server module example](https://github.com/clockworklabs/com.clockworklabs.spacetimedbsdk/tree/master/examples~/quickstart-chat/server). -The next step would be to create a client module that interacts with this module. You can use any of SpacetimDB's supported client languages to do this. Take a look at the quick start guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart). +The next step would be to create a client that interacts with this module. You can use any of SpacetimDB's supported client languages to do this. Take a look at the quick start guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart). If you are planning to use SpacetimeDB with the Unity game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity/part-1). diff --git a/docs/modules/rust/quickstart.md b/docs/modules/rust/quickstart.md index 9bbb4b3b..9572ed0b 100644 --- a/docs/modules/rust/quickstart.md +++ b/docs/modules/rust/quickstart.md @@ -182,7 +182,7 @@ You could extend the validation in `validate_message` in similar ways to `valida ## Set users' online status -Whenever a client connects, the module will run a special reducer, annotated with `#[reducer(client_connected)]`, if it's defined. By convention, it's named `client_connected`. We'll use it to create a `User` record for the client if it doesn't yet exist, and to set its online status. +Whenever a client connects, the database will run a special reducer, annotated with `#[reducer(client_connected)]`, if it's defined. By convention, it's named `client_connected`. We'll use it to create a `User` record for the client if it doesn't yet exist, and to set its online status. We'll use `ctx.db.user().identity().find(ctx.sender)` to look up a `User` row for `ctx.sender`, if one exists. If we find one, we'll use `ctx.db.user().identity().update(..)` to overwrite it with a row that has `online: true`. If not, we'll use `ctx.db.user().insert(..)` to insert a new row for our new user. All three of these methods are generated by the `#[table(..)]` macro, with rows and behavior based on the row attributes. `ctx.db.user().find(..)` returns an `Option`, because of the unique constraint from the `#[primary_key]` attribute. This means there will be either zero or one matching rows. If we used `try_insert` here it would return a `Result<(), UniqueConstraintViolation>` because of the same unique constraint. However, because we're already checking if there is a user with the given sender identity we know that inserting into this table will not fail. Therefore, we use `insert`, which automatically unwraps the result, simplifying the code. If we want to overwrite a `User` row, we need to do so explicitly using `ctx.db.user().identity().update(..)`. @@ -190,7 +190,7 @@ To `server/src/lib.rs`, add the definition of the connect reducer: ```rust #[reducer(client_connected)] -// Called when a client connects to the SpacetimeDB +// Called when a client connects to a SpacetimeDB database server pub fn client_connected(ctx: &ReducerContext) { if let Some(user) = ctx.db.user().identity().find(ctx.sender) { // If this is a returning user, i.e. we already have a `User` with this `Identity`, @@ -208,11 +208,11 @@ pub fn client_connected(ctx: &ReducerContext) { } ``` -Similarly, whenever a client disconnects, the module will run the `#[reducer(client_disconnected)]` reducer if it's defined. By convention, it's named `client_disconnected`. We'll use it to un-set the `online` status of the `User` for the disconnected client. +Similarly, whenever a client disconnects, the database will run the `#[reducer(client_disconnected)]` reducer if it's defined. By convention, it's named `client_disconnected`. We'll use it to un-set the `online` status of the `User` for the disconnected client. ```rust #[reducer(client_disconnected)] -// Called when a client disconnects from SpacetimeDB +// Called when a client disconnects from SpacetimeDB database server pub fn identity_disconnected(ctx: &ReducerContext) { if let Some(user) = ctx.db.user().identity().find(ctx.sender) { ctx.db.user().identity().update(User { online: false, ..user }); @@ -275,6 +275,6 @@ spacetime sql quickstart-chat "SELECT * FROM message" You can find the full code for this module [in the SpacetimeDB module examples](https://github.com/clockworklabs/SpacetimeDB/tree/master/modules/quickstart-chat). -You've just set up your first database in SpacetimeDB! The next step would be to create a client module that interacts with this module. You can use any of SpacetimDB's supported client languages to do this. Take a look at the quickstart guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart). +You've just set up your first database in SpacetimeDB! The next step would be to create a client that interacts with this module. You can use any of SpacetimDB's supported client languages to do this. Take a look at the quickstart guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart). If you are planning to use SpacetimeDB with the Unity game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity/part-1). diff --git a/docs/sdks/c-sharp/index.md b/docs/sdks/c-sharp/index.md index 16fd2068..3fd4c9b0 100644 --- a/docs/sdks/c-sharp/index.md +++ b/docs/sdks/c-sharp/index.md @@ -53,11 +53,11 @@ A connection to a remote database is represented by the `DbConnection` class. Th | Name | Description | |------------------------------------------------------------------------|-------------------------------------------------------------------------------| -| [Connect to a module](#connect-to-a-module) | Construct a `DbConnection` instance. | +| [Connect to a database](#connect-to-a-database) | Construct a `DbConnection` instance. | | [Advance the connection](#advance-the-connection-and-process-messages) | Poll the `DbConnection` or run it in the background. | | [Access tables and reducers](#access-tables-and-reducers) | Access the client cache, request reducer invocations, and register callbacks. | -## Connect to a module +## Connect to a database ```csharp class DbConnection @@ -66,12 +66,12 @@ class DbConnection } ``` -Construct a `DbConnection` by calling `DbConnection.Builder()`, chaining configuration methods, and finally calling `.Build()`. At a minimum, you must specify `WithUri` to provide the URI of the SpacetimeDB instance, and `WithModuleName` to specify the module's name or identity. +Construct a `DbConnection` by calling `DbConnection.Builder()`, chaining configuration methods, and finally calling `.Build()`. At a minimum, you must specify `WithUri` to provide the URI of the SpacetimeDB instance, and `WithModuleName` to specify the database's name or identity. | Name | Description | |---------------------------------------------------------|--------------------------------------------------------------------------------------------| | [WithUri method](#method-withuri) | Set the URI of the SpacetimeDB instance hosting the remote database. | -| [WithModuleName method](#method-withmodulename) | Set the name or identity of the remote module. | +| [WithModuleName method](#method-withmodulename) | Set the name or identity of the remote database. | | [OnConnect callback](#callback-onconnect) | Register a callback to run when the connection is successfully established. | | [OnConnectError callback](#callback-onconnecterror) | Register a callback to run if the connection is rejected or the host is unreachable. | | [OnDisconnect callback](#callback-ondisconnect) | Register a callback to run when the connection ends. | @@ -87,7 +87,7 @@ class DbConnectionBuilder } ``` -Configure the URI of the SpacetimeDB instance or cluster which hosts the remote module. +Configure the URI of the SpacetimeDB instance or cluster which hosts the remote module and database. ### Method `WithModuleName` @@ -98,7 +98,7 @@ class DbConnectionBuilder } ``` -Configure the SpacetimeDB domain name or `Identity` of the remote module which identifies it within the SpacetimeDB instance or cluster. +Configure the SpacetimeDB domain name or `Identity` of the remote database which identifies it within the SpacetimeDB instance or cluster. ### Callback `OnConnect` @@ -109,7 +109,7 @@ class DbConnectionBuilder } ``` -Chain a call to `.OnConnect(callback)` to your builder to register a callback to run when your new `DbConnection` successfully initiates its connection to the remote module. The callback accepts three arguments: a reference to the `DbConnection`, the `Identity` by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to [`WithToken`](#method-withtoken) to authenticate the same user in future connections. +Chain a call to `.OnConnect(callback)` to your builder to register a callback to run when your new `DbConnection` successfully initiates its connection to the remote database. The callback accepts three arguments: a reference to the `DbConnection`, the `Identity` by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to [`WithToken`](#method-withtoken) to authenticate the same user in future connections. ### Callback `OnConnectError` @@ -133,7 +133,7 @@ class DbConnectionBuilder } ``` -Chain a call to `.OnDisconnect(callback)` to your builder to register a callback to run when your `DbConnection` disconnects from the remote module, either as a result of a call to [`Disconnect`](#method-disconnect) or due to an error. +Chain a call to `.OnDisconnect(callback)` to your builder to register a callback to run when your `DbConnection` disconnects from the remote database, either as a result of a call to [`Disconnect`](#method-disconnect) or due to an error. ### Method `WithToken` @@ -203,7 +203,7 @@ class DbConnection } ``` -The `Reducers` field of the `DbConnection` provides access to reducers exposed by the remote module. See [Observe and invoke reducers](#observe-and-invoke-reducers). +The `Reducers` field of the `DbConnection` provides access to reducers exposed by the module of the remote database. See [Observe and invoke reducers](#observe-and-invoke-reducers). ## Interface `IDbContext` @@ -522,7 +522,7 @@ record Event } ``` -Event when we are notified that a reducer ran in the remote module. The [`ReducerEvent`](#record-reducerevent) contains metadata about the reducer run, including its arguments and termination [`Status`](#record-status). +Event when we are notified that a reducer ran in the remote database. The [`ReducerEvent`](#record-reducerevent) contains metadata about the reducer run, including its arguments and termination [`Status`](#record-status). This event is passed to row callbacks resulting from modifications by the reducer. @@ -574,7 +574,7 @@ record Event } ``` -Event when we are notified of a transaction in the remote module which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings. +Event when we are notified of a transaction in the remote database which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings. This event is passed to [row callbacks](#callback-oninsert) resulting from modifications by the transaction. @@ -741,7 +741,7 @@ class ErrorContext { } ``` -The `Reducers` property of the context provides access to reducers exposed by the remote module. See [Observe and invoke reducers](#observe-and-invoke-reducers). +The `Reducers` property of the context provides access to reducers exposed by the remote database. See [Observe and invoke reducers](#observe-and-invoke-reducers). ## Access the client cache diff --git a/docs/sdks/c-sharp/quickstart.md b/docs/sdks/c-sharp/quickstart.md index aba4b77c..44065195 100644 --- a/docs/sdks/c-sharp/quickstart.md +++ b/docs/sdks/c-sharp/quickstart.md @@ -90,7 +90,7 @@ We'll work outside-in, first defining our `Main` function at a high level, then 1. Initialize the `AuthToken` module, which loads and stores our authentication token to/from local storage. 2. Connect to the database. 3. Register a number of callbacks to run in response to various database events. -4. Start our processing thread which connects to the SpacetimeDB module, updates the SpacetimeDB client and processes commands that come in from the input loop running in the main thread. +4. Start our processing thread which connects to the SpacetimeDB database, updates the SpacetimeDB client and processes commands that come in from the input loop running in the main thread. 5. Start the input loop, which reads commands from standard input and sends them to the processing thread. 6. When the input loop exits, stop the processing thread and wait for it to exit. @@ -121,13 +121,13 @@ void Main() ## Connect to database -Before we connect, we'll store the SpacetimeDB host name and our module name in constants `HOST` and `DB_NAME`. +Before we connect, we'll store the SpacetimeDB hostname and our database name in constants `HOST` and `DB_NAME`. A connection to a SpacetimeDB database is represented by a `DbConnection`. We configure `DbConnection`s using the builder pattern, by calling `DbConnection.Builder()`, chaining method calls to set various connection parameters and register callbacks, then we cap it off with a call to `.Build()` to begin the connection. In our case, we'll supply the following options: -1. A `WithUri` call, to specify the URI of the SpacetimeDB host where our module is running. +1. A `WithUri` call, to specify the URI of the SpacetimeDB host where our database is running. 2. A `WithModuleName` call, to specify the name or `Identity` of our database. Make sure to pass the same name here as you supplied to `spacetime publish`. 3. A `WithToken` call, to supply a token to authenticate with. 4. An `OnConnect` callback, to run when the remote database acknowledges and accepts our connection. @@ -137,10 +137,10 @@ In our case, we'll supply the following options: To `Program.cs`, add: ```csharp -/// The URI of the SpacetimeDB instance hosting our chat module. +/// The URI of the SpacetimeDB instance hosting our chat database and module. const string HOST = "http://localhost:3000"; -/// The module name we chose when we published our module. +/// The database name we chose when we published our module. const string DBNAME = "quickstart-chat"; /// Load credentials from a file and connect to the database. @@ -453,9 +453,9 @@ void PrintMessagesInOrder(RemoteTables tables) Since the input loop will be blocking, we'll run our processing code in a separate thread. -This thread will loop until the thread is signaled to exit, calling the update function `FrameTick` on the `DbConnection` to process any updates received from the module, and `ProcessCommand` to process any commands received from the input loop. +This thread will loop until the thread is signaled to exit, calling the update function `FrameTick` on the `DbConnection` to process any updates received from the database, and `ProcessCommand` to process any commands received from the input loop. -Afterward, close the connection to the module. +Afterward, close the connection to the database. To `Program.cs`, add: @@ -488,9 +488,9 @@ The input loop will read commands from standard input and send them to the proce Supported Commands: -1. Send a message: `message`, send the message to the module by calling `Reducer.SendMessage` which is automatically generated by `spacetime generate`. +1. Send a message: `message`, send the message to the database by calling `Reducer.SendMessage` which is automatically generated by `spacetime generate`. -2. Set name: `name`, will send the new name to the module by calling `Reducer.SetName` which is automatically generated by `spacetime generate`. +2. Set name: `name`, will send the new name to the database by calling `Reducer.SetName` which is automatically generated by `spacetime generate`. To `Program.cs`, add: diff --git a/docs/sdks/index.md b/docs/sdks/index.md index 46078cb9..ad9c082b 100644 --- a/docs/sdks/index.md +++ b/docs/sdks/index.md @@ -12,7 +12,7 @@ The SpacetimeDB Client SDKs offer the following key functionalities: ### Connection Management -The SDKs handle the process of connecting and disconnecting from the SpacetimeDB server, simplifying this process for the client applications. +The SDKs handle the process of connecting and disconnecting from SpacetimeDB database servers, simplifying this process for the client applications. ### Authentication @@ -32,7 +32,7 @@ The SpacetimeDB Client SDKs offer powerful callback functionality that allow cli #### Connection and Subscription Callbacks -Clients can also register callbacks that trigger when the connection to the server is established or lost, or when a subscription is updated. This allows clients to react to changes in the connection status. +Clients can also register callbacks that trigger when the connection to the database server is established or lost, or when a subscription is updated. This allows clients to react to changes in the connection status. #### Row Update Callbacks diff --git a/docs/sdks/rust/index.md b/docs/sdks/rust/index.md index a6dd23bb..4c180f52 100644 --- a/docs/sdks/rust/index.md +++ b/docs/sdks/rust/index.md @@ -53,11 +53,11 @@ A connection to a remote database is represented by the `module_bindings::DbConn | Name | Description | |------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| -| [Connect to a module](#connect-to-a-module) | Construct a `DbConnection`. | +| [Connect to a database](#connect-to-a-database) | Construct a `DbConnection`. | | [Advance the connection](#advance-the-connection-and-process-messages) | Poll the `DbConnection`, or set up a background worker to run it. | | [Access tables and reducers](#access-tables-and-reducers) | Access subscribed rows in the client cache, request reducer invocations, and register callbacks. | -### Connect to a module +### Connect to a database ```rust impl DbConnection { @@ -65,7 +65,7 @@ impl DbConnection { } ``` -Construct a `DbConnection` by calling `DbConnection::builder()` and chaining configuration methods, then calling `.build()`. You must at least specify `with_uri`, to supply the URI of the SpacetimeDB to which you published your module, and `with_module_name`, to supply the human-readable SpacetimeDB domain name or the raw `Identity` which identifies the module. +Construct a `DbConnection` by calling `DbConnection::builder()` and chaining configuration methods, then calling `.build()`. You must at least specify `with_uri`, to supply the URI of the SpacetimeDB to which you published your module, and `with_module_name`, to supply the human-readable SpacetimeDB domain name or the raw `Identity` which identifies the database. | Name | Description | |-----------------------------------------------------------|--------------------------------------------------------------------------------------| @@ -85,7 +85,7 @@ impl DbConnectionBuilder { } ``` -Configure the URI of the SpacetimeDB instance or cluster which hosts the remote module. +Configure the URI of the SpacetimeDB instance or cluster which hosts the remote database containing the module. #### Method `with_module_name` @@ -95,7 +95,7 @@ impl DbConnectionBuilder { } ``` -Configure the SpacetimeDB domain name or `Identity` of the remote module which identifies it within the SpacetimeDB instance or cluster. +Configure the SpacetimeDB domain name or `Identity` of the remote database which identifies it within the SpacetimeDB instance or cluster. #### Callback `on_connect` @@ -105,7 +105,7 @@ impl DbConnectionBuilder { } ``` -Chain a call to `.on_connect(callback)` to your builder to register a callback to run when your new `DbConnection` successfully initiates its connection to the remote module. The callback accepts three arguments: a reference to the `DbConnection`, the `Identity` by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to [`with_token`](#method-with_token) to authenticate the same user in future connections. +Chain a call to `.on_connect(callback)` to your builder to register a callback to run when your new `DbConnection` successfully initiates its connection to the remote database. The callback accepts three arguments: a reference to the `DbConnection`, the `Identity` by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to [`with_token`](#method-with_token) to authenticate the same user in future connections. This interface may change in an upcoming release as we rework SpacetimeDB's authentication model. @@ -135,7 +135,7 @@ impl DbConnectionBuilder { } ``` -Chain a call to `.on_disconnect(callback)` to your builder to register a callback to run when your `DbConnection` disconnects from the remote module, either as a result of a call to [`disconnect`](#method-disconnect) or due to an error. +Chain a call to `.on_disconnect(callback)` to your builder to register a callback to run when your `DbConnection` disconnects from the remote database, either as a result of a call to [`disconnect`](#method-disconnect) or due to an error. #### Method `with_token` @@ -553,7 +553,7 @@ spacetimedb_sdk::Event spacetimedb_sdk::Event::Reducer(spacetimedb_sdk::ReducerEvent) ``` -Event when we are notified that a reducer ran in the remote module. The [`ReducerEvent`](#struct-reducerevent) contains metadata about the reducer run, including its arguments and termination [`Status`](#enum-status). +Event when we are notified that a reducer ran in the remote database. The [`ReducerEvent`](#struct-reducerevent) contains metadata about the reducer run, including its arguments and termination [`Status`](#enum-status). This event is passed to row callbacks resulting from modifications by the reducer. @@ -589,7 +589,7 @@ This event is passed to [row `on_delete` callbacks](#callback-on_delete) resulti #### Variant `UnknownTransaction` -Event when we are notified of a transaction in the remote module which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings. +Event when we are notified of a transaction in the remote database which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings. This event is passed to [row callbacks](#callback-on_insert) resulting from modifications by the transaction. diff --git a/docs/sdks/rust/quickstart.md b/docs/sdks/rust/quickstart.md index ea1080ac..21f4d947 100644 --- a/docs/sdks/rust/quickstart.md +++ b/docs/sdks/rust/quickstart.md @@ -22,7 +22,7 @@ cargo new client `client/Cargo.toml` should be initialized without any dependencies. We'll need two: -- [`spacetimedb-sdk`](https://crates.io/crates/spacetimedb-sdk), which defines client-side interfaces for interacting with a remote SpacetimeDB module. +- [`spacetimedb-sdk`](https://crates.io/crates/spacetimedb-sdk), which defines client-side interfaces for interacting with a remote SpacetimeDB database. - [`hex`](https://crates.io/crates/hex), which we'll use to print unnamed users' identities as hexadecimal strings. Below the `[dependencies]` line in `client/Cargo.toml`, add: @@ -131,12 +131,12 @@ In our case, we'll supply the following options: 3. An `on_disconnect` callback, to run when our connection ends. 4. A `with_token` call, to supply a token to authenticate with. 5. A `with_module_name` call, to specify the name or `Identity` of our database. Make sure to pass the same name here as you supplied to `spacetime publish`. -6. A `with_uri` call, to specify the URI of the SpacetimeDB host where our module is running. +6. A `with_uri` call, to specify the URI of the SpacetimeDB host where our database is running. To `client/src/main.rs`, add: ```rust -/// The URI of the SpacetimeDB instance hosting our chat module. +/// The URI of the SpacetimeDB instance hosting our chat database and module. const HOST: &str = "http://localhost:3000"; /// The database name we chose when we published our module. diff --git a/docs/sdks/typescript/index.md b/docs/sdks/typescript/index.md index 532fe951..ef55ed1e 100644 --- a/docs/sdks/typescript/index.md +++ b/docs/sdks/typescript/index.md @@ -94,11 +94,11 @@ A connection to a remote database is represented by the `DbConnection` type. Thi | Name | Description | |-----------------------------------------------------------|--------------------------------------------------------------------------------------------------| -| [Connect to a module](#connect-to-a-module) | Construct a `DbConnection`. | +| [Connect to a database](#connect-to-a-database) | Construct a `DbConnection`. | | [Access tables and reducers](#access-tables-and-reducers) | Access subscribed rows in the client cache, request reducer invocations, and register callbacks. | -### Connect to a module +### Connect to a database ```typescript class DbConnection { @@ -106,7 +106,7 @@ class DbConnection { } ``` -Construct a `DbConnection` by calling `DbConnection.builder()` and chaining configuration methods, then calling `.build()`. You must at least specify `withUri`, to supply the URI of the SpacetimeDB to which you published your module, and `withModuleName`, to supply the human-readable SpacetimeDB domain name or the raw `Identity` which identifies the module. +Construct a `DbConnection` by calling `DbConnection.builder()` and chaining configuration methods, then calling `.build()`. You must at least specify `withUri`, to supply the URI of the SpacetimeDB to which you published your module, and `withModuleName`, to supply the human-readable SpacetimeDB domain name or the raw `Identity` which identifies the database. | Name | Description | |-------------------------------------------------------|--------------------------------------------------------------------------------------| @@ -126,7 +126,7 @@ class DbConnectionBuilder { } ``` -Configure the URI of the SpacetimeDB instance or cluster which hosts the remote module. +Configure the URI of the SpacetimeDB instance or cluster which hosts the remote database. #### Method `withModuleName` @@ -137,7 +137,7 @@ class DbConnectionBuilder { ``` -Configure the SpacetimeDB domain name or hex string encoded `Identity` of the remote module which identifies it within the SpacetimeDB instance or cluster. +Configure the SpacetimeDB domain name or hex string encoded `Identity` of the remote database which identifies it within the SpacetimeDB instance or cluster. #### Callback `onConnect` @@ -149,7 +149,7 @@ class DbConnectionBuilder { } ``` -Chain a call to `.onConnect(callback)` to your builder to register a callback to run when your new `DbConnection` successfully initiates its connection to the remote module. The callback accepts three arguments: a reference to the `DbConnection`, the `Identity` by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to [`withToken`](#method-withtoken) to authenticate the same user in future connections. +Chain a call to `.onConnect(callback)` to your builder to register a callback to run when your new `DbConnection` successfully initiates its connection to the remote database. The callback accepts three arguments: a reference to the `DbConnection`, the `Identity` by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to [`withToken`](#method-withtoken) to authenticate the same user in future connections. #### Callback `onConnectError` @@ -173,7 +173,7 @@ class DbConnectionBuilder { } ``` -Chain a call to `.onDisconnect(callback)` to your builder to register a callback to run when your `DbConnection` disconnects from the remote module, either as a result of a call to [`disconnect`](#method-disconnect) or due to an error. +Chain a call to `.onDisconnect(callback)` to your builder to register a callback to run when your `DbConnection` disconnects from the remote database, either as a result of a call to [`disconnect`](#method-disconnect) or due to an error. #### Method `withToken` @@ -499,7 +499,7 @@ type Event = { tag: 'Reducer'; value: ReducerEvent } ``` -Event when we are notified that a reducer ran in the remote module. The [`ReducerEvent`](#type-reducerevent) contains metadata about the reducer run, including its arguments and termination status(#type-updatestatus). +Event when we are notified that a reducer ran in the remote database. The [`ReducerEvent`](#type-reducerevent) contains metadata about the reducer run, including its arguments and termination status(#type-updatestatus). This event is passed to row callbacks resulting from modifications by the reducer. @@ -540,7 +540,7 @@ This event is passed to [row `onDelete` callbacks](#callback-ondelete) resulting { tag: 'UnknownTransaction' } ``` -Event when we are notified of a transaction in the remote module which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings. +Event when we are notified of a transaction in the remote database which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings. This event is passed to [row callbacks](#callback-oninsert) resulting from modifications by the transaction. diff --git a/docs/sdks/typescript/quickstart.md b/docs/sdks/typescript/quickstart.md index e567dc3d..1e1151ff 100644 --- a/docs/sdks/typescript/quickstart.md +++ b/docs/sdks/typescript/quickstart.md @@ -7,7 +7,7 @@ Please note that TypeScript is supported as a client language only. **Before you - [Rust](/docs/modules/rust/quickstart) - [C#](/docs/modules/c-sharp/quickstart) -By the end of this introduciton, you will have created a basic single page web app which connects to the `quickstart-chat` module created in the above module quickstart guides. +By the end of this introduciton, you will have created a basic single page web app which connects to the `quickstart-chat` database created in the above module quickstart guides. ## Project structure @@ -393,7 +393,7 @@ import { Identity } from '@clockworklabs/spacetimedb-sdk'; ## Create your SpacetimeDB client -Now that we've imported the `DbConnection` type, we can use it to connect our app to our module. +Now that we've imported the `DbConnection` type, we can use it to connect our app to our database. Add the following to your `App` function, just below `const [newMessage, setNewMessage] = useState('');`: @@ -459,11 +459,11 @@ Add the following to your `App` function, just below `const [newMessage, setNewM }, []); ``` -Here we are configuring our SpacetimeDB connection by specifying the server URI, module name, and a few callbacks including the `onConnect` callback. When `onConnect` is called after connecting, we store the connection state, our `Identity`, and our SpacetimeDB credentials in our React state. If there is an error connecting, we print that error to the console as well. +Here we are configuring our SpacetimeDB connection by specifying the server URI, database name, and a few callbacks including the `onConnect` callback. When `onConnect` is called after connecting, we store the connection state, our `Identity`, and our SpacetimeDB credentials in our React state. If there is an error connecting, we print that error to the console as well. We are also using `localStorage` to store our SpacetimeDB credentials. This way, we can reconnect to SpacetimeDB with the same `Identity` and token if we refresh the page. The first time we connect, we won't have any credentials stored, so we pass `undefined` to the `withToken` method. This will cause SpacetimeDB to generate new credentials for us. -If you chose a different name for your module, replace `quickstart-chat` with that name, or republish your module as `quickstart-chat`. +If you chose a different name for your database, replace `quickstart-chat` with that name, or republish your module as `quickstart-chat`. In the `onConnect` function we are also subscribing to the `message` and `user` tables. When we subscribe, SpacetimeDB will run our subscription queries and store the result in a local "client cache". This cache will be updated in real-time as the data in the table changes on the server. The `onApplied` callback is called after SpacetimeDB has synchronized our subscribed data with the client cache. @@ -630,7 +630,7 @@ Try opening a few incognito windows to see what it's like with multiple users! ### Notify about new users -We can also register `onInsert` and `onDelete` callbacks for the purpose of handling events, not just state. For example, we might want to show a notification any time a new user connects to the module. +We can also register `onInsert` and `onDelete` callbacks for the purpose of handling events, not just state. For example, we might want to show a notification any time a new user connects to the database. Note that these callbacks can fire in two contexts: diff --git a/docs/unity/part-2.md b/docs/unity/part-2.md index 84e262b5..36ebfc82 100644 --- a/docs/unity/part-2.md +++ b/docs/unity/part-2.md @@ -382,7 +382,7 @@ You should see something like the following output: ### Connecting our Client :::server-rust -Next let's connect our client to our module. Let's start by modifying our `debug` reducer. Rename the reducer to be called `connect` and add `client_connected` in parentheses after `spacetimedb::reducer`. The end result should look like this: +Next let's connect our client to our database. Let's start by modifying our `debug` reducer. Rename the reducer to be called `connect` and add `client_connected` in parentheses after `spacetimedb::reducer`. The end result should look like this: ```rust #[spacetimedb::reducer(client_connected)] @@ -392,16 +392,16 @@ pub fn connect(ctx: &ReducerContext) -> Result<(), String> { } ``` -The `client_connected` argument to the `spacetimedb::reducer` macro indicates to SpacetimeDB that this is a special reducer. This reducer is only ever called by SpacetimeDB itself when a client connects to your module. +The `client_connected` argument to the `spacetimedb::reducer` macro indicates to SpacetimeDB that this is a special reducer. This reducer is only ever called by SpacetimeDB itself when a client connects to your database. > SpacetimeDB gives you the ability to define custom reducers that automatically trigger when certain events occur. > > - `init` - Called the first time you publish your module and anytime you clear the database with `spacetime publish --delete-data`. -> - `client_connected` - Called when a user connects to the SpacetimeDB module. Their identity can be found in the `sender` value of the `ReducerContext`. -> - `client_disconnected` - Called when a user disconnects from the SpacetimeDB module. +> - `client_connected` - Called when a user connects to the SpacetimeDB database. Their identity can be found in the `sender` value of the `ReducerContext`. +> - `client_disconnected` - Called when a user disconnects from the SpacetimeDB database. ::: :::server-csharp -Next let's connect our client to our module. Let's start by modifying our `Debug` reducer. Rename the reducer to be called `Connect` and add `ReducerKind.ClientConnected` in parentheses after `SpacetimeDB.Reducer`. The end result should look like this: +Next let's connect our client to our database. Let's start by modifying our `Debug` reducer. Rename the reducer to be called `Connect` and add `ReducerKind.ClientConnected` in parentheses after `SpacetimeDB.Reducer`. The end result should look like this: ```csharp [Reducer(ReducerKind.ClientConnected)] @@ -411,13 +411,13 @@ public static void Connect(ReducerContext ctx) } ``` -The `ReducerKind.ClientConnected` argument to the `SpacetimeDB.Reducer` attribute indicates to SpacetimeDB that this is a special reducer. This reducer is only ever called by SpacetimeDB itself when a client connects to your module. +The `ReducerKind.ClientConnected` argument to the `SpacetimeDB.Reducer` attribute indicates to SpacetimeDB that this is a special reducer. This reducer is only ever called by SpacetimeDB itself when a client connects to your database. > SpacetimeDB gives you the ability to define custom reducers that automatically trigger when certain events occur. > > - `ReducerKind.Init` - Called the first time you publish your module and anytime you clear the database with `spacetime publish --delete-data`. -> - `ReducerKind.ClientConnected` - Called when a user connects to the SpacetimeDB module. Their identity can be found in the `Sender` value of the `ReducerContext`. -> - `ReducerKind.ClientDisconnected` - Called when a user disconnects from the SpacetimeDB module. +> - `ReducerKind.ClientConnected` - Called when a user connects to the SpacetimeDB database. Their identity can be found in the `Sender` value of the `ReducerContext`. +> - `ReducerKind.ClientDisconnected` - Called when a user disconnects from the SpacetimeDB database. ::: Publish your module again by running: @@ -462,7 +462,7 @@ This will generate a set of files in the `client-unity/Assets/autogen` directory └── SpacetimeDBClient.g.cs ``` -This will also generate a file in the `client-unity/Assets/autogen/SpacetimeDBClient.g.cs` directory with a type aware `DbConnection` class. We will use this class to connect to your module from Unity. +This will also generate a file in the `client-unity/Assets/autogen/SpacetimeDBClient.g.cs` directory with a type aware `DbConnection` class. We will use this class to connect to your database from Unity. > IMPORTANT! At this point there will be an error in your Unity project. Due to a [known issue](https://docs.unity3d.com/6000.0/Documentation/Manual/csharp-compiler.html) with Unity and C# 9 you need to insert the following code into your Unity project. > @@ -475,7 +475,7 @@ This will also generate a file in the `client-unity/Assets/autogen/SpacetimeDBCl > > Add this snippet to the bottom of your `GameManager.cs` file in your Unity project. This will hopefully be resolved in Unity soon. -### Connecting to the Module +### Connecting to the Database At this point we can set up Unity to connect your Unity client to the server. Replace your imports at the top of the `GameManager.cs` file with: diff --git a/docs/unity/part-3.md b/docs/unity/part-3.md index b31cac11..4dfb8e24 100644 --- a/docs/unity/part-3.md +++ b/docs/unity/part-3.md @@ -7,7 +7,7 @@ This progressive tutorial is continued from [part 2](/docs/unity/part-2). ### Spawning Food :::server-rust -Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your module before any clients connect. +Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. Add this new reducer above our `connect` reducer. @@ -78,7 +78,7 @@ pub fn spawn_food(ctx: &ReducerContext) -> Result<(), String> { ``` ::: :::server-csharp -Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `Init` reducer. SpacetimeDB calls the `Init` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your module before any clients connect. +Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `Init` reducer. SpacetimeDB calls the `Init` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. Add this new reducer above our `Connect` reducer. @@ -508,7 +508,7 @@ public static Entity SpawnCircleAt(ReducerContext ctx, uint player_id, uint mass The `EnterGame` reducer takes one argument, the player's `name`. We can use this name to display as a label for the player in the match, by storing the name on the player's row. We are also spawning some circles for the player to control now that they are entering the game. To do this, we choose a random position within the bounds of the arena and create a new entity and corresponding circle row. ::: -Let's also modify our `disconnect` reducer to remove the circles from the arena when the player disconnects from the server. +Let's also modify our `disconnect` reducer to remove the circles from the arena when the player disconnects from the database server. :::server-rust ```rust diff --git a/docs/unity/part-4.md b/docs/unity/part-4.md index 9ec81bd5..7e77fc83 100644 --- a/docs/unity/part-4.md +++ b/docs/unity/part-4.md @@ -579,10 +579,10 @@ We didn't even have to update the client, because our client's `OnDelete` callba Notice that the food automatically respawns as you vaccuum them up. This is because our scheduled reducer is automatically replacing the food 2 times per second, to ensure that there is always 600 food on the map. ## Connecting to Maincloud -- Publish to Maincloud `spacetime publish -s maincloud --delete-data` - - `` This name should be unique and cannot contain any special characters other than internal hyphens (`-`). +- Publish to Maincloud `spacetime publish -s maincloud --delete-data` + - `` This name should be unique and cannot contain any special characters other than internal hyphens (`-`). - Update the URL in the Unity project to: `https://maincloud.spacetimedb.com` -- Update the module name in the Unity project to ``. +- Update the module name in the Unity project to ``. - Clear the PlayerPrefs in Start() within `GameManager.cs` - Your `GameManager.cs` should look something like this: ```csharp @@ -600,7 +600,7 @@ private void Start() } ``` -To delete your Maincloud module, you can run: `spacetime delete -s maincloud ` +To delete your Maincloud database, you can run: `spacetime delete -s maincloud ` # Conclusion @@ -611,7 +611,7 @@ So far you've learned how to configure a new Unity project to work with Spacetim So far you've learned how to configure a new Unity project to work with SpacetimeDB, how to develop, build, and publish a SpacetimeDB server module. Within the module, you've learned how to create tables, update tables, and write reducers. You've learned about special reducers like `ClientConnected` and `Init` and how to created scheduled reducers. You learned how we can used scheduled reducers to implement a physics simulation right within your module. ::: -You've also learned how view module logs and connect your client to your server module, call reducers from the client and synchronize the data with client. Finally you learned how to use that synchronized data to draw game objects on the screen, so that we can interact with them and play a game! +You've also learned how view module logs and connect your client to your database server, call reducers from the client and synchronize the data with client. Finally you learned how to use that synchronized data to draw game objects on the screen, so that we can interact with them and play a game! And all of that completely from scratch!