diff --git a/docs/media/imgs/default-gem-icon.png b/docs/media/imgs/default-gem-icon.png new file mode 100644 index 000000000..1a5870af3 Binary files /dev/null and b/docs/media/imgs/default-gem-icon.png differ diff --git a/docs/unity/getting-started/installing-beamable.md b/docs/unity/getting-started/installing-beamable.md index be29c6360..8fd280630 100644 --- a/docs/unity/getting-started/installing-beamable.md +++ b/docs/unity/getting-started/installing-beamable.md @@ -40,7 +40,7 @@ Open the Beamable Login Window by clicking the Beamable button in the Unity tool Now you are ready to start your first Beamable project! ## Say _hello_ to Beamable! -To confirm that you have a working Beamable setup, we will pull in the `BeamableBehavior` component and make sure we can access a player account using the [Admin Console](../user-reference/runtime-systems/admin-console.md). +To confirm that you have a working Beamable setup, we will pull in the `BeamableBehaviour` component and make sure we can access a player account using the [Admin Console](../user-reference/runtime-systems/admin-console.md). ![Animated walkthrough of the Unity Editor in play mode: the Beamable runtime initializes in the Console, then the Admin Console opens to confirm access to a player account.](../../media/imgs/getting-started.gif) diff --git a/docs/unity/user-reference/SUMMARY.md b/docs/unity/user-reference/SUMMARY.md index 59558a713..1505d0eab 100644 --- a/docs/unity/user-reference/SUMMARY.md +++ b/docs/unity/user-reference/SUMMARY.md @@ -5,7 +5,7 @@ - [Admin Console](runtime-systems/admin-console.md) - Editor Systems - [Editor Login](editor-systems/unity-editor-login.md) - - [Beam Library](editor-systems/beam-library.md) + - [Beam Samples](editor-systems/beam-library.md) - [Offline Mode](editor-systems/offline-mode.md) - [Autogenerated SDK](editor-systems/autogenerated-sdk.md) - [Builds & Environments](editor-systems/builds-environments.md) diff --git a/docs/unity/user-reference/beamable-services/bi/ab-testing-overview.md b/docs/unity/user-reference/beamable-services/bi/ab-testing-overview.md index e00eea142..5034c19b0 100644 --- a/docs/unity/user-reference/beamable-services/bi/ab-testing-overview.md +++ b/docs/unity/user-reference/beamable-services/bi/ab-testing-overview.md @@ -117,7 +117,7 @@ Access these values programmatically via **get** as `game.private.player`. ### Debugging manifests -For debugging the manifests, game players can use the Admin Flow to enter commands. +For debugging the manifests, game players can use the Admin Console to enter commands. **Commands** diff --git a/docs/unity/user-reference/beamable-services/profile-storage/content/content-unity.md b/docs/unity/user-reference/beamable-services/profile-storage/content/content-unity.md index 65f6722dd..9aff0dd01 100644 --- a/docs/unity/user-reference/beamable-services/profile-storage/content/content-unity.md +++ b/docs/unity/user-reference/beamable-services/profile-storage/content/content-unity.md @@ -196,6 +196,9 @@ Content filter strings can be entered into the Content Manager's search box, or | `tag:a` | returns all content elements that have the `"a"` tag | | `tag:a b` | returns all content elements that have the `"a"` tag and the `"b"` tag | +!!! info "Good to know: tag filtering and `OmitContentManifestTags`" + If you enable `OmitContentManifestTags` on `ContentConfiguration`, the manifest your game fetches at runtime is downloaded without tags. Tag-based `GetManifest` and `ContentQuery` filters (for example, `tag:weapon`) then return no results in builds. The in-Editor Content Manager search box is unaffected, since it filters local content. + **Id Filtering:** To filter by content id, use the `id` filter constraint, or use no constraint at all. The `id` filter constraint is the default constraint. The following table shows examples of id constraints. | Filter String | Description | diff --git a/docs/unity/user-reference/editor-systems/beam-library.md b/docs/unity/user-reference/editor-systems/beam-library.md index d88fd5a96..ee29c03a8 100644 --- a/docs/unity/user-reference/editor-systems/beam-library.md +++ b/docs/unity/user-reference/editor-systems/beam-library.md @@ -1,131 +1,17 @@ -# Beam Library overview +# Beam Samples overview -The Beam Library is a collection of package samples and prefabs to help get you started learning the Unity SDK. To open the Beam Library, click on the Beamable Button (at the top-right of the Unity window), and select _Beam Library_. +The **Beam Samples** window is a collection of Lightbeam samples that help you get started learning the Unity SDK. To open it, click the Beamable button (at the top-right of the Unity window) and select _Beam Samples_. -![Select "Open Beam Library" from the Beamable Button](../../../media/imgs/533076e9cddc444ecdf9be5f5e2310b7d293fbc95b5792a9959a803433fd7955-image.png){width="400px"} +![Select "Open Beam Samples" from the Beamable button](../../../media/imgs/533076e9cddc444ecdf9be5f5e2310b7d293fbc95b5792a9959a803433fd7955-image.png){width="400px"} -Now the _Beam Library_ should be open. +Now the _Beam Samples_ window should be open. -![Beam Library Window](../../../media/imgs/7b0d4957423d75029795d0d58132b6e7ca953f448a97b7057065519465467364-image.png){width="400px"} +![The Beam Samples window](../../../media/imgs/7b0d4957423d75029795d0d58132b6e7ca953f448a97b7057065519465467364-image.png){width="400px"} -Each card represents a Package Sample. When you click the "Open Scene" button, a Beamable sample will be added to your assets folder under `Assets/Samples/Beamable`. +Each card represents a Lightbeam sample. Selecting a sample copies it into your project under `Assets/Samples/Beamable`. ## Admin Console -Most of the package samples are entire Scenes that help you get started understanding a topic. However, the _Admin Console_ is unique, because it is a prefab that gets added to your project.The prefab is helpful to dropping into your project, because you can use it to interact with Beamable at runtime. +!!! warning "Deprecated: prefab-based Admin Console" + Earlier SDK versions shipped the Admin Console as a prefab (the "Admin Flow" feature) that you added to your scene from this window. That prefab is deprecated and scheduled for removal in a future release. The Admin Console is now a built-in runtime integration that requires no prefab — see [Admin console](../runtime-systems/admin-console.md) for setup, the built-in command reference, and the custom-command API. - -### Admin Console prefab - -#### Overview - -The **Admin Flow** Feature Prefab provides developers with debugging capabilities. - -The purpose of this feature is to offer the game maker an in-game UI for executing game commands and cheats. - -#### Usage - -The Admin Flow can be opened at runtime in multiple ways: - -- Within the Unity Editor, press the "~" key -- Within a Mobile Build, use a "three-finger swipe-up gesture" - -#### The user interface - -![The Beamable "Admin Flow" UI in the Unity Game Window](../../../media/imgs/admin-flow-ui-game-window.png){width="200px"} - -#### Adding to your project - -The Admin Prefab is accessible via the _Beam Library_ window. You can open the _Beam Library_ and add the admin prefab to your scene. - -#### Admin commands - -Once the Admin Flow is open, type an admin command into the input field and press return. - -There are built-in Beamable admin commands and game makers can create custom admin commands for additional functionality. - -##### Using Beamable admin commands - -| Command | Detail | -| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | -| `help` | Shows the list of all admin commands | -| `TRACK_PAYMENT` | Track a test payment audit | -| `ECHO ` | Repeat message to console. | -| `WHERE ` | Find where a specific console command was registered from, if it was registered with a DBeamConsoleCommand attribute | -| `account_toggle` | emit an account management toggle event | -| `account_list` | list user data | -| `IDFA` | print advertising identifier | -| `RESET` | Clear the access token and start with a fresh account | -| `LOCALNOTE [ [ [<body>]]]` | Send a local notification. Default delay is 10 seconds. | -| `TIMESCALE <value> \| variable` | Sets the current timescale | -| `SUBSCRIBER_DETAILS` | Query subscriber details | -| `DBID` | Show current player PlayerId | -| `ENTITLEMENTS <symbol> <state>` | Show current player entitlements | -| `HEARTBEAT <dbid>` | Get heartbeat of a user | -| `LOGIN_ACCOUNT <email> <password> ` | Log in to the PlayerId designated by the given username and password | -| `MAIL_GET <category>` | Get mailbox messages | -| `MAIL_UODATE <id> <state> <acceptAttachments> ` | Update a mail | -| `REGISTER_ACCOUNT <email> <password>` | Registers this PlayerId with the given username and password | -| `EXPIRE_TOKEN` | Expires the current access token to trigger the refresh flow | -| `CORRUPT_TOKEN` | Corrupts the current access token to trigger the refresh flow | -| `TEST-ANALYTICS` | Run 1000 events to test batching/load | -| `IAP_BUY <listing> <sku>` | Invokes the real money transaction flow to purchase the given item_symbol. | -| `IAP_PENDING` | Displays pending transactions | - -#### Force-enabled - -Within the Unity Editor, press the "~" key to open the in-game console. This always works, regardless of player privileges or "Admin Flow" settings. - -On device, use a three-finger swipe gesture to open the in-game console. This only works if the player has sufficient privileges, or if the "Admin Flow" settings specify the console should always be available. - -!!! info "Best Practice" - - - For security reasons, it is not recommended to allow a players to access the in-game console. Beamable has precautions in place to prevent this - -The in-game console, on-device, will **only** appear if the force-enabled checkbox is true, or if the current player's account has tester, developer, or admin privileges. - -The Beamable Portal allows game makers to grant player privileges. This privilege-requirement only applies to device, not the Unity Editor. - - -### AdminFlow API - -#### Creating custom admin commands - -Game makers can create custom admin commands for additional functionality. - -AdminFlowCustomCommandExample.cs -```csharp -using Beamable.ConsoleCommands; -using UnityEngine; - -namespace Beamable.Examples.Features.AdminFlow -{ - [BeamableConsoleCommandProvider] - public class CustomConsoleCommandProvider - { - [BeamableConsoleCommand ("Add", "A sample addition command", "Add <int> <int>")] - public string Add(string[] args) - { - var a = int.Parse(args[0]); - var b = int.Parse(args[1]); - return "Result: " + (a + b); - } - } - - /// <summary> - /// Demonstrates <see cref="AdminFlow"/>. - /// </summary> - public class AdminFlowCustomCommandExample : MonoBehaviour - { - // Unity Methods -------------------------------- - protected void Start() - { - Debug.Log($"Start() Instructions...\n" + - " * Run The Scene\n" + - " * Type '~' in Unity Game Window to open Admin Console\n" + - " * Type 'Add 5 10'\n" + - " * See 'Result: 15' in Unity Console Window\n"); - } - } -} -``` diff --git a/docs/unity/user-reference/runtime-systems/admin-console.md b/docs/unity/user-reference/runtime-systems/admin-console.md index 30673db3a..2c56b921d 100644 --- a/docs/unity/user-reference/runtime-systems/admin-console.md +++ b/docs/unity/user-reference/runtime-systems/admin-console.md @@ -69,6 +69,76 @@ Use the `help` command to list every registered command and its usage: > help ``` +## Built-in commands + +Beamable registers these commands by default: + +| Command | Detail | +| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | +| `help` | Show the list of all admin commands | +| `TRACK_PAYMENT` | Track a test payment audit | +| `ECHO <message>` | Repeat a message to the console | +| `WHERE <command>` | Find where a console command was registered from, if it was registered with a `BeamableConsoleCommand` attribute | +| `account_toggle` | Emit an account management toggle event | +| `account_list` | List user data | +| `IDFA` | Print the advertising identifier | +| `RESET` | Clear the access token and start with a fresh account | +| `LOCALNOTE [<delay> [<title> [<body>]]]` | Send a local notification (default delay is 10 seconds) | +| `TIMESCALE <value> \| variable` | Set the current timescale | +| `SUBSCRIBER_DETAILS` | Query subscriber details | +| `DBID` | Show the current player's PlayerId | +| `ENTITLEMENTS <symbol> <state>` | Show the current player's entitlements | +| `HEARTBEAT <dbid>` | Get the heartbeat of a user | +| `LOGIN_ACCOUNT <email> <password>` | Log in to the PlayerId designated by the given username and password | +| `MAIL_GET <category>` | Get mailbox messages | +| `MAIL_UPDATE <id> <state> <acceptAttachments>` | Update a mail | +| `REGISTER_ACCOUNT <email> <password>` | Register this PlayerId with the given username and password | +| `EXPIRE_TOKEN` | Expire the current access token to trigger the refresh flow | +| `CORRUPT_TOKEN` | Corrupt the current access token to trigger the refresh flow | +| `TEST-ANALYTICS` | Run 1000 events to test batching and load | +| `IAP_BUY <listing> <sku>` | Invoke the real-money transaction flow to purchase the given item | +| `IAP_PENDING` | Display pending transactions | + +## Custom commands + +You can register your own commands to extend the console. Annotate a class with `[BeamableConsoleCommandProvider]` and each command method with `[BeamableConsoleCommand]`: + +CustomConsoleCommandExample.cs +```csharp +using Beamable.ConsoleCommands; +using UnityEngine; + +namespace Beamable.Examples.AdminConsole +{ + [BeamableConsoleCommandProvider] + public class CustomConsoleCommandProvider + { + [BeamableConsoleCommand("Add", "A sample addition command", "Add <int> <int>")] + public string Add(string[] args) + { + var a = int.Parse(args[0]); + var b = int.Parse(args[1]); + return "Result: " + (a + b); + } + } + + /// <summary> + /// Demonstrates a custom <see cref="BeamableAdminConsole"/> command. + /// </summary> + public class CustomConsoleCommandExample : MonoBehaviour + { + // Unity Methods -------------------------------- + protected void Start() + { + Debug.Log($"Start() Instructions...\n" + + " * Run the scene\n" + + " * Type '~' in the Unity Game window to open the Admin Console\n" + + " * Type 'Add 5 10'\n" + + " * See 'Result: 15' in the Unity Console window\n"); + } + } +} +``` ## Logging to the console diff --git a/docs/unity/whatsnew/5.1.md b/docs/unity/whatsnew/5.1.md index 288fb5228..40d25b7f8 100644 --- a/docs/unity/whatsnew/5.1.md +++ b/docs/unity/whatsnew/5.1.md @@ -1,12 +1,12 @@ # Version 5.1 -These are the release notes for the Beamable Unity SDK version 5.1. This release includes a new Admin Console, reworkd Lightbeam samples and bug fixes to enhance your experience with the Beamable Unity SDK. Below are the highlights of this release: +These are the release notes for the Beamable Unity SDK version 5.1. This release introduces a built-in Admin Console, reworked Lightbeam samples, Content Manager workflow improvements, and a range of bug fixes. Below are the highlights of this release. ## Highlights -### Reworked Lightbeam Samples +### Reworked Lightbeam samples -The Lightbeams samples was reworked to improve the interfaces and visuals alongside many bug fixes and new docs. You can access them from the `Beam Samples Window` in the Unity Editor. +The Lightbeam samples were reworked to improve their interfaces and visuals, alongside many bug fixes and new docs. You can access them from the **Beam Samples** window in the Unity Editor. ![The reworked Lightbeam samples window in the Unity Editor, with selectable cards for each bundled feature sample.](../../media/imgs/lightbeam-samples.gif){width=800px} @@ -23,19 +23,49 @@ See the [Lightbeam samples overview](../samples/lightbeam.md) for the shared fra ### New Admin Console -The [Admin Console](../user-reference/runtime-systems/admin-console.md) is now a built-in runtime overlay managed directly by the Beamable runtime — no manual prefab setup is required. +The [Admin Console](../user-reference/runtime-systems/admin-console.md) is now a built-in runtime overlay managed directly by the Beamable runtime — no manual prefab setup is required. ![The Beamable Admin Console overlay rendered over a running game scene, showing a Console ready prompt above a command input line.](../../media/imgs/admin-console.gif){width=800px} -To start using it Open the console with the backtick (`` ` ``) key on keyboard or a 3-finger swipe on touch platforms. +To start using it, open the console with the backtick (`` ` ``) key on a keyboard or a 3-finger swipe on touch platforms. -The old AdminFlow console is now considered [deprecated](#deprecations) +The old AdminFlow console is now [deprecated](#deprecations). -### Deprecations +### Content Manager improvements -#### AdminFlow Prefab -The previous AdminFlow prefab approach is still available for backward compatibility, but it is now deprecated and scheduled for removal in a future release, currently planned for late 2026 or early 2027. +The Content Manager received several workflow improvements: + +- Sync and revert operations now report progress directly in the window +- Renamed content entries appear as a single *Modified Renamed* entry instead of a separate new-and-deleted pair +- Default assets and content are now imported manually on your first visit to the Content Manager +- A new setting controls download concurrency for editor content sync + +See [Content in Unity](../user-reference/beamable-services/profile-storage/content/content-unity.md) for the Content Manager workflow. + +## Other changes + +- The **Beam Library** window is now the **Beam Samples** window, updated with the latest samples and docs +- `ContentConfiguration` adds an `OmitContentManifestTags` option that excludes content tags from the public manifest fetched at runtime. When enabled, runtime tag-based `ContentQuery` filters (for example, `tag:weapon`) return no results. In-Editor Content Manager filtering is unaffected +- `MicroserviceConfiguration` adds a Max Parallel Service Build count setting to control how many services build concurrently +- The default gem icon was updated: + + ![The new default gem icon, a faceted purple gem](../../media/imgs/default-gem-icon.png){width=96px} + +## Fixes + +This release includes numerous bug fixes, including: + +- Improved content sync resilience for transient SSL and socket-reset download failures +- Fixed an intermittent account login `TaskCanceledException` caused by overlapping Unity Editor CLI refreshes +- Fixed first-run Account window build-config setup when `config-defaults.txt` is missing or has no PID +- Fixed a periodic freeze caused by telemetry collector polling + +## Deprecations + +### AdminFlow prefab + +The previous AdminFlow prefab approach is still available for backward compatibility, but it is now deprecated and scheduled for removal in a future release, currently planned for late 2026 or early 2027. The prefab is no longer offered in the Beam Samples window. When using the legacy AdminFlow system, the new Admin Console is automatically disabled by default to prevent conflicts between both implementations. -To use the new Admin Console instead, remove the legacy AdminFlow prefab from your scene. \ No newline at end of file +To use the new Admin Console instead, remove the legacy AdminFlow prefab from your scene.