FactMatcher is a system that chooses the highest "scoring" rule, from a database of many rules. FactMatcher is heavily inspired by the dialogue system in Left4Dead, see this talk By Elan Ruskin, https://www.youtube.com/watch?v=tAbBID3N64A&ab_channel=GDC to see where the system is coming from. A rule contains a list of factTests. A factTest is a logic test which either checks a value against another value, or it can check if a string is equal or not equal to another string. Every rule is evaluated and given a score, and the highest scoring rule(or rules) is returned from the system. If a rule has a factTest that fails, by default, it will score 0. The FactValues are stored inside a RuleDB that has been initialized. To initialize a RuleDB and start picking rules and manipulating facts, the FactMatcher class, is what you use. ==Update to API== There has been some updates to the API to make it more expressive from the application side of things. There is now a distinction of Picking rules, and peeking rules. If you Pick - then the rule-write-back system, will run for each rule you picked. If you Pick one single best rule, only that rule will write back with FactWrites. Here is the Gist of it : PickBestRule - only write back to one rule PickBestRules - write back to all rules that share the same bestMatch PeekBestRule - return bestRule but do not write back to the system PeekBestRules - return best rules - ie all rules sharing the same best match PickAllValidRules - return number of valid rules, and run write-backs on all rules that have no failed tests PeekAllValidRule - return number of valid rules, do not run write-back on them GetRuleFromMatches(index) returns the rule , i.e if you have numRules = peekBestRules() // 2 then GetRuleFromMatches(0) and GetRuleFromMatches(1) would work. to get the rules after running a "PeekAllValidRules" , use GetRuleFromValidMatches(index) where index is lower than result from PeekAllValidRules To create rules - FactMatcher parses text files called RuleScripts, which follows this syntax: -- This is comment. -- Naming conventions , snake_case. -- Keywords are written in upper caps. -- Indentation is optional, but makes it easier to read for humans. .rule_name_with_template_ IF fact_test_string_example = hello world fact_test_value_example >= 1337 ?weak_fact_test_example = 99 IF fact_test_or_group_example_1 = TRUE OR fact_test_or_group_example_2 = FALSE OR fact_test_or_group_example_3 = pizza .THEN WRITE fact_test_value += 3 fact_test_value_2 (+=) fact_test_value .THEN PAYLOAD scriptableobject_path_relative_to_a_resource_folder .THEN RESPONSE A string response returned if the rule is picked .END This is quite dense, but shows a complete example of the syntax. If a fact-test starts with ? , it is a weak test, meaning if the test fails. The scoring of the rule does not get set to 0, it just does not add to its score. We also see an example of OR-groups, which is a block that starts with a factTest prefixed and each test in the OR-group, starts with OR. An entire OR-GROUP , will only score 1 point if any of its tests passes. Next up is examples of writing back to the factValue database. This only gets written if the rule scores the most and is picked. You can set a setting so that all the rules that are valid, that is, scores more than 1, also writes back to its rules. What you need depends on how you use the system. The .THEN WRITE, is optional, so your rule does not have to write back if it does not want to. The syntax, operands supported for writing back is as follows : fact_value += 1337 , adding a number to a fact_value fact_value -= 1337 , subtracting a number to a fact_value fact_value = 909 , setting the fact_value to a number fact_value_str = some_string , setting the fact_value to a string And variants where you use another fact_value fact_value (+=) fact_value_2, adding the value of fact_value_2 to fact_value fact_value (-=) fact_value_2, subtracting the value of fact_value_2 to fact_value fact_value (=) fact_value_2, setting the fact_value to the value of fact_value_2 fact_value_str (=) fact_value_str_2, setting the fact_value_str to the value of fact_value_str_2 The .THEN PAYLOAD , is optional, and expects a line below where the path to a ScriptableObject is located. This is relative to the resource folder. Finally the .THEN RESPONSE text .END is not optional,and defines the end of the rule. To use the factMatcher Create a RuleDB asset. This RuleDB Asset will then be filled with RuleScripts, which are text files containing dialog with some fact requirements. These text-files gets parsed and populated the RuleDB asset, which in turns generates a source file containing id's for each fact. To get started , you can Create a RuleScript, which creates a default rulescript with some examples and then use that with the RuleDB asset. Next up, to inspect and play with your RuleDB , you can open the RuleDBWindow Working with a RuleDB in your game/GameObject. Create a FactMatcher and init with your RuleDB asset. FactMatcher factMatcher = new FactMatcher(rulesDB); factMatcher.Init(); factMatcher.SetFact(factMatcher.FactID("fact_test_value_example"), 1337.0f); //remember to Disponse and de-init stuff. if (factMatcher != null && factMatcher.HasDataToDispose()) { factMatcher.DisposeData(); factMatcher = null; } == Template support == One can create rules that are templates for other rules. Here is template_example.rule .template_rule_%0 IF test = %1 bunch_of_other_tests_1 = 8 bunch_of_other_tests_2 = 9 .THEN RESPONSE Hello %2 .END and then one could write a rulescript that references the template file like this .TEMPLATE = template_example.rule %0 = example %1 = test_string %2 = World .TEMPLATE_END and this would now insert a rule that is called template_rule_example with a test for test = test_string and the response would be Hello World. Getting the FactID is quite cumbersome. Usually you would create a system that caches all the FactIDS you want your game to send. You can optionally also compile things to generated c# which allows you to access the value database like this: factMatcher[FactMatcherGen.fact_test_value_example] = 1337.0 Strings are stored as stringIDs, so you would do something like factMatcher[FactMatcherGen.fact_test_string_example] = factMatcher.StringID("test") ; You can compile this with Burst if you want to by adding a define FACTMATCHER_BURST It should be quite performant with a large number of rules and facts, but consider scoping your ruleDB for the current situation in your game. For added performance , you can also divide your rules into buckets. The following rule shows the syntax to create a bucket .bucket_test_on_shot IF @concept = on_shot @who = Johnny Lemon player.health < 10 .THEN RESPONSE rule matches if health is lower than 10 and name is Johnny Lemon .END This creates a bucket "concept:on_shot,who:Johnny Lemon" The main idea is that all rules that deals with the Johnny Lemon character being shot, are put into this bucket, and the application can then query against only this specific bucket when rule matching. From the application side, the way you use this - is as follows: In the example below, we look at the bucket that is concept:on_shot,who:everybody public class FactMatcherBucketPerfTest : MonoBehaviour, FactMatcherProvider { public RulesDB rules; private FactMatcher _matcher; public RuleDBEntry lastRulePicked; private BucketSlice OnShotEveryBodyBucket; public string who = "everybody"; public string concept = "onShot"; // Start is called before the first frame update void Start() { _matcher = new FactMatcher(rules); _matcher.Init(); OnShotEveryBodyBucket = _matcher.BucketSlice($"concept:{concept},who:{who}"); } private void OnDestroy() { if (_matcher.IsInited && _matcher.HasDataToDispose()) { _matcher.DisposeData(); _matcher = null; } } // Update is called once per frame void Update() { lastRulePicked = _matcher.PickRuleInBucket(OnShotEveryBodyBucket); } public FactMatcher GetFactMatcher() { return _matcher; } } Credits: Agens Håvard Christensen Additional programming Ole Anders Astad Feedback, input and support Knut Clausen Feedback, input and support Trond Abusdal Licence The MIT License (MIT) Copyright © 2023 <copyright holders> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.