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" />

Or add through command line:

dotnet add package Gum.raylib

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 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.gumx");
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