Rule Help

This section gives you all configuration details for each rule type. Use it as an online help to understand and configure rules.

Application

About

The application rule is unique and always accessible from Home tab in GameRules Studio. It defines an ordered set of rulesets that identifies the parts of the game and a list of libraries used to generate the namespace imports. In addition, Application rule relates a Product rule to determine all flows and state machines to generate for this game.

Definition

The GameRules Application uses information on this tab during product build.

Ruleset list

The order of the ruleset lists on this tab affects the assembly order of your ruleset list and the operation of the rule resolution algorithm.

A ruleset with the name of the game is automatically generated by the installation wizard and placed at the top of the ruleset list. Rules created for this game are typically placed in this ruleset. The default GameRulesCore ruleset is also automatically added at the bottom of the ruleset list to provide a strong baseline with hundreds of predefined rules.

You can add rulesets to integrate third party packages and frameworks.

Library list

This list is an unordered list of library rules. Each library rules indicates the different namespaces to import for the generated C# scripts. This list compiles all library sub-lists. Default UnityEngine library references UnityEngine, UnityEngine.AI and UnityEngine.UI.

You can add as many library rule as needed to use additional classes from Unity and external librairies from Asset store.

Product to build

The combination of a product name and version references a unique product rule. A product rule contains a list of Flows, Animation Flows and State Machines to generate.

When clicking the Build Product button from this form or from GameRules Studio top bar, the build process is using current referenced product rule to regenerate C# scripts. Other rules already generated that are not part from this product rule remain untouched.

The installation wizard automatically creates a new product rule with same application name and version 01.01.

Product

About

A product rule defines rules that need to be build. When clicking on Build Product button, the product rule referenced in the Application rule takes the list of Flows, Animation Flows and State Machines and regenerates their C# scripts in folder:

  • Assets/GameRulesWorkspace/Scripts/<sub folder structure based on class name>/<rule name>.cs

The script Assets/GameRulesWorkspace/Scripts/GameRulesActions.cs is also updated with used Message rules of type Action to manage messages between different scripts.

A product rule has a two parts key:

  • Product name: As a best practice, take the name of the game or milestone being developed.
  • Product version: Can only contains alphanumeric and ‘.’ characters. As a best practice, use release version to help identifying the specific rules to generate for this version.

Contents

Complete this tab to identify the flows, animation flows and state machines that make up the game or application to build.

Flows to include

Optional. Select a flow rule that identifies a class name and flow rule name. The class name is used as primary class name for all rule resolution when assembling referencing rules used by this flow.

The flow rule doesn’t need to belong to same class but has to belong to inheritance path of the selected class. The assembled C# script is generated in a folder corresponding to the selected class name.

Select Enable Tracer to let the script assembler to add additional code to provide debugging insights and having the execution being traced with the Tracer window. This option has only effect when running inside UnityEditor.

When creating a new flow rule, a row with flow name and class is automatically added.

State machines to include

Optional. Select a state machine rule that identifies a class name and satte machine rule name. The class name is used as primary class name for all rule resolution when assembling referencing rules used by this state machine.

The state machine rule doesn’t need to belong to same class but has to belong to inheritance path of the selected class. The assembled C# script is generated in a folder corresponding to the selected class name.

Select Enable Tracer to let the script assembler to add additional code to provide debugging insights and having the execution being traced with the Tracer window. This option has only effect when running inside UnityEditor.

When creating a new satte machine rule, a row with state machine name and class is automatically added.

Animation flows to include

Optional. Select an animation flow rule that identifies a class name and animation flow rule name. The class name is used as primary class name for all rule resolution when assembling referencing rules used by this animation flow.

The animation flow rule doesn’t need to belong to same class but has to belong to inheritance path of the selected class. The assembled C# script is generated in a folder corresponding to the selected class name.

Select Enable Tracer to let the script assembler to add additional code to provide debugging insights and having the execution being traced with the Tracer window. This option has only effect when running inside UnityEditor.

When creating a new animation flow rule, a row with animation flow name and class is automatically added.

Library

About

A library rule defines a list of namespaces to be incorporated in all generated C# scripts. The compilation of the namespace lists from all library rules used by the application defines the complete namespace list used by the C# script assembler and the code completion helper.

Namespaces

Complete this tab to reference the different namespaces to be used by the game or application to build.

Namespace list

Fill in the namespace name. You don’t need to finish with semi-colon character, the script assembler automatically adds it.

For example, if the namespace is UnityEngine.AI, the generated code is:

using UnityEngine.AI;

Flow and Animation Flow

About

A flow models a script in your game by using graphical shapes and connectors. Each time a new flow or animation flow is created, it is automatically added to current product rule. Flow and Animation Flow rules are very similar. A flow rule generates a MonoBehaviour script to be used by any game object. An Animation flow rule generates a StateMachineBehaviour script to be used by Animation assets. Also flow and animation flow rule don’t reference same message types, to reflect different inherited methods to implement.

Flow

This tab gives access to the flow modeler, which you can use to add shapes to the flow diagram.

Start state

A start shape references a message rule. A flow cannot reference a message rule of type UnityStateMachineBehaviour. An animation flow cannot reference a message rule of type Interface, Public function and Unity MonoBehaviour.

Each start shape generates a method, with a signature based on the message rule itself. Parameters from the message rule can be used directly for subsequent logic and when rules as input parameter.

Logic state

A logic shape references a logic rule. Each logic rule is generated as a private method with following naming convention:

void perform_<logic name>()

Fill in input parameters with either variables from ancestor start shape or reference a property rule using ‘@’ prefix. Output parameters needs to reference a property rule.

Decision state

A decision state initiates different branches in the processing logic. A decision state itself has no configuration. Instead, you can add as many transitions as you need from a decision state. Each transition references either a when rule or generates an Else statement.

The likelihood percentage indicates the order of the transitions when evaluating when rules. there is no specific restrictions on the likelihood values.

Each when rule generates a private method with following naming convention:

bool evaluate_<when name>()

End state

An end state is an optional shape except for start states referencing a message rule which returns something different than void. It helps for better visibility and understanding of the flow diagram.

Generally the end state contains no configuration, except when an ancestor start state references a message rule of type Interface or Public function which returns a value instead of void. In that case, you have to reference a property rule or an input parameter from the start state to be returned.

Parameters (only for Animation Flow)

The option Shared between animation attribute let you control how behaviours are instantiated. By default the Animator does instantiate a new instance of each behaviour define in the controller. Checking this option generates a C# script with class attribute:

[SharedBetweenAnimators]
public class AttackBehaviour : StateMachineBehaviour
{

When

About

A when condition rule evaluates a boolean logical statement involving comparisons among values of properties, to return true or false.

Conditions

Use the Conditions tab to enter or revise a when condition rule that can be expressed as a single Boolean expression, or the conjunction (AND or OR) of one or more Boolean expressions.

Conditions

In each row, enter a condition and label you want to include in the when evaluation.

For Label, enter a unique number or text value in the row header that serves as an identifier for this row. These are used in the Logic String elements. Do not choose and, or, or not as labels. You can enter // as a label to mark this row as a comment; a condition that is not evaluated. By default, the system uses L0, L1, L2, and so on.

Use the fields to enter property references, literal constants, or calls to other when rules. By default, the first condition compares two values. Optional. Select the down arrow at the end of the row for a list of standard condition templates.

Logic string

Enter the Boolean logic operations performed on the Conditions array that will compute to a True or False result at runtime. You can use and, &&, or, ||, ! and not in the statement. You can use parentheses to control the order of evaluation.

For example, if the table contains four labels A, B, C, and D, you can enter:

  • (A and B) or (C and not D)

and the C# generated statement will be:

  • (A && B) || (C && ! D)

Parameters

Input parameters

Each parameter defined is added to the method signature. You need to specify the C# class and the name of the parameter. Optionally a default value can be specified also.

The generated code is:

bool evaluate_IsActive(GameObject gameObject, bool deactivate = false)
{

Preprocessing logic

You can reference a logic rule to perform a pre-processing. Some when rules need sometimes to perform a pre-processing logic to check or initialize values. This logic rule is called inside the evaluate method before any condition evaluation.

Logic

About

Logic rules automate processing. Logic rules contain a sequence of structured steps. Each step calls a method or contains a control instruction such as Call.

Steps

Use the Steps tab to define a sequential set of instructions, or steps, for a logic to execute. Each step calls a method or supported rule type to perform the required processing. You can control the flow of execution by defining a set of pre-conditions for a step, or jumping to a later step. As a best practice, limit each logic to twenty or fewer steps to promote modularity.

Each numbered row on the Steps tab represents a step. Use the following options to control how the logic processes a step at run time.

  • Label: unique identifier. Enter a short (one-or two-character) string that other steps can reference in their jump criteria. Otherwise, leave this field blank. Enter two slash marks (//) to comment out a step, or exclude it from execution.
  • When: Click to specify a when rule that controls whether a step is executed or skipped. Clear the Enable conditions before this action check box to remove the when criteria.
  • > : Parameter details for the specified Method. Click to expand the Method Parameters section and provide parameters to the specified method or rule instance. Click a second time to collapse the section.
  • Method and Param: The method or rule to execute. Select a method name from the list. Many methods and instructions require parameters.
  • Description: Internal documentation. Enter a brief description for other developers to understand what this step does.
  • Jump: Click to define how this step transitions to the next step or jumps to a later step. Click to review or edit the transition criteria. Clear the Enable conditions after this action check box to remove the transition criteria.

Property-Set

Use this method to set the value of one or more specified properties.

The Property-Set method uses an array of parameters. Each row of the array contains a property name or reference (the destination), and a value (the source). Order is significant.

The property name needs to begin with @ keyword to be recognized as a property rule. For property value, enter an expression to compute a value for each property.

C-Sharp-Method

Use this method to call a method returning void. The full expression is specified directly in Param field. e.g. @player.SetActive(activate).

Call-Logic

Use this method to call another logic rule from inheritance path. The logic rule name is specified in Param field. Use parameters to fill in called logic parameters.

When using Invoke option with time delayed in seconds, the generated code is:

Invoke("perform_ActivateGameObject", 0.1f);

Time delayed is only available of called logic has no parameters.

Call-Action

Use this method to send a message to other game objects using actions delegate C# feature. Specify in Param field a message rule of type GameRules Action.

All GameRules Actions are automatically generated in GameRulesActions.cs script with public methods send_<Action name>_<class name>.

Call-Flow

Use this method to call a flow attached to a game object. The called flow needs to have at least one Start state with a message of type Public function:

  • Game Object: specify a property or variable that contains a reference to the game object. You can use inherited gameObject variable to use current game object.
  • Class : specify a class name. This class does not need to be part of the inheritance path of this logic class.
  • Flow: specify a flow rule from the inheritance path of the class name. Check that specified combination of class and flow has been generated previously or is part of current product rule.
  • Public Function: list of start state that defines a Message rule of type public function.
  • Parameters: optional input parameters of the public function called.
  • Return: specify a property rule or local variable to capture the returned value of the public function called.

C-Sharp

Use this method to write free form C# code. This method is useful when having to loop over lists and calling other logic rule. Syntax for property rules still applies. When calling other logic or when rule, specify directly the generated method. Add the name of the logic or when rule in Parameters tab to be sure that it will be assembled also.

For example:

for(int i=0; i<@spawnPoints.Length; i++)
{
        perform_ActivateGameObject(@spawnPoints[i].gameObject, true, false);
}

Log-Message

Use this method to log a message onto UnityEditor console. Specify the message to log in Param field.

For example, if the message to log is “Game object name=” + @enemy.gameObject.name, the generated code would be:

UnityEngine.Debug.Log("Game object name=" + enemy.gameObject.name);

Note

Instead of calling Log-Message, consider instead enabling Tracer in product rule to have deep insight with generated rules at runtime in UnityEditor.

Exit-Logic

Use this method to immediately stop any processing and return.

Yield

This method is only visible when the logic is of type Coroutine (See parameters tab).

Use Param field to specify the yield statement. Typical statements are:

return new WaitForSeconds(1.5f);
return new WaitForFixedUpdate();

Note

The script assembler automatically appends yield prefix.

Parameters

Complete this tab to setup additional configuration for this logic rule.

Parameters

Complete this logic method signature:

  • Switch: use in for input parameter. Use out for output parameter. use ref for input parameters passed as reference. For out and ref, related keywords are added to the generated method signature.
  • Class: class of the parameter.
  • Name: name of the parameter.
  • Default value: optional. Default value added in method signature.

Local variables

Local variables are defined only in this generated logic method. They differ from property rules which are generated at class level. Local variables are generally used as temporary variables to hold calculated or retrieved values. Use a Property-Set step to initialize them.

Local varaibles are declared at the very begining of the logic generated method.

Logic type

Default value is Logic.

When selecting Coroutine, the generated method becomes:

IEnumerator perform_ActivateGameObject()
{

With this option, the yield step method becomes available.

When referenced in a Flow or StateMachine rule, the call to this logic rule becomes:

StartCoroutine(perform_ActivateGameObject());

Additional logic rules

Force additional logic rules to be assembled. This is necessary when using C-Sharp step method and referencing directly another logic rule.

Additional when rules

Force additional when rules to be assembled. This is necessary when using C-Sharp step method and referencing directly another when rule for evaluation.

Message

About

A message rule represents a method to be generated in the MonoBehaviour or StateMachineBehaiour script.

It is referenced in start states in Flow and Animation Flow rules. It indicates also in State Machine rules in which method evaluating the state. It is also used in Property rules to indicate the method to be used for initialization.

Definition

Complete this tab to specify the message type.

Game Rules Action

Use this message rule type when you have to create your own action delegate.

All action delegates are centralized in a single script GameRulesAction.cs with following naming convention:

  • <message name>_<class name>

For example, message rule OnFire from class Tanks-Weapon will generate in GameRulesActions the action delegate:

OnFire_Tanks_Weapon();

Once referenced, the rule assembler automatically generates a private method with same name than the message rule ID. It also generates subscription and unscription in OnEnable and OnDisable methods.

For example for OnFire message rule, it will generate:

namespace GameRules
{
        public class Test
        {
                // This function is called when the object becomes enabled and active.
                void OnEnable ()
                {
                        GameRulesActions.OnFire_Tanks_Weapon += OnFire;
                }

                // This function is called when the behaviour becomes disabled () or inactive.
                void OnDisable ()
                {
                        GameRulesActions.OnFire_Tanks_Weapon -= OnFire;
                }

                void OnFire ()
                {
                }
        }
}

Third Party Action

Use this message rule type when you have to subscribe to an event managed from a class outside GameRules generated scripts. You have to specify:

  • Namespace: namespace of the class of the event to subscribe. This namespace is automatically added only to this C# script.
  • Action: name of the event to subscribe including class name and action name.

Once referenced, the rule assembler automatically generates a private method with same name than the message rule ID. It also generates subscription and unscription in OnEnable and OnDisable methods.

For example, the message rule sceneLoaded refers to the action SceneManager.sceneLoaded from UnityEngine.SceneManagement. The generated code is:

using UnityEngine.SceneManagement;
namespace GameRules
{
        public class Test
        {
                // This function is called when the object becomes enabled and active.
                void OnEnable ()
                {
                        SceneManager.sceneLoaded += sceneLoaded;
                }

                // This function is called when the behaviour becomes disabled () or inactive.
                void OnDisable ()
                {
                        SceneManager.sceneLoaded -= sceneLoaded;
                }

                void sceneLoaded (UnityEngine.SceneManagement.Scene scene, UnityEngine.SceneManagement.LoadSceneMode loadSceneMode)
                {
                }
        }
}

Interface

Represents a method to implement from an Interface. You have to specify:

  • Return type: class of the return type. Default value is void.
  • Namespace: namespace of the interface. This namespace is automatically added only to this C# script.
  • Interface: name of the interface.

The name of the function has exactly same name than the message rule ID. For example:

using UnityEngine.EventSystems;

namespace GameRules
{
        public class Test : IBeginDragHandler
        {
                public void OnBeginDrag (PointerEventData eventData)
                {
                }
        }
}

Interface message rules from Unity are already predefined in Core class from GameRulesCore ruleset.

Public Function

Represents a public function. You can specify the return type class. Default value is void.

The name of the function has exactly same name than the message rule ID. For example:

public void Fire()
{}

Using public functions facilitates direct interactions between a logic rule from a flow and another flow attached to a game object by using Call-Flow step method.

Unity MonoBehaviour

Represents message types inherited from MonoBehaviour. All message rules of this type are already predefined in Core class from GameRulesCore ruleset.

Typical message rules are OnGUI, Start, Update, FixedUpdate, ...

Unity StateMachineBehaviour

Represents message types inherited from StateMachineBehaviour to be used with Animation Flow rules. All message rules of this type are already predefined in Core class from GameRulesCore ruleset.

Typical message rules are OnStateEnter, OnStateExit, OnStateMove, OnStateIK, ...

Unity ScriptableObjects

Represents message types inherited from ScriptableObject. All message rules of this type are already predefined in Core class from GameRulesCore ruleset.

Typical message rules are Awake, OnEnable, OnDisable, OnDestroy, ...

Parameters

Each parameter defined is added to the method signature. You need to specify the C# class and the name of the parameter.

Property

About

A property rule represents a global variable. Because a property definition is a rule, it shares the benefits of versioning and inheritance that GameRules provides to all rules.

In all other rules (Logic, When, Flow, StateMachine, AnimationFlow, Property), you can easily refers to a property by using the prefix @. During rule assembly, the prefix is removed and the property rule is assembled also.

GameRules includes hundreds of standard properties useful to your game. Review the relevant existing properties before creating new properties.

General

Complete the property class field to specify the C# class or structure of the property (e.g. Vector3).

Options

Complete this tab for additional setup.

Visibility

When generating the property, it is declared as a global variable. This field drives the visibility of the variable:

  • public: generates a public global variable. This variable will be visible in Inspector when the script is attached to a GameObject.
  • public Hide in inspector: generates a public global variable so it will be visible for other scripts, but with the attribute [HideInInspector] this variable doesn’t show up in Inspector.
  • private: generates private global variable so it will not be visible outside the script.

Initialization Code

Specify the C# code used to initialize the variable. When Initialization Message is empty, this code is automatically added to the global variable. When Initialization Message is specified, it is generated instead inside the message rule.

For example, distance property has no Initialization Method:

public float distance = 0f;

For example, light property has Initialization Method = Awake:

private Light light;

// Awake is called when the script instance is being loaded.</color>
void Awake ()
{
        light = GetComponent<Light>();
}

Ruleset

About

Create a ruleset to identify, store, and manage the set of rules that define an application or a major portion of an application. Generally, you may need five to eight rulesets per application. Installation wizard automatically generates a ruleset with same name than the application.

How you use rulesets in your application has important design consequences. For large and complex games, several rulesets may be appropriate. Before you create a ruleset, think carefully about the purpose, use, and dependencies of current rulesets and the new ruleset. Then add your new ruleset to the Application rule.

GameRules provide GameRuleCore ruleset which contains hundreds of predefined rules to speed up game development.

Each ruleset contains one or more versions, using sequential integer. You can lock a ruleset version to prevent any rule belonging to this version from being modifiable. In that case, when you need to modify a rule, you have to save it in a higher unlocked ruleset version.

Versions

Use this tab to update any version rules defined for this ruleset, or to create additional versions.

For each ruleset version, you can setup:

  • Locked: identifies a locked or unlocked version. Simply click on the lock icon to change secured state.
  • Version: sequential integer.
  • Description: free form text.
  • All rules: shortcut to all rule instances created in this ruleset version.

State Machine

About

A StateMachine rule models a MonoBehaviour script in your game by using graphical shapes and connectors to behave as a finite state machine. Each time a new state machine is created, it is automatically added to current product rule. A StateMachine is made of state shapes where we can define logic processing in different messages, and connectors used to evaluate state transitions in different messages also.

In addition, events are automatically sent at each state transition to ease interactions with other game objects.

State Machine

State shape

A state shape represents a particular state. Double-click on the shape to open general configuration panel:

  • State properties
    • name: name of the state.
  • When entering state
    • logic: logic rule to process when entering this state. This logic rule executes only once each time the state machine enters this state.
  • When exiting state
    • logic: logic rule to process when exiting this state. This logic rule executes only once each time the state machine exits this state.
  • State logic rules
    • message and logic rule: Add as many message rules that you need. For each message, specifies the logic rule to process. For example, if you need to process MoveTank logic rule in FixedUpdate message for the state Move, then set message rule = FixedUpdate, logic rule = MoveTank. At rule assembly, the generated script will evaluate in FixedUpdate method if the current state is Move and if yes will call perform_MoveTank function.

Transition connector

  • Likelihood: this value determines in which order to evaluate different transitions from a state. For example, inside a same message Update, if Move state has two transitions to Fire and Pause states, then the highest likelihood is evaluated first.
  • Condition: a condition is made of a message rule and a when rule, and optionally a logic rule. The combination of message and when rule determines when to evaluate the transition (for example in FixedUpdate message, evaluate IsMoving when rule. The optional logic rule is performed if the condition is true, to be able to perform a processing specifically when transiting from one state to another. This logic rule executes before the when entering state logic rule specifies in the target state. You can add as many condition as you need in a transition connector.

Any state

The AnyState has no particular condition. Transitions defines from this shape are evaluated the same way than other transitions, whatever the current state is.

Parameters

Default state settings

A finit state machine needs to starts with a state. Here we indicate which starting state is used and in which message rule it is initialized. Typically, the default state is setup in Awake or Start message rule. If the default state has a logic rule specified when entering state, this logic rule will be performed when teh default state is setup.

  • State name: choose a state among defined states
  • State message: choose a message rule where the default state will be initialized

Persistence

The persistence option automatically saves in persistence storage the current state of the game object. Each time curren state changes, the storage is updated. At startup, when initializing the default state, the persisted state will be initialized instead of default state.

  • Persist state: enable the persistence.

Class

About

A class rule defines the inheritance path which is part of the rule resolution. A class is also used to classify other rules in the game. Subclasses are formed using ‘-‘ character (for example Tanks-Weapon-MachineGun).

Caution

A class rule is not related to C# class concept.

When creating a new class, parent class rules are automatically created if missing. If you create Tanks-Weapon-MachineGun class and if only Tanks class exists, an additional class rule Tanks-Weapon will be created also.

For class rule resolution, we distinguishes two types of hierarchy to build class hierarchy:

  • Naming hierarchy:
    • Tanks-Weapon-MachineGun
    • Tanks-Weapon
    • Tanks
  • Direct class inheritance list
    • Core (default value)

By default, a class rule has same direct inheritance than its parent class. Ultimately, the top class (Tanks) needs to specify the direct inheritance class list (Core by default). Any class rule can have a different direct inheritance class list.

for example Tanks-Weapon-MachineGun can define:

  • Ammo-Bullet
  • Core

In that case, the full inheritance class hierarchy for Tanks-Weapon-MachineGun will be:

  • Tanks-Weapon-MachineGun
  • Tanks-Weapon
  • Tanks
  • Ammo-Bullet
  • Ammo
  • Core

To ease maintenance and configuration, the inheritance class hierarchy is always recapitulated in class rule form.

Note

Try to always keep Core class at the bottom of the direct inheritance class list.

General

Created in ruleset

Enter here a ruleset name. This ruleset is only used when exporting the rules in zip file, to be sure that class rules are also exported with other rules from this particular ruleset.

Inheritance list

When same inheritance class list than parent is unchecked, you can specify the ordered list of class rules used for direct inheritance.

Rule resolution class hierarchy

Informational list of resulting class hierarchy which will apply for rule resolution algorithm.