> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engagefabric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules Engine

> Build event-driven gamification rules with EngageFabric. Create triggers that award XP, unlock achievements, and progress quests automatically.

The Rules Engine is the heart of EngageFabric's automation. Define rules that automatically trigger actions when events occur.

## How It Works

```mermaid theme={null}
graph LR
    A[Event] --> B[Rules Engine]
    B --> C{Conditions Met?}
    C -->|Yes| D[Execute Actions]
    C -->|No| E[Skip]
    D --> F[Update Player]
    D --> G[Emit Events]
```

When an event arrives, the rules engine evaluates all matching rules. If conditions are met, it executes the configured actions and updates player state.

### Event Processing Detail

```mermaid theme={null}
flowchart TD
    EV[Incoming Event] --> M{Match Rules}
    M -->|Rule 1| AX[Award XP]
    M -->|Rule 2| PQ[Progress Quest]
    M -->|Rule 3| UL[Update Leaderboard]
    M -->|Rule 4| WH[Fire Webhook]
    AX --> PC[Player State Updated]
    PQ --> PC
    UL --> PC
```

A single event can trigger multiple rules simultaneously -- awarding XP, progressing quests, updating leaderboards, and firing webhooks all from one event.

## Rule Structure

Every rule consists of:

* **Trigger**: The event that activates the rule
* **Conditions**: Optional filters to check before executing
* **Actions**: What happens when conditions are met

```json theme={null}
{
  "name": "Award XP for lesson completion",
  "trigger": {
    "event": "lesson_completed"
  },
  "conditions": [
    {
      "type": "property_equals",
      "property": "properties.passed",
      "value": true
    }
  ],
  "actions": [
    {
      "type": "GRANT_XP",
      "amount": 100
    },
    {
      "type": "PROGRESS_QUEST",
      "questId": "complete-10-lessons"
    }
  ]
}
```

***

## Condition Types

<AccordionGroup>
  <Accordion title="property_equals">
    Check if an event property equals a specific value.

    ```json theme={null}
    {
      "type": "property_equals",
      "property": "properties.category",
      "value": "premium"
    }
    ```
  </Accordion>

  <Accordion title="property_greater_than">
    Check if a numeric property exceeds a threshold.

    ```json theme={null}
    {
      "type": "property_greater_than",
      "property": "properties.score",
      "value": 80
    }
    ```
  </Accordion>

  <Accordion title="property_less_than">
    Check if a numeric property is below a threshold.

    ```json theme={null}
    {
      "type": "property_less_than",
      "property": "properties.errors",
      "value": 3
    }
    ```
  </Accordion>

  <Accordion title="player_level_equals">
    Check the player's current level.

    ```json theme={null}
    {
      "type": "player_level_equals",
      "value": 10
    }
    ```
  </Accordion>

  <Accordion title="player_level_greater_than">
    Check if player has reached a minimum level.

    ```json theme={null}
    {
      "type": "player_level_greater_than",
      "value": 5
    }
    ```
  </Accordion>

  <Accordion title="time_window">
    Only trigger during specific times.

    ```json theme={null}
    {
      "type": "time_window",
      "startHour": 9,
      "endHour": 17,
      "timezone": "UTC"
    }
    ```
  </Accordion>

  <Accordion title="first_time">
    Only trigger the first time this event occurs for the player.

    ```json theme={null}
    {
      "type": "first_time"
    }
    ```
  </Accordion>

  <Accordion title="cooldown">
    Limit how often a rule can trigger for a player.

    ```json theme={null}
    {
      "type": "cooldown",
      "minutes": 60
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Action Types

<AccordionGroup>
  <Accordion title="GRANT_XP">
    Award experience points to the player.

    ```json theme={null}
    {
      "type": "GRANT_XP",
      "amount": 100
    }
    ```
  </Accordion>

  <Accordion title="GRANT_CURRENCY">
    Award virtual currency.

    ```json theme={null}
    {
      "type": "GRANT_CURRENCY",
      "currencyId": "coins",
      "amount": 50
    }
    ```
  </Accordion>

  <Accordion title="GRANT_BADGE">
    Award a badge to the player.

    ```json theme={null}
    {
      "type": "GRANT_BADGE",
      "badgeId": "first-purchase"
    }
    ```
  </Accordion>

  <Accordion title="PROGRESS_QUEST">
    Increment progress on a quest.

    ```json theme={null}
    {
      "type": "PROGRESS_QUEST",
      "questId": "complete-10-lessons",
      "amount": 1
    }
    ```
  </Accordion>

  <Accordion title="UNLOCK_QUEST">
    Make a quest available to the player.

    ```json theme={null}
    {
      "type": "UNLOCK_QUEST",
      "questId": "advanced-challenges"
    }
    ```
  </Accordion>

  <Accordion title="UPDATE_LEADERBOARD">
    Update a player's leaderboard score.

    ```json theme={null}
    {
      "type": "UPDATE_LEADERBOARD",
      "leaderboardId": "weekly-xp",
      "score": "${player.xp}"
    }
    ```
  </Accordion>

  <Accordion title="SEND_NOTIFICATION">
    Send a push notification or in-app message.

    ```json theme={null}
    {
      "type": "SEND_NOTIFICATION",
      "title": "Achievement Unlocked!",
      "message": "You've completed your first quest!"
    }
    ```
  </Accordion>

  <Accordion title="EMIT_EVENT">
    Emit a custom event (can trigger other rules).

    ```json theme={null}
    {
      "type": "EMIT_EVENT",
      "eventName": "milestone_reached",
      "properties": {
        "milestone": "first_purchase"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Dynamic Values

Use dynamic values in actions with template syntax:

| Variable                | Description            |
| ----------------------- | ---------------------- |
| `${player.id}`          | Player's ID            |
| `${player.xp}`          | Player's current XP    |
| `${player.level}`       | Player's current level |
| `${event.name}`         | Triggering event name  |
| `${event.properties.X}` | Event property value   |

**Example:**

```json theme={null}
{
  "type": "GRANT_XP",
  "amount": "${event.properties.score * 10}"
}
```

***

## Rule Priority

When multiple rules can trigger from the same event, they execute in priority order:

```json theme={null}
{
  "name": "High priority rule",
  "priority": 100,
  "trigger": { "event": "purchase_completed" }
}
```

Higher priority numbers execute first.

***

## Testing Rules

Use the Rules Sandbox in the Admin Console to test rules before deploying:

1. Select a rule to test
2. Provide a mock event payload
3. See which actions would execute
4. Verify conditions are evaluated correctly

<Tip>
  Always test rules in a staging environment before deploying to production.
  Use test API keys and test players to verify behavior.
</Tip>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep rules simple" icon="sparkles">
    One rule should do one thing well. Chain multiple rules for complex logic.
  </Card>

  <Card title="Use meaningful names" icon="tag">
    Name rules clearly so team members understand their purpose.
  </Card>

  <Card title="Add cooldowns" icon="clock">
    Prevent abuse by adding cooldowns to high-reward rules.
  </Card>

  <Card title="Test thoroughly" icon="flask">
    Use the sandbox and staging environments before production.
  </Card>
</CardGroup>