clockworklabs · dylanh724 · Feb 7, 2024 · Feb 8, 2024 · Feb 8, 2024 · Feb 8, 2024
diff --git a/docs/deploying/hosted.md b/docs/deploying/hosted.md
@@ -0,0 +1,74 @@
+# Deploying - Hosted
+
+This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI. Via CLI, we will then:
+
+1. Ensure our hosted server named `testnet` exists as the default.
+1. Create an `Identity`.
+1. `Publish` your app.
+
+💡 This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI and that you already have `testnet` server added (exists by default). If you accidentally removed `testnet`, add it back via CLI:
+
+```bash
+spacetime server add "https://testnet.spacetimedb.com" testnet
+```
+
+## SpacetimeDB Cloud (Hosted) Deployment
+
+Currently, for hosted deployment, only the `testnet` server is available for SpacetimeDB cloud, which is subject to wipes.
+
+📢 Stay tuned (such as [via Discord](https://discord.com/invite/SpacetimeDB)) for `mainnet` coming soon!
+
+## Set the Server Default
+
+To make CLI commands easier so that we don't need to keep specifying `testnet` as the target server, let's set it as default: 
+
+```bash
+spacetime server set-default testnet
+```
+
+## Creating an Identity
+
+By default, there are no identities created. Let's create a new one via CLI:
+```bash
+spacetime identity new --name {Nickname} --email {Email}
+```
+
+💡If you already created an identity but forgot to attach an email, add it via CLI:
+```bash
+spacetime identity set-email {Email}
+```
+
+## Create and Publish a Module
+
+Let's create a vanilla Rust module called `HelloSpacetimeBD` from our home dir, then publish it "as-is". For Windows users, use `PowerShell`:
+
+```bash
+cd ~
+spacetime init --lang rust HelloSpacetimeDB
+cd HelloSpacetimeDB
+spacetime publish HelloSpacetimeDB
+```
+
+## Hosted Web Dashboard
+
+By earlier associating an email with your CLI identity, you can now view your published modules on the web dashboard. For multiple identities, first list them and copy the hash you want to use:
+
+```bash
+spacetime identity list
+```
+
+1. Open the SpacetimeDB [login page](https://spacetimedb.com/login) using the same email above.
+1. Choose your identity from the dropdown menu.
+   - \[For multiple identities\] `CTRL+F` to highlight the correct identity you copied earlier.
+1. Check your email for a validation link.
+
+You should now be able to see your published modules on the web dashboard!
+
+---
+
+## Summary
+
+- We ensured the hosted `testnet` server existed, then set it as the default.
+- We added an `identity` to bind with our hosted `testnet` server, ensuring it contained both a Nickname and Email.
+- We then logged in the web dashboard via an email `one-time password (OTP)` and were then able to view our published apps.
+- With SpacetimeDB Cloud, you benefit from automatic scaling, robust security, and the convenience of not having to manage the hosting environment.
diff --git a/docs/deploying/index.md b/docs/deploying/index.md
@@ -0,0 +1,48 @@
+# Deploying Overview
+
+SpacetimeDB supports both hosted and self-hosted publishing in multiple ways. Below, we will:
+
+1. Generally introduce Identities.
+1. Generally introduce Servers.
+1. Choose to proceed with either a [Hosted](/docs/deploying/hosted.md) or [Self-Hosted](/docs/deploying/self-hosted.md) deployment.
+
+💡 This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI.
+
+## About Identities
+
+An `Identity` is a hash attached to a `Nickname` and `Email`, allowing you to manage your app (such as `Publishing` your app).
+
+Each `Identity` is bound to one, single `Server`: Unlike GitHub, for example, you would require one identity per server.
+
+By default, there are no identities created. While the next tutorial will go more in-depth, you may create a new one via CLI:
+```bash
+spacetime identity new --name {Nickname} --email {Email}
+```
+
+See the verbose [overview identity explanation](https://spacetimedb.com/docs#identities), [API reference](/docs/http/identity.md) or CLI help (below) for further managing `Identities`:
+```bash
+spacetime identity --help
+```
+
+## About Servers
+
+You `publish` your app to a target `Server` database: While we recommend to **host** your SpacetimeDB app with us for simplicity and scalability, you may also **self-host** (such as locally).
+
+By default, there are already two default servers added ([testnet](/docs/deploying/hosted.md) and [local](/docs/deploying/self-hosted.md)). While the next tutorial will go more in-depth, you may list your servers via CLI:
+```bash
+spacetime server list
+```
+
+See the [API reference](/docs/http/database.md) or CLI help (below) for further managing `Servers`:
+```bash
+spacetime server --help
+```
+
+---
+
+## Deploying via CLI
+
+Choose a server for your hosting tutorial path to set a server as default, create an identity, and deploy (`publish`) your app:
+
+1. [testnet](/docs/deploying/hosted.md) (hosted)
+2. [local](/docs/deploying/self-hosted.md) (self-hosted)
diff --git a/docs/deploying/self-hosted.md b/docs/deploying/self-hosted.md
@@ -0,0 +1,60 @@
+# Deploying - Self-Hosted
+
+This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI. Via CLI, we will then:
+
+1. Ensure our localhost server named `local` exists as the default.
+1. Start our localhost server in a separate terminal window.
+1. Create an `Identity` with at least a Nickname.
+1. `Publish` your app.
+
+💡 This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI and that you already have `local` server added (exists by default). If you accidentally removed `local`, add it back via CLI with the `--no-fingerprint` flag (since our server is not yet running):
+
+```bash
+spacetime server add "http://127.0.0.1:3000" local --no-fingerprint
+```
+
+## Set the Server Default
+
+To make CLI commands easier so that we don't need to keep specifying `local` as the target server, let's set it as default:
+
+```bash
+spacetime server set-default local
+```
+
+## Start the Local Server
+
+In a **separate** terminal window, start the local listen server in the foreground:
+```bash
+spacetime start
+```
+
+## Creating an Identity
+
+By default, there are no identities created. Let's create a new one via CLI:
+```bash
+spacetime identity new --name {Nickname}
+```
+
+💡We could optionally add `--email {Email}` to the above command, but is currently unnecessary for local deployment since there's no web dashboard. If you already created an identity but forgot to attach a Nickname, add it via CLI to easier identify your modules:
+```bash
+spacetime identity set-name {Nickname}
+```
+
+## Create and Publish a Module
+
+Let's create a vanilla Rust module called `HelloSpacetimeBD` from our home dir, then publish it "as-is". For Windows users, use `PowerShell`:
+
+```bash
+cd ~
+spacetime init --lang rust HelloSpacetimeDB
+cd HelloSpacetimeDB
+spacetime publish HelloSpacetimeDB
+```
+
+---
+
+## Summary
+
+- We ensured the self-hosted `local` server existed, then set it as the default. 
+- We then opened a separate terminal to run the self-hosted `local` server in the foreground.
+- We added an `identity` to bind with our self-hosted `local` server set to default, ensuring it contained a Nickname.
diff --git a/docs/deploying/testnet.md b/docs/deploying/testnet.md
diff --git a/docs/index.md b/docs/index.md
@@ -94,29 +94,27 @@ SpacetimeDB was designed first and foremost as the backend for multiplayer Unity
 1. What is SpacetimeDB?
    It's a whole cloud platform within a database that's fast enough to run real-time games.
 
-1. How do I use SpacetimeDB?
+2. How do I use SpacetimeDB?
    Install the `spacetime` command line tool, choose your favorite language, import the SpacetimeDB library, write your application, compile it to WebAssembly, and upload it to the SpacetimeDB cloud platform. Once it's uploaded you can call functions directly on your application and subscribe to changes in application state.
 
-1. How do I get/install SpacetimeDB?
+3. How do I get/install SpacetimeDB?
    Just install our command line tool and then upload your application to the cloud.
 
-1. How do I create a new database with SpacetimeDB?
+4. How do I create a new database with SpacetimeDB?
    Follow our [Quick Start](/docs/getting-started) guide!
 
-TL;DR in an empty directory:
+TL;DR in an empty directory, init and publish a barebones app named HelloWorld.
 
 ```bash
 spacetime init --lang=rust
-spacetime publish
+spacetime publish HelloWorld
 ```
 
 5. How do I create a Unity game with SpacetimeDB?
    Follow our [Unity Project](/docs/unity-project) guide!
 
-TL;DR in an empty directory:
+TL;DR after already initializing and publishing (see FAQ #5), generate the SDK:
 
 ```bash
-spacetime init --lang=rust
-spacetime publish
 spacetime generate --out-dir <path-to-unity-project> --lang=csharp
 ```
diff --git a/docs/modules/c-sharp/index.md b/docs/modules/c-sharp/index.md
@@ -4,6 +4,36 @@ You can use the [C# SpacetimeDB library](https://github.com/clockworklabs/Spacet
 
 It uses [Roslyn incremental generators](https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.md) to add extra static methods to types, tables and reducers marked with special attributes and registers them with the database runtime.
 
+## C# Module Limitations & Nuances
+
+Since SpacetimeDB runs on [WebAssembly (WASM)](https://webassembly.org/), it's important to be aware of the following:
+
+1. No DateTime-like types in Types or Tables:
+   - Use `long` for microsecond unix epoch timestamps
+   - See example usage and converts at the [_TimeConvert_ module demo class](https://github.com/clockworklabs/zeke-demo-project/blob/3fa1c94e75819a191bd785faa7a7d15ea4dc260c/Server-Csharp/src/Utils.cs#L19) 
+
+
+2. No Timers or async/await, such as those to create repeating loops:
+   - For repeating invokers, instead **re**schedule it from within a fired [Scheduler](https://spacetimedb.com/docs/modules/c-sharp#reducers) function.
+
+
+3. Using `Debug` advanced option in the `Publisher` Unity editor tool will add callstack symbols for easier debugging:
+   - However, avoid using `Debug` mode when publishing outside a `localhost` server:
+      - Due to WASM buffer size limitations, this may cause publish failure.
+
+
+4. If you `throw` a new `Exception`, no error logs will appear. Instead, use either:
+   1. Use `Log(message, LogLevel.Error);` before you throw.
+   2. Use the demo's static [Utils.cs](https://github.com/clockworklabs/zeke-demo-project/tree/dylan/feat/mini-upgrade/Server-Csharp/src/Utils.cs) class to `Utils.Throw()` to wrap the error log before throwing.
+
+
+5. `[AutoIncrement]` or `[PrimaryKeyAuto]` will never equal 0:
+   - Inserting a new row with an Auto key equaling 0 will always return a unique, non-0 value.
+
+
+6. Enums cannot declare values out of the default order:
+   - For example, `{ Foo = 0, Bar = 3 }` will fail to compile.
+
 ## Example
 
 Let's start with a heavily commented version of the default example from the landing page:

diff --git a/docs/nav.js b/docs/nav.js
@@ -9,14 +9,22 @@ function section(title) {
 const nav = {
     items: [
         section("Intro"),
-        page("Overview", "index", "index.md"),
+        page("Overview", "index", "index.md"), // TODO(BREAKING): For consistency & clarity, 'index' slug should be renamed 'intro'?
+        page("Getting Started", "getting-started", "getting-started.md"),
+        page("Overview", "index", "index.md"), // TODO(BREAKING): For consistency & clarity, 'index' slug should be renamed 'intro'?
         page("Getting Started", "getting-started", "getting-started.md"),
         section("Deploying"),
-        page("Testnet", "deploying/testnet", "deploying/testnet.md"),
-        section("Unity Tutorial"),
-        page("Part 1 - Basic Multiplayer", "unity/part-1", "unity/part-1.md"),
-        page("Part 2 - Resources And Scheduling", "unity/part-2", "unity/part-2.md"),
-        page("Part 3 - BitCraft Mini", "unity/part-3", "unity/part-3.md"),
+        page("Overview", "deploying", "deploying/index.md"),
+        page("Hosted", "deploying/hosted", "deploying/hosted.md"),
+        page("Self-Hosted", "deploying/hosted", "deploying/self-hosted.md"),
+        section("Unity Tutorial - Basic Multiplayer"),
+        page("Overview", "unity-tutorial", "unity/index.md"),
+        page("1 - Project Setup", "unity/part-1", "unity/part-1.md"),
+        page("2 - Server (C# Module)", "unity/part-2", "unity/part-2a-rust.md"),
+        page("3 - Client (Unity)", "unity/part-2", "unity/part-2.md"),
+        section("Unity Tutorial - Advanced"),
+        page("4 - Resources & Scheduling", "unity/part-4", "unity/part-4.md"),
+        page("5 - BitCraft Mini", "unity/part-5", "unity/part-5.md"),
         section("Server Module Languages"),
         page("Overview", "modules", "modules/index.md"),
         page("Rust Quickstart", "modules/rust/quickstart", "modules/rust/quickstart.md"),

diff --git a/docs/sdks/c-sharp/index.md b/docs/sdks/c-sharp/index.md
@@ -65,11 +65,12 @@ dotnet add package spacetimedbsdk
 
 ### Using Unity
 
-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`.
-
-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.
+To install the SpacetimeDB SDK into a Unity project, simply add the following line to your `Packages/manifest.json`:
+```json
+"com.clockworklabs.spacetimedbsdk": "https://github.com/clockworklabs/com.clockworklabs.spacetimedbsdk.git"
+```
 
-(See also the [Unity Tutorial](/docs/unity/part-1))
+💡 See also the [Unity Tutorial](/docs/unity/index.md)
 
 ## Generate module bindings
 

diff --git a/docs/unity/index.md b/docs/unity/index.md
@@ -1,23 +1,24 @@
 # Unity Tutorial Overview
 
-Need help with the tutorial or CLI commands? [Join our Discord server](https://discord.gg/spacetimedb)!
+> [!IMPORTANT]
+> TODO: This draft may link to WIP repos, docs or temporarily-hosted images - be sure to replace with final links/images after prerequisite PRs are approved (that are not yet approved upon writing this) -> then delete this memo.
 
-The objective of this progressive tutorial is to help you become acquainted with the basic features of SpacetimeDB. By the end, you should have a basic understanding of what SpacetimeDB offers for developers making multiplayer games. It assumes that you have a basic understanding of the Unity Editor, using a command line terminal and coding.
+💡 Need help? [Join our Discord server](https://discord.gg/spacetimedb)!
+
+The objective of this progressive tutorial is to help you become acquainted with the basic features of SpacetimeDB. By the end, you should have a basic understanding of what SpacetimeDB offers for developers making multiplayer games. It assumes that you have a basic understanding of the Unity Editor, Git, using a commandline terminal and coding.
 
 We'll give you some CLI commands to execute. If you are using Windows, we recommend using Git Bash or PowerShell. For Mac, we recommend Terminal.
 
-Tested with UnityEngine `2022.3.20f1 LTS` (and may also work on newer versions).
+Tested with Unity `2022.3.20 LTS` (and may also work on newer versions). We'll be opening .cs files in an IDE like _Visual Studio_ or _Rider_.
 
 ## Unity Tutorial - Basic Multiplayer
 Get started with the core client-server setup. For part 2, you may choose your server module preference of [Rust](/docs/modules/rust) or [C#](/docs/modules/c-sharp):
 
-- [Part 1 - Setup](/docs/unity/part-1.md)
-- [Part 2a - Server (Rust)](/docs/unity/part-2a-rust.md)
-- [Part 2b - Server (C#)](/docs/unity/part-2b-csharp.md)
-- [Part 3 - Client](/docs/unity/part-3.md)
+![Core Architecture](/images/unity-tutorial/overview/core-architecture.png)
+<!-- ![Core Architecture-PREV](https://i.imgur.com/Me0JlsK.png) -->
 
-## Unity Tutorial - Advanced
-By this point, you should already have a basic understanding of SpacetimeDB client, server and CLI:
+1. [Setup](/docs/unity/part-1.md)
+2. [Server (C#)](/docs/unity/part-2.md) ☼
+3. [Client (Unity)](/docs/unity/part-3.md)
 
-- [Part 4 - Resources & Scheduling](/docs/unity/part-4.md)
-- [Part 5 - BitCraft Mini](/docs/unity/part-5.md)
+☼ While the tutorial uses C#, the repo cloned in [Part 1](/docs/unity/part-1.md) does include a legacy Rust example to optionally use, instead.