Processors Overview

The RisingV.Core.Processors namespace provides a set of “Processor” classes responsible for handling discrete game‐related events and routing them through the RisingV framework. Processors act as the bridge between low‐level events—often published by Hooks—and high‐level Engines or Aspects that implement persistent or game‐affecting logic. By centralizing event‐specific processing, Processors ensure that RisingV’s domain workflows (such as administering bans, managing death logic, or spawning scripts) are consistently applied across all plugins.

For full details on available classes and methods, see the official API documentation:

🔗 RisingV.Core.Processors API Reference

Role and Responsibilities

Event Handling Pipeline
- Source: Most Processors receive events published by the Harmony Hook layer (e.g., a player death, a script‐triggered spawn, or an admin command) via the shared EventBridge.
- Processing: Each Processor filters, validates, or enriches the event data—often resolving Entity IDs, player references, or context metadata.
- Delegation: After processing, Processors invoke appropriate Engines or Aspects to carry out domain‐specific logic (e.g., updating databases, applying buffs, enforcing permissions).
- Consistency: By consolidating domain workflows into discrete Processor classes, RisingV maintains a consistent behavior across plugins, simplifies hot‐reload, and reduces duplicate code.
Separation of Concerns
- Hooks are responsible for intercepting game methods and publishing raw events.
- Processors interpret these events—applying RisingV rules, transforming data, or performing validations.
- Engines/Aspects then execute persistent logic (database updates, world modifications, network sends).
  This separation ensures each class has a single responsibility: Hooks → Processors → Engines/Aspects.
Abstract Base Classes
- TargetEntityProcessor<TEvent> and SourceToTargetEntityProcessor<TSourceEvent, TTargetEvent> provide generic frameworks to handle events involving one or two entity references, respectively.
- Subclasses override the Process(TEvent evt) method to implement specific workflows (e.g., resolving player data, checking permissions, or invoking Engine methods).

Core Processor Classes

Below is a summary of each Processor class in RisingV.Core.Processors, along with its primary responsibilities and typical usage.

AdminAuthProcessor

Purpose

Abstract base for processing player “admin” status checks.
Validates whether a sender (command issuer) has appropriate permissions before downstream logic executes.

Key Responsibilities

Subscribe to admin‐related events.
Extract the requesting player’s Entity or UserId.
Check against RisingV’s admin configuration or persistent list.
If authorized, forward the event to a concrete handler; otherwise, block or respond with a “permission denied” message.

Typical Flow

public class DevAdminAuthProcessor : AdminAuthProcessor
{
    protected override bool? IsAdmin(PlayerAspect player)
    {
        return true; // Always allow for admin auth in dev
    }
}

BanProcessor

Purpose

Listens for KickBanSystem_Server.IsBanned calls to determine the ban state of a player.

Key Responsibilities

Validate ban parameters (duration, target player).
Invoke AdminEngine or a custom BanService to mark a player as banned.

Typical Flow

public class CustomBanProcessor : BanProcessor
{
    protected override bool? IsBanned(PlayerAspect player)
    {
        var result = MyBanService.IsBanned(player.UserId);
        return result;
    }
}

DeathProcessor

Purpose

Handles entity death events published by DeathHook or similar hooks.

Key Responsibilities

Extract victim and killer entity references from the event.
Throw events specific to the unit type (e.g., DeathUnitEvent or DeathPlayerEvent for player characters).
Coordinate with DeathEngine to process death‐related workflows:
- Award experience or drop loot via LootEngine.
- Update statistics (e.g., death counts) through StatChangeProcessor.
- Trigger respawn timers or “downed” flow if applicable.

Typical Flow

public void Initialize()
{
    EventBridge.Subscribe<DeathUnitEvent>(OnDeathUnitEvent);
}

public void OnDeathUnitEvent(DeathUnitEvent evt)
{
    var victim = evt.VictimEntity.As<UnitAspect>();
    var killer = evt.KillerEntity.As<UnitAspect>();

    // Update death count
    MyStatService.IncrementDeathCount(victim);

    // Generate loot drop
    LootEngine.GenerateAndDropItems(_itemTables[victim.UnitCategory], victim.Entity);

    // Invoke any special death animations or UI, etc
    MyDeathService.HandlePostMortem(victim, killer);
}

DownedProcessor

Purpose

Processes the “downed” state of an entity before final death.

Key Responsibilities

Listen for events where a character transitions to a “downed” animation or state (e.g., DownedUnitEvent, DownedPlayerEvent).
Apply RisingV’s rules for revivable states or bleed‐out timers.
If bleed‐out occurs, the DeathProcessor will initiate from the death hook; otherwise, we could allow for revival workflows, etc.

Typical Flow

public void Initialize()
{
    EventBridge.Subscribe<DownedUnitEvent>(OnDownedUnitEvent);
}

public void OnDownedUnitEvent(DownedUnitEvent evt)
{
    var downedEntity = evt.Entity;
    // Start a custom bleed-out countdown
    CustomBleedOutService.StartTimer(downedEntity, evt.Duration);

    // If revived before timer expires, cancel bleed-out
}

SpawnProcessor

Purpose

Handles general spawn events, whether triggered by the game or by script.

Key Responsibilities

Publishes events like SpawnUnitEvent, SpawnPlayerEvent, etc. based on the entity unit type.

Typical Flow

public void Initialize()
{
    EventBridge.Subscribe<SpawnUnitEvent>(OnSpawnUnitEvent);
}

public void OnSpawnUnitEvent(SpawnUnitEvent evt)
{
    var newEntity = evt.Entity;
    // Initialize health, buffs, or AI components
    EntityComponentDatabase.GetOrCreate(newEntity);
    BuffAspect.ApplyDefaultBuffs(newEntity);
}

ScriptSpawnProcessor & ScriptDespawnProcessor

Purpose

Specifically handle entities spawned or despawned by script.

Key Responsibilities

ScriptSpawnProcessor:
- Publishes a ScriptSpawnEvent, which includes a script identifier and spawn parameters.
ScriptDespawnProcessor:
-Publishes a ScriptDespawnEvent, identifying which scripted entity to remove.

Typical Flow

public void Initialize()
{
    EventBridge.Subscribe<ScriptSpawnEvent>(OnScriptSpawnEvent);
    EventBridge.Subscribe<ScriptDespawnEvent>(OnScriptDespawnEvent);
}

public void OnScriptSpawnEvent(ScriptSpawnEvent evt)
{
    MyCustomScriptSpawnService.Handle(evt);
}

public void OnScriptDespawnEvent(ScriptDespawnEvent evt)
{
    MyCustomScriptSpawnService.Handle(evt);
}

SourceToTargetEntityProcessor & TargetEntityProcessor

Purpose

Provide generic, reusable bases for processors that require one or two entity references.

Key Responsibilities

TargetEntityProcessor<TEvent>:
- Extract a single Entity from the event payload.
- Commonly used for events like “player requested action” or “entity took damage.”
SourceToTargetEntityProcessor<TSourceEvent, TTargetEvent>:
- Map an incoming “source” event (e.g., a network packet or command issuer) to a “target” event involving a different entity.
- For example, converting a raw “knockback request” from a client‐side entity into a server‐validated “apply knockback” on a target entity.

Typical Flow

public class MyDamageProcessor : TargetEntityProcessor<DamagedUnitEvent>
{
    public override void Process(DamagedUnitEvent evt)
    {
        var target = evt.TargetEntity;
        var data = evt.Data;
        var amount = data.Change;
        // Apply damage logic
    }
}

StatChangeProcessor

Purpose

Processes events that modify or query entity statistics (e.g., health, stamina, mana).

Key Responsibilities

Listen for StatChangeEvent, which encapsulates the stat type and delta (increase or decrease).
Register custom events based on the type of stat and unit for custom events (e.g. DamagedUnitEvent).

Typical Flow

var statChangeProcessor = ProcessManager.Get<StatChangeProcessor>()!;
statChangeProcessor.RegisterUnitEvent(StatType.Health, StatChangeReason.DealDamageSystem_0, (sourceEntity, targetEntity, @event) 
        => new DamagedUnitEvent(sourceEntity, targetEntity, @event));

Integration & Workflow

Hook Publication
- Hooks (e.g., DeathHook, SpawnHook, StatChangeSystemHook, AdminAuthSystemHook) intercept game methods and publish raw events to the EventBridge.
Processor Event Publishing
- Each Processor publishes to a specific event types after processing 'paths' are made.
Delegation to Engines/Aspects
- Processors delegate domain logic to the EventBus and Aspects (e.g., BuffAspect, EntityAspect).
- Engines handle persistent state changes, database updates, or world modifications.
- Aspects provide high‐level facades for component manipulation or network calls.
Hot‐Reload & State Preservation
- Because Processors rely on abstract event subscriptions and Engine/Aspect calls, they support hot‐reload seamlessly:
  - On Reload, existing subscriptions remain intact, and stateful Engines/Aspects restore from their respective databases.
  - Any in‐flight events are either re‐published or ignored based on the ReloadReason.
Server vs. Client Context
- Most Processors execute on the server side (authoritative game logic).
- Some lightweight Processors (e.g., StatChangeProcessor) may also run on the client for prediction or UI updates, but any authoritative state change is forwarded to the server Processor to avoid desynchronization.

Summary

The Processors in RisingV.Core orchestrate the following responsibilities:

Interpret & Validate Events: Transform raw events from Hooks into validated, context‐rich payloads (resolving entity references, checking permissions).
Coordinate Domain Workflows: Invoke the correct Engine or Aspect to fulfill a workflow—such as banning a player, processing a death, or spawning scripted content.
Maintain Consistency: Centralize processing logic to avoid duplication across plugins, ensuring uniform behavior throughout the modding ecosystem.
Facilitate Hot‐Reload: Rely on EventBridge subscriptions and abstract base classes so that event workflows seamlessly survive plugin or server reloads.

By understanding and leveraging Processors, plugin authors can ensure that their custom features integrate cleanly with RisingV’s event‐driven architecture and scale reliably as the framework evolves.

Table of Contents

Processors Overview

Role and Responsibilities

Core Processor Classes

AdminAuthProcessor

BanProcessor

DeathProcessor

DownedProcessor

SpawnProcessor

ScriptSpawnProcessor & ScriptDespawnProcessor

SourceToTargetEntityProcessor & TargetEntityProcessor

StatChangeProcessor

Integration & Workflow

Summary