> ## 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.

# Game Economy

> Design your gamification economy with EngageFabric. Configure XP curves, virtual currencies, level thresholds, and achievement reward systems.

EngageFabric provides a complete game economy system that you can customize for your application.

## How the Economy Works

```mermaid theme={null}
flowchart LR
    E[Event Tracked] --> R[Rules Engine]
    R --> XP[Award XP]
    R --> C[Award Currency]
    R --> A[Unlock Achievement]
    XP --> LV[Level Up Check]
    LV -->|Threshold Met| LU[Level Up!]
    C --> S[Currency Balance]
```

Events flow through the rules engine and trigger economy actions -- awarding XP, granting currency, or unlocking achievements. XP accumulates toward level thresholds, and currency updates the player's balance.

***

## Experience Points (XP)

XP is the primary measure of player progress. Players earn XP by completing actions, and XP accumulates toward level progression.

### Awarding XP

XP can be awarded through:

* **Rules Engine**: Automatically via event triggers
* **API**: Direct XP grants for custom logic

```javascript theme={null}
// Via Rules Engine (automatic)
await client.events.track({
  playerId: 'player-123',
  name: 'lesson_completed',
  properties: { courseId: 'math-101' }
});
// Rule: "lesson_completed" → Grant 100 XP

// Via API (manual)
await client.players.grantXP('player-123', {
  amount: 100,
  reason: 'bonus_reward'
});
```

***

## Levels

Levels represent milestones in player progression. Configure how players level up with **level curves**.

### Level Curve Types

<Tabs>
  <Tab title="Linear">
    XP required increases by a fixed amount per level.

    ```
    Level 1: 100 XP
    Level 2: 200 XP
    Level 3: 300 XP
    ...
    ```

    **Formula:** `xpRequired = baseXP * level`
  </Tab>

  <Tab title="Exponential">
    XP required grows exponentially, making higher levels harder to achieve.

    ```
    Level 1: 100 XP
    Level 2: 150 XP
    Level 3: 225 XP
    ...
    ```

    **Formula:** `xpRequired = baseXP * (multiplier ^ (level - 1))`
  </Tab>

  <Tab title="Custom Table">
    Define exact XP requirements for each level.

    ```json theme={null}
    {
      "1": 100,
      "2": 250,
      "3": 500,
      "4": 1000,
      "5": 2000
    }
    ```
  </Tab>
</Tabs>

### Level-Up Events

When a player levels up, EngageFabric:

1. Emits a `level_up` WebSocket event
2. Can trigger rules for level-up rewards
3. Updates the player's level in the database

```javascript theme={null}
// Subscribe to level-up events
socket.on('level_up', (data) => {
  console.log(`Player reached level ${data.newLevel}!`);
  showLevelUpAnimation();
});
```

***

## Currencies

Support multiple virtual currencies for different purposes.

### Currency Types

| Type               | Example        | Use Case                |
| ------------------ | -------------- | ----------------------- |
| **Soft Currency**  | Coins, Gold    | Earned through gameplay |
| **Hard Currency**  | Gems, Diamonds | Premium/purchased       |
| **Event Currency** | Event Tokens   | Limited-time events     |

### Managing Currencies

```javascript theme={null}
// Grant currency
await client.players.grantCurrency('player-123', {
  currencyId: 'coins',
  amount: 500
});

// Spend currency
await client.players.spendCurrency('player-123', {
  currencyId: 'coins',
  amount: 100
});

// Get balances
const player = await client.players.get('player-123');
console.log(player.currencies);
// { coins: 400, gems: 50 }
```

***

## Lives / Energy

Implement session-limiting mechanics with the lives system.

### Configuration

| Setting       | Description                       |
| ------------- | --------------------------------- |
| `maxLives`    | Maximum lives a player can have   |
| `regenRate`   | Minutes between life regeneration |
| `regenAmount` | Lives restored per regeneration   |

### Example Flow

```
Player starts with 5 lives
↓
Player uses 1 life to attempt a level
↓
Player has 4 lives remaining
↓
After 30 minutes, 1 life regenerates
↓
Player has 5 lives (capped at max)
```

### API Usage

```javascript theme={null}
// Check lives
const player = await client.players.get('player-123');
console.log(`Lives: ${player.lives}/${player.maxLives}`);

// Use a life
await client.players.useLive('player-123');

// Grant bonus lives
await client.players.grantLives('player-123', { amount: 3 });
```

***

## Economy Configuration

Configure your game economy in the Admin Console or via API:

```json theme={null}
{
  "xp": {
    "enabled": true
  },
  "levels": {
    "enabled": true,
    "curveType": "exponential",
    "baseXP": 100,
    "multiplier": 1.5,
    "maxLevel": 100
  },
  "currencies": [
    {
      "id": "coins",
      "name": "Coins",
      "icon": "coin",
      "initialBalance": 100
    },
    {
      "id": "gems",
      "name": "Gems",
      "icon": "gem",
      "initialBalance": 0
    }
  ],
  "lives": {
    "enabled": true,
    "maxLives": 5,
    "regenRateMinutes": 30,
    "regenAmount": 1
  }
}
```

<Tip>
  Start with a simple economy and expand based on player feedback.
  Overly complex economies can overwhelm new users.
</Tip>