Dylan/onboarding-upgrades (#28)

* doc: Onboarding impr, fixes, consistency, cleanup

refactor: Whats next cleanup, +unity, -bloat

Removed redundant text while there

refactor: Unity quickstart fixes, impr, prettify

refactor: Unity pt1 fixes, impr, prettify

fix(README): Rm "see test edits below" ref

* !exists

refactor(minor): General onboarding cleanup

* Shorter, prettier, consistent

fix(sdks/c#): Broken unitypackage url

feat(sdks/c#): Add OneTimeQuery api ref

* doc: Onboarding impr, fixes, consistency, cleanup

* fix: Rm redundant 'module_bindings' mention

* fix: Floating period, "arbitrary", "important":

- PR review change requests
- Additionally: hasUpdatedRecently fix and reformatting

* fix: Mentioned FilterBy, used FindBy

- Used FindBy since that was what the tutorial used, and also looking for a single Identity.
- Note: There may be a similar rust discrepancy in the Unity pt1 tutorial. It'll work with Filter, but just simply less consistent. Holding off on that since my Rust syntax knowledge !exists.

* fix(Unity-pt1): Rm copy+paste redundant comments

* Duplicate comments found both above and within funcs

* fix(unity): Rm unused using statement +merged info

* Removed `System.Runtime.CompilerServices`
* SpacetimeDB.Module seems to already include this (merged the info)

* refactor(minor): Code spacing for grouping/clarity

* feat: 'Standalone mode runs in foreground' memo

* At general quickstart for `spacetime start`

* refactor(unity-pt1): Standalone mode foreground memo

* Also, removed the "speed" loss mention of C#

* fix(syntaxErr): Fix err, keep FilterBy, handle null

- After a verbose discussion, we will eventually swap to FindBy for single-result queries, but not in this PR.
- For now, the syntax err is fixed by making the var nullable and suffixing a LINQ FirstOrDefault(). Approved by Tyler in Discord.
- We never *actually* created a player in the tutorial. This creates the player. Approved by Tyler in Discord.

* fix: Remote player `is null` check removal

Author: dylanh724

docs/README.md

@@ -13,7 +13,7 @@ To make changes to our docs, you can open a pull request in this repository. You
 git clone ssh://[email protected]/<username>/spacetime-docs
 ```
 
-3. Make your edits to the docs that you want to make + test them locally (see Testing Your Edits below)
+3. Make your edits to the docs that you want to make + test them locally
 4. Commit your changes:
 
 ```bash

docs/docs/getting-started.md

@@ -2,29 +2,33 @@
 
 To develop SpacetimeDB applications locally, you will need to run the Standalone version of the server.
 
-1. [Install](/install) the SpacetimeDB CLI (Command Line Interface).
-2. Run the start command
+1. [Install](/install) the SpacetimeDB CLI (Command Line Interface)
+2. Run the start command:
 
 ```bash
 spacetime start
 ```
 
-The server listens on port `3000` by default. You can change this by using the `--listen-addr` option described below.
+The server listens on port `3000` by default, customized via `--listen-addr`.
 
-SSL is not supported in standalone mode.
+💡 Standalone mode will run in the foreground.
+⚠️ SSL is not supported in standalone mode.
 
 ## What's Next?
 
-You are ready to start developing SpacetimeDB modules. We have a quickstart guide for each supported server-side language:
+You are ready to start developing SpacetimeDB modules. See below for a quickstart guide for both client and server (module) languages/frameworks.
+
+### Server (Module)
 
 - [Rust](/docs/modules/rust/quickstart)
 - [C#](/docs/modules/c-sharp/quickstart)
 
-Then you can write your client application. We have a quickstart guide for each supported client-side language:
+⚡**Note:** Rust is [roughly 2x faster](https://faun.dev/c/links/faun/c-vs-rust-vs-go-a-performance-benchmarking-in-kubernetes/) than C#
+
+### Client
 
 - [Rust](/docs/sdks/rust/quickstart)
-- [C#](/docs/sdks/c-sharp/quickstart)
+- [C# (Standalone)](/docs/sdks/c-sharp/quickstart) 
+- [C# (Unity)](/docs/unity/part-1)
 - [Typescript](/docs/sdks/typescript/quickstart)
-- [Python](/docs/sdks/python/quickstart)
-
-We also have a [step-by-step tutorial](/docs/unity/part-1) for building a multiplayer game in Unity3d.
+- [Python](/docs/sdks/python/quickstart)

docs/docs/modules/c-sharp/index.md

@@ -42,6 +42,7 @@ static partial class Module
     {
         // We can skip (or explicitly set to zero) auto-incremented fields when creating new rows.
         var person = new Person { Name = name, Age = age };
+        
         // `Insert()` method is auto-generated and will insert the given row into the table.
         person.Insert();
         // After insertion, the auto-incremented fields will be populated with their actual values.
@@ -211,8 +212,10 @@ public partial struct Person
 
     // Finds a row in the table with the given value in the `Id` column and returns it, or `null` if no such row exists.
     public static Person? FindById(int id);
+    
     // Deletes a row in the table with the given value in the `Id` column and returns `true` if the row was found and deleted, or `false` if no such row exists.
     public static bool DeleteById(int id);
+    
     // Updates a row in the table with the given value in the `Id` column and returns `true` if the row was found and updated, or `false` if no such row exists.
     public static bool UpdateById(int oldId, Person newValue);
 }

docs/docs/modules/c-sharp/quickstart.md

@@ -16,7 +16,18 @@ If you haven't already, start by [installing SpacetimeDB](/install). This will i
 
 ## Install .NET 8
 
-Next we need to [install .NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) so that we can build and publish our module. .NET 8.0 is the earliest to have the `wasi-experimental` workload that we rely on.
+Next we need to [install .NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) so that we can build and publish our module.
+
+You may already have .NET 8 and can be checked:
+```bash
+dotnet --list-sdks
+```
+
+.NET 8.0 is the earliest to have the `wasi-experimental` workload that we rely on, but requires manual activation:
+
+```bash
+dotnet workload install wasi-experimental
+```
 
 ## Project structure
 
@@ -35,7 +46,11 @@ spacetime init --lang csharp server
 
 ## Declare imports
 
-`spacetime init` should have pre-populated `server/Lib.cs` with a trivial module. Clear it out, so we can write a module that's still pretty simple: a bare-bones chat server.
+`spacetime init` generated a few files: 
+
+1. Open `server/StdbModule.csproj` to generate a .sln file for intellisense/validation support.
+2. Open `server/Lib.cs`, a trivial module.
+3. Clear it out, so we can write a new module that's still pretty simple: a bare-bones chat server.
 
 To the top of `server/Lib.cs`, add some imports we'll be using:
 
@@ -45,8 +60,10 @@ using SpacetimeDB.Module;
 using static SpacetimeDB.Runtime;
 ```
 
-- `System.Runtime.CompilerServices` allows us to use the `ModuleInitializer` attribute, which we'll use to register our `OnConnect` and `OnDisconnect` callbacks.
-- `SpacetimeDB.Module` contains the special attributes we'll use to define our module.
+- `System.Runtime.CompilerServices` 
+- `SpacetimeDB.Module` 
+  - Contains the special attributes we'll use to define our module. 
+  - Allows us to use the `ModuleInitializer` attribute, which we'll use to register our `OnConnect` and `OnDisconnect` callbacks.
 - `SpacetimeDB.Runtime` contains the raw API bindings SpacetimeDB uses to communicate with the database.
 
 We also need to create our static module class which all of the module code will live in. In `server/Lib.cs`, add:
@@ -184,7 +201,7 @@ You could extend the validation in `ValidateMessage` in similar ways to `Validat
 
 In C# modules, you can register for `Connect` and `Disconnect` events by using a special `ReducerKind`. We'll use the `Connect` event to create a `User` record for the client if it doesn't yet exist, and to set its online status.
 
-We'll use `User.FilterByIdentity` to look up a `User` row for `dbEvent.Sender`, if one exists. If we find one, we'll use `User.UpdateByIdentity` to overwrite it with a row that has `Online: true`. If not, we'll use `User.Insert` to insert a new row for our new user. All three of these methods are generated by the `[SpacetimeDB.Table]` attribute, with rows and behavior based on the row attributes. `FilterByIdentity` returns a nullable `User`, because the unique constraint from the `[SpacetimeDB.Column(ColumnAttrs.PrimaryKey)]` attribute means there will be either zero or one matching rows. `Insert` will throw an exception if the insert violates this constraint; if we want to overwrite a `User` row, we need to do so explicitly using `UpdateByIdentity`.
+We'll use `User.FindByIdentity` to look up a `User` row for `dbEvent.Sender`, if one exists. If we find one, we'll use `User.UpdateByIdentity` to overwrite it with a row that has `Online: true`. If not, we'll use `User.Insert` to insert a new row for our new user. All three of these methods are generated by the `[SpacetimeDB.Table]` attribute, with rows and behavior based on the row attributes. `FindByIdentity` returns a nullable `User`, because the unique constraint from the `[SpacetimeDB.Column(ColumnAttrs.PrimaryKey)]` attribute means there will be either zero or one matching rows. `Insert` will throw an exception if the insert violates this constraint; if we want to overwrite a `User` row, we need to do so explicitly using `UpdateByIdentity`.
 
 In `server/Lib.cs`, add the definition of the connect reducer to the `Module` class:
 
@@ -235,7 +252,7 @@ public static void OnDisconnect(DbEventArgs dbEventArgs)
     else
     {
         // User does not exist, log warning
-        Log($"Warning: No user found for disconnected client.");
+        Log("Warning: No user found for disconnected client.");
     }
 }
 ```
@@ -250,12 +267,16 @@ From the `quickstart-chat` directory, run:
 spacetime publish --project-path server <module-name>
 ```
 
+```bash
+npm i wasm-opt -g
+```
+
 ## Call Reducers
 
 You can use the CLI (command line interface) to run reducers. The arguments to the reducer are passed in JSON format.
 
 ```bash
-spacetime call <module-name> send_message '["Hello, World!"]'
+spacetime call <module-name> send_message "Hello, World!"
 ```
 
 Once we've called our `send_message` reducer, we can check to make sure it ran by running the `logs` command.
@@ -288,4 +309,4 @@ spacetime sql <module-name> "SELECT * FROM Message"
 
 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 quick start guide for your client language of choice: [Rust](/docs/languages/rust/rust-sdk-quickstart-guide), [C#](/docs/languages/csharp/csharp-sdk-quickstart-guide), [TypeScript](/docs/languages/typescript/typescript-sdk-quickstart-guide) or [Python](/docs/languages/python/python-sdk-quickstart-guide).
 
-If you are planning to use SpacetimeDB with the Unity3d game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity/part-1) or check out our example game, [BitcraftMini](/docs/unity/part-3).
+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) or check out our example game, [BitcraftMini](/docs/unity/part-3).

docs/docs/modules/rust/quickstart.md

@@ -269,4 +269,4 @@ You can find the full code for this module [in the SpacetimeDB module examples](
 
 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), [TypeScript](/docs/sdks/typescript/quickstart) or [Python](/docs/sdks/python/quickstart).
 
-If you are planning to use SpacetimeDB with the Unity3d game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity/part-1) or check out our example game, [BitcraftMini](/docs/unity/part-3).
+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) or check out our example game, [BitcraftMini](/docs/unity/part-3).

docs/docs/sdks/c-sharp/index.md

@@ -17,9 +17,10 @@ The SpacetimeDB client C# for Rust contains all the tools you need to build nati
     - [Method `SpacetimeDBClient.Connect`](#method-spacetimedbclientconnect)
     - [Event `SpacetimeDBClient.onIdentityReceived`](#event-spacetimedbclientonidentityreceived)
     - [Event `SpacetimeDBClient.onConnect`](#event-spacetimedbclientonconnect)
-  - [Subscribe to queries](#subscribe-to-queries)
+  - [Query subscriptions & one-time actions](#subscribe-to-queries)
     - [Method `SpacetimeDBClient.Subscribe`](#method-spacetimedbclientsubscribe)
     - [Event `SpacetimeDBClient.onSubscriptionApplied`](#event-spacetimedbclientonsubscriptionapplied)
+    - [Method `SpacetimeDBClient.OneOffQuery`](#event-spacetimedbclientoneoffquery)
   - [View rows of subscribed tables](#view-rows-of-subscribed-tables)
     - [Class `{TABLE}`](#class-table)
       - [Static Method `{TABLE}.Iter`](#static-method-tableiter)
@@ -64,13 +65,11 @@ dotnet add package spacetimedbsdk
 
 ### Using Unity
 
-To install the SpacetimeDB SDK into a Unity project, download the SpacetimeDB SDK from the following link.
+To install the SpacetimeDB SDK into a Unity project, [download the SpacetimeDB SDK](https://github.com/clockworklabs/com.clockworklabs.spacetimedbsdk/releases/latest), packaged as a `.unitypackage`.
 
-https://sdk.spacetimedb.com/SpacetimeDBUnitySDK.unitypackage
+In Unity navigate to the `Assets > Import Package > Custom Package` menu in the menu bar. Select your `SpacetimeDB.Unity.Comprehensive.Tutorial.unitypackage` file and leave all folders checked.
 
-In Unity navigate to the `Assets > Import Package > Custom Package...` menu in the menu bar. Select your `SpacetimeDBUnitySDK.unitypackage` file and leave all folders checked.
-
-(See also the [Unity Tutorial](/docs/unity/part-1).)
+(See also the [Unity Tutorial](/docs/unity/part-1))
 
 ## Generate module bindings
 
@@ -319,6 +318,15 @@ void Main()
 }
 ```
 
+### Method [`OneTimeQuery`](#method-spacetimedbclientsubscribe)
+
+You may not want to subscribe to a query, but instead want to run a query once and receive the results immediately via a `Task` result:
+
+```csharp
+// Query all Messages from the sender "bob"
+SpacetimeDBClient.instance.OneOffQuery<Message>("WHERE sender = \"bob\"");
+```
+
 ## View rows of subscribed tables
 
 The SDK maintains a local view of the database called the "client cache". This cache contains whatever rows are selected via a call to [`SpacetimeDBClient.Subscribe`](#method-spacetimedbclientsubscribe). These rows are represented in the SpacetimeDB .Net SDK as instances of [`SpacetimeDB.Types.{TABLE}`](#class-table).