SSAL.Testing 1.0.0

SSAL — s&box Shared API Layer

Status: Release · Revision 1.0.0

A versioned, interface-driven C# library that gives addon creators and gamemode developers a single shared contract to target, instead of depending on each other.

Table of Contents

• Overview
• Why This Exists
• Package Structure
• Quick Start
  • For Addon Authors
  • For Gamemode Developers
• Core Interfaces
• Standard Events
• Service Registry
• Versioning
• Roslyn Analyzer Rules
• Testing
• Migrating from Ad-Hoc Interop
• Roadmap
• Full Interface Reference
• Contributing

Overview

s&box encourages a modular ecosystem. A user running a survival gamemode might simultaneously equip addons for a custom inventory UI, a weather system, and a voice-chat overlay, all authored by different people, all executing inside the same C# scripting sandbox.

Without a formal contract, these packages discover each other through reflection, dynamic casts, and copy-pasted stubs. The result is silent runtime failures, versioning nightmares, and a fragmented ecosystem.

SSAL solves this with three focused packages that define the vocabulary for cross-boundary communication: types, interfaces, events, and service locators that turn ad-hoc calls into well-typed, discoverable, forward-compatible contracts.

Why This Exists

Package Structure

SSAL
├── SSAL.Contracts   ← Both addons AND gamemodes reference this
├── SSAL.Core        ← Gamemodes only (ServiceRegistry, EventBus, BootstrapHost)
└── SSAL.Testing     ← Test projects only (FakeGameContext, FakeInventory, ...)

Dependency rule: Addons depend on Contracts only. Gamemodes depend on Contracts + Core. This direction is never reversed and is enforced by the Roslyn analyzer (SAL001).

  s&box Runtime / Sandbox.*
          │
  SSAL.Core        ← Gamemode layer
  ServiceRegistry | EventBus | BootstrapHost
          │  implements / references
  SSAL.Contracts   ← Shared surface
  IGameContext | IInventory | IPlayerState | IEventChannel
       │                              │
  Gamemode A                     Addon Pack B

Quick Start

For Addon Authors

Add only the Contracts package to your .csproj:

<ItemGroup>
  
  <PackageReference Include="SSAL.Contracts" Version="1.*" />
  <PackageReference Include="SSAL.Analyzers" Version="1.*" PrivateAssets="all" />
</ItemGroup>

Implement IAddon as your entry point:

[AddonEntry]
public sealed class WeatherAddon : IAddon
{
    private IEventChannel? _events;

    public void OnLoad(IGameContext ctx)
    {
        _events = ctx.Events;

        // Optional service — gracefully degrade if not present
        var scoreboard = ctx.GetService<IScoreboard>();
        if (scoreboard is not null)
            HookScoreboardWeatherBonus(scoreboard);

        _events.Subscribe<RoundStartedEvent>(OnRoundStarted);
    }

    public void OnUnload() { /* clean up subscriptions */ }

    private void OnRoundStarted(RoundStartedEvent e)
        => SpawnWeatherForRound(e.RoundIndex);
}

Capability negotiation — never throw on a missing optional service:

public void OnLoad(IGameContext ctx)
{
    // Hard requirement
    var players = ctx.GetService<IPlayerRegistry>()
        ?? throw new AddonLoadException($"{Manifest.Name} requires IPlayerRegistry.");

    // Soft requirement — disable the feature if absent
    var teams = ctx.GetService<ITeamManager>();
    if (teams is null)
    {
        Log.Warning("Team colors disabled: ITeamManager not registered.");
        _teamColorsEnabled = false;
    }
}

For Gamemode Developers

Reference both Contracts and Core:

<ItemGroup>
  <PackageReference Include="SSAL.Contracts" Version="1.*" />
  <PackageReference Include="SSAL.Core"      Version="1.*" />
  <PackageReference Include="SSAL.Analyzers" Version="1.*" PrivateAssets="all" />
</ItemGroup>

Register your services during startup and declare capabilities in gamemode.json:

public override void OnStart()
{
    base.OnStart();

    var registry = ServiceRegistry.Create();
    registry.Register<IInventory>(() => new SurvivalInventory(maxSlots: 10));
    registry.Register<ITeamManager>(() => new TwoTeamManager());
    registry.Register<IScoreboard>(() => new SurvivalScoreboard());

    GameContextHost.Initialize(registry);
}

{
  "title": "Survival Wars",
  "sal": {
    "minVersion": "1.0",
    "provides": ["IInventory", "ITeamManager", "IScoreboard", "IPlayerRegistry"]
  }
}

Publish standard events when things happen:

private void HandlePlayerDeath(SurvivalPlayer victim, DamageInfo dmg)
{
    victim.IsAliveInternal = false;

    _context.Events.Publish(new PlayerDiedEvent
    {
        Player     = victim,
        DamageInfo = DamageInfoAdapter.FromSandbox(dmg),
        Attacker   = _playerRegistry.Find(dmg.Attacker),
        Timestamp  = DateTimeOffset.UtcNow,
    });
}

Core Interfaces

IGameContext

Root context for a running session. Resolved by addons via ServiceRegistry.Current at load time.

[ApiVersion(1, 0)]
public interface IGameContext
{
    Guid SessionId { get; }
    T? GetService<T>() where T : class;
    IEnumerable<T> GetServices<T>() where T : class;
    IEventChannel Events { get; }
    IGamemodeInfo GamemodeInfo { get; }
}

IPlayerState

Observable state of a single player — no concrete gamemode type needed.

[ApiVersion(1, 0)]
public interface IPlayerState
{
    Guid PlayerId { get; }
    string DisplayName { get; }
    bool IsAlive { get; }
    float Health { get; }
    float MaxHealth { get; }
    Vector3 Position { get; }
    ITeam? Team { get; }
    ITaggedDataBag Tags { get; }  // gamemode-specific extension data
}

IInventory

[ApiVersion(1, 0)]
public interface IInventory
{
    IReadOnlyList<IItem> Items { get; }
    int MaxSlots { get; }
    bool TryAdd(IItem item);
    bool TryRemove(Guid itemId);
    IItem? FindById(Guid itemId);
    event EventHandler<InventoryChangedEventArgs>? Changed;
}

IEventChannel

Type-safe publish/subscribe. All inter-boundary communication that isn't a direct method call goes through here.

[ApiVersion(1, 0)]
public interface IEventChannel
{
    IDisposable Subscribe<T>(Action<T> handler) where T : ISharedEvent;
    void Publish<T>(T @event) where T : ISharedEvent;
    ValueTask PublishAsync<T>(T @event, CancellationToken ct = default)
        where T : ISharedEvent;
}

ITaggedDataBag

Extension data bag for gamemode-specific values. Avoids an ever-growing IPlayerState interface.

public interface ITaggedDataBag
{
    bool HasTag(string key);
    bool TryGet<T>(string key, out T? value);
    void Set<T>(string key, T value);
    void Remove(string key);
}

// Usage in an addon:
if (playerState.Tags.TryGet<int>("stamina", out var stamina))
    RenderStaminaBar(stamina);

Standard Events

All events are defined in SSAL.Contracts. Gamemodes raise them; addons subscribe to them.

All event types implement ISharedEvent and should be immutable records.

Service Registry

The ServiceRegistry in SSAL.Core is a minimal IoC container with no runtime reflection. Three lifetime scopes are supported:

Versioning

Every interface and event carries [ApiVersion(major, minor)]. The Roslyn analyzer warns at compile time when version mismatches are detected.

Adding optional members without breaking existing implementors (minor bump):

// SAL 1.1 — backward compatible addition
[ApiVersion(1, 1)]
public interface IPlayerState
{
    bool IsSprinting => false;      // safe default for old gamemodes
    float StaminaPercent => 1.0f;
}

Roslyn Analyzer Rules

SSAL.Analyzers ships with the package and enforces correct usage at compile time.

Testing

SSAL.Testing provides pre-built fakes so addon authors can unit-test without a running s&box instance.

public class WeatherAddonTests
{
    [Fact]
    public void SpawnsStorm_WhenRoundStartsWithIndex3()
    {
        var ctx   = new FakeGameContext();
        var addon = new WeatherAddon();
        addon.OnLoad(ctx);

        ctx.Events.Publish(new RoundStartedEvent { RoundIndex = 3 });

        Assert.Equal(WeatherType.Storm, addon.CurrentWeather);
    }
}

Migrating from Ad-Hoc Interop

Reflection → Service Resolution

// ❌ Before
var method = Game.Current.GetType().GetMethod("GetPlayerInventory");
var inv    = method?.Invoke(Game.Current, new[] { playerId });

// ✅ After
var inv = ctx.GetService<IInventory>();

Custom Static Events → IEventChannel

// ❌ Before
SurvivalGame.OnPlayerDied += MyHandler;

// ✅ After — subscription is IDisposable, auto-cleaned on OnUnload
ctx.Events.Subscribe<PlayerDiedEvent>(MyHandler);

Roadmap

Full Interface Reference

All types in SSAL.Contracts v1.0:

Contributing

This project is in draft — the interface surface is not yet frozen.

• Open an issue to propose new interfaces or events before implementing
• All PRs targeting Contracts require a discussion thread first (changes affect the entire ecosystem)
• Breaking changes (major version bumps) require a migration guide in docs/migrations/
• Run dotnet test and ensure all analyzer tests pass before opening a PR
• Follow the dependency rule — addon-facing code must never reference Core