com.phantomsxr.actionnotification/README.md

The action notification manager is a function in the XRMOD framework, which is used to provide messages and Actions execution in all modules. Corresponding modules will not depend on each other, only need to issue the corresponding Action-ID to execute.

# XRMODActionNotifier

The `XRMODActionNotifier` is a robust, lightweight, and thread-safe notification system designed for Unity and the XRMOD ecosystem. It follows the observer pattern, allowing components to communicate without direct dependencies.

## Key Features
- **Flexible Observers**: Register actions or functions that return results.
- **Sync & Async Support**: Seamlessly handle both immediate and long-running tasks.
- **Result Collection**: Collect results from multiple observers in a single notification post.
- **Reentrancy Safe**: Safe to add or remove observers while a notification is being posted.

---

## Quick Start

### 1. Define Notification Data
Inherit from `BaseNotificationData` to pass custom data.

```csharp
public class UserUpdateData : BaseNotificationData
{
    public string UserName;
}
```

### 2. Register an Observer
Use `ActionNotificationCenter.DefaultCenter` to start listening for events.

```csharp
ActionNotificationCenter.DefaultCenter.AddObserver(data => 
{
    var userData = data as UserUpdateData;
    Debug.Log($"User updated: {userData.UserName}");
}, "OnUserUpdated");
```

### 3. Post a Notification
Trigger all observers listening to the event.

```csharp
ActionNotificationCenter.DefaultCenter.PostNotification("OnUserUpdated", new UserUpdateData { UserName = "JohnDoe" });
```

---

## Detailed API Examples

### Synchronous Notifications with Results
You can collect data back from your observers.

```csharp
// Observer returning a value
ActionNotificationCenter.DefaultCenter.AddObserver(data => 
{
    return "Handled by Receiver A";
}, "GetStatus");

// Posting and collecting results
List<object> results = ActionNotificationCenter.DefaultCenter.PostNotificationWithResult("GetStatus", new BaseNotificationData());

foreach (var res in results)
{
    Debug.Log(res.ToString());
}
```

### Asynchronous Notifications
Ideal for operations that require waiting (e.g., downloading assets, database calls).

```csharp
// Register an async observer
ActionNotificationCenter.DefaultCenter.AddAsyncObserver(async data => 
{
    await Task.Delay(1000);
    return "Async task finished";
}, "DownloadStarted");

// Post and await
var results = await ActionNotificationCenter.DefaultCenter.PostNotificationAsync("DownloadStarted", new BaseNotificationData());
```

---

## Important Considerations & Pitfalls

### ⚠️ Registration & Cleanup
Always balance your `AddObserver` with `RemoveObserver`. Failing to do so can lead to memory leaks and unexpected behavior, especially in Unity when objects are destroyed.

> [!IMPORTANT]
> Use `OnEnable` for registration and `OnDisable` for unregistration in MonoBehaviours.

```csharp
void OnDisable()
{
    ActionNotificationCenter.DefaultCenter.RemoveObserver("OnUserUpdated");
}
```

### ⚠️ Reentrancy
The system handles adding/removing observers during a `PostNotification` call by queuing the operations. They will be applied before the next notification is processed.

### ⚠️ Casting Notification Data
Since `BaseNotificationData` is used universally, always use safe casting (`as` or pattern matching) to avoid `InvalidCastException`.

---

## Architecture

```mermaid
graph TD
    Sender[Notification Sender] -- PostNotification --> Center[ActionNotificationCenter]
    Center -- Invoke --> SYNC[SyncNotificationHandler]
    Center -- InvokeAsync --> ASYNC[AsyncNotificationHandler]
    SYNC -- Execute --> Observer1[Synchronous Observer]
    ASYNC -- Await --> Observer2[Asynchronous Observer]
    Observer1 -- Result --> Center
    Observer2 -- Task Result --> Center
```

---

## Author
Developed with ❤️ by the PhantomsXR Team.
Contact [nswell@phantomsxr.com](mailto:nswell@phantomsxr.com) for inquiries.