Expression Reference

StoryEngine Expressions are used in MemorySharingRules and in GoalDefinitions to define rules based on state from games and StoryEngine. This gives narrative designers a scriptable method to create rules that consider the narrative state and the game state to determine narrative progression.

Expressions are written using CEL. CEL uses a C-like syntax, but it is not Turing-complete and you have limited ability for looping and branching logic. For more information and documentation about the CEL expression syntax, review their documentation here:

CEL Language Introduction

CEL Language Definition

The CEL Project

https://github.com/google/cel-spec/blob/master/doc/langdef.md

Expression Examples

Only share a memory if the actor has the team_sherlock fact:

"team_sherlock" in actor.fact_ids

Only share a memory if the actor has a more than 5 empathy facet points

ctx["actors"][actor.id]["facets"]["facet_empathy"] > 5

Only complete a goal if the owner and the actor are both on team_sherlock:

"team_sherlock" in actor.fact_ids && "team_sherlock" in owner.fact_ids

Only complete a goal if the actor has a specific memory:

"mem_yavuz_is_the_killer" in actor.memory_ids

Only complete if the owner has two or more memories from a list of memories

size(owner.memory_ids.filter(x, x in ["mem_blackwood_fake_symptoms", "mem_blackwood_bribe_felton", 
"mem_syringe_use", "mem_anointing_oil_laced", "mem_smc_last_act"])) >= 2

It is also possible to retrieve arbitrary data from the Snapshot, for example checking the name of a location…

s.locations[actor.location_id].name == "Disneyland"

// Although a better rule would be...

actor.location_id == "loc_disneyland"

A rule that checks the completion state of an arbitrary goal:

s.active_goals["goal_close_door"].completed

Only share a memory if the actor is discussing a specific memory as a conversation topic:

size(ctx.conversation_topics.filter(topic, topic.id in ["mem_yavuz_is_the_killer"])) == 1

Types

The following types are available when working with expressions. Typically you gain access to specific objects through the Snapshot. MemorySharingRules and GoalDefinitions provide global variables with current state for you to use. Refer to the specific documentation to learn what variables are available.

Actor

Represents an actor in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the actor.
`source_id`	`string (null)`	Source identifier for the actor (nullable)fa.
`name`	`string`	Name of the actor.
`world_id`	`string`	Identifier of the associated world.
`location_id`	`string`	Identifier of the actor's current location.
`fact_ids`	`array[string]`	List of associated fact IDs.
`memory_ids`	`array[string]`	List of associated memory IDs.
`valid_episode_ids`	`array[string]`	List of valid episode IDs.
`story_history`	`string`	The actor's story history.
`temp_submitted_answer_ids`	`array[string]`	List of temporary submitted answer IDs.

Location

Represents a location in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the location.
`source_id`	`string (null)`	Source identifier for the location (nullable).
`name`	`string`	Name of the location.
`lat`	`number`	Latitude of the location.
`lng`	`number`	Longitude of the location.
`fact_ids`	`array[string]`	List of associated fact IDs.
`valid_episode_ids`	`array[string]`	List of valid episode IDs.
`destination_ids`	`array[string]`	List of possible destination IDs.

Item

Represents an item in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the item.
`source_id`	`string (null)`	Source identifier for the item (nullable).
`name`	`string`	Name of the item.
`owner_id`	`string (null)`	Identifier of the item's owner (nullable).
`location_id`	`string`	Identifier of the item's current location.
`fact_ids`	`array[string]`	List of associated fact IDs.
`valid_episode_ids`	`array[string]`	List of valid episode IDs.

Fact

Represents a fact in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the fact.
`text`	`string`	The text of the fact.

Asset

Represents an asset in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the asset.
`url`	`string`	URL of the asset.
`content_type`	`string`	Content type of the asset.

Incident

Represents an incident in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the incident.
`text`	`string`	The text of the incident.
`valid_episode_ids`	`array[string]`	List of valid episode IDs.
`location_id`	`string`	Identifier of the incident's location.
`subject_actor_ids`	`array[string]`	List of subject actor IDs.

Memory

Represents a memory in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the memory.
`text`	`string`	The text of the memory.

MemorySharingRule

Represents a rule for sharing memories.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the rule.
`world_id`	`string`	Identifier of the associated world.
`memory_id`	`string (null)`	Identifier of the memory (nullable).
`tag`	`string`	Tag for the memory-sharing rule.
`owner_id`	`string (null)`	Identifier of the owner (nullable).
`rule`	`string`	The rule definition.
`description`	`string`	Description of the rule.

Answer

Represents an answer in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the answer.
`text`	`string`	The text of the answer.

Episode

Represents an episode in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the episode.
`source_id`	`string (null)`	Source identifier for the episode (nullable).
`name`	`string`	Name of the episode.
`completed`	`boolean`	Whether the episode is completed.
`completed_criteria_goal_definition_id`	`string (null)`	Identifier of the completed criteria goal definition (nullable).

PassiveGoal

Represents a passive goal in the system.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the passive goal.
`source_id`	`string (null)`	Source identifier for the goal (nullable).
`owner_id`	`string (null)`	Identifier of the goal owner (nullable).
`webhook_url`	`string`	URL for webhook integration.
`request_id`	`string`	Identifier of the associated request.
`goal_definition_id`	`string`	Identifier of the goal definition.
`completed`	`boolean`	Whether the goal is completed.

ActiveGoal

Similar to PassiveGoal, but represents an active goal.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the active goal.
`source_id`	`string (null)`	Source identifier for the goal (nullable).
`owner_id`	`string (null)`	Identifier of the goal owner (nullable).
`webhook_url`	`string`	URL for webhook integration.
`request_id`	`string`	Identifier of the associated request.
`goal_definition_id`	`string`	Identifier of the goal definition.
`completed`	`boolean`	Whether the goal is completed.

GoalDefinition

Represents the definition of a goal.

Field Name	JSON Type	Description
`id`	`string`	Unique identifier for the goal definition.
`source_id`	`string (null)`	Source identifier for the definition (nullable).
`name`	`string`	Name of the goal.
`fact_ids`	`array[string]`	List of fact IDs associated with the goal.
`target_actor_ids`	`array[string]`	List of target actor IDs.
`target_item_ids`	`array[string]`	List of target item IDs.
`target_location_ids`	`array[string]`	List of target location IDs.
`subject_actor_ids`	`array[string]`	List of subject actor IDs.
`subject_item_ids`	`array[string]`	List of subject item IDs.
`subject_location_ids`	`array[string]`	List of subject location IDs.
`requires_answer_ids`	`array[string]`	List of required answer IDs.
`possible_answer_ids`	`array[string]`	List of possible answer IDs.
`valid_event_type_ids`	`array[string]`	List of valid event type IDs.
`include_in_prompt`	`boolean`	Whether the goal should be included in prompts.
`requires_minimum_age`	`integer`	Minimum age required to complete the goal.
`max_completions`	`integer`	Maximum number of times the goal can be completed.
`mutation_action_definition_ids`	`array[string]`	IDs of mutation action definitions.
`render_action_definition_ids`	`array[string]`	IDs of render action definitions.

Snapshot

Represents the state of the system.

Field Name	JSON Type	Description
`actors`	`object<string, Actor>`	Map of actor IDs to actor objects.
`locations`	`object<string, Location>`	Map of location IDs to location objects.
`items`	`object<string, Item>`	Map of item IDs to item objects.
`facts`	`object<string, Fact>`	Map of fact IDs to fact objects.
`assets`	`object<string, Asset>`	Map of asset IDs to asset objects.
`incidents`	`object<string, Incident>`	Map of incident IDs to incident objects.
`memories`	`object<string, Memory>`	Map of memory IDs to memory objects.
`memory_sharing_rules`	`object<string, MemorySharingRule>`	Map of memory-sharing rule IDs to objects.
`answers`	`object<string, Answer>`	Map of answer IDs to answer objects.
`episodes`	`object<string, Episode>`	Map of episode IDs to episode objects.
`passive_goals`	`object<string, PassiveGoal>`	Map of passive goal IDs to goal objects.
`active_goals`	`object<string, ActiveGoal>`	Map of active goal IDs to goal objects.
`goal_definitions`	`object<string, GoalDefinition>`	Map of goal definition IDs to goal objects.