Mesh to Actor Swap System #
Mesh To Actor Swap System V3 – Documentation #
We have this overview video which includes the most common use cases and how to’s:
This is a detailed video on how the architecture works in general, it is not 1 on 1 but gives the principle:
And a dev-log during the dev process for the ones interested, not that is has changed over time:
Discord Support Channel #
The main verified user support channel accessible on the Games by Hyper discord server
https://discord.com/channels/829273511822491708/1375823161236525096
An additional tutorial for expanding the data table configuration.
https://discord.com/channels/829273511822491708/1436607408561717299
Overview #
The Hyper Mesh To Actor Swap System is a modular system that provides a mechanism for increasing your games overall performance by giving you tools to reduce the number of active actors put into a game level at design time and swapping actors and meshes during runtime.
.
The Hyper Mesh To Actor Swap System allows you to:
- Swap meshes into actors on the fly as the player overlaps them or if the player hits them, and it is configurable.
- Handle auto swapping out actors and turning them back into meshes based on data asset settings.
- Use data tables for configuring which actors and meshes to swap.
- Work with Static Meshes and Instanced Static meshes added to the level with PCG, Foliage Painting, or Direct Placement.
- Add measurable performance to your project compared to levels that only contain the actors in them, which in turn can allow you to have a higher number of items in your level, or possibly give you back that performance gain if your level is built out and underperforming.
The Hyper Mesh To Actor Swap System comes with a demo example map that can be used to see the functionality of the system as well as provide some instruction on how to set it up for yourself.
It comes with example actors for your use.
It comes with a basic DT_Items which uses the same data structure as the Games by Hyper Inventory System V3 so it can drop straight into a project with any other Games by Hyper V3 asset without issues
The data table reading code can be modified to suit your own inventory system quite easily as long as it contains the basic data requirements being Static Mesh and optionally the actor blueprint to spawn.
🔧 Everything is modular and designed for drop-in use across all V3 Games by Hyper assets.
Core Components #
Actor Components
- The AC_MeshToActor_Swapper Actor Component holds the functional logic and support functions for the system. It handles:
- Reading in the Data Tables that define the configuration of swappable meshes and actors.
- Detecting and performing the swapping of a Mesh to an Actors.
- Saving and Loading of swapped meshes and actor states.
- Automatically cleaning up after itself via the Respawn Component.
- The AC_RespawnActor_Base Actor Component holds the functional logic and support functions for swapping the actor back out to a mesh if it was not interacted with as well as handling any respawning required if the actor was interacted with. It handles:
- Reading in the Respawn Data Asset that helps to defines the respawn configuration.
- When placed on an actor can be configured for the actors class.
- Performing the swap of an actor back into a mesh.
- Automatically respawning an actor or mesh as defined in the configuration on the actor.
Configuration Overview
- Project Settings : You will be required adding the MeshToActorSwap object type to your project collision channel settings if it does not already exist. It is already defined in all Games by Hyper V3 asset projects.
- Player Character : You would add the component AC_MeshToActor_Swapper to your player character. You would configure some of the swapping setting directly inside the player character on this component once it’s added.
- DT_Items : In Games by Hyper systems this is the data table that holds the games general interactable items such as pickup and inventory items.
- DT_MeshToActorSwap : This is where to define any mesh and actor blueprint linking for swapping that are NOT DEFINED in DT_Items. NOTE be aware that if the same exact mesh is defined with a mesh defined in DT_Items the Actor for swapping will get changed with this Actor in memory where the data is configured for fast access.
- DA_Respawn : This is used for most respawn settings, However be aware that the mesh to actor swap respawn settings are set directly inside of the AC_MeshToActor_Swapper instance editable settings when it is added to an actor.
Configuring The SystemConfiguring the Project and Collision Settings #
Project Settings
Open Project Settings -> Collision and add the Object Channel MeshToActor_Swap and set it to ignore.
Collision Settings on Meshes placed in the world.
When placing a static mesh in the world – either via PCG, Foliage Painting or Direct Placement, ensure you set Generate Overlap Events to True and set it’s Collision Preset to Custom and set the Object Type to MeshToActor_Swap. The Collision Enabled has to be one of the Query types
The collision details used will be whatever else you need them to be configured for but make sure you have the Object Response for the MeshToActor_Swap set to Overlap.
Player Character Setup
Player Character
Add AC_MeshToActor_Swapper to the player character and then select it and in the details panel you can modify it’s configuration if you are not happy with the defaults.
The main things to configure here are :
- Reswap Actor to Mesh Time, default is 7 seconds. This is the time for swapping an actor back to a mesh if there is no interaction with the Actor by the player
- Overlap Sphere Radius, default is 200 unreal units, the sphere is automatically created on the player during runtime and it’s size determines how big an area to check for meshes to swap to actors if they are configured for swap on overlap.
- Force an Overlap Check on Respawn Back Timer, this will tell the system to do an overlap check in case the actor is in before respawning back to a mesh, typically you would leave this set to true.
- Swapped Tag, this is the tag that will get used on a swapped actor to signal to the system that a mesh was swapped to an actor.
Configuring The Swapped Actors #
If you take a look at BP_Pickup_Master you will notice that it has the AC_Respawn_Actor_PickupItem component on it, this component is a child of AC_Respawn_Actor_Base with an override for the Spawn Respawn Actor function specifically for pickup items as these will get respawned into the world based on the inventory item data.
Regardless, for enabling the actor to swap back to a mesh then add either AC_Respawn_Actor_PickupItem or AC_Respawn_Actor_Base to the actor and configure it depending on the actors use case.
To configure the AC_Respawn_Actor_PickupItem component for actor mesh swapping assuming tjat it’s a pickup item that is going to swap on overlap
Enable Respawn as Static Mesh, Respawn Static Mesh with Swap Activation on Overlap and Start Inactivity Timer On BeginPlay Of Actor
For swap on hit actors that should not swap on overlap use these settings with AC_Respawn_Actor_Base placed on the actor,
Enable Respawn as Static Mesh and Start Inactivity Timer On BeginPlay Of Actor
Disable Respawn Static Mesh with Swap Activation on Overlap if it is enabled.
Note the DA_Respawn_Quick_Testing data asset, this is used to configure the other actor respawn stuff that is separate to the Mesh To Actor Swapping System.
Data Table Configuration #
If you are using the Hyper Inventory system for your inventory and pickup items then you won’t need to change anything inside that data table.
If you have either of the Hyper Mineable rocks or Choppable Trees assets then you would need to add the trees / rocks blueprints and meshes to the DT_MeshToActorSwap.
Open the data table DT_MeshToActorSwap
In the content browser go to the trees / rocks blueprints that is planned to be used in your level, such as chaos / staged for rocks or chaos / materialoffset / instantbreakable for trees, and open each blueprint actor one at a time.
After opening an actor scroll down and select the static mesh and copy it (right click and select Copy, use CTRL C, or press shift and right click)
As the actor should still selected in the content browser switch over to the data table and for the actor BP entry hit the arrow to add the actor to the blueprint
In this example I am using the actor BP_MaterialBased_ChoppableTree_Master_Hilltree,
now in the mesh box, paste the static mesh property data copied before.
Configuring Data Tables continued #
Now it’s time to decide how the actual swap will be performed.
Simply enable either SwapOnHit if you want the swap to occur when the mesh is hit and takes any damage or SwapOnOverlapRadius if you want to to swap to the actor when the player is near
NOTE The data table DT_MeshToActorSwap data table uses the structure Struct_Swappable_Mesh and so when making custom data tables for swappable meshes be aware of the need to use this data structure as it is the expected inside the function Store_SwappableMeshesToActorMap
Configuring The Static Meshes #
Foliage Painting #
When adding the static meshes to the foliage paint panel there will be the need to configure the collision settings. Ensure that MeshToActor_Swap is set to Overlap.
NOTE If the mesh is to be swapped on hit make sure Damageable is set to Block in the Object Response section.
Then in the Outliner select the FoliageInstancedStaticMesh actor.
And in the Details Panel select all the instances
Now set the Collision Settings object type to MeshToActor_Swap
Finally double check the object responses. To make sure we have the correct settings.
In this example I have multiple types of object responses on the damageable and pawn responses.
The main thing is to confirm that the MeshToActor_Swap Object Response is set to Overlap.
In this example I have a mixture of objects – some swap on overlap, some swap on hit which is why Damageable Object Response has some in each.
Configuring The Static Meshes continued #
PCG Graph Spawning #
When spawning from a PCG Graph Static Mesh Spawner, once you have setup how the mesh is going to spawn and you are adding the mesh entries to the mesh spawner, the Collision Data needs to be configured.
Set the collision preset to Custom, set your Collision Enabled to at least one of the Query Options for the specific mesh and most importantly set the Object Type to MeshToActor_Swap
Then in Object Responses configure the MeshToActor_Swap response to Overlap
NOTE You will need to do this for each mesh you add to the mesh entries array.
Configuring The Static Meshes continued #
Direct World Placement #
When placing static meshes manually in the world you will need to configure the collsion settings for the mesh instance placed.
Make sure to set Generate Overlaps to True and then set the Collision Preset to Custom.
Next set the Collision Enabled type to a suitable Query type for the intended use.
Set the Object Type to MeshToActor_Swap
Finally set the Object Response for MeshToActor_Swap to Overlap
Performance Measuring #
Instanced Static Meshes vs Actors
In this example of performance testing, it is using Play In Editor mode which is one of the worst case ways to test performance, The level is on a 1K x 1K sized landscape with a little over 150K meshes painted that are all configured for actor swapping with approx. 70 FPS on an Intel 12900KS with an Nvidia 4080 Super TI 16GB video card and 128GB of RAM with ram usage at
Compare that with actors instead of meshes and it becomes very clear how much the Hyper Mesh To Actor Swapping System can improve the performance of your level as long as you take full advantage of the system.
70K actors tanks performance to approx. 8 seconds per frame on the dev system, 18K actors generated via a PCG Graph results in similar FPS to 150K swappable static meshes.
Struct Swappable_Mesh #
The components of the structure are :
Mesh The static mesh that will be used to determine which mesh can be swapped. This will be a mesh that should be configured as the MeshToActor_Swap Object Type in the collision settings when adding the mesh to the level via any of the supported methods such as Foliage Paint, Direct Placement, PCG, Custom Runtime Placement etc.
Actor_BP This is the actor blueprint that will be spawned when the mesh is swapped to an actor.
SwapOnHit If set to true then the mesh will only swap on being hit via the OnTakeDamage event.
SwapOnOverlapRadius If set to true then the mesh will swap when it’s inside the overlap radius sphere that gets automatically added to the player character from the Hyper Mesh To Actor Swap System
Optional_Linked_Name is primarily used when reading in the Items Data Table. It is used for storing a link from a swappable mesh to a specific data table row name. You could use this in custom code for storing actor preset data for example that could then be used when spawning the actor. An example of this being used is inside the function Spawn_Pickup_Item.
Graphs and Events #
Graphs #
There are some subgraphs that are used during initialization to make following the code flow a little easier to read.
Store Mesh To Actor Swappable Data This handles creating and storing the swappable data.
Overlap Sphere Initialization And Bind This handles creating the overlap sphere on the player and the setting things up to allow swapping the mesh when the player is near.
Forcing An Update Overlap On Begin Play This sets things up for detecting overlaps on begin play
Multi Remove Instance This handles removing individual instances from Instancing Components such as directly placed ISM’s, Custom Runtime Generated ISM’s, Painted Foliage, PCG Generated etc.
Events #
OnComponentBeginOverlap_Event
This handles checking for on overlap events with the player and activating the swapping when appropriate.
Multicast_Multi: Remove Instance
This handles removing individual instances and managing the data for the removed instance.
Begin Play
This manages configuring and setting up the Hyper Mesh To Actor Swap System overall.
Event Server: Try Swap Mesh To Actor
This tries attempting to swap the static mesh into an actor on the server.
Function Categories #
Functions are broken up into categories and sub categories.
Initialization
These functions primarily handle the initialization of the component data
Store
These functions manage reading in the data tables and caching the swapping data.
Utility
These are support functions that are often used by other functions and events
Swap Mesh To Actor
These functions perform the swapping of meshes to actors.
Core
These functions are core to the system and perform various swap mesh to actor action based on the type of mesh.
Spawn
These functions handle the spawning of the actors based on the swapping data.
There are 2 additional functions that handle replication and setting the respawn settings on a swapped actor.
Developer Settings
These are the main settings of the component that are changeable when adding the component to a character
Swapped Tag
This is the tag added to an actor when it is swapped for a static mesh and is checked for when swapping back to a mesh, you could configure this to any specific tag required. The default tag is swapped and should work fine for most projects unless it is already used for something else.
Reswap Actor To Mesh Time
This is the time in seconds to attempt to automatically swap the actor back into a mesh.
Overlap Sphere Radius
This is the size in unreal units of the overlap sphere that gets created and added to the player character automatically during initialization. A larger radius will mean swapping meshes to actors will occur further away from the player.
Force An Overlap Check On Respawn Back Timer
When respawning back to a mesh, if this is True, then it will do an overlap check in case the actor is still inside the Overlap Sphere Radius, if it is still inside the sphere, then it won’t switch it back to a mesh.
If this is False then it will swap the actor back to a mesh regardless once the Reswap Actor To Mesh Time has been reached.
Typically it would be left as True unless there is a specific reason not to do so.
Function Descriptions #
These are in depth descriptions of each function.
Initialize
Store #
Store_SwappableMeshesToActorMap
Used to read the data table DT_MeshToActorSwap and store the contents in the StaticMeshName_to_SwappableDataInfo MAP array.
Store_DT_Items_as Swappable mesh
Used to read the data table DT_Items and store only the specific required data from it in the StaticMeshName_to_SwappableDataInfo MAP array.
Create OverlapSphere on owning character
Creates an OverlapSphere collision sphere component and adds it to the owning character of this AC_MeshToActorSwapper component to enable triggering Swap On Overlap events and links a reference to it in the Overlap_Sphere variable in this component.
Utility #
Get static mesh component from actor
This will get the static mesh component on an actor.
Requires an Actor Object Reference
Returns True and the Static Mesh Component if successful, False if not successful
Try Find Swappable info of Mesh Component
Tries to find if the mesh component has swappable info.
Requires a Static Mesh Component Object Reference
Returns a struct Swappable_Swappable_Mesh and True if it found a mesh to swap. Otherwise it returns False.
Is Mesh Component already from a swapped actor
Determines if the Mesh Component is from an actor that was swapped from a mesh.
Requires a Static Mesh Component Object Reference
Returns True if the Mesh Component is from an Actor that was already swapped. Otherwise it returns False.
Update Overlaps
Forces an update of the overlap sphere.
Swap Mesh To Actor #
Core #
Try Swap Mesh To Actor
Attempts to perform the swapping of a static mesh to an actor.
Requires a Static Mesh Component Object Reference, The hit index integer and a bool to indicate if it should Swap On Hit
Returns True if it successfully swapped the Mesh to an Actor as well as a reference to the Actor.
Perform Swap Mesh to Actor on instanced Static Mesh
Performs the actual swap of a mesh to an actor on an instanced static mesh component of some sort such as ISM, FISM, HISM.
Requires an Instanced Static Mesh Component object reference, The instance index and the swapping data.
Returns True and the Actor reference.
Perform Swap Mesh to Actor on Static Mesh
Performs the actual swap of a mesh to an actor on a static mesh component such as directly placed or runtime placed static meshes.
Requires a Static Mesh Component and the swapping data
Returns True and an Actor reference
Spawn #
Spawn actor based on swapping data
Spawns the actor based on the BP_Actor data stored in the Swappable Mesh data.
Requires a Struct_Swappable_Mesh and a Transform.
Returns a reference to the spawned actor.
Spawn Generic Actor
Spawns an actor based on the class and transform passed to it.
Requires an Actor Class and a Transform.
Returns an Actor Object reference.
Spawn Pickup Item
Specifically spawns an actor of type BP_Pickup_Item which is used for inventory items inside of DT_Items.
Requires an Actor Class, a Transform and a Struct_Swappable_Mesh
Returns an Actor Object reference
Swap Mesh To Actor continued #
Set Actor Respawn settings to swappable mesh
Sets up the respawn settings for the actor to respawn as a static mesh if it’s not interacted with after some time.
Requires an Actor Object reference and a bool to determine if it’s to be swapped on hit.
NOTE The actor is required to have a child of the AC_Respawn_Abstract class component on it otherwise it will bypass setting the Respawn Settings.