Props

A prop is special type of property that can store a value on an entity. It differs from a field in that it signals when it changes.

pub prop hero.Health
pub fn hero.Example() {
    Health = 100
    with Health {
        Transmission { "Health: " + Health }
    }
    Health = 75
}
// Outputs "Health: 100" then "Health: 75"

Declaration

Every prop must have 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 prop. When accessing the prop, the object will be found implicitly from context if not specified explicitly.

The prop's name must begin with an uppercase letter.

prop hero.Health
prop World.NumBananas

Props 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 file it is declared within. If two private props have the same name but are in different files, they are not the same prop and will not interfere with each other.

pub prop hero.Health
pub prop World.NumBananas

Working with props

Reading a prop using its name.

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

Write to a prop by using an assignment statement =.

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

await can be used to wait until a prop changes. The new value of the prop will be returned.

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

Like all other await functions, it is possible to use with, on or once to handle the change.

with Health {
    Transmission { "Health: " + Health }
}

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

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

IDs

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

The ID may be optional.

pub symbol HeadSlot
pub symbol HandSlot

pub prop hero.Inventory<Id>

pub fn hero.Example() {
    on Inventory<HeadSlot> {
        Transmission { "Head: " + Inventory<HeadSlot> }
    }
    on Inventory<HandSlot> {
        Transmission { "Hand: " + Inventory<HandSlot> }
    }
    
    Inventory<HeadSlot> = $helmetOfWisdom
    Inventory<HandSlot> = $swordOfRighteousness
}
// Outputs "Head: $helmetOfWisdom" then "Hand: $swordOfRighteousness"

Local Properties

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

pub fn hero.ExcitementSystem() {
    prop hero.Excitement = 100
    
    on ButtonDown(KeySpacebar) {
        Excitement += 10
    }

    Content {
        with Excitement {
            "Current excitement level: " + Excitement
        }
    }
}

Initializing a local property

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

pub fn hero.ExcitementSystem() {
    prop hero.Excitement = 100 // resets Excitement to 100 every time `ExcitementSystem` 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.ExcitementSystem() {
    // only sets Excitement to 100 if it is not already set
    prop hero.Excitement ??= 100
    
    // any changes to Excitement are retained between calls to `ExcitementSystem`
    // because of the use of the optional assignment operator ??=
    on ButtonDown(KeySpacebar) {
        Excitement += 10
    }
}