ASGL2 1.0.0

ASGL2

A small 2D game library for .NET Framework 4.8, built on SDL2.

• Game loop and states: GameBase (fixed 60 Hz logic loop, separate render loop), BaseState screens.
• Graphics: Renderer, sprites and sprite sheets, scrolling and parallax layers, star fields, TrueType text (TtfFont), Camera (dead zone, look-ahead, shake).
• Tile maps: layers, collision (MoveAndCollide), animated tiles, and a JSON map format (TileMapData, *.tilemap.json) that the ASGL map editor reads and writes.
• Gameplay helpers: waypoints, oscillators, phase machines, timers, hitbox and convex polygon collision, particle and floating-text effects.
• Input and audio: keyboard and mouse with per-tick pressed/released edges, text input, sound manager and sound pool.
• UI toolkit (ASGL2.UI): panels, buttons, text boxes, list boxes, dialogs, toolbar and status bar, drawn with SDL.
• 3D (ASGL2.Graphics3D): a software renderer on top of the 2D renderer, with textures and an OBJ loader.

The SDL2 native libraries are required and are not in this package

ASGL2 calls SDL2 (through the managed ppy.SDL2-CS binding, which this package depends on and installs for you), but the native libraries themselves are not included. Your game will fail at start-up with a DllNotFoundException until you add them.

You need these files next to your game's .exe (64-bit, so build your game for x64):

Get them from the official Windows (VC or mingw) builds: the SDL2-2.x.y-win32-x64.zip from https://github.com/libsdl-org/SDL/releases and the SDL2_ttf-2.x.y-win32-x64.zip from https://github.com/libsdl-org/SDL_ttf/releases. Depending on the SDL2_ttf version, that zip contains libfreetype-6.dll and zlib1.dll (older releases) or has FreeType built into SDL2_ttf.dll (newer ones, then you do not need those two files). Keep the files that belong to the SDL2_ttf you use.

The simplest way to copy them on every build is to put the four files in your project and mark them "Copy to output directory" (Copy if newer), or add this to your .csproj:

<ItemGroup>
  <Content Include="native\SDL2.dll"          CopyToOutputDirectory="PreserveNewest" />
  <Content Include="native\SDL2_ttf.dll"      CopyToOutputDirectory="PreserveNewest" />
  <Content Include="native\libfreetype-6.dll" CopyToOutputDirectory="PreserveNewest" />
  <Content Include="native\zlib1.dll"         CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

SDL2 and SDL2_ttf use the zlib license; FreeType and zlib have their own permissive licenses. Check their terms if you redistribute them with your game.

A first game

using ASGL2;
using SDL2;

public enum Screen { Play }

public sealed class MyGame : GameBase
{
    public override bool Initialize()
    {
        Renderer.Instance.Initialize("My game", new RendererSettings
        {
            LogicalWidth = 800,     // the drawing area; the window is scaled to fit it
            LogicalHeight = 480,
            WindowWidth = 1200,
            WindowHeight = 720,
        });
        ClearColor = SDLColors.FromRgb(20, 24, 40);

        SetLogicFPS(60);
        SetRenderFPS(60);
        RegisterState(Screen.Play, typeof(PlayState));
        ChangeGameState(Screen.Play, null);
        return true;
    }
}

public sealed class PlayState : BaseState
{
    public PlayState(object sender, object[] args) : base(sender, args) { }

    public override void Initialize() { }
    public override void Terminate() { }

    public override void GameLogic(object sender, SDL.SDL_Event e)
    {
        // once per logic tick (60 a second): input, movement, collisions
    }

    public override void Render(object sender)
    {
        // once per frame: draw with Renderer.Instance, sprites, tile maps, the UI...
    }
}

internal static class Program
{
    private static void Main()
    {
        new MyGame().StartGame();
    }
}

Loading a tile map made with the map editor

TileMapData data = TileMapData.Load("Assets/Levels/level1.tilemap.json");
GenericTileMap map = data.CreateMap(Renderer.Instance.SDLRenderer, null, 800, 480, "Assets/Levels/level1.tilemap.json");
Point? start = data.FindSpawn("player");

// every logic tick:
map.UpdateTileAnimations();     // animated tiles (coins, water...) defined in the map file
// every frame:
map.Render(Renderer.Instance.SDLRenderer, 0, 0);

Requirements

• .NET Framework 4.8, Windows, x64 (the audio part uses CSCore, which is Windows only).
• Dependencies installed automatically by NuGet: ppy.SDL2-CS, CSCore, System.Text.Json.
• If your project uses packages.config (an older style project), you may have to add binding redirects for the System.* packages (Visual Studio does this when AutoGenerateBindingRedirects is on, which is the default for executables).

License

MIT. See the license in the package metadata. The dependencies (ppy.SDL2-CS, CSCore, System.Text.Json) have their own licenses.