Making the Crafting Station
A Ritual takes place at a Ritual crafting station. The main difference from a normal crafting station is that you must use BP_PL_RitualStation as the parent class.
Once created, set the mesh as normal and create a matching building item. The position at which the player stands when performing a ritual can be adjusted by moving the CraftingLocation component.
Each Ritual Station requires a unique CraftingGroup, which cannot be utilized by any other crafting station:
The CraftingGroup controls which recipes (aka rituals) can be performed at that crafting station. Non-ritual recipes can also be added to this CraftingGroup and will be craftable as normal (for example, the Research recipes on the Thaumaturgy Bench).
The CraftingQueue for a ritual station has a max size of 1. This is because we CANNOT allow players to queue rituals. If you try to let players queue them up, the behavior will become erratic and problematic (taking control of players who have left the area and might be fighting an NPC for example).
Ritual Recipes
Each Ritual has an associated unique recipe. This is what is shown in the station UI, and for the most part is setup like any other recipe.
The Ritual Recipe needs to be taught to the player via a feat like any other recipe.
The Time To Craft should be set to match the duration of the ritual event (often a montage that is run on the player).
As a general rule, ritual recipes should have “Is Crafting Time Unaffected by Server Settings” enabled.
All recipe ingredients must be present inside the ritual station, and are consumed as normal for a recipe. Additionally, any recipe result items are created in the ritual station once the ritual has completed. If the ritual is interrupted, ingredients are not consumed and the result items are not created.
Ritual recipes do not always play nicely with creative mode. If you are having trouble getting your recipe to craft, make sure you are not in creative and have learned the recipe-awarding feat.
Ritual DataTable
Once the ritual recipe is created, make an entry for it in the RitualData table/your mod’s RitualData table.
The row’s name needs to be the recipe Template ID. The rest of the values are fairly simple:
-
RitualBP- Point this to your Ritual BP (more on this below). Multiple rituals can use the same Ritual BP if desired. -
AddCorruption/AddCorruptionLimit- The amount of corruption to add to the player when the ritual finishes, up to AddCorruptionLimit. -
AddMaxCorruption/AddMaxCorruptionLimit- Increase the maximum amount of corruption the player can have, up to AddMaxCorruptionLimit.-
⚠️ This is a deprecated feature and may or may not behave as expected. Use at your own risk.
-
-
Payload- A string that can be used to pass any data, or no data if left empty. -
CustomCriteria- Defaults to false. See the Custom Behaviors section for more info.
Ritual Blueprint
The functionality of a Ritual is contained within its own blueprint. When the ritual is started, that blueprint is spawned with the same transform as the ritual station and standardized events are called on it.
All Ritual Blueprints must be children of BP_RitualBase.
3D Components:
As the Ritual is spawned into the world, you are able to add 3D components to the ritual BP, such as particles, meshes, or more. These are useful for ritual-specific effects, easily calculating world-space coordinates, or anything else you can think of.
For ease of use, you can put the ritual station’s mesh in the ritual BP, and set it to “Hidden in Game”.
The lifespan of a ritual actor is guaranteed to be at least as long as the ritual is ongoing. Beyond that, it is undefined and may behave oddly in specific circumstances.
Rituals API
These variables/functions are available in your ritual blueprint and provide access to useful data to make implementing your ritual easier.
Payload
Function:
GetPayload
Returns the payload string from the RitualData table for the selected ritual. This is very useful for having a single ritual blueprint that handles multiple rituals.
Player
Variable:
Player
The player character who is performing the ritual
CraftingStation
Variable:
CraftingStation
The placeable where the ritual is being performed. The variable type is BP_PL_RitualStation but you can cast it down to a specific station blueprint if you need.
RecipeID
Variable:
RecipeID
The template ID of the recipe that initiated this ritual. Ideally the payload would be used to enable recipe-specific results, instead of the RecipeID.
Implementable Events:
These events are where the majority of the logic for your ritual will live.
It may help to think of these events as moments in time. Each event happens at a specific moment in time during the lifecycle of performing a ritual.
These events run on both server and client simultaneously.
Init
Event:
Init
Called when the ritual is being setup. The player is walking into place, and nothing has actually started happening. Primarily used for starting any asynchronous loading or preparing of assets that may take time.
Most rituals have no reason to use Init.
Start
Event:
Start
The player has moved into place, and the ritual blueprint is expected to now take over. The ritual blueprint should start playing a montage on the player. This will both lock the player into position and play a ritualistic animation (and associated audio/FX) on the player character.
Additionally, non-montage audio and FX can be started in this event. For example, flame surrounding a Circle of Power are ignited in the Start event.
Start is called at the same time that the ritual recipe starts its crafting timer in the RitualStation.
ALL rituals should implement the Start event.
ALL rituals should start their montage on the player.
Interrupted
Event:
Interrupted
The ritual has been interrupted, either voluntarily by the player, or involuntarily by anything else (an aggressive monster, internet outage, etc).
ALL rituals should implement the Interrupted event.
ALL rituals should stop their montage on the player.
Interrupted is called even if Start has not yet been called. If you have resources allocated in Init that need to be freed up, you can do so in Interrupted.
Finished
Event:
Finished
When the recipe has finished crafting, Finished is called. This timing happens irregardless of FX, the montage running on the player, or anything else.
Finished is the perfect time to do cleanup, such as fading out sounds, deactivating particles, etc
ALL rituals should implement the Finished event.
ALL rituals should stop their montage on the player.
Custom Behaviors
Some rituals may require modifications to otherwise standardized behavior. These are available by overriding specific functions in the ritual blueprint:
Custom criteria
Function:
CanStartRitual
You can setup additional ritual criteria beyond the standard crafting recipe ingredient/catalyst requirements. Note that the
CanStartRitual
function is NOT called on a spawned copy of the ritual, but on the template. As such, you do not have access to anything normally setup/loaded in
Init
, or otherwise accessible via the API.
In the CanStartRitual function, accessing Player, CraftingStation, or RecipeID will give you garbage/invalid data. Use the Query*** variables passed into the function instead.
The payload can be accessed with the function GetPayloadFromRecipeID
Cancellation
Function:
AllowPlayerCancellation
By default players are allowed to cancel in-progress rituals by moving. You can disable this by returning false from this function.
This only disables voluntary player cancellation. Other forms of cancellation such as being attacked by a creature or disconnecting from the game will still cancel the ritual.
UNSUPPORTED
Function:
CompleteRitualIfCancelledRightNow?
When player cancellation is allowed, you may want the ritual to still complete if it has reached a certain point, even if the player attempts to move away/cancel it. This function is called at the moment the player tries to voluntarily cancel the ritual.
This function is for a deprecated feature and may not behave as expected.
Ritual Station Interaction Control
Function:
ShouldAutomaticallyReenableInteractionOnFinishOrInterrupt
When a ritual is started, the ritual station disables all interaction. The default behavior is that when the ritual completes (by the crafting timer finishing) or is interrupted, the ritual station will re-enable interaction. If your ritual requires more control over this, you can disable it.
Interaction can be re-enabled by calling EnableInteract on the ritual station (BP_PL_RitualStation).
When using this function, you are responsible for ensuring that the crafting station is made interactive again.
A ritual’s lifespan is undefined once the ritual has completed. Ideally the crafting station would be made interactive again in the Interrupted and Finished events.
Player Positioning
Function:
GetRitualPositioning
Some rituals may want to have a different player placement than the station’s default, or perhaps the player’s placement should be dynamically calculated (like the Circle of Power does).
This is achieved by overriding the GetRitualPositioning function and returning a STR_RitualPositioning struct.
-
Use Ritual Specific Location - When true, override the default placement as set in the RitualStation.
-
Location Tolerance - How close the player character has to be aligned with the given location (in UU/cm).
-
World Location - World coordinates the player should move to. Easy to fetch by calling “GetWorldLocation” on a component.
-
Turn To - Whether the player should turn to face a location before starting the ritual.
-
Turn To Location - The world coordinates the player should look towards.
As a general rule, it is recommended to give as much tolerance as possible. This reduces the chance of the character being unable to path exactly into position.
Camera Mode
Function:
GetCameraModeOverride
This function allows overriding the player camera configuration while performing the ritual. This is good for giving that cinematic feel.
Recommended for rituals: Sorcery_RitualClose, Sorcery_RitualFar
Ritual Best Practices:
-
Start the montage on the player in Start, and stop it in Interrupted and Finished
-
Use the Finished event to perform any special logic
-
Avoid using Delay nodes
-
Avoid using Multicast, Run on Server, or Run on Owning Client networking events - You shouldn’t need them, the ritual is already synchronized between client and server
-
Use “Is Server” and (Not) “Is Dedicated Server” checks to separate execution paths
-
Keep player placement while performing rituals inside the bounds of the ritual station. This reduces the likelihood of pathing problems when starting a ritual
File Locations
Rituals live in:
/Game/Sorcery/Rituals
The Ritual crafting stations live in:
/Game/Systems/Building
Ritual montages (including generic ones) live in:
/Game/Characters/humans/animations/sorcery/rituals/
RitualData table:
/Game/Sorcery/Rituals/RitualData