User Story: Modding API with C# Script Support

david commented

2025-12-05 09:19:59 +00:00

Owner

As a

Game modder or content creator

I want to

Create custom entities and behaviors by writing C# scripts that implement engine interfaces, compiling them into DLLs that the Spelusion Engine can dynamically load and execute

So that

I can extend the game's functionality without modifying the engine's source code, enabling community-driven content and custom gameplay mechanics

Acceptance Criteria

Mod Interface Definition

Engine provides a documented IModEntity interface that extends or works with IEntity
Engine provides IModComponent interface for custom entity components
Engine provides IModInitializer interface for mod entry points
All modding interfaces are available in a separate Spelusion.Engine.Modding.SDK NuGet package

Mod Development Workflow

Modders can reference Spelusion.Engine.Modding.SDK in their C# projects
Modders can implement interfaces like:

public class CustomEnemy : IModEntity
{
    public void Initialize(IModContext context) { }
    public void Update(GameTime gameTime) { }
    public void Draw(SpriteBatch spriteBatch) { }
}

Modders compile their project to produce a DLL
Clear documentation with code examples is provided

Mod Discovery & Loading

Engine scans a designated Mods/ folder for DLL files on startup
Engine validates each DLL for required interfaces and dependencies
Engine safely loads compatible mods using AssemblyLoadContext
Engine logs which mods were successfully loaded or failed with clear error messages

Mod Execution & Integration

Loaded mod entities can be instantiated and added to scenes
Mod components integrate with the existing Entity component system
Mods have access to safe engine APIs (Transform, Scene, Component management)
Mods are isolated from sensitive engine internals using sandboxing or controlled API surface

Mod Lifecycle Management

Engine calls mod initialization methods on startup
Engine properly disposes/unloads mods on shutdown
Hot-reload support for development (optional for v1)
Ability to enable/disable mods without deleting files

Error Handling & Safety

Mod loading failures don't crash the engine
Runtime exceptions in mods are caught, logged, and don't affect other mods
Version compatibility checks between mod SDK and engine version
Clear error messages guide modders to fix issues

Developer Experience

Sample mod project template available
Documentation includes:
Getting started guide
API reference for IModEntity, IModComponent, IModInitializer
Example mods (custom enemy, custom weapon, particle effects)
Debugging support (modders can attach debugger to engine process)

Technical Notes

Consider using System.Reflection and AssemblyLoadContext for dynamic loading
Expose core engine features through a IModContext or IModAPI interface
Leverage existing Entity and IEntityComponent architecture
Mods should serialize/deserialize with the scene system (JsonObject Serialize())
Security: Restrict file system access, network operations, or provide opt-in permissions

Definition of Done

Modding SDK package is published
Engine successfully loads and runs at least one example mod
Documentation is complete and reviewed
Unit tests cover mod loading, validation, and error scenarios
Integration test demonstrates a custom entity mod in a scene

## As a Game modder or content creator ## I want to Create custom entities and behaviors by writing C# scripts that implement engine interfaces, compiling them into DLLs that the Spelusion Engine can dynamically load and execute ## So that I can extend the game's functionality without modifying the engine's source code, enabling community-driven content and custom gameplay mechanics --- ## Acceptance Criteria 1. Mod Interface Definition - [ ] Engine provides a documented IModEntity interface that extends or works with IEntity - [ ] Engine provides IModComponent interface for custom entity components - [ ] Engine provides IModInitializer interface for mod entry points - [ ] All modding interfaces are available in a separate Spelusion.Engine.Modding.SDK NuGet package 2. Mod Development Workflow - [ ] Modders can reference Spelusion.Engine.Modding.SDK in their C# projects - [ ] Modders can implement interfaces like: ``` csharp public class CustomEnemy : IModEntity { public void Initialize(IModContext context) { } public void Update(GameTime gameTime) { } public void Draw(SpriteBatch spriteBatch) { } } ``` - [ ] Modders compile their project to produce a DLL - [ ] Clear documentation with code examples is provided 3. Mod Discovery & Loading - [ ] Engine scans a designated Mods/ folder for DLL files on startup - [ ] Engine validates each DLL for required interfaces and dependencies - [ ] Engine safely loads compatible mods using AssemblyLoadContext - [ ] Engine logs which mods were successfully loaded or failed with clear error messages 4. Mod Execution & Integration - [ ] Loaded mod entities can be instantiated and added to scenes - [ ] Mod components integrate with the existing Entity component system - [ ]Mods have access to safe engine APIs (Transform, Scene, Component management) - [ ] Mods are isolated from sensitive engine internals using sandboxing or controlled API surface 5. Mod Lifecycle Management - [ ] Engine calls mod initialization methods on startup - [ ] Engine properly disposes/unloads mods on shutdown - [ ] Hot-reload support for development (optional for v1) - [ ] Ability to enable/disable mods without deleting files 6. Error Handling & Safety - [ ] Mod loading failures don't crash the engine - [ ] Runtime exceptions in mods are caught, logged, and don't affect other mods - [ ] Version compatibility checks between mod SDK and engine version - [ ] Clear error messages guide modders to fix issues 7. Developer Experience - [ ] Sample mod project template available - [ ] Documentation includes: - [ ] Getting started guide - [ ] API reference for IModEntity, IModComponent, IModInitializer - [ ] Example mods (custom enemy, custom weapon, particle effects) - [ ] Debugging support (modders can attach debugger to engine process) --- ## Technical Notes - Consider using System.Reflection and AssemblyLoadContext for dynamic loading - Expose core engine features through a IModContext or IModAPI interface - Leverage existing Entity and IEntityComponent architecture - Mods should serialize/deserialize with the scene system (JsonObject Serialize()) - Security: Restrict file system access, network operations, or provide opt-in permissions --- ## Definition of Done - [ ] Modding SDK package is published - [ ] Engine successfully loads and runs at least one example mod - [ ] Documentation is complete and reviewed - [ ] Unit tests cover mod loading, validation, and error scenarios - [ ] Integration test demonstrates a custom entity mod in a scene