Eigenschaftsformeln schreiben

Writing Property Formulas

A property formula is a short expression that computes a property's value at every timestep. Think of it as a spreadsheet formula that knows about the graph: it can read other properties on the same agent, look at past timesteps, and traverse links to neighboring agents.

Formulas are written in Rhai, a small scripting language designed to feel familiar if you've ever written JavaScript, Python, or Excel formulas. You don't need to learn the whole language to be productive — most useful formulas are one or two lines.

Where formulas live

Formulas are defined on a node type (the metamodel level), so all agents of that type share the same formula by default. To add one:

Select the node type in the Tree View (e.g., "Employee")
Open the Properties Panel
In the property list, tick the formula checkbox (marked with f(x)) for the property you want to drive
A formula editor appears — type your Rhai expression there

The next time the simulation evaluates, every agent of this type uses the formula to fill in that property at every timestep.

Reading the agent's own values

Inside a formula, the current agent is available as agent:

agent.get_prop("salary")           // current value
agent.get_prop("salary", -1)       // value one timestep ago
agent.get_prop("salary", -3)       // value three timesteps ago

The second argument is an offset — negative numbers look back in time. This is how you write self-referential formulas without infinite recursion: agent.get_prop("x", -1) reads yesterday's value to compute today's.

A first formula: 3% annual raise

If your timesteps are months, a salary that grows 3% in January and stays flat the rest of the year:

if __timestep % 12 == 0 && __timestep > 0 {
    agent.get_prop("salary", -1) * 1.03
} else {
    agent.get_prop("salary", -1)
}

__timestep is the current step's index (0, 1, 2, …). You also have __dt (the scenario's step size) for time-scaled rates.

Reading other agents through the graph

The graph is the way agents coordinate. To pull values from connected agents:

// Total payroll across all team members
sum_prop(get_connected(agent, "has_member"), "salary")

get_connected returns the agents reachable via a relationship type. sum_prop, count_prop, and any of Rhai's array methods (.filter(), .map(), .len()) work on the result.

When formulas fall short, reach for an act method

A property formula computes one value. If a behavior touches several properties at once, or if the logic depends on the order of property updates, write an act method instead — a longer Rhai script attached to the node type. See Writing Act Methods.

Start simple, scale up

Many models live their entire lives on one-line formulas. The point isn't to write clever Rhai — it's to push the busywork out of the spreadsheet. Reach for the more advanced patterns (history reads, graph traversal, custom helpers from rhai-sci) only when the simpler form genuinely can't express what you need.

Next steps

Reading Connected Agents in Rhai — graph traversal patterns in detail
Writing Act Methods — multi-property updates and state transitions
Diagnosing Simulation Errors and Warnings — when a formula doesn't do what you expect
Rhai Function Reference — the full list of agent methods and helpers