From 57bed114ba50ed1b9e57d4f778c5f606d46ffc9b Mon Sep 17 00:00:00 2001 From: Andrew Barnett Date: Thu, 29 Jan 2026 16:54:20 -0500 Subject: [PATCH] Drew Docs edits, UE: SDK User References/Editor Systems --- .../editor-systems/editor-systems-overview.md | 22 ++++---- .../editor-systems/pie-settings.md | 15 ++--- docs/unreal/user-reference/overview.md | 56 +++++++++++-------- 3 files changed, 51 insertions(+), 42 deletions(-) diff --git a/docs/unreal/user-reference/editor-systems/editor-systems-overview.md b/docs/unreal/user-reference/editor-systems/editor-systems-overview.md index 2b9473736..0d2be6666 100644 --- a/docs/unreal/user-reference/editor-systems/editor-systems-overview.md +++ b/docs/unreal/user-reference/editor-systems/editor-systems-overview.md @@ -2,29 +2,29 @@ Beamable Unreal SDK provides a set of editor systems that help you manage multiple aspects of your game integration. These systems are designed to integrate seamlessly with the Unreal Engine editor, allowing you to access Beamable features directly from the editor. -## The Beamable Editor Panel +## Beamable Editor Panel ![editor-home.png](../../../media/imgs/editor-home.png) -The Beamable Editor Panel is the main interface for interacting with Beamable features in the Unreal Engine editor.It provides access to various tools and settings that allow you to manage your game integration, including: +The Beamable Editor Panel is the main interface for interacting with Beamable features in the Unreal Engine editor. It provides access to various tools and settings that allow you to manage your game integration, including: -* **Home**: A dashboard that provides an overview of your Beamable project, including current realm and quick access to the Portal. -* **Beamable Content Editor**: A tool for managing your game content, including assets, blueprints, and other resources. -* **Microservices**: A system for managing and run local microservices that can extend the functionality of your game. -* **PIE Settings**: A set of settings that allow you to configure your game for Play In Editor (PIE) mode, including player profiles and custom play presets. +* **Home**: dashboard that provides an overview of your Beamable project, including current realm and quick access to the Portal. +* **Beamable Content Editor**: tool for managing your game content, including assets, blueprints, and other resources. +* **Microservices**: system for managing and running local microservices that can extend the functionality of your game. +* **PIE Settings**: set of settings that allow you to configure your game for Play In Editor (PIE) mode, including player profiles and custom play presets. ### Accessing the Beamable Editor Panel -To open the Beamable Editor Panel, go to the **Beamable** icon in the right side of the Unreal Engine editor toolbar and click on" it. This will open the Beamable Editor Panel, where you can access all the available features and settings. +To open the Beamable Editor Panel, select the **Beamable** icon on the right side of the Unreal Engine toolbar. This will open the Beamable Editor Panel, where you can access all available features and settings. ![editor-home-opening.png](../../../media/imgs/editor-home-opening.png) ### Home Section -The Home section allows you to select the current realm for your project and provides quick access to the Beamable Portal. The realm selection is located at the top of the panel, and you can switch between different realms as needed. By using the **Apply to Build** button, you can apply the selected realm to your current build configuration. +The Home section allows you to select the current realm for your project and provides quick access to the Beamable Portal. Realm selection is located at the top of the panel, and you can switch between different realms as needed. By using the **Apply to Build** button, you can apply the selected realm to your current build configuration. In the same section, you can also find the **Home Dashboard** button, which will open the Beamable Portal in your web browser, allowing you to manage your project settings and resources online. There's also other shortcuts to the Portal specific sections, such as the **Microservices** and **Content**. ### Other Sections You will find specific documentation for each of the editor systems in the following pages: -- [Content](../beamable-services/content.md): A tool for managing your game content, -- [Microservices](../microservices/microservices.md): A system for managing and running local microservices, -- [PIE Settings](pie-settings.md): A set of settings that allow you to configure \ No newline at end of file +- [Content](../beamable-services/content.md): tool for managing your game content. +- [Microservices](../microservices/microservices.md): system for managing and running local microservices. +- [PIE Settings](pie-settings.md): set of settings that allow you to configure your game for Play In Editor. \ No newline at end of file diff --git a/docs/unreal/user-reference/editor-systems/pie-settings.md b/docs/unreal/user-reference/editor-systems/pie-settings.md index cd067b526..a183409d8 100644 --- a/docs/unreal/user-reference/editor-systems/pie-settings.md +++ b/docs/unreal/user-reference/editor-systems/pie-settings.md @@ -2,7 +2,7 @@ The new Beamable PIE Settings provide a flexible way to configure your game for Play In Editor (PIE). With this system, you can create, capture, and save player profiles for use at runtime, as well as define custom play presets directly within your Unreal projects. -This enables you to test your game across multiple configurations and entry points without repeatedly changing project settings. You can even simulate custom lobbies inside **Gameplay Level** while even overriding both per-player and global settings. +This enables you to test your game across multiple configurations and entry points without repeatedly changing project settings. You can even simulate custom lobbies inside **Gameplay Levels** while overriding both per-player and global settings. !!! warning "PIE Settings are Experimental" PIE Settings are currently marked as Experimental under `Project Settings > Engine > Beamable Core` and are disabled by default. @@ -44,7 +44,8 @@ To create a new Play Preset, click the **Create New Preset** button. You can the ![pie-use-preset.png](../../../media/imgs/pie-use-preset.png) -**_IMPORTANT: When "None" is selected, the entire system is disabled; including the automatic Beamable SDK initialization._** +!!! warning "IMPORTANT" +When "None" is selected, the entire system is disabled; including the automatic Beamable SDK initialization._ ### Map Settings Play Presets can be configured to apply to specific maps or a list of maps which match the name rule requirement (Regex). This allows you to have different presets for different levels or game modes. You can specify the maps in the **Available Maps** list of the preset editor and/or add a name rule in the Map Name Pattern in case you have a lot of maps. @@ -54,14 +55,14 @@ Play Presets can be configured to apply to specific maps or a list of maps which ### Fake Lobbies Play Presets can be configured to initialize lobbies for PIE, allowing you to test multiplayer scenarios with real Beamable accounts **_directly in PIE from the Gameplay Level_**. This is especially useful when testing games that use the **Gameplay Level** as the entry point, since it ensures the initialization of Beamable systems and lobby setup. Normally, this initialization would occur in earlier Levels, such as the **Main Boot Level** (Main Menu/Title Screen/etc...). -!!! warning "Integration with Beamable Realtime Multiplayer Systems" +!!! warning "Tight Integration with Beamable Realtime Multiplayer Systems" Play Presets' PIE Lobby feature is tightly integrated with the Beamable Runtime Multiplayer Systems, having some requirements in your scenes to work properly. For more information, check the [Realtime Multiplayer Overview](../realtime-multiplayer/realtime-multiplayer-overview.md) page. In the PIE Lobby Settings you can configure: -- **Enable/Disable**: The Checkbox in the header enables or disables the PIE Lobby simulation for this preset. -- **Server Map Override**: The map that will be used as the server map for the PIE Lobby. This overrides the default server map defined in the Unreal Project Settings. -- **Game Type**: The Game Type content that will be used for the PIE Lobby Scene. If there is a federation configured here, the federation does run too. +- **Enable/Disable**: checkbox in the header enables or disables the PIE Lobby simulation for this preset. +- **Server Map Override**: map that will be used as the server map for the PIE Lobby. This overrides the default server map defined in the Unreal Project Settings. +- **Game Type**: Game Type content that will be used for the PIE Lobby Scene. If there is a federation configured here, the federation does run too. - **Lobby Global Data**: Custom Global Key-Value pairs that will be used to initialize the PIE Lobby. This data is available in the Gameplay Scene and can be used to simulate different scenarios. ![pie-fake-lobby.png](../../../media/imgs/pie-fake-lobby.png) @@ -77,7 +78,7 @@ For the most part, adding users will configure this correctly. We also do valida When selecting players, a few things are relevant: - You can check `Copy on PIE` in order to get a new user with Stats and Inventory copied from the selected user account. This is useful when you want to keep a consistent starting state so you can test things (think of keeping users at various progression points in your game). -- **Shared Users** will always `Copy on PIE`. This is because Shared Users are meant a workflow baseline. The recommendation is that designer leads can leverage this to enforce in-house workflows, training and on-boarding. +- **Shared Users** will always `Copy on PIE`. This is because Shared Users are meant a workflow baseline. The recommendation is that design leads can leverage this to enforce in-house workflows, training and on-boarding. - **Users from realms other than your current one** will also always `Copy on PIE`. This is because BeamPIE cannot sign in with a user from another realm into a different one. So we copy it instead. When Fake Lobbies are enabled, the Add Lobby Data will be available to add custom Key-Value pairs that will be used to initialize the per-player key-value store lobby itself. This data is accessible in the Gameplay Level and can be used to simulate various scenarios such as the selection of which skin the player chose or many other parameters that would get put into the lobby either via Federation or Matchmaking/Lobby systems themselves. diff --git a/docs/unreal/user-reference/overview.md b/docs/unreal/user-reference/overview.md index 3abcdeb1f..d4b9f8c33 100644 --- a/docs/unreal/user-reference/overview.md +++ b/docs/unreal/user-reference/overview.md @@ -1,35 +1,38 @@ # SDK Technical Overview The Beamable SDK is a collection of custom UE `Engine`, `Editor` and `GameInstance` Subsystems. -If you are not familiar with Unreal Subsystems, you can [take a look at their docs here](https://dev.epicgames.com/documentation/en-us/unreal-engine/programming-subsystems-in-unreal-engine). +If you are not familiar with Unreal Subsystems, you can take a look at their docs [here](https://dev.epicgames.com/documentation/en-us/unreal-engine/programming-subsystems-in-unreal-engine). **Game-Maker Code** (as in, code the Beamable customer writes) can take advantage of various guarantees we provide by understanding how these subsystems work. +### Plugin Modules The SDK's Plugin is divided into several modules: - **BeamableCore** contains the `UEngineSubsystem` implementations shared between `Editor` and `Runtime` executing environments. It also contains the `UBeamContentObject` schema definitions for our [content system](beamable-services/content.md). -- **BeamableCoreRuntime** contains the `UBeamRuntime` and `UBeamRuntimeSubsystem` implementations and manage the SDK lifecycle at runtime (during PIE and in packaged clients). +- **BeamableCoreRuntime** contains the `UBeamRuntime` and `UBeamRuntimeSubsystem` implementations and manages the SDK lifecycle at runtime (during PIE and in packaged clients). - **BeamableCoreEditor** and **BeamableCoreRuntimeEditor** contains `UBeamEditor` and our editor integration code: custom BlueprintNodes, PropertyCustomizations, etc... -For any technical lead (making system-level decisions), effective use of Beamable and the Unreal SDK requires you to understand a few core concepts. So, after reading this document, you'll want to start here: +### Core Concepts -- [**Content**](beamable-services/content.md) is how you define your game's configuration --- balancing data, currency and item definitions, etc... Most of our systems depend on Content so, its a good place to start. -- [**Identity**](beamable-services/identity.md) the various ways you can manage a player's account and login flows. -- [**Microservices**](microservices/microservices.md) are our version of cloud-code --- but also much more. -- [**Federation**](federation/federation.md) are effectively exposed hooks in our backend's various features that you can hook into with custom behavior. You can leverage this for integrating with third-party authentication, initial player state and a lot more. +For any technical lead making system-level decisions, effective use of Beamable and the Unreal SDK requires you to understand a few core concepts. So, after reading this document, you'll want to start here: + +- [**Content**](beamable-services/content.md): how you define your game's configuration -- balancing data, currency and item definitions, etc. Most of our systems depend on Content, so its a good place to start. +- [**Identity**](beamable-services/identity.md): the various ways you can manage a player's account and login flows. +- [**Microservices**](microservices/microservices.md): our version of cloud-code -- but also much more. +- [**Federation**](federation/federation.md): effectively exposed hooks in our backend's various features that you can hook into with custom behavior. You can leverage this for integrating with third-party authentication, initial player state and a lot more. Aside from those core concepts, the links below explain some of our higher-level systems. -- [**Stats**](beamable-services/stats.md) and [**Inventory**](beamable-services/inventory.md) are our general-case player-data stores. You can use these to store player-related data and implement a variety of features. -- [**Matchmaking**](beamable-services/matchmaking.md), [**Lobbies**](beamable-services/lobbies.md), [**Friends**](beamable-services/friends.md) and [**Parties**](beamable-services/parties.md) are part of our suite of services for real-time multiplayer games. -- [**Stores**](beamable-services/stores.md), [**Leaderboards**](beamable-services/leaderboards.md) and [**Announcements**](beamable-services/announcements.md) are part of our suite of services to help with live-ops meta-game engagement. +- [**Stats**](beamable-services/stats.md) and [**Inventory**](beamable-services/inventory.md) are our general-case player-data stores. These can be used to store player-related data and implement a variety of features. +- [**Matchmaking**](beamable-services/matchmaking.md), [**Lobbies**](beamable-services/lobbies.md), [**Friends**](beamable-services/friends.md) and [**Parties**](beamable-services/parties.md) are all parts of our suite of services for real-time multiplayer games. +- [**Stores**](beamable-services/stores.md), [**Leaderboards**](beamable-services/leaderboards.md) and [**Announcements**](beamable-services/announcements.md) are all parts of our suite of services to help with live-ops meta-game engagement. ## Beamable Runtime SDK -`UBeamRuntime` is the entry point for the Beamable SDK at runtime (PIE, packaged game clients and dedicated servers). It is a `GameInstanceSubsystem` and follows its lifecycle rules. It is responsible for a couple of things: +`UBeamRuntime` is the entry point for the Beamable SDK at runtime (PIE, packaged game clients, and dedicated servers). It is a `GameInstanceSubsystem` and follows its lifecycle rules. It is responsible for a couple of things: -- It controls the SDK's runtime initialization flow. -- It controls the various SDK's user \[un\]-authentication flows. -- It controls `UBeamRuntimeSubsystems'` lifecycle with respect to the SDK's initialization flow itself and `FUserSlot` authentication. +- Controls the SDK's runtime initialization flow. +- Controls the various SDK's user \[un\]-authentication flows. +- Controls `UBeamRuntimeSubsystems'` lifecycle with respect to the SDK's initialization flow itself and `FUserSlot` authentication. The image below describes how the SDK's lifecycle injects itself into UE's lifecycle: @@ -42,23 +45,23 @@ The next image shows a high-level description of the authentication flows suppor **_We highly recommend that every engineer working with Beamable understand this lifecycle!_** It should enable them to make the best use and decisions when designing systems with or on top of Beamable. ### Beamable Runtime Subsystems -`BeamRuntimeSubsystems` are stateful subsystems that aim to provide an extendable baseline of some Beamable functionality. They are built on top of our auto-generated lower-level API (`UBeam____Api` classes) to make it simpler to leverage our APIs; that way: +`BeamRuntimeSubsystems` are stateful subsystems that aim to provide an extendable baseline of some Beamable functionality. They are built on top of our auto-generated lower-level API (`UBeam____Api` classes) to make it simpler to leverage our APIs so that: 1. You don't have to set up the common case. 2. You can use them and their extension points for variations of the common case. 3. You can use them as reference implementations to implement your own custom use cases. -These are handwritten and maintained by the Beamable SDK team. Here's a few examples: +These are handwritten and maintained by the Beamable SDK team. Here are a few examples: -- `UBeamStatsSubsystem`: This enables you to store arbitrary key-value pairs associated to a player's account. -- `UBeamInventorySubsystem`: This provides builder functions around our Inventory APIs that allows you to combine what would be multiple API requests into a single batched inventory update. It also receives inventory notifications coming from the server and keeps your in-memory player state in sync. -- `UBeamMatchmakingSubsystem`: This provides you a stateful way of joining/canceling a matchmaking queue and receiving updates when a match is found. +- `UBeamStatsSubsystem`: enables you to store arbitrary key-value pairs associated to a player's account. +- `UBeamInventorySubsystem`: provides builder functions around our Inventory APIs that allows you to combine what would be multiple API requests into a single batched inventory update. It also receives inventory notifications coming from the server and keeps in-memory player state in sync. +- `UBeamMatchmakingSubsystem`: provides a stateful way of joining/canceling a matchmaking queue and receiving updates when a match is found. -These systems make use of the various `UBeamRuntimeSubsystem` callbacks to keep their state correct and expose callbacks and configuration options for **Game-Maker Code** to run with semantically relevant guarantees. Coupled with [Federations](federation/federation.md), these guarantees can be leveraged to greatly simplify the complexity of client implementations --- usually reducing the complexity and cost of your game's systems implementation. +These systems make use of the various `UBeamRuntimeSubsystem` callbacks to keep their state correct and expose callbacks and configuration options for **Game-Maker Code** to run with semantically relevant guarantees. Coupled with [Federations](federation/federation.md), these guarantees can be leveraged to greatly simplify the complexity of client implementations -- usually reducing the complexity and cost of your game's systems implementation. All of our [Blueprint](runtime-systems/blueprints.md) nodes, except our **Low-Level** ones, are backed by these sub-system implementations. -If the exposed hooks on these are not enough for your use case and constraints, as a user you can create your own `UBeamRuntimeSubsystem`. The SDK does not obfuscate its inner-workings from you so you can use the existing `UBeamRuntimeSubsystems` as a reference to understand how to create your own. The documentation in [Lower Level SDK](runtime-systems/lower-level.md) and [Operations & Waits](runtime-systems/operations-and-waits.md) can also be useful when implementing your own `UBeamRuntimeSubsystems`. +If the exposed hooks on these are not enough for your use case and constraints, you can create your own `UBeamRuntimeSubsystem`. The SDK does not obfuscate its inner-workings from you so you can use the existing `UBeamRuntimeSubsystems` as a reference to understand how to create your own. The documentation on [Lower Level SDK](runtime-systems/lower-level.md) and [Operations & Waits](runtime-systems/operations-and-waits.md) can also be useful when implementing your own `UBeamRuntimeSubsystems`. #### Advanced - Disabling Runtime Subsystems @@ -74,9 +77,9 @@ Keep in mind that the simplest way is to build your features *on top of* these s However, there are complex cases where it may be easier to make your own system *instead of* these subsystems. That's why we allow you to enable/disable systems with this granularity. -#### Advanced - Beyond the Hooks and Modifications to the SDK +#### Advanced - Beyond Hooks and SDK Modifications -In line with our philosophy that tools should enable you to do what you need, we distribute the SDK with the source code so that you can edit it if you need to do so. The code is kept organized and commented (as best as we can) to try and make modifications to it feasible. We do this for a few different reasons: +In line with our philosophy that tools should enable you to do what you need, we distribute the SDK with the source code so that you can edit it if you need to do so. The code is kept organized and commented (as best as we can) to try and make modifications feasible. We do this for a few different reasons: - **Owning Dependencies**: It is the philosophy of the UE team here at Beamable that dependencies should be managed explicitly and, whenever possible, be included in your VCS. Since the Beamable SDK is a huge dependency of your project, we want you to have as much control over it as possible. - **Visibility**: We also believe that, while you shouldn't depend directly on internals of the SDK, having access to them can inform better system design choices. You shouldn't be afraid to take a look at the details of how we implement our `UBeamRuntimeSubsystem`s as it can be informative when designing custom systems on top of Beamable yourself. @@ -84,4 +87,9 @@ In line with our philosophy that tools should enable you to do what you need, we We are all for helping you get a head start in development, but if at any point our systems aren't helping you should be free to adjust them easily or replace them. -I should make a disclaimer though: **_IF YOU MODIFY THE SDK, YOU ARE TAKING OWNERSHIP OF MAKING THAT MODIFICATION WORK WITH THE REST OF THE SDK_**. Our Pro-Support will gladly help you investigate and in future versions of the SDK we might even ship a generalization of what you need based on data that stems from that process, but we hope you understand that we cannot guarantee any modification you make will work out of the box, with itself or future versions of the SDK --- only you can do that. Still, sometimes this risk and cost _can_ be worth it. So, we trust tech-leads and senior engineers to evaluate that correctly and go for it when appropriate for their case. +!!! warning "Disclaimer" + **_IF YOU MODIFY THE SDK, YOU ARE TAKING OWNERSHIP OF MAKING THAT MODIFICATION WORK WITH THE REST OF THE SDK_**. + + Our Pro-Support will gladly help you investigate, and in future versions of the SDK we might even ship a generalization of what you need based on data that stems from that process, but we CANNOT guarantee that any modification you make will work out of the box with itself or future versions of the SDK. + + Still, sometimes this risk and cost _can_ be worth it. So, we trust tech-leads and senior engineers to evaluate that correctly and go for it when appropriate for their case.