Preferences

A preference is special type of field that can store a value on a player entity persistently between games.

pub preference owner.LikesCarrots

pub fn owner.Example() {
    Transmission { "Do you like carrots, Y/N?" }
    
    on ButtonDown(BtnY) {
        LikesCarrots = true
    }
    on ButtonDown(BtnN) {
        LikesCarrots = false
    }
    
    Transmission {
        with LikesCarrots {
            if IsUndefined(LikesCarrots) {
                "We don't know yet if you like carrots"
            } else if LikesCarrots {
                "You like carrots!"
            } else {
                "You don't like carrots!"
            }
        }
    }
}

Declaration

Every preference must have a subject parameter, and the subject parameter must be owner, representing the player who owns the preference.

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

preference owner.LikesCarrots

Preferences 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.

pub preference owner.LikesCarrots

It is not possible to have two preferences with the same name, even if they are both private and in separate files. Doing so will generate a compiler error. This is because the preference name forms a globally unique key which is used to look up the value from persistent storage.

Working with preferences

Reading a preference using its name.

let value = LikesCarrots // implicit subject (recommended)
let value = owner.LikesCarrots // or explicit subject

Write to a preference by using an assignment statement =. The value will be stored in the player's browser storage immediately, which may take time, so it is best to only call this when needed.

LikesCarrots = true // implicit subject (recommended)
owner.LikesCarrots = true // or explicit subject

await can be used to wait until a preference changes.

let value = await LikesCarrots // implicit subject (recommended)
let value = await owner.LikesCarrots // or explicit subject

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

with LikesCarrots {
    Transmission {
        if LikesCarrots {
            "You like carrots!"
        } else {
            "You don't like carrots!"
        }
    }
}

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

delete LikesCarrots // implicit subject
delete owner.LikesCarrots // or explicit subject

Limits

Preferences are stored in the user's browser storage. A maximum of 4 KB of data can be stored per player. This is quite small, so is not suitable for storing large amounts of data. If the stored preferences exceed the limit, the data may be dropped, and the player will be treated as a new player with undefined preferences the next time they play.

Serializable values only

Only serializable values can be stored in a preference. This is because the value must be stored and loaded in a way that is compatible with not just future versions of the engine, but also your Easel program.

IDs

When a preference 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.

Declare the ID after the preference name using angle brackets. The ID may be declared as optional with a question mark (?) suffix.

pub preference owner.Likes<V>
pub symbol Apple
pub symbol Banana

pub fn owner.Example() {
    Transmission {
        "Press A if you like Apples, B if you like Bananas"
    }
    
    on ButtonDown(BtnA) {
        Likes<Apple> = true
    }
    on ButtonDown(BtnB) {
        Likes<Banana> = true
    }
    
    Transmission {
        with Likes<Apple>, Likes<Banana> {
            "You "
            %(Likes<Apple> ? "like" : "don't like")
            " Apples and you "
            %(Likes<Banana> ? "like" : "don't like")
            " Bananas"
        }
    }
}