# Reality Event Function System

## Reality Event Function System

The `Reality Event Function System` is used to attach reusable `Reality Functions` to gameplay events.

This system is used in:

* `Reality Game Data`
* `Reality Game Phase`

It allows you to define what should happen when an event occurs, such as:

* a player joining,
* a player dying,
* a player spawning,
* a team being created,
* a team score being updated,
* a custom named event being triggered.

> `Reality Game Data` defines the default event behavior for the whole game mode.\
> `Reality Game Phase` can define its own event behavior and override or extend the default behavior.

<figure><img src="/files/K4UOVRmyVMoKuYdXChf6" alt=""><figcaption></figcaption></figure>

***

## Overview

| Feature              | Description                                        |
| -------------------- | -------------------------------------------------- |
| Player Event Logic   | Attach functions to player-related gameplay events |
| GameMode Event Logic | Attach functions to team and GameMode events       |
| Custom Event Logic   | Attach functions to named custom events            |
| Default Extension    | Add logic before or after default behavior         |
| Full Override        | Replace default behavior completely                |
| Phase Override       | Phases can define their own event behavior         |
| Reusable Actions     | Uses `Reality Function` objects                    |

***

## Where This System Is Used

| System             | Usage                                                      |
| ------------------ | ---------------------------------------------------------- |
| Reality Game Data  | Stores the default event execution logic for the game mode |
| Reality Game Phase | Can define phase-specific event execution logic            |
| Reality GameMode   | Triggers event execution during gameplay                   |
| Reality Function   | Used as the executable action inside each event entry      |

***

## Execution Type

`Execution Type` controls how a specific event behaves compared to the default parent logic.

### Available Values

| Name                    | Description                                                                    |
| ----------------------- | ------------------------------------------------------------------------------ |
| Default                 | Uses the normal execution order after the default list                         |
| NotExec                 | No custom behavior is executed, and the default parent logic is not overridden |
| Additional Pre Default  | Runs custom logic before the default parent logic                              |
| Additional Post Default | Runs custom logic after the default parent logic                               |
| Override                | Fully replaces the default parent logic                                        |

***

## Execution Container Mode

`Execution Container Mode` controls how the whole event container behaves.

### Available Values

| Name               | Description                                           |
| ------------------ | ----------------------------------------------------- |
| Per Event          | Each event uses its own execution rule                |
| Override All Event | All events in the container are treated as overridden |

***

## Execution Logic Summary

| Mode                    | Result                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------ |
| Default                 | Keeps the normal parent logic and runs the configured function list in default order |
| NotExec                 | No custom execution for this event                                                   |
| Additional Pre Default  | Custom functions run before default logic                                            |
| Additional Post Default | Custom functions run after default logic                                             |
| Override                | Parent logic is replaced by the configured functions                                 |
| Override All Event      | The whole container overrides parent behavior for all events                         |

***

## Function Execution Entry

A single event entry is represented by an execution data structure.

### Function Execution Data

| Property                | Type  | Description                                                |
| ----------------------- | ----- | ---------------------------------------------------------- |
| Execution Type          | Enum  | Defines how this event entry interacts with parent logic   |
| Function Execution List | Array | List of `Reality Function` objects executed for this event |

***

### Usage

| Use Case                                           | Setup                   |
| -------------------------------------------------- | ----------------------- |
| Add extra logic after normal player spawn behavior | Additional Post Default |
| Add setup before the normal player spawn behavior  | Additional Pre Default  |
| Replace normal death behavior completely           | Override                |
| Disable custom event execution for one entry       | NotExec                 |

***

## Player Event Container

This container stores execution rules for player-related GameMode events.

### Supported Events

| Event                  | Description                                 |
| ---------------------- | ------------------------------------------- |
| Player Join            | Called when a player joins the game         |
| Player Exit            | Called when a player leaves the game        |
| Player Die             | Called when a player dies                   |
| Player Spawn           | Called when a player is spawned             |
| Player Request Respawn | Called when a player requests a respawn     |
| Player Spectating      | Called when a player enters spectating mode |
| Player Kill Player     | Called when a player kills another player   |

***

### Player Event Container Structure

| Property                      | Type | Description                                                                |
| ----------------------------- | ---- | -------------------------------------------------------------------------- |
| Override Execution Event Type | Enum | Defines whether the container uses per-event rules or overrides all events |
| Player Event                  | Map  | Maps each player event to its execution data                               |

***

## GameMode Event Container

This container stores execution rules for GameMode and team-related events.

### Supported Events

| Event              | Description                                 |
| ------------------ | ------------------------------------------- |
| Team Created       | Called when a team is created               |
| Team Destroyed     | Called when a team is removed               |
| Team Initialized   | Called when a team is initialized and ready |
| Team Score Updated | Called when a team score changes            |
| Team Eliminate     | Called when a team is eliminated            |

***

### GameMode Event Container Structure

| Property                      | Type | Description                                                                |
| ----------------------------- | ---- | -------------------------------------------------------------------------- |
| Override Execution Event Type | Enum | Defines whether the container uses per-event rules or overrides all events |
| GameMode Event                | Map  | Maps each GameMode event to its execution data                             |

***

## Custom Event Container

This container stores execution rules for custom named events.

### Structure

| Property                      | Type | Description                                                                |
| ----------------------------- | ---- | -------------------------------------------------------------------------- |
| Override Execution Event Type | Enum | Defines whether the container uses per-event rules or overrides all events |
| Custom Event                  | Map  | Maps event names to execution data                                         |

***

### Usage

| Use Case                                | Example                                             |
| --------------------------------------- | --------------------------------------------------- |
| Trigger project-specific gameplay logic | Custom event named `RoundWin`                       |
| Handle mod-specific behavior            | Custom event named `SpecialObjectiveCompleted`      |
| Create reusable gameplay hooks          | Trigger named custom events from GameMode or phases |

***

## Relationship Between Game Data and Phases

This is the most important part of the system.

### Default Behavior

| Source             | Role                                                         |
| ------------------ | ------------------------------------------------------------ |
| Reality Game Data  | Defines the default event execution logic for the whole game |
| Reality Game Phase | Can define phase-specific event execution logic              |

***

### Phase Override Behavior

| Situation                                 | Result                                                             |
| ----------------------------------------- | ------------------------------------------------------------------ |
| No phase-specific event entry             | Uses the default behavior from Game Data                           |
| Phase entry with Additional Pre Default   | Runs phase logic before Game Data logic                            |
| Phase entry with Additional Post Default  | Runs phase logic after Game Data logic                             |
| Phase entry with Override                 | Replaces the default Game Data logic for that event                |
| Phase container set to Override All Event | All matching default behavior is overridden by the phase container |

***

## Practical Flow

| Step | Result                                                                    |
| ---- | ------------------------------------------------------------------------- |
| 1    | Event is triggered by the GameMode or another system                      |
| 2    | The system checks whether the active phase has event logic for that event |
| 3    | If the phase defines override behavior, that rule is applied              |
| 4    | Otherwise, the default logic from Game Data is used                       |
| 5    | The associated `Reality Function` list is executed                        |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://beyond-sandbox.gitbook.io/realitysdk/documentation/gamemode/game-data/reality-event-function-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.