MageAPI

MageAPI

MageAPI is a comprehensive BepInEx plugin that provides a powerful framework for creating custom content in Mage Arena. The API simplifies the process of adding new damageables, event subscriptions, and game mechanics while handling complex backend systems so modders can focus on design and implementation.

Features

• Entity Health Management: Robust health system with event-driven damage handling
• Collision Detection: Advanced collision system with filtering and event triggers
• Instance Management: Centralized access to game singletons and object pools
• Event System: Comprehensive event system for game lifecycle hooks
• Modular Architecture: Clean, organized structure for easy extensibility

Installation

1. Prerequisites:

• Mage Arena with BepInEx 5.4.21 or newer

1. Installation:

   MageArena/
   └── BepInEx/
       └── plugins/
           └── MageAPI
               └── MageAPI.dll

Core Components

HealthModule

A comprehensive health management system that wraps MonoBehaviour entities with health functionality:

• Custom health field integration
• Death/respawn handling
• Event-driven health changes
• Collider management

DamageCollisionCheck

Advanced collision detection system:

• Trigger and collision event handling
• Health module integration
• Collider filtering capabilities
• Rigidbody support

InstanceManager

Centralized access to game instances:

• Singleton managers (MainMenu, Bootstrap, Coloseum, etc.)
• Object pools for all entity types
• Player and NPC instance management

Event System

Comprehensive event architecture:

• Client events
• Player events
• Game events
• Miscellaneous events

Usage Examples

Creating a Custom Entity with Health

public class CustomEntity : MonoBehaviour
{
    private HealthModule _healthModule;
    
    private void Start()
    {
        _healthModule = gameObject.AddComponent();
        _healthModule.Setup(this, 100f, OnDeath);
    }
    
    private void OnDeath()
    {
        // Custom death logic
    }
}

Handling Collision Events

public class DamageDealer : MonoBehaviour
{
    private DamageCollisionCheck _collisionCheck;
    
    private void Start()
    {
        _collisionCheck = gameObject.AddComponent();
        _collisionCheck.OnEnterHealthCollider += OnDamageableHit;
    }
    
    private void OnDamageableHit(Collider collider, HealthModule health)
    {
        health.Health -= 10f;
    }
}

Using Game Events

public class GameEventHandler
{
    public GameEventHandler()
    {
        Events.Player.PlayerDeathEvent.After += OnPlayerDeath;
        Events.Game.GameStartEvent.After += OnGameStart;
    }
    
    private void OnPlayerDeath((PlayerInstance, object?) args)
    {
        // Handle player death
    }
    
    private void OnGameStart()
    {
        // Handle game start
    }
}

API Structure

Namespaces

• MageAPI.Enums: Game enumerations and types
• MageAPI.Interfaces: Core interfaces
• MageAPI.Modules: Modular systems and utilities
• MageAPI.Modules.Events: Event system architecture
• MageAPI.Mono: MonoBehaviour components and extensions
• MageAPI.Managers: Management systems and singletons