Raylib-CSharp-Vinculum 4.5.0-rc1

This is a prerelease version of Raylib-CSharp-Vinculum.
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.0-rc1
NuGet\Install-Package Raylib-CSharp-Vinculum -Version 4.5.0-rc1
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.0-rc1" />
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.0-rc1
#r "nuget: Raylib-CSharp-Vinculum, 4.5.0-rc1"
#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.0-rc1&prerelease

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

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

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

  • Windows supported. With Linux planned.
  • Supports .Net 5+, Mono 6.4+, Net Core3.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 Imperitive Gui
    • 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 for 3d workflows.
  • A focus on performance. No runtime allocations if at all possible.
  • A fork of Raylib-CsLo as the maintainer wishes to step down.
  • No intellisense docs. You can read the Raylib cheatsheet for some help or view the examples
  • Nuget package can be found here
  • Go give Ray some love, https://github.com/sponsors/raysan5

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 namespace is different Raylib-CsLo > ZeroElectric.Vinculum

What is Raylib?

Raylib is a easey-to-use videogame framework well suited for prototyping, tooling, embedded systems and education, inclueds 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 C# autogen wrapper, which lets you use Raylib in C#/.Net.

High performance for 3D! (but unsafe to use)

3D requires the unsafe keyword. If you use 3D, you will need to understand how pointers work. A basic guide on pointers can be found here.

Additionally, 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.

How to Install

via Nuget

  • By adding the package using .NET CLI:

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

via Source

Prerequisites

  • Currently only buildable on Windows 10/11
  • 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

If you didn't/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' it 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

  • Changed the namespace from Raylib-CsLo > ZeroElectric.Vinculum
  • Greatly optimized the project layout
  • Uses a newer build of Raylib
  • New Build system, now you just run build.bat from the root to build the lib

Examples

Basic Example:

using ZeroElectric.Vinculum;

namespace VinculumExample
{
  public static class Program
  {
    public static void Main(string[] args)
    {
      Raylib.InitWindow(1280, 720, "Hello, Raylib-Vinculum");
      Raylib.SetTargetFPS(60);
      
      // Main game loop
      while (!Raylib.WindowShouldClose()) // Detect window close button or ESC key
      {
        Raylib.BeginDrawing();
        Raylib.ClearBackground(Raylib.SKYBLUE);
       
        Raylib.DrawFPS(10, 10);
        
        Raylib.DrawText("Hello Raylib in CSharp!", 640 , 360, 50, Raylib.BLUE);
        
        Raylib.EndDrawing();
      }

      Raylib.CloseWindow();
    }
  }
}
  • View code example collection here
  • raylib 4.5 cheatsheet here
  • raylib architecture design here

FAQ & Tips

  • How do I convert a string to sbyte* or vice-versa?
    • All API's that take sbyte* have string wrappers, so be sure to look at the overload you can call.
  • Do I have to really cast my Enum to int?
    • The autogen bindings are left untouched, however convenience wrappers have been added. Usually these will automatically "work" via function overloads, but when this is not possible, try adding an underscore _ to the end of the function/property. For example:
      Camera3D.projection_ = CameraProjection.CAMERA_ORTHOGRAPHIC;
      
      Gesture gesture = Raylib.GetGestureDetected_();
      
    • If all else fails, yes. Cast to (int).
  • I ran the Example project in a profiler. What are all these sbyte[] arrays being allocated?
    • A pool of sbyte[] is allocated for string marshall purposes, to avoid runtime allocations.
  • Can I, Should I use RayMath?
    • ZeroElectric.Vinculum.RayMath contains a lot of super helpful functions for doing gamedev related maths.
    • The RayMath helper functions have been translated into C# code. This makes the code pretty fast, but if the same function exists under System.Numerics you should use that instead, because the DotNet CLR treats things under System.Numerics special, and optimizes it better.
  • Why are my matricies corrupt?
    • Raylib/OpenGl uses column-major matricies, while dotnet/vulkan/directx uses row-major. When passing your final calculated matrix to raylib for rendering, call Matrix4x4.Transpose(yourMatrix)

Known Issues

  • RayGui: be sure to call RayGui.GuiLoadStyleDefault(); right after you InitWindow(). This is needed to initialize the gui properly. If you don't, if you close a raylib window and then open a new one (inside the same app), the gui will be broken.
  • The Text.Unicode example doesn't render unicode properly. Maybe the required font is missing, maybe there is a bug in the example (Utf16 to Utf8 conversion) or maybe there is a bug in Raylib. A hunch: I think it's probably due to the fonts not including unicode characters, but I didn't investigate further.
  • Native Memory allocation functions are not ported: use System.Runtime.InteropServices.NativeMemory.Alloc() instead
  • LogCustom() is ported but doesn't support variable length arguments.
  • Texture2D doesn't exist. it is just an alias for Texture so use that instead.
  • You might want to use using aliases like the following
    //Use 'global using'-'global using static' 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;
    

License

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
WoopWoopEngine

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
4.5.0.1 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.0-rc1: Added RayCamera

4.5.0-dev-alpha: Updated to Raylib 4.5-dev

4.2.0.0-alpha: Initial release of Raylib-CSharp-Vinculum, CSharp bindings for Raylib 4.2. Supports Windows