Class

GKRuleSystem

A list of rules, together with a context for evaluating them and interpreting results, for use in constructing data-driven logic or fuzzy logic systems.

Declaration

@interface GKRuleSystem : NSObject

Overview

A GKRuleSystem object manages a list of rules (GKRule objects). A rule system also offers methods for evaluating its list of rules in a context defined by two features: a state dictionary containing information to be tested by rules, and a set of facts representing the conclusions drawn as a result of rule evaluation. You can evaluate facts based on a binary truth state—that is, a fact either is or is not in the set—or on a continuously variable membership grade, representing different levels of veracity, confidence, or strength for use in fuzzy logic.

You construct a rule system by creating GKRule objects and adding them to the system’s list of rules. There are multiple ways to construct rules: for greater reusability, use the methods listed in Creating Data-Driven Rules; or for greater flexibility, use the ruleWithBlockPredicate:action: method or create a custom subclass of GKRule or GKNSPredicateRule. Then, add rules to the system with the methods listed in Managing a System’s List of Rules.

To evaluate a system, call the evaluate method. This method processes each rule in the system in the order it appears in the system’s agenda list. You set this order with the salience property of each rule, or with the order in which you add rules to the system. As the system processes each rule, it tests the rule’s evaluatePredicateWithSystem: method to determine whether the rule is satisfied in the context of the system. If the rule’s predicate is satisfied, the system executes the rule’s performActionWithSystem: method and moves the rule to the executed list (so the further evaluation of the agenda doesn’t repeatedly trigger the rule’s action).

Rules typically use the system’s state dictionary as input and its set of facts as output. (However, more complex systems can include sets of rules whose predicates test facts or whose actions mutate the system’s state.) After evaluating a rule system, you can examine the set of facts it has produced using the methods listed in Drawing Conclusions from Facts. You can then use the presence of a fact in the set, the value of its membership grade, or the combined membership grades of a group of facts to influence the behaviors in your game.

For more information about rules and rule systems, read Rule Systems in GameplayKit Programming Guide.

Topics

Creating a Rule System

- init

Initializes a new, empty rule system.

Managing State Information

state

A dictionary of state information to be evaluated by the system’s rules.

Managing a System’s List of Rules

rules

The list of rules to be executed when evaluating the system.

- addRule:

Adds the specified rule to the system.

- addRulesFromArray:

Adds the specified list of rules to the system.

- removeAllRules

Removes all rules from the system.

Evaluating a Rule System

- evaluate

Evaluates the rule system, executing the list of rules in its agenda.

agenda

The list of rules to be considered when evaluating the system.

executed

The list of rules whose actions have been performed during evaluation of the system.

- reset

Returns the rule system to its original agenda and clears all facts.

Asserting and Retracting Facts

facts

The list of facts claimed by the rule system.

- assertFact:

Adds the specified fact to the fact set with a membership grade of 1.0, and reevaluates the rules in the system’s agenda.

- assertFact:grade:

Increases the membership grade of the specified fact by the specified amount, adding it to the fact set if necessary, and reevaluates the rules in the system’s agenda.

- retractFact:

Removes the specified fact from the fact set, and reevaluates the rules in the system’s agenda.

- retractFact:grade:

Reduces the membership grade of the specified fact by the specified amount, removing it from the fact set if necessary, and reevaluates the rules in the system’s agenda.

Drawing Conclusions from Facts

- gradeForFact:

Returns the membership grade of the specified fact.

- minimumGradeForFacts:

Returns the lowest membership grade among the specified facts.

- maximumGradeForFacts:

Returns the highest membership grade among the specified facts.

Relationships

Inherits From

See Also

Rule Systems

GKRule

A rule to be used in the context of a rule system, with a predicate to be tested and an action to be executed when the test succeeds.

GKNSPredicateRule

A rule for use in a rule system that uses a Foundation NSPredicate object to evaluate itself.