STORYENGINE

MutationActionDefinition

MutationActionDefinitions are templates that describe how the world changes when a goal completes. Upon goal completion, StoryEngine internally generates a MutationAction for every MutationActionDefinition assigned to the goal’s GoalDefinition.

Each MutationActionDefinition identifies the StoryEngine entity that should change, and then the new value to assign. Entities are identified using their path, a short script that uniquely identifies the entity.

Paths

Paths identify entities using a common structure:

World.<EntityType>.<EntityID>.<EntityProperty>

Entity Types

Paths support these core entity types:

Entity IDs

Entity IDs can be provided directly, or by using variables that maps to events.

Using variables requires that you wrap the variable name with {{ and }}.

See the Variables section below for details on what is possible.

Entity Properties

Each entity has its own set of properties that can be modified.

Actor

Property Type Description
LocationID string The id of the actor’s current location
Facts array[string] A list of fact IDs for the actor
Memories array[string] A list of memory IDs for the actor
ValidEpisodes array[string] A list of episode IDs for the actor

Item

Property Description
LocationID string The id of the item’s current location
Facts array[string] A list of fact IDs for the item
ValidEpisodes array[string] A list of episode IDs for the item
OwnerID string The id of the actor that owns the item
CategoryIDs array[string] A list of category IDs for the item

Location

Property Description
Visible boolean A flag indicating if the location is visible
Facts array[string] A list of fact IDs for the location
ValidEpisodes array[string] A list of episode IDs for the location
DestinationIDs array[string] A list of locationIDs representing the locations that are reachable from the location

Actions

MutationActionDefinitions take specific actions on the property that is resolved through the path. Each action provides a specific value or a variable that is evaluated to determine what value to use when applying an action.

See the Variables section below for details on what data is available.

Add

Adds a value to a property that contains an array. Typically this adds a new ID to a list like Facts or Memories. If the value already exists in the list, is it not duplicated, so it is safe to add a value that may already exist.

Remove

Removes a value from a property that contains an array. Typically this removes an ID from a list like Facts or Memories. If the value does not exist in the list, no action is taken, so it is safe to remove a value that may not exist.

Set

Sets a property to a specific value. Currently you can only set single values like strings or booleans. You cannot set arrays to new arrays.

Clear

Clears a property to an empty value.

Variables

When games emit events, they assign the actor who owns the event, and can optionally assign specific target and subject entities.

Targets describe what the owner is targeting with the event. For example, if an event is “SpeakTo” the event’s owner is speaking to the TargetActor.

Subjects can be used to indicate what the event is about. Given the same “SpeakTo” event, the SubjectActor or SubjectItem could indicate what the owning actor is speaking about.

Ultimately it is up to the game to decide how they want to interpret and use event variables, but the provided names give a common structure to work within.

Variable Description Example Use
{{actor}}
{{event.Owner}} The actor that owns the event When you want to modify a property on the owning actor.
{{event.TargetActor}}
{{event.TargetActors[n]}} The actor targeted by the event. If multiple TargetActors are provided, TargetActor evaluates to the first actor. TargetActors[n] resolves to the nth provided TargetActor. When the owning actor is speaking to a targeted actor
{{event.TargetItem}}
{{event.TargetItems[n]}} the item targeted by the event. If multiple TargetItems are provided, this evaluates to the first item. TargetItems[n] resolves to the nth provided TargetItem. When the owning actor is picking up a targeted item
{{event.TargetLocation}}
{{event.TargetLocations[n]}} The location targeted by the event. If multiple TargetLocations are provided, this evaluates to the first location. TargetLocation[n] resolves to the nth provided TargetLocation. When the owning actor is traveling to the target location
{{event.SubjectActor}}
{{event.SubjectActors[n]}} The actor who is the subject of the event. If multiple SubjectActors are provided, this evaluates to the first actor. SubjectActors[n] resolves to the nth provided SubjectActor. When the owning actor is speaking about the subject actor
{{event.SubjectItem}}
{{event.SubjectItems[n]}} The item that is the subject of the event. If multiple SubjectItems are provided, this evaluates to the first item. SubjectItems[n] resolves to the nth provided SubjectItem. When the owning actor is speaking about the subject item
{{event.SubjectLocation}}
{{event.SubjectLocation[n]}} The location that is the subject of the event. If multiple SubjectLocations are provided, this evaluates to the first location. SubjectLocation[n] resolves to the nth provided SubjectLocation. When the owning actor is speaking about the subject location
{{event.SubjectMemory}}
{{event.SubjectMemories[n]}} The memory that is the subject of the event. If multiple SubjectMemories are provided, SubjectMemory evaluates to the first memory. SubjectMemories[n] resolves to the nth provided SubjectMemory. The game wants to assign SubjectMemory to the event’s owner.
{{event.SubjectFact}}
{{event.SubjectFacts[n]}} The fact that is the subject of the event. If multiple SubjectFacts are provided, SubjectFact evaluates to the first memory. SubjectFacts[n] resolves to the nth provided SubjectFact. The game wants to assign SubjectFact to the event’s owner.

Examples

Change An Actor’s Location

Path World.Actor.{{actor.ID}}.locationID
Set {{event.TargetLocation}}

Give An Actor A New Memory

Path World.Actor.{{actor.ID}}.Memories
Add {{event.SubjectMemory}}

Remove A Location Fact

Path World.Location.{{event.TargetLocation}}.Facts
Remove {{event.SubjectFact}}