Skip to main content

Fields

A field is a property of an entity that can store a value.

field hero.Health
pub fn hero.Example() {
    hero.Health = 100
    Health = 75 // `hero` is implicit
    Transmission { "Your health is: " + Health }
    delete Health // delete the field
}

Declaration​

Every field must be declared with an object parameter. The object parameter designates the entity on which the value will be stored. The object parameter can be any identifier beginning with a lowercase letter, or World to make a global field. When accessing the field, the object will be found implicitly from context if not specified explicitly.

A field's name must begin with an uppercase letter.

field hero.Health
field World.NumBananas

Public vs Private​

Fields can be declared as public using the pub keyword, which allows them to be accessed from all files in the program. Otherwise they are private and can only be accessed from within the same file. If two private fields have the same name but are in different files, they are not the same field and will not interfere with each other.

pub field hero.Health
pub field World.NumBananas

Fields can also be declared local to a function, see Local Fields.

Working with fields​

Reading a field using its name. The object will be found implicitly if not specified explicitly.

let value = Health // implicit object (recommended)
let value = hero.Health // or explicit object

Write to a field by using an assignment statement =.

Health = 100 // implicit object (recommended)
hero.Health = 100 // or explicit object

Fields can also be deleted to remove their value from memory.

delete Health // implicit object (recommended)
delete hero.Health // or explicit object

IDs​

When a field is declared with an ID, it stores multiple values that can only be accessed with when using the same ID. This enables code to be more generic.

The ID may be optional.

pub symbol HeadSlot
pub symbol HandSlot
field hero.Inventory<Id>

pub fn hero.Example() {
    Inventory<HandSlot> = $swordOfRighteousness
    Inventory<HeadSlot> = $helmetOfWisdom
}

Local Fields​

If you declare a field inside a function, then field will only be accessible from within that function. Because the field is stored on an entity, it will retain its value between calls to the function.

pub fn hero.DrinkPoison() {
    field hero.PoisonLevel += 10 // increase the poison level by 10 each time the function is called
    if PoisonLevel >= 100 {
        Print { "You are dead!" }
    } else {
        Print { "You feel sick." }
    }
}

Initializing a local field​

If you assign a value to a local field using =, it will reset the value every time.

pub fn hero.Example() {
    field hero.Excitement = 100 // resets Excitement to 100 every time `Example` is called
    Print { "Current excitement level: " + Excitement } // always prints 100
}

If you want to only set the value once, then retain it between calls, you can use the optional assignment operator ??=, which will only set the value if it is not already set:

pub fn hero.Example() {
    field hero.Excitement ??= 100 // only sets Excitement to 100 if it is not already set
    
    // Changes to Excitement will not be overwritten because of the optional assignment operator
    on ButtonDown(KeySpacebar) {
        Excitement += 10
    }
}