[{"name":"Narrative.Rules","comment":" Rules are a declarative way of describing meaningful events in your story.\n\nThey are made up of 3 parts: a \"trigger\", a set of \"conditions\", and a set of \"changes\" to apply if the rule matches. Each time you call `findMatchingRule`, the engine will test all of your rules against the provided trigger and the current state of your story world, and will find the best matching rule (if one exists).\n\nRules are weighted based on how specific they are, so you can \"override\" a more generic rule by making a more specific rule that will also match.\n\nIt is possible to create generic rules (using `MatchAny`) to control basic story logic, and more specific rules to flesh out the story.\n\nSee how the rules are defined in the [full working example](https://github.com/jschomay/elm-narrative-engine/blob/master/src/Example.elm).\n\n@docs Rule, RuleID, Rules, findMatchingRule, weight\n\n","unions":[],"aliases":[{"name":"Rule","comment":" A declarative rule describing the conditions in which it should apply. Specifically, it defines a trigger and a list of other conditions that must be present. All of these are described by `EntityMatcher`s. All rules are tested on each player interaction, and the highest weighted matching rule will be returned. You can then apply the specified changes.\n\nNote that `Rule`s are extensible records, meaning that you can add other fields to them in your game. For example, you could add a `narrative` field to add a story text to use when the rule matches, or a `sound` to play, etc. All of these \"side effects\" would be handled in your game code. Alternatively, you could use the returned `RuleID` to lookup side effects in a separate data structure. This design follows the Entity Component System (ECS) design pattern.\n\n","args":["a"],"type":"{ a | trigger : Narrative.WorldModel.EntityMatcher, conditions : List.List Narrative.WorldModel.EntityMatcher, changes : List.List Narrative.WorldModel.ChangeWorld }"},{"name":"RuleID","comment":" Unique ID for a rule. These ids will be returned when a matching rule is found.\n","args":[],"type":"String.String"},{"name":"Rules","comment":" All of the rules in your \"rule book\" that define your game logic.\n","args":["a"],"type":"Dict.Dict Narrative.Rules.RuleID (Narrative.Rules.Rule a)"}],"values":[{"name":"findMatchingRule","comment":" Finds the rule that best matches against the provided trigger (entity ID) and current world model. If multiple rules match, this chooses the \"best\" match based on the most _specific_ rule. In general, the more conditions, the more specific.\n\nCall this any time the player \"interacts\" with an entity in your game, supplying the ID of the entity that was interacted with.\n\nWhile the trigger is intended to match one of the entity IDs defined in your world model, you could also programmatically call this at any time with any string, as long as there is a rule with a matching trigger. This can be useful for \"abstract\" events that you want to respond to, like \"wait\" or \"next day\".\n\n","type":"Narrative.WorldModel.ID -> Narrative.Rules.Rules a -> Narrative.WorldModel.WorldModel b -> Maybe.Maybe ( Narrative.Rules.RuleID, Narrative.Rules.Rule a )"},{"name":"weight","comment":" Assigns a \"weighting\" to a rule. Used internally.\n","type":"Narrative.Rules.Rule a -> Basics.Int"}],"binops":[]},{"name":"Narrative.WorldModel","comment":" See how the world model is defined in the [full working example](https://github.com/jschomay/elm-narrative-engine/blob/master/src/Example.elm).\n\n\n## Types\n\n@docs ID, WorldModel, NarrativeComponent, Tags, Stats, Links\n\n\n## Creating entities\n\n@docs emptyTags, emptyStats, emptyLinks, tag, stat, link\n\n\n## Updating entities\n\n@docs ChangeWorld, ChangeEntity, applyChanges\n\n\n## Querying the world model\n\nQueries are run against the world model to assert a condition or select particular entities. This is useful to render a list of characters in a given location for example. The engine uses these when checking rules.\n\n@docs EntityMatcher, Query, query, assert, assertMatch, getStat, getLink\n\n","unions":[{"name":"ChangeEntity","comment":" Declarative statements for changing a property on an entity.\n\nNote that you can use `$` as the `ID` in `SetLink` to reference the entity ID that triggered the rule (useful for generic rules).\n\n","args":[],"cases":[["AddTag",["String.String"]],["RemoveTag",["String.String"]],["SetStat",["String.String","Basics.Int"]],["IncStat",["String.String","Basics.Int"]],["DecStat",["String.String","Basics.Int"]],["SetLink",["String.String","Narrative.WorldModel.ID"]]]},{"name":"ChangeWorld","comment":" Declarative statements of how an entity should change, designed to be used with rules.\n\nNote that you can use `$` as the `ID` to reference the entity ID that triggered the rule (useful for generic rules).\n\n","args":[],"cases":[["Update",["Narrative.WorldModel.ID","List.List Narrative.WorldModel.ChangeEntity"]],["UpdateAll",["List.List Narrative.WorldModel.Query","List.List Narrative.WorldModel.ChangeEntity"]]]},{"name":"EntityMatcher","comment":" Semantic means for matching entities. Specifies an optional entity ID and a list of queries to match against.\n\nNote that you can use `$` as the `ID` to reference the entity ID that triggered the rule (useful for generic rules).\n\n","args":[],"cases":[["Match",["Narrative.WorldModel.ID","List.List Narrative.WorldModel.Query"]],["MatchAny",["List.List Narrative.WorldModel.Query"]]]},{"name":"Query","comment":" Semantic queries for checking properties of an entity.\n","args":[],"cases":[["HasTag",["String.String"]],["HasStat",["String.String","Basics.Order","Basics.Int"]],["HasLink",["String.String","Narrative.WorldModel.EntityMatcher"]],["Not",["Narrative.WorldModel.Query"]]]}],"aliases":[{"name":"ID","comment":" A unique identifier for each entity.\n","args":[],"type":"String.String"},{"name":"Links","comment":" \"Links\" on an entity.\n\nExamples: \"locatedIn\", \"knows\", \"suspects\", etc.\n\n","args":[],"type":"Dict.Dict String.String Narrative.WorldModel.ID"},{"name":"NarrativeComponent","comment":" Entities are just IDs coupled with various fields of information. The engine requires that your entities have `tags`, `stats`, and `links` fields.\n\nIt uses these fields to track \"salience-based\" and \"quality/stats-based\" narratives (described very well in [Emily Shot's blog post](https://emshort.blog/2016/04/12/beyond-branching-quality-based-and-salience-based-narrative-structures/)), which can provide a more flexible and robust story.\n\nBecause 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.\n\nNote 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.\n\n","args":["a"],"type":"{ a | tags : Narrative.WorldModel.Tags, stats : Narrative.WorldModel.Stats, links : Narrative.WorldModel.Links }"},{"name":"Stats","comment":" \"Stats\" on an entity.\n\nExamples: \"health\", \"honor\", \"plotProgression\", \"bars of gold\", etc.\n\n","args":[],"type":"Dict.Dict String.String Basics.Int"},{"name":"Tags","comment":" \"Tags\" on an entity.\n\nExamples: \"item\", \"edible\", \"poisonous\", \"SmithFamily\", etc.\n\n","args":[],"type":"Set.Set String.String"},{"name":"WorldModel","comment":" 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.\n","args":["a"],"type":"Dict.Dict Narrative.WorldModel.ID (Narrative.WorldModel.NarrativeComponent a)"}],"values":[{"name":"applyChanges","comment":" 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 `$`).\n","type":"List.List Narrative.WorldModel.ChangeWorld -> Narrative.WorldModel.ID -> Narrative.WorldModel.WorldModel a -> Narrative.WorldModel.WorldModel a"},{"name":"assert","comment":" Asserts if the current state of the world model matches the given queries.\n","type":"Narrative.WorldModel.ID -> List.List Narrative.WorldModel.Query -> Narrative.WorldModel.WorldModel a -> Basics.Bool"},{"name":"assertMatch","comment":" A utility to test an `EntityMatcher` matcher against a specific entity `ID`.\n","type":"Narrative.WorldModel.EntityMatcher -> Narrative.WorldModel.WorldModel a -> Narrative.WorldModel.ID -> Basics.Bool"},{"name":"emptyLinks","comment":" A empty starting state for the \"links\" property\n","type":"Narrative.WorldModel.Links"},{"name":"emptyStats","comment":" A empty starting state for the \"stats\" property\n","type":"Narrative.WorldModel.Stats"},{"name":"emptyTags","comment":" A empty starting state for the \"tags\" property\n","type":"Narrative.WorldModel.Tags"},{"name":"getLink","comment":" Get a specific link from a specific entity.\n","type":"Narrative.WorldModel.ID -> String.String -> Narrative.WorldModel.WorldModel a -> Maybe.Maybe Narrative.WorldModel.ID"},{"name":"getStat","comment":" Get a specific stat from a specific entity.\n","type":"Narrative.WorldModel.ID -> String.String -> Narrative.WorldModel.WorldModel a -> Maybe.Maybe Basics.Int"},{"name":"link","comment":" 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.\n","type":"String.String -> Narrative.WorldModel.ID -> ( Narrative.WorldModel.ID, Narrative.WorldModel.NarrativeComponent a ) -> ( Narrative.WorldModel.ID, Narrative.WorldModel.NarrativeComponent a )"},{"name":"query","comment":" A way to retrieve information from the store.\n","type":"List.List Narrative.WorldModel.Query -> Narrative.WorldModel.WorldModel a -> List.List ( Narrative.WorldModel.ID, Narrative.WorldModel.NarrativeComponent a )"},{"name":"stat","comment":" 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.\n","type":"String.String -> Basics.Int -> ( Narrative.WorldModel.ID, Narrative.WorldModel.NarrativeComponent a ) -> ( Narrative.WorldModel.ID, Narrative.WorldModel.NarrativeComponent a )"},{"name":"tag","comment":" A helper function to add a tag to an entity when setting up your world model.\n","type":"String.String -> ( Narrative.WorldModel.ID, Narrative.WorldModel.NarrativeComponent a ) -> ( Narrative.WorldModel.ID, Narrative.WorldModel.NarrativeComponent a )"}],"binops":[]}]