Condition Definitions

{
  "conditionDefs": {
    "blocked_user": {
      "any": [
        {
          "type": "IS_BANNED"
        },
        {
          "type": "IS_SUSPENDED"
        }
      ]
    },
    "eligible_reward": {
      "all": [
        {
          "type": "LEVEL_AT_LEAST",
          "params": {
            "level": 10
          }
        },
        {
          "!ref": "blocked_user"
        }
      ]
    }
  },
  "rules": [
    {
      "trigger": "PLAYER_JOINED",
      "conditions": [
        {
          "ref": "eligible_reward"
        }
      ],
      "actions": [
        {
          "type": "GIVE_COINS",
          "params": {
            "amount": 25
          }
        }
      ]
    }
  ]
}

ref uses a named condition definition. !ref is equivalent to not wrapping that reference.

Definitions can contain static conditions, expression conditions, operators, ref, and !ref. References are resolved during engine construction, not at runtime.

Combine With Expressions

Keep one condition shape per object. Combine a reference with an expression by using all or any:

{
  "all": [
    {
      "ref": "eligible_reward"
    },
    {
      "type": "expr",
      "expr": "wallet.coins < 100"
    }
  ]
}

This keeps the JSON predictable and avoids special cases such as mixing ref and expr in the same object.

Compile-Time Behavior

• unknown references fail during compilation
• cyclic references fail during compilation
• unused condition definitions are not compiled into the engine
• a definition that contains expressions requires expressions only if it is actually used

Recommendations

• follow YAGNI: do not define a condition before it is reused
• prefer domain names such as eligible_reward or blocked_user
• do not hide very large decision trees behind one name
• keep reusable definitions close to concepts that reviewers understand
• move complex domain checks to static Java conditions