s&box

Extend RpcCallback

# Extend RPC Library

A library for **s&box** that makes it easy to send RPC calls and receive **asynchronous callbacks**.

It simplifies **client ↔ server** communication while taking full advantage of async/await.

## 🚀 Features

- Asynchronous RPC calls

- Receive callbacks using `async/await`

- Simplified error and timeout handling

- Supported return types:

✅ **Primitives** (int, float, bool, string, etc.)

✅ **structs**

✅ **records**
✅ **List<>**

## 📦 Installation

Clone or download this repository and add its content directly into your **s&box** project at Libraries/extend.extend_rpc folder.

## 🛠 Basic Usage Example

[RpcCallback]
public async Task<int> Compute(int a, int b)
{
    return a + b;
}

protected override void OnStart()
{
    Task.RunInThreadAsync(async () =>
    {
        var result = await Compute(1, 4);
        Log.Info("Result is: " + result);
    });
}

## 🛠 List Usage Example

[RpcCallback]
public async Task<List<int>> Compute(int a, int b)
{
    return [a + b];
}

protected override void OnStart()
{
    Task.RunInThreadAsync(async () =>
    {
        var results = await Compute(1, 4);
        Log.Info("Result is: " + string.Join(", ", results));
    });
}

## 🛠 Using a struct as return type

protected override void OnStart()
{
    Task.RunInThreadAsync(async () =>
    {
        var stats = await GetPlayerStats("Player_42");
        Log.Info($"Kills: {stats.Kills}, Deaths: {stats.Deaths}, Accuracy: {stats.Accuracy}");
    });
}

[RpcCallback]
public async Task<PlayerStats> GetPlayerStats(string playerId)
{
    // Simulate database fetch
    await Task.Delay(100); 

    return new PlayerStats
    {
        Kills = 10,
        Deaths = 3,
        Accuracy = 0.75f
    };
}

public struct PlayerStats
{
    public int Kills { get; set; }
    public int Deaths { get; set; }
    public float Accuracy { get; set; }
}

## 🛠 Using a record as return type

// Primary constructors are not supported yet when serializing / deserializing in s&box
public record InventoryItem( string Name, int Quantity );

// Instead, use this way
public record InventoryItem
{
    public string Name { get; set; }
    public int Quantity { get; set; } 

    public InventoryItem( string name, int quantity )
    {
        Name = name;
        Quantity = quantity;
    }
}

[RpcCallback]
public async Task<InventoryItem> GetInventoryItem(string itemId)
{
    await Task.Delay(50);

    return new InventoryItem("Health Potion", 5);
}

protected override void OnStart()
{
    Task.RunInThreadAsync(async () =>
    {
        var item = await GetInventoryItem("potion_health");
        Log.Info($"Item: {item.Name}, Quantity: {item.Quantity}");
    });
}

## ⚙️ How it works

Functions marked with the [RpcCallback] attribute are **wrapped automatically**.

When you call them:

1. The wrapper sends an **RPC to the server**.

2. The server executes the **original method**.

3. The return value is captured.

4. Another **RPC is sent back to the caller (client)** with the result.

This makes it possible to await the call just like a local async function.

The caller receives the result as a Task<T> (async/await).

Any return type is supported as long as it’s a primitive, a struct, or a record that can be serialized.

Collections (List<T>, arrays, etc.) are also supported if T is a valid type.

The library handles serialization, network transport, and automatic value return.

Configurable timeout (default: 5s).

## 📖 Quick Reference

[RpcCallback] → Marks a method as an asynchronous RPC.

Task.RunInThreadAsync(...) → Runs a task outside the main game thread.

Exceptions are automatically propagated back to the caller.

## 🤝 Contributing

Pull Requests are welcome!

Please follow C# best practices. Unit tests is optional.

Report

Package

Revision