Sandbox Framework is a minimal and generic framework that let’s you add sandbox features to your game. Typical real work examples include Creative Mode from Fortnite, Scenario Editor from Age of Empires and so on. If your game requires a similar feature then Sandbox Framework is for you.
Custom Asset
Sandbox Framework provides custom asset for easily creating assets that can be spawned at runtime.
Custom Graph
Allows you to define your own logic. Every node in graph is a full object that can contain gameplay logic.
Easy to use API
Provides easy to access subsystems for communicating with Sandbox Graph and Assets.
Installation
Installing Sandbox Framework to any of the supported Unreal Engine is the same as with any other plugin from Unreal Marketplace.
- Open Epic Games Launcher.
- Go to Vault Section.
- Search for Sandbox Framework and install.
Sandbox Asset
This is a UObject that describes your asset and auto registers with Asset Registry. Sandbox Framework does not rely on any actors or components and solely uses Sandbox Assets to spawn desired actor in world so this is the first asset you create if you want to spawn a certain actor in world.
Sandbox Assets are auto registered which means you only need to provide paths in Project Settings -> Sandbox Settings -> Asset Paths and simply create Sandbox Assets in these locations. At runtime, these locations are scanned for assets and load them automatically.
If you do not provide a location to scan, whole project will be scanned which can be slow depending on your project size.
The idea of Sandbox Asset is that you define the required properties in it and access them in your Actor class (in Blueprint or C++).
To create a Sandbox Asset, right click inside Content Browser and choose Sandbox Asset from Sandbox context menu.
You will now be prompted to choose a parent class so choose and press Select. A new Sandbox Asset will be created which you can double click to open and you should see the below interface.
It is divided into 2 parts: Details and Viewport.
Details:
This is there all the properties are defined. It is important to remember that these properties have no implementation by default. You can access these properties in your Actor and drive the logic based on the values provided by this asset.
Viewport:
The viewport shows the mesh that you assign in details panel as well as additional information such as the approximate size of the mesh in various units. Everytime you change any property in details panel, the viewport will focus on the asset automatically.
Extending Sandbox Asset
Sandbox Assets are meant to be data assets so only add variables. Do not add any logic via Event Graph.
Based on your project, you might need to add extra properties to Sandbox Asset. To do so, simply create a new Blueprint class based on Sandbox Asset like you do for normal Blueprint and use it as parent when creating new Sandbox Asset.
After creating your Sandbox Asset Blueprint Base, you can select it when creating new Sandbox Asset.
Sandbox Graph
This is similar to Blueprint but one of the main difference between Blueprint and Sandbox Graph is that, each node is a full UObject in Sandbox Graph where as in Blueprint they are functions nodes. That means, you can have your gameplay logic in a single node.
Sandbox Graph spawns multiple nodes by default which are executed at various times. You can also create your own Graph Node via C++ or Blueprints.
To create a new Sandbox Graph, right click inside Content Browser and from Sandbox category, select Sandbox Graph.
When you open the newly created Sandbox Graph, you should see the below interface.
By default, Sandbox Graph spawns 3 nodes. These nodes are automatically called and cannot skipped or deleted.
Sandbox Begin Play
Triggered once when this graph is started. Similar to Begin Play in Blueprint.
Sandbox Mode Play
Triggered everytime when Sandbox switches to Play Mode.
Sandbox Mode Edit
Triggered everytime when Sandbox switches to Edit Mode.
For custom behavior, you can create Custom Input node with an Event Name (similar to Custom Events in Blueprint) that can be called externally from Blueprint or C++. Sandbox Graph also provides multiple custom input nodes with various types such as bool, float, UObject, Gameplay Tags and more.
Sandbox Component
This is the heart of Sandbox Framework and Sandbox Component communicates between Actor, Sandbox Subsystems and Sandbox Graph. It registers itself with Sandbox Graph Subsystem at Begin Play and unregisters in End Play. You cannot interact directly with this Component and instead use Sandbox Graph Subsystem.
Upon initialization, Sandbox Component will set the tag to itself that was passed from Sandbox Asset (Asset Tag property). Later in gameplay, you can use this information to find the component and its owning actor from Sandbox Graph Subsystem.
Sandbox Generic Interface
This interface contains few overridable functions to help with Sandbox gameplay.
On Validate Asset
Validates an asset to make sure it is ready for gameplay. It is upto the developer to create any custom rule to validate the asset. For example, you can check if a mesh is assigned or a variable is set and so on.
On Sandbox Actor Spawned
Called when an actor is spawned in world via Sandbox World Subsystem.
On Sandbox Actor Loaded
Called when this actor is loaded from save game.
Get Notify Tag
This is primarly used to pass any notify tag to a Sandbox supported actor from Sandbox Node. See the example project for implementation example.
Sandbox Subsystems
Sandbox Framework uses subsystem to make things easier for developers. Subsystems are automcatically instanced with managed lifetime and can be easily accessed from Blueprint or C++.
There are 2 subsystems included with Sandbox Framework and they are Sandbox World Subsystem and Sandbox Graph Subsystem.
Sandbox World Subsystem
This subsystem is inherited from UWorldSubsystem and is automatically initialized upon map load and deinitialized upon map unload and is used to interact with Sandbox supported actors in world. Here is a quick overview of this subsystem.
• Spawn Sandbox Asset in world.
• Add/remove gameplay tags to/from Sandbox supported actors.
• Switch between Sandbox play and edit modes.
To spawn a new Sandbox supported Actor, always use Spawn Actor from Asset function using Sandbox World Subsystem.
DO NOT USE the default Spawn Actor node in Blueprint or GetWorld()->SpawnActor() in C++ to spawn Sandbox supported Actor.
#include “Subsystems/SandboxWorldSubsystem”
…
USandboxWorldSubsystem* SandboxWorldSubsystem = GetWorld()->GetSubsystem<USandboxWorldSubsystem>();
SandboxWorldSubsystem->SpawnActorFromAsset(AssetPtr, SpawnTransform);
Shown below are functions provided to switch between Play, Edit mode and check what mode we are currently on.
This subsystem also provides two functions for validating assets at runtime to make sure they are ready for gameplay although this is completely optional. When executed, the validation function will iterate through all sandbox actors and execute On Validate Asset function (In C++ it is called K2_OnValidateAsset) which the developer can override to provide validation rule.
Below is an example actor implementing validation rule in Blueprint which makes sure a specific tag is set properly.
Sandbox Graph Subsystem
This subsystem is inherited from UGameInstanceSubsystem and is automatically initialized upon game start and deinitalized before exiting the game. This subsystem is designed to interact with Sandbox Graph. Here is a quick overview of this subsytem.
• Manages lifetime of Sandbox Graphs.
• Connects Snadbox Graphs with Sandbox supported actors.
• Provides delegates for various Sandbox specific events.
To call a specific node in your Sandbox Graph Asset you can use Start Graph Event node with your desired event name. Here is an example screenshot showing how to call a custom node Sandbox Graph Asset externally from Blueprint.
But the limitation with the above method is you cannot pass inputs to the graph. To pass inputs, you have to use Start Graph Event with Value where value can be anything listed below.
• Object
• Float
• Bool
• Byte
• Int
• Int64
• String
• Text
• Name
• Gameplay Tag Container
• Gameplay Tag
• Vector
• Rotator
• Transform
Here is an example screenshot showing how to pass input to Sandbox Graph Node.
To complete the graph at anytime you can call Finish Sandbox Graph from Sandbox Graph Subsystem.
Tutorials and Project
You can grab the example project (requires Sandbox Framework Plugin) hosted on our GitHub page.
