GameBus expression language

GameBus expression language is used for transforming data and evaluating conditions. It's designed to be readable by non-programmers while powerful enough for complex business logic.

GameBus expression language is a port of the GoRules ZEN expression language.

Expressions and progress displays

Task rules, skill outcomes, and milestone gateways use this expression language.

Expressions can use $. as their root reference. GameBus converts this internally to ZEN's $root. syntax.

Task expressions

Task expressions receive the activity properties as an object keyed by property slug.

For example, this activity property:

{
  "template": "duration",
  "obj": {
    "value": 25,
    "unit": "minutes"
  }
}

is available to an expression as:

{
  "duration": {
    "value": 25,
    "unit": "minutes"
  }
}

This allows expressions such as:

Context	Expression	Meaning
Task rule	`$.duration.value >= 20`	Match an activity lasting at least 20 configured units.
Task rule	`$.completionPercentage.value >= 100`	Match a completed video.
Skill outcome	`10`	Add 10 points to the linked skill.
Skill outcome	`$.distance.value / 1000`	Calculate an outcome from an activity property.

Gateway expressions

Each milestone gateway is linked to one skill. Its expression therefore receives the participant's and group's achievements for that skill directly.

For example:

$.member.contribution >= 40

fires when the participant reaches 40 points for the skill linked to the gateway.

Gateway input has the following shape:

{
  "member": {
    "contribution": 40
  },
  "group": {
    "contribution": {
      "sum": 120,
      "min": 0,
      "max": 50,
      "avg": 24,
      "median": 20,
      "countOfContributors": 4
    }
  }
}

Examples include:

Expression	Meaning
`$.member.contribution >= 40`	Fire when the participant reaches 40 points.
`$.group.contribution.avg >= 20`	Fire when the group's average reaches 20 points.
`$.group.contribution.countOfContributors >= 5`	Fire when at least five members have a positive contribution.

The expression does not need to identify the skill itself. member and group always refer to the skill linked to the gateway.

When gateways are evaluated

Gateway evaluation depends on its evaluationType:

CONTRIBUTION_BASED gateways are evaluated after an activity changes the relevant member or group skill contribution.
TIME_BASED gateways are evaluated when their evaluationCron is reached.
A milestone transition can itself trigger further task or gateway evaluation when the resulting activity qualifies elsewhere.

Gateways are evaluated by order and then ID within each active milestone enrollment. The milestone's hitPolicy determines whether evaluation stops after the first successful gateway or continues across all gateways.

Reading a page can also evaluate a gateway to show its current outcome, but these read-only evaluations do not advance the participant.

Progress displays

Milestones do not have a separate progress expression.

Instead, progress displays use the optional goal of a skill:

(contribution / goal) × 100

The displayed percentage is clamped between 0 and 100%.

The underlying contribution is not clamped. A participant can therefore have a negative contribution or exceed the configured goal without changing the stored value.