Events

on city.powerChanged(powered)       // catalog: city.powerChanged {powered: boolean}
    hasPower = powered
end

on building.visitorEntered          // no payload
    business.visitors += 1
end

The catalog

Events come from the game's catalog: in Caria, the project's .event documents. Each has an id (city.powerChanged), a label, a scope, a producer and a payload:

{
  "version": 1,
  "id": "city.powerChanged",
  "label": "Town power changed",
  "scope": "city",
  "producer": "test",
  "payload": [{"key": "powered", "label": "Power", "type": "boolean", "default": false}]
}

• An event name the catalog does not know is a compile error.
• Scope: a self event reaches only its own object; a city event reaches every subscriber.
• Producer: engine events come only from the game itself; test events can also be sent from Play's Events panel. Sending events from a script comes in the next version.

Handlers

• Declaring a handler subscribes to the event.
• Parameters bind to the payload's fields by name and take their types from the catalog. A type may be written; it must match.
• A handler runs to its end and cannot wait. One handler runs at a time in an instance; there is no reentry.
• Inside a state, a handler answers only while the instance is in that state (States).

Lifecycle events

Written only at the script's level:

• on ready runs once, when a new instance starts (Lifecycle).
• on migrate(from: int) runs when a live world moves to a new version of the script; from is the old version (Saving and migration).

Changes of fields

When a transaction changes an object's fields, the game raises object.stateChanged for that object. In its handler, changed(field) tells whether a declared field is among the changes; the new value is read from the field itself.

on object.stateChanged
    if changed(business.open)
        log("open: {business.open}")
    end
end

Events from fields

The world can publish events from its own fields: a rule on the world names the event, the field that sends it (when) and which fields fill its payload. When a transaction really changes the when field, the event goes out with the fields' new values. For example, the world's power.on field can send city.powerChanged, which every business hears.