See how the world model is defined in the full working
example. Note that you can use the syntax and corresponding parsers defined in NarrativeEngine.Syntax.EntityParser for defining entities, updates, and queries.
Your story/game will have a store, or "world model", of all of the entities that live in your world, and the various properties that describe them. The narrative engine expects your world model to have this shape.
Entities are just IDs coupled with various fields of information. The engine requires that your entities have tags, stats, and links fields.
It uses these fields to track "salience-based" and "quality/stats-based" narratives (described very well in Emily Shot's blog post), which can provide a more flexible and robust story.
Because this is an extensible record, you can have other properties on your entities as well (like "name" and "description" or "sprite" for example), which works well with the "Entity Component System" design pattern.
Note that you are not restricted to the traditional "items/characters/locations" world model. You can define your entities with what ever properties you want, to fit any story world.
"Tags" on an entity.
Examples: "item", "edible", "poisonous", "SmithFamily", etc.
"Stats" on an entity.
Examples: "health", "honor", "plotProgression", "bars of gold", etc.
"Links" on an entity.
Examples: "locatedIn", "knows", "suspects", etc.
A empty starting state for the "tags" property
A empty starting state for the "stats" property
A empty starting state for the "links" property
These let you add tags directly to an entity.
Add a tag to a narrative component.
Add a stat to a narrative component. A stat is a key and a numeric value on any scale you like.
Add a link to a narrative component. The key is the type of relationship, and the value is intended to be the id of another entity.
These are useful for an "entity buider pattern".
A helper function to add a tag to an entity when setting up your world model.
A helper function to add a stat to an entity when setting up your world model. A stat is a key and a numeric value on any scale you like.
A helper function to add a link to an entity when setting up your world model. The key is the type of relationship, and the value is intended to be the id of another entity.
Declarative statements of how an entity should change, designed to be used with rules.
Note that you can use $ as the ID to reference the entity ID that triggered the rule (useful for generic rules).
Declarative statements for changing a property on an entity.
Links can set to a specific entity or you can supply an entity and key to lookup a link.
You can use $ as the ID in both cases to reference the entity ID that triggered the rule (useful for generic rules).
Caution, if the look up entity or link isn't found this will keep the original link.
Update the world model based on a list of changes. Also takes the id of the entity that triggered the rule to allow changes to use trigger matching (with $).
Queries are run against the world model to search for matching entities, or to assert that an entity has specific properties. This is useful to render a list of characters in a given location for example. The engine uses this when checking rules.
Semantic means for matching entities. Specifies an optional entity ID and a list of queries to match against.
Note that you can use $ as the ID to reference the entity ID that triggered the rule (useful for generic rules).
Links can either be a specific entity matcher, or you can supply an entity ID and a link key to do a comparison.
Note that you can use $ as the ID to reference the entity ID that triggered the rule (useful in conditional narrative content).
Stats can either be a specific integer, or you can supply an entity ID and a stat key to do a comparison.
Note that you can use $ as the ID to reference the entity ID that triggered the rule (useful in conditional narrative content).
A way to retrieve information from the store.
Provide an entity matcher to get back a list of matching entities. This is most useful for "match any" style queries, but works with specifc queries as well, just keep in mind the result is always a list.
query (MatchAny [ HasTag "item" ]) worldModel
-- [items...]
query (Match "PLAYER" [ HasStat "brave" GT <| SpecificStat 5 ]) worldModel |> List.isEmpty
-- True/FalseNote that you should run replaceTrigger first if you have "$"'s in your matcher.
Replaces "$" in a matcher with the supplied ID. Useful when you have a generic query and don't know the ID ahead of time.
You can get specific stats or links from an entity too.
Get a specific stat from a specific entity.
Get a specific link from a specific entity.
Note, if the linked-to value doesn't exist in the world model, this will return Nothing.
A unique identifier for each entity.