Raylib-CSharp-Vinculum 4.5.1

There is a newer version of this package available.
See the version list below for details.
dotnet add package Raylib-CSharp-Vinculum --version 4.5.1
NuGet\Install-Package Raylib-CSharp-Vinculum -Version 4.5.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Raylib-CSharp-Vinculum" Version="4.5.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Raylib-CSharp-Vinculum --version 4.5.1
#r "nuget: Raylib-CSharp-Vinculum, 4.5.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Raylib-CSharp-Vinculum as a Cake Addin
#addin nuget:?package=Raylib-CSharp-Vinculum&version=4.5.1

// Install Raylib-CSharp-Vinculum as a Cake Tool
#tool nuget:?package=Raylib-CSharp-Vinculum&version=4.5.1

Raylib-CSharp-Vinculum Nuget Source Code .NET 5+ Platforms GitHub

Raylib-CSharp-Vinculum is a autogen raylib binding for .Net/C#, raylib is a simple and easy-to-use 2d/3d videogame framework, similar to XNA & MonoGame.

  • Windows & Linux supported,
  • Supports .Net 5+, Mono 6.4+, Core 3.0,
  • 1-1 bindings + convenience wrappers to make it easier to use,
  • Includes bindings for all of Raylib's extras:
    • raylib : Core features, including Audio,
    • rlgl : OpenGl abstraction,
    • raygui : An immediate mode GUI framework,
    • physac : A simple 2d physics framework,
    • rres : A simple and easy-to-use file-format to package resources,
    • easings : Use for simple animations (C# Managed Port),
    • raymath : A game math library (C# Managed Port),
    • rcamera : A basic camera system (Direct C# port of rcamera.h).
  • Requires unsafe keyword for 3d workflows. A basic guide on pointers can be found here,
  • A focus on performance. No runtime allocations if at all possible,
  • A fork of Raylib-CsLo as the maintainer wishes to step down,
  • Very little intellisense docs. You can read the Raylib cheatsheet for some help or view the examples
  • Go give Ray some love ❤️, https://github.com/sponsors/raysan5

Warning: 3D users: be sure you check the FAQ & Tips section below, especially on how you need to use Matrix4x4.Transpose() when sending Matricies to Raylib.

Note: Users comming from Raylib-CsLo make sure to read the Differences section below

Wait a minute haven't I seen this repository before?

Maybe! This repo is a fork of Raylib-CsLo and the Maintainer (jasonswearingen/Novaleaf) announced they wanted to step down from the project and seeing as I use the project for a set a game-making tools I decided to fork the project and greatly optimize the project layout for better long term maintainability. Why did I change the name? Honestly the name Raylib-CsLo is kinda boring, and being inspired by projects with names like Vortice, I chose the name Vinculum [vin·cu·lum] witch means Bond in Latin, also I dont want to "steal" the name, other then the name, the only real change from a end-user point of view is a namespace difference Raylib-CsLo > ZeroElectric.Vinculum

What is Raylib?

Raylib is a easey-to-use videogame framework well suited for prototyping, tooling, embedded systems and education, includes systems for: audio, 3D, 2D, 2D physics, fonts, animation, an OpenGL abstraction layer & more. Inspired By XNA & The Borland Graphics Interface. However, Raylib is a C framework. Raylib-CSharp-Vinculum is a .Net/C# autogen wrapper, which lets you use raylib in .Net/C#.

How to Install

📦 via Nuget

  • By adding the package using the .NET CLI:

    dotnet add package Raylib-CSharp-Vinculum
  • Or by searching for Raylib-CSharp-Vinculum in Visual Studio's Nuget Package Manager

🏗️ via Source

Attention: The current build system is only usable on Windows 10/11, this is temporary.


<summary>Building for Windows</summary>


  • Visual Studio 2022 with the following workloads:
    • .NET SDK (NET6+)
    • Visual C++ Toolset
    • MSVC v142 (or higher) x64/x86
  1. Clone this repo using the git command below. (Note: Downloading this repo as a zip file will not work, it is important you use git clone --recursive to get all of the submodules)
git clone --recursive https://github.com/ZeroElectric/Raylib-CSharp-Vinculum.git

Note: If you didn't or forgot to use --recursive, you can run git submodule update --init --recursive to fix it

  • Run build.bat and wait for the build to complete
  • Reference Raylib-CSharp-Vinculum.dll from Output\bin and import the folder runtimes into your project's root directory
  • Compiled 'Examples' will be in Output\example-bin

If the build wasn't successful make a new issue with the error it gave you


Differences from Raylib-CsLo

The only real changes from a end-user point of view is a namespace difference Raylib-CsLo > ZeroElectric.Vinculum & uses newer build of raylib that might have removed or changed some functions you use.

Other changes:
  • Greatly optimized the project layout,
  • New build system, now you just run build.bat from the root folder to build the library.


Basic Example:

using ZeroElectric.Vinculum;

namespace VinculumExample;

public static class Program
	public static void Main(string[] args)
		// Set the width and height of the window     
		int screenWidth = 800;
		int screenHeight = 450;

		// Initialize the window with the specified width, height, and title
		Raylib.InitWindow(screenWidth, screenHeight, "Hello World , Raylib-CSharp-Vinculum");

		// Set the FPS to 60

		// Loop until the window is closed
		while (!Raylib.WindowShouldClose())
			// Begin drawing to the window

			// Clear the background to white

			// Draw the text "Hello World" in maroon color at position (190, 200)
			Raylib.DrawText("Hello Raylib in CSharp!", 190, 200, 20, Color.MAROON);

			// End drawing to the window

		// Close the window
  • View code example collection here
  • raylib 4.5 cheatsheet here
  • raylib architecture design here

❓ FAQ & Tips

Make sure your matricies aren't corrupt!

  • Raylib is built upon OpenGL which uses column-major matricies, while .Net uses row-major. When passing your final calculated matrix to raylib for rendering, call Matrix4x4.Transpose(yourMatrix).

How do I convert a string to sbyte*?

  • Most methods that take sbyte* have a string wrapper, so be sure to look at the overloads you can call.
  • If you still with to convert a string, use SpanOwner<T> from the CommunityToolkit.HighPerformance Nuget package and MarshalUtf8() & AsPtr() from the ZeroElectric.Vinculum.Extensions namspace , for example:
    using CommunityToolkit.HighPerformance.Buffers;
    using ZeroElectric.Vinculum.Extensions; 
    string mytext = "Here be some text";
    using SpanOwner<sbyte> spanOwner = mytext.MarshalUtf8();
    DrawText(spanOwner.AsPtr(), 10, 10, 10, BLACK);

Do I have to cast enums to int?

  • The autogen bindings are left untouched, however convenience wrappers have been added. Usually these will automatically "work" via method overloads, but when this is not possible, try adding an underscore _ to the end of the method or property, for example:
    Camera3D.projection_ = CameraProjection.CAMERA_ORTHOGRAPHIC;
    Gesture gesture = Raylib.GetGestureDetected_();
  • If all else fails, yes, cast to int.

Can or Should I use RayMath?

  • ZeroElectric.Vinculum.RayMath contains a lot of helpful methods for doing game related math.
  • The RayMath helper methods have been translated into C#, this makes the code pretty fast, but if the same method exists under System.Numerics you should use that instead, because the .Net CLR treats things under System.Numerics special, and optimizes it better.

I ran the Example project in a profiler. What are all these sbyte[] arrays being allocated?

  • A pool of sbyte[] arrays are allocated for string marshalling purposes, to avoid runtime allocations.

TIP: You might want to use the global using directive to create aliases like the following to make C# code function more like the raylib C examples.

global using static ZeroElectric.Vinculum.Raylib;
global using static ZeroElectric.Vinculum.RayMath;
global using static ZeroElectric.Vinculum.RayCamera;
global using static ZeroElectric.Vinculum.RayGui;
global using static ZeroElectric.Vinculum.RlGl;

global using Camera = ZeroElectric.Vinculum.Camera3D;
global using RenderTexture2D = ZeroElectric.Vinculum.RenderTexture;
global using Texture2D = ZeroElectric.Vinculum.Texture;
global using TextureCubemap = ZeroElectric.Vinculum.Texture;
global using Matrix = System.Numerics.Matrix4x4;

Known Issues

  • When using RayGui, if you close a raylib window after calling RayGui.GuiLoadStyleDefault() and then open a new raylib window (within the same running instance), multiple rayGui ui elements will be broken,
  • Texture2D doesn't exist, it's just an alias for Texture so use that instead,
  • LogCustom() is ported but doesn't support variable length arguments,
  • The Linux build supplied by the nuget pakage was buiilt under debug mode,
  • The Text.Unicode example doesn't render unicode properly.


Mozilla Public License 2.0 (MPL)

This repository is licensed under the Mozilla Public License 2.0 (MPL). The MPL is a popular "weak copyleft" license that allows just about anything. For example, you may use/include/static-link this library in a commercial, closed-source project without any burdens. The main limitation of the MPL being that: Modifications to the source code in this project must be open sourced.

The MPL is a great choice, both by providing flexibility to the user, and by encouraging contributions to the underlying project. If you would like to read about the MPL, FOSSA has a great overview of the MPL 2.0 here.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Raylib-CSharp-Vinculum:

Package Downloads

A basic C# game engine with Raylib for rendering.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.0.1 1,520 1/14/2024
5.0.0 1,559 11/22/2023
4.5.2 2,248 5/12/2023
4.5.1 2,114 4/20/2023 2,152 4/8/2023
4.5.0 2,277 3/18/2023
4.5.0-rc1 2,014 3/16/2023
4.5.0-dev-alpha 2,040 3/14/2023
4.2.0-alpha 2,031 12/8/2022

Release Notes:
4.5.1 (Apr 20 2023), Raygui 3.5

Updated raygui to 3.5
- Added new Tab Bar contorol `GuiTabBar()`, based upon `GuiToggle()`,
- Added helper functions to split text in separate lines,
- Added new icons useful for code editing tools,
- Redesigned `GuiTextBox()` to support cursor movement and `GuiDrawText()` to divide drawing by lines.

The following functions have been removed:
- REMOVED: Unneeded icon editing functions
- REMOVED: GuiTextBoxMulti(), very limited and broken
- REMOVED: MeasureTextEx() dependency, logic directly implemented
- REMOVED: DrawTextEx() dependency, logic directly implemented (Apr 7 2023):
- Added Linux support.

4.5.0 (Mar 18 2023):
- A simpler and more extendable Camera module (RayCamera a C# port of rcamera.h).
- Support for M3D models and M3D/GLTF animations,
- Support for QOA audio format,
- Added new data structures validation functions such as `IsImageReady()`, `IsTextureReady()`, `IsSoundReady()` & more!
- Redesigned rlgl module for automatic render-batch limits checking and rshapes module to minimize the rlgl dependency.

The following functions have been removed or renamed:

- REMOVED: Multichannel audio API: PlaySoundMulti(), StopSoundMulti()
- REMOVED: UnloadModelKeepMeshes()
- REMOVED: DrawCubeTexture(), DrawCubeTextureRec(), functions moved to new example: `DrawCubeWithTexture`

- REMOVED: DrawTextureQud()
- REMOVED: DrawTexturePoly(), function moved to example: `textures_polygon`
- REMOVED: DrawTextureTiled(),function implementation moved to the textures_tiled.c

- RENAMED: TextCodepointsToUTF8() to LoadUTF8()
- RENAMED: GetCodepoint() -> GetCodepointNext()

With more then 25 new functions and 40+ functions revsions make sure to check out raylib's [CHANGELOG]([CHANGELOG](https://github.com/raysan5/raylib/blob/master/CHANGELOG)) for a detailed list of changes in raylib 4.5

- Added RayCamera

- Updated to Raylib 4.5-dev
- Initial release of Raylib-CSharp-Vinculum, a C# binding for Raylib 4.2, supports Windows.