Entity Scope

Scopes represents a Lua UserData contextual condition entity contained data information scope. It stores the entity's attributes and properties that can be used in conditions at evaluation time.

The scope is referred as self in the condition's lua scripts.

📔 Note

Properties that are configured with their boolean field hide_from_conditions as true will not be accessible from with-in entity's scopes in conditionals evaluation.

The scopes also contains information about the entity as its name, description, id, template and version.

How to create an Entity Scope

Entity scopes can be created programmatically from Lua or Rust APIs using the generate_scope method from the Entity UserData in a Lua context or by using the Scope::new method from Rust.

To access an attribute or property from with-in the scope in a conditional expression syntax, one can just reference the attribute or property name using the dot notation [.] like in the example below.

self.str >= 5

Field access missing behavior

How a scope behaves when a field that is being tried to be access is missing can be configured when we instantiate a new scope with the parameter non_field_behavior. The possible behaviors are to return nil or to raise an error. The value of the non_field_behavior differs depending on the API we are using.

Lua API `non_field_behavior`

In the Lua API, the non_field_behavior value can be a string, an integer or nil.

String values

The possible and accepted values for non_field_behavior are the following:

error: alacrity will raise an error if the field being accessed does not exists (this is the safest option)
nil: alacrity will return nil if the field is not found (emulating how a Lua table would behave)

Integer values

The possible and accepted values when using an integer are the following:

0: alacrity will raise an error if the field being accessed does not exists (safest option)
1: alacrity will return nil emulating the behavior of a Lua table

Rust API `non_field_behavior`

In the rust API the non_field_behavior parameter accepts one of the variants of the NonFieldBehavior enum from the Scope type, the possible variants are Error and Nil, their names are self explanatory.

📔 Note

You don't usually need to create Entity scopes manually unless you are doing some manual conditional verifications in Lua space, generally, Alacrity will handle the creation of scopes when they are needed automatically.

Alacrity Book