raylib (raylib-cs)

Introduction

This page assumes you have an existing raylib-cs project. This can be an empty project or an existing game.

The raylib-cs runtime library is still actively developed and the maintainers are prioritizing bugs and features which are needed immediately by the community. If run into a bug or missing feature please let us know on Discord or GitHub issues so we can prioritize fixes for your project.

Adding Gum NuGet package

The easiest way to add Gum to your project is to use the NuGet package. Open your project in your preferred IDE, or add Gum through the command line.

Add the Gum.raylib NuGet package (https://www.nuget.org/packages/Gum.raylib)

Modify csproj:

<PackageReference Include="Gum.raylib" />
<PackageReference Include="KernSmith.RaylibGum" /> <!-- Recommended, optional: dynamic fonts -->
<PackageReference Include="KernSmith.Rasterizers.StbTrueType" /> <!-- Only needed if targeting web -->

Or add through command line:

dotnet add package Gum.raylib
dotnet add package KernSmith.RaylibGum               # Recommended, optional: dynamic fonts
dotnet add package KernSmith.Rasterizers.StbTrueType # Only needed if targeting web

Don't name your project RaylibGum, that's the assembly name inside the Gum.raylib package. A same-named project produces a same-named output DLL that silently overwrites the runtime's copy in your bin folder, causing a TypeLoadException at runtime with no build warning. Gum's build now catches this for you: if your AssemblyName collides, the build fails with an error telling you to change it.

Adding Source (Optional)

You can directly link your project to source instead of a NuGet package for improved debuggability, access to fixes and features before NuGet packages are published, or if you are interested in contributing.

To add source, first clone the Gum repository: https://github.com/vchelaru/Gum

If you have already added the Gum NuGet package to your project, remove it.

Add the following projects to your solution:

• <Gum Root>/Runtimes/RaylibGum/RaylibGum.csproj
• <GumRoot>/GumCommon/GumCommon.csproj

Next, add RaylibGum as a project reference in your game project. Your project might look like this depending on the location of the Gum repository relative to your game project:

<ProjectReference Include="..\Gum\Runtimes\RaylibGum\RaylibGum.csproj" />

Adding Gum to Program

Gum can be added to a Program class with a few lines of code. Projects are encouraged to create a local GumService property called GumUI for convenience.

Add code to your Program class to Initialize, Update, and Draw Gum as shown in the following code block:

using Gum.Forms.Controls;
using Gum.Wireframe;
using Gum;
using Raylib_cs;
namespace raylibExample1;

public class Program
{
    static GumService GumUI => GumService.Default;

    // STAThread is required if you deploy using NativeAOT on Windows - See https://github.com/raylib-cs/raylib-cs/issues/301
    [STAThread]
    public static void Main()
    {
        const int screenWidth = 800;
        const int screenHeight = 450;

        Raylib.InitWindow(screenWidth, screenHeight, "Gum Sample");
        Raylib.SetTargetFPS(60);

        // This tells Gum to use the entire screen
        GraphicalUiElement.CanvasWidth = screenWidth;
        GraphicalUiElement.CanvasHeight = screenHeight;

        GumUI.Initialize();

        while (!Raylib.WindowShouldClose())
        {
            GumUI.Update(Raylib.GetTime());

            Raylib.BeginDrawing();
            Raylib.ClearBackground(Raylib_cs.Color.SkyBlue);
            GumUI.Draw();

            Raylib.EndDrawing();
        }
        Raylib.CloseWindow();
    }
}

Adding Dynamic Fonts (Optional)

By default, Gum uses pre-built bitmap font (.fnt) files for text rendering. The KernSmith.RaylibGum package added above enables dynamic in-memory font generation, which lets you set Font, FontSize, IsBold, IsItalic, OutlineThickness, and UseFontSmoothing on any TextRuntime without needing .fnt/.png files on disk:

using RaylibGum.Renderables;

CustomSetPropertyOnRenderable.InMemoryFontCreator = new KernSmithRaylibFontCreator();

For shipping games, you should register custom .ttf fonts rather than relying on system fonts. For more information, see the Fonts page.

On web: fonts built at runtime start with the FreeType rasterizer, which is native code and cannot run in a browser. KernSmith starts with FreeType on every platform, so adding the KernSmith.Rasterizers.StbTrueType package above is not enough on its own. You also have to name that backend and make sure it gets registered. If the font cannot be built, Gum uses its built in 18 pixel font instead and shows no error, so the sign of this problem is text in the wrong font.

Web builds are trimmed by default, which removes the code KernSmith uses to find backends on its own, so register it yourself. Add this to your web target's Program.cs, before GumUI.Initialize():

using System.Runtime.CompilerServices;
using KernSmith.Rasterizers.StbTrueType;

RuntimeHelpers.RunClassConstructor(typeof(StbTrueTypeRasterizer).TypeHandle);

Then pass the backend explicitly:

CustomSetPropertyOnRenderable.InMemoryFontCreator =
    new KernSmithRaylibFontCreator(KernSmith.RasterizerBackend.StbTrueType);

Adding Expression Support (Optional)

If your Gum project uses arithmetic expressions in variable references (such as Width = OtherInstance.Width + 20), you can add the Gum.Expressions NuGet package for full expression evaluation at runtime. Without this package, simple variable references like Width = OtherInstance.Width still work.

Add the NuGet package:

dotnet add package Gum.Expressions

Then call GumExpressionService.Initialize() after GumUI.Initialize. Expression support is typically used with a Gum project that has variable references defined in the tool:

// Initialize
GumUI.Initialize("GumProject/GumProject.gumj");
GumExpressionService.Initialize();

If linking to source instead of NuGet, add <Gum Root>/Runtimes/GumExpressions/GumExpressions.csproj to your solution.

For more information, see the Runtime Variable References page.

Adding a Button (Testing the Setup)

Gum can be tested by adding a Button after Gum is initialized. To do so, add code to create a Button as shown in the following block of code after Gum is initialized:

public static void Main()
{
    //...
    GumUI.Initialize();
    
    var button = new Button();
    button.AddToRoot();
    button.Width = 200;
    button.Anchor(Anchor.Center);
    button.Click += (_,_) => button.Text = $"Clicked\n{DateTime.Now}";
    //additional code omitted

Button in raylib responding to clicks