Unreal Blackholio Tutorial Documentation (#3253)

# Description of Changes

Closes: clockworklabs/SpacetimeDBPrivate#1926

Duplicated and rewrote the Unity Blackholio documentation to work with
the Unreal SpacetimeDb SDK.

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Documentation only

# Testing

- [x] Walk-through the documentation using the new Unreal SpacetimeDb
SDK

---------

Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Phoebe Goldman <phoebe@clockworklabs.io>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

Author: 4 people

docs/docs/nav.js

@@ -22,6 +22,12 @@ const nav = {
     page('2 - Connecting to SpacetimeDB', 'unity/part-2', 'unity/part-2.md'),
     page('3 - Gameplay', 'unity/part-3', 'unity/part-3.md'),
     page('4 - Moving and Colliding', 'unity/part-4', 'unity/part-4.md'),
+    section('Unreal Tutorial - Basic Multiplayer'),
+    page('Overview', 'unreal', 'unreal/index.md'),
+    page('1 - Setup', 'unreal/part-1', 'unreal/part-1.md'),
+    page('2 - Connecting to SpacetimeDB', 'unreal/part-2', 'unreal/part-2.md'),
+    page('3 - Gameplay', 'unreal/part-3', 'unreal/part-3.md'),
+    page('4 - Moving and Colliding', 'unreal/part-4', 'unreal/part-4.md'),
     section('CLI Reference'),
     page('CLI Reference', 'cli-reference', 'cli-reference.md'),
     page(
@@ -59,6 +65,7 @@ const nav = {
       'sdks/typescript/quickstart.md'
     ),
     page('TypeScript Reference', 'sdks/typescript', 'sdks/typescript/index.md'),
+    page('Unreal Reference', 'unreal/reference', 'unreal/reference.md'),
     section('SQL'),
     page('SQL Reference', 'sql', 'sql/index.md'),
     section('Subscriptions'),

docs/docs/unity/part-3.md

@@ -610,7 +610,7 @@ The `OnApplied` callback will be called after the server synchronizes the initia
 
 In the scene view, select the `GameManager` object. Click on the `Border Material` property and choose `Sprites-Default`.
 
-### Creating GameObjects 
+### Creating GameObjects
 
 Now that we have our arena all set up, we need to take the row data that SpacetimeDB syncs with our client and use it to create and draw `GameObject`s on the screen.
 

docs/docs/unreal/Circle.png

@@ -0,0 +1,36 @@
+# Unreal Tutorial - Overview
+
+Need help with the tutorial or CLI commands? [Join our Discord server](https://discord.gg/spacetimedb)!
+
+In this tutorial you'll learn how to build a small-scoped massive multiplayer online action game in Unreal, from scratch, using SpacetimeDB. Although, the game we're going to build is small in scope, it'll scale to hundreds of players and will help you get acquainted with all the features and best practices of SpacetimeDB, while building [a fun little game](https://github.com/ClockworkLabs/Blackholio).
+
+By the end, you should have a basic understanding of what SpacetimeDB offers for developers making multiplayer games.
+
+The game is inspired by [agar.io](https://agar.io), but SpacetimeDB themed with some fun twists. If you're not familiar [agar.io](https://agar.io), it's a web game in which you and hundreds of other players compete to cultivate mass to become the largest cell in the Petri dish.
+
+Our game, called [Blackhol.io](https://github.com/clockworklabs/SpacetimeDB/tree/master/demo/Blackholio), will be similar but space themed. It should give you a great idea of the types of games you can develop easily with SpacetimeDB.
+
+This tutorial assumes that you have a basic understanding of the Unreal Engine, using a command line terminal and programming in C++. 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.
+
+We’ll keep things intentionally simple: a single “Game Manager” class, minimal error handling, and hardcoded settings where convenient. This makes the SDK flow easy to see. For production, prefer Unreal’s Subsystems, move secrets out of code, follow best practices, and add proper logging/retry.
+
+SpacetimeDB supports Unreal Engine version `5.6`. This tutorial has been tested only with that version.
+
+This tutorial is written for C++, but the SpacetimeDB Unreal client SDK also supports Blueprints! Stay tuned for a Blueprint-based tutorial.
+
+Please file an issue [here](https://github.com/clockworklabs/SpacetimeDB/issues) if you encounter an issue with a specific Unreal version, but please be aware that the SpacetimeDB team is unable to offer support for issues related to versions of Unreal prior to `5.6`.
+
+## Blackhol.io Tutorial - Basic Multiplayer
+
+First you'll get started with the core client/server setup. For part 2, you'll be able to choose between [Rust](/docs/modules/rust) or [C#](/docs/modules/c-sharp) for your server module language:
+
+- [Part 1 - Setup](/docs/unreal/part-1)
+- [Part 2 - Connecting to SpacetimeDB](/docs/unreal/part-2)
+- [Part 3 - Gameplay](/docs/unreal/part-3)
+- [Part 4 - Moving and Colliding](/docs/unreal/part-4)
+
+## Blackhol.io Tutorial - Advanced
+
+If you already have a good understanding of the SpacetimeDB client and server, check out our completed tutorial project!
+
+https://github.com/clockworklabs/SpacetimeDB/tree/master/demo/Blackholio

docs/docs/unreal/index.md

@@ -0,0 +1,140 @@
+# Unreal Tutorial - Part 1 - Setup
+
+Need help with the tutorial? [Join our Discord server](https://discord.gg/spacetimedb)!
+
+> A completed version of the game we'll create in this tutorial is available at:
+>
+> https://github.com/clockworklabs/SpacetimeDB/tree/master/demo/Blackholio
+
+## Prepare Project Structure
+
+> **NOTE:** Ensure you have SpacetimeDB version 1.4.0 installed to enable Unreal Engine code generation support.
+
+This project is separated into two subdirectories;
+
+1. Server (module) code
+2. Client code
+
+First, we'll create a project root directory (you can choose the name):
+
+```bash
+mkdir blackholio
+cd blackholio
+```
+
+We'll start by populating the client directory.
+
+## Setting up the Tutorial Unreal Project
+
+In this section, we will guide you through the process of setting up a Unreal Project that will serve as the starting point for our tutorial. By the end of this section, you will have a basic Unreal project and be ready to implement the server functionality.
+
+### Step 1: Create a Blank Unreal Project
+
+SpacetimeDB supports Unreal version `5.6`. See [the overview](.) for more information on specific supported versions.
+
+Launch Unreal 5.6 and create a new project by selecting Games from the Unreal Project Browser.
+
+> ⚠️ Important: Select the **Blank** template and in **Project Defaults** select **C++**.
+
+For **Project Name** use `client_unreal`.
+For **Project Location**, use your `blackholio` directory (created in the previous step).
+
+Click **Create** to generate the blank project.
+
+![Create Blank Project](https://tmp-unreal-engine-tutorial-images.nyc3.digitaloceanspaces.com/part-1-01-create-project.png)
+
+### Import the SpacetimeDB Unreal SDK
+
+While the SpacetimeDB Unreal client SDK is in preview releases, it can only be installed from GitHub:
+
+> https://github.com/clockworklabs/SpacetimeDB/tree/master/sdks/unreal/src
+
+Once the SDK is stabilized, we'll find a more ergonomic way to distribute it.
+
+> **Note:** Before beginning make sure to close the Unreal project and IDE.
+
+#### Installation steps
+
+1. Navigate to your Unreal project directory and create a `Plugins` folder if it doesn’t already exist:
+   ```bash
+   cd client_unreal
+   mkdir Plugins
+   ```
+2. Download or clone the SDK from GitHub and copy the SpacetimeDbSdk folder into your new Plugins directory.
+   - This should create `/client_unreal/Plugins/SpacetimeDbSdk`.
+3. In the root of the Unreal project, right click the client_unreal.uproject and select **Generate Visual Studio project files**. On Windows 11 you may need to expand **Show more options** to select the generate option.
+
+![Generate project files](https://tmp-unreal-engine-tutorial-images.nyc3.digitaloceanspaces.com/part-1-02-01-generate-project.png)
+![Generate project files](https://tmp-unreal-engine-tutorial-images.nyc3.digitaloceanspaces.com/part-1-02-02-generate-project.png)
+
+### Create the GameManager Actor
+
+1. Open the `client_unreal` project in your IDE (Visual Studio or JetBrains Rider) and run the project to launch the Unreal Editor.
+   - This will enable **Live Coding**, making the workflow a bit smoother.
+   - Unreal will prompt you to build the `SpacetimeDbSdk` plugin. Do so.
+2. Open **Tools -> New C++ Class** in the top menu, select **Actor** as the parent and click **Next**
+3. Select **Public** Class Type
+4. Name the class `GameManager`.
+
+The `GameManager` class will be where we will put the high level initialization and coordination logic for our game.
+
+> **Note:** In a production Unreal project, you would typically implement this logic in a Subsystem. For simplicity, this tutorial uses a singleton actor.
+
+### Set Up the Level
+
+Set up the empty level, add the new `GameManager` to the level, and add lighting.
+
+1. **Create a new level**  
+   - Open **File -> New Level** in the top menu, select **Empty Level**, and click **Create**.  
+   - Save the level and name it `Blackholio`.
+
+2. **Create a GameManager Blueprint**  
+   - In the **Content Drawer**, click **Add**, then select **Blueprint -> Blueprint Class**.  
+   - Expand **All Classes**, search for **GameManager**, highlight it, and click **Select**.  
+   - Name the blueprint `BP_GameManager`.
+
+   ![Pick Parent Class](https://tmp-unreal-engine-tutorial-images.nyc3.digitaloceanspaces.com/part-1-03-create-blueprint.png)
+
+3. **Update Maps & Modes**  
+   - Open **Edit -> Project Settings** in the top menu, then select **Project -> Maps & Modes** on the left.  
+   - Set **Editor Startup Map** to `Blackholio`.  
+   - Set **Game Default Map** to `Blackholio`.
+
+4. **Add to the Level**  
+   - Drag the `BP_GameManager` blueprint from the **Content Drawer** into the scene view.
+
+5. **Add a Directional Light**  
+   - Click **Add** in the top toolbar, then select **Lights -> Directional Light**.  
+   - Set **Rotation** to -105.0, -31.0, -14.0.
+
+6. **Add a Post Process Volume**  
+   - Click **Add** in the top toolbar, then select **Volumes -> Post Process Volume**.  
+   - Enable and set **Exposure -> Exposure Compensation** to 0.0.  
+   - Enable and set **Exposure -> Min EV100** to 1.0.  
+   - Enable and set **Exposure -> Max EV100** to 1.0.  
+   - Enable **Post Process Volume Settings -> Infinite Extend (Unbounded)**.
+
+### Add a Simple GameMode
+
+Create a simple GameMode to tweak the startup settings and connect it to the World Settings.
+
+1. **Create the C++ class**  
+   - Open **Tools -> New C++ Class** in the top menu, select **GameModeBase** as the parent, and click **Next**.  
+   - Select **Public** as the class type.  
+   - Name the class `BlackholioGameMode`.
+
+2. **Create a GameMode Blueprint**  
+   - In the **Content Drawer**, click **Add**, then select **Blueprint -> Blueprint Class**.  
+   - Expand **All Classes**, search for `BlackholioGameMode`, highlight it, and click **Select**.  
+   - Name the blueprint `BP_BlackholioGameMode`.
+
+3. **Update World Settings**  
+   - Open **Window -> World Settings** in the top menu.  
+   - Change **GameMode Override** from **None** to `BP_BlackholioGameMode`.  
+   - Save the level.
+
+At this point, the foundation of the Unreal project is set up. Pressing Play will show a blank screen, but the game should start without errors. Next, we’ll create the SpacetimeDB server module so we have something to connect to.
+
+### Create the Server Module
+
+We've now got the very basics set up. In [part 2](part-2) you'll learn the basics of how to create a SpacetimeDB server module and how to connect to it from your client.