Events Manager Architecture Technical

The Events Manager is a distributed system designed to handle real-time game events, leaderboards, and goal tracking. It operates on a client-server model where Unity clients communicate with a PHP/MySQL backend.

System Components

Client Runtime (Singleton): bl_GameEventManager handles data synchronization, polling, and state management in the game.
Admin/Editor Manager: bl_EventManager allows developers/admins to create and manage events from the Unity Editor or a dedicated Admin build.
Configuration: bl_EventManagerSettings (ScriptableObject) centralizes connection settings, timeouts, and logging policies.
Backend: bl_EventManager.php acts as the API gateway, interfacing with the MySQL database.

Data Flow

Initialization: Client connects to the PHP backend using the URL defined in bl_LoginProDataBase or manual configuration.
Polling: bl_GameEventManager periodically polls for active events (default: 30s).
Event State: When an event is active, the client receives EventDetails (Goals, XP Boosts, End Time).
Interaction: Player actions (Kills/Wins) are sent to the server to update the live leaderboard.

Installation & Setup

1. Server-Side Setup

Upload the PHP files to your web server.

                    /YourServerRoot/

                    ├── bl_Common.php (Required dependency)

                    ├── bl_EventManager.php

                    └── ...

Database: The system will automatically create the bl_game_events table on the first API call if it doesn't exist. Ensure your database user has CREATE TABLE permissions.

2. Unity Setup

Import the EventsManager package into your project.
Locate the EventManagerSettings asset in Resources/EventManagerSettings.asset.
Ensure TextMeshPro is installed in your project.

Configuration

The system is configured primarily through the bl_EventManagerSettings ScriptableObject.

Settings Asset

Setting	Type	Description	Default
Connection Timeout	Float	Max time (seconds) to wait for server response.	5.0
Max Retries	Int	Number of retry attempts for failed requests.	3
Update Interval	Float	Frequency (seconds) of event data polling.	30.0
Enable Logs	Bool	Master switch for internal logging system.	True
Log Categories	Struct	Fine-grained control over log types (Network, UI, etc.).	All True

PHP Host Configuration

The system resolves the PHP URL in two ways:

With ULSP (Login Pro): Automatically uses bl_LoginProDataBase.Instance.PhpHostPath.
Standalone: You must manually set the path in bl_EventManager.cs or ensure your custom implementation provides it.

Server API Reference

The bl_EventManager.php script handles all requests. It expects a POST or GET request with an action parameter.

Database Schema (bl_game_events)

                    id (INT, PK, AI)
                    event_name (VARCHAR)
                    event_mode (VARCHAR)   - e.g., "Team Deathmatch"
                    event_server (VARCHAR) - Region code (e.g., "us", "eu")
                    xp_boost (INT)         - Multiplier (e.g., 2)
                    goal (VARCHAR)         - "kills" or "wins"
                    status (VARCHAR)       - "Open", "Closed", "Ended"
                    start_time (INT)       - Unix Timestamp
                    end_time (INT)         - Unix Timestamp
                    goal_target (VARCHAR)  - Numeric target (e.g., "1000")
                    leaderboard (JSON)     - Serialized player data
                

API Actions

CreateEvent: Initializes a new event entry.
geteventlist: Returns all events (paginated).
LoadEventDetails: Fetches full data for a specific event ID.
UpdateLeaderboard: Updates player stats within the JSON blob.
updatestatus: Changes event state (e.g., to Close/End).

Scripting API

bl_GameEventManager (Singleton)

The primary entry point for gameplay logic.

public void LoadEventData(bl_GameEventUI ui)

Fetches the current active event data and populates the provided UI component.

public void LoadCurrentLeaderboard(bl_GameEventUI ui)

Requests the specific leaderboard JSON for the active event and updates the UI list.

Data Structures

EventDetails

public class EventDetails
{
    public int id;
    public string event_name;
    public string event_mode;
    public float xp_boost;
    public string goal;        // "Kills" or "Wins"
    public string status;
    public string end_time;    // Formatted date string
}
                

LeaderboardEntry

public class LeaderboardEntry
{
    public string PlayerName;
    public LeaderboardStats Stats;
}

public class LeaderboardStats
{
    public int Kills;
    public int Wins;
    public int Deaths;
}
                

UI System Architecture

Admin Panel (bl_EventManagerUI)

Located in the Admin scene or prefab. It allows authorized users to manage events.

Features: Pagination, Filtering, Server Region selection, Event Creation Wizard.
Prefab: Event [ADMIN PANEL]

Player Dashboard (bl_GameEventUI)

The in-game display for players.

Features: Shows active event, progress bar, and "Top Players" list.
Dynamic Filtering: Automatically switches leaderboard columns based on Goal Type (Kills vs Wins) via _GoalType enum.
Prefab: Controlled Event

Creating Events

Follow these steps to launch a new event:

Open the Admin Panel scene/UI.
Navigate to the "Create Event" tab.
Event Name: Unique identifier for the event.
Mode: Select the game mode (must match your GameMode keys).
Server: Choose "Global" for all regions or a specific region code (e.g., 'us', 'eu').
XP Boost: Set the multiplier (e.g., 2x, 3x).
Goal:
- Kills: Race to specific kill count.
- Wins: Race to specific win count.
Duration: Set the event length (Days/Hours).
Click Create Event. The system will sync with the PHP backend.

Validation: Ensure the "Mode" string matches exactly with your Game Mode definitions in MFPS, otherwise players won't be able to matchmake correctly into the event.

Troubleshooting

Connection Failed

Symptom: "Connection failed" error in console.

Fix: Check bl_EventManagerSettings. Ensure the PHP URL is reachable from your browser. Verify bl_LoginProDataBase path if using ULSP.

Leaderboard Not Updating

Symptom: Players get kills but leaderboard stays empty.

Fix: 1. Ensure the event status is "Open".
2. Check if the player is in the correct event_mode.
3. Verify the PHP script has write permissions to the JSON column in MySQL.

Debug Logs

Enable "Debug" level logging in EventManagerSettings to see raw JSON responses from the server. This is critical for identifying PHP errors.