Raylib-CSharp-Vinculum 5.0.1

dotnet add package Raylib-CSharp-Vinculum --version 5.0.1
NuGet\Install-Package Raylib-CSharp-Vinculum -Version 5.0.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="5.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Raylib-CSharp-Vinculum --version 5.0.1
#r "nuget: Raylib-CSharp-Vinculum, 5.0.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=5.0.1

// Install Raylib-CSharp-Vinculum as a Cake Tool
#tool nuget:?package=Raylib-CSharp-Vinculum&version=5.0.1
Raylib-CSharp-Vinculum .NET 5+ Nuget Source Code Platforms GitHub
<img align="left" src="https://github.com/ZeroElectric/Raylib-CSharp-Vinculum/blob/main/.assets/raylib-csharp-vinculum_logo_256x256.png" width="256px"> Raylib-CSharp-Vinculum is a .Net/C# autogen raylib binding, 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 the following raylib 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 (C# port of rcamera.h).
  • Requires unsafe keyword. A basic guide on pointers can be found here,
  • A focus on performance & minimal runtime allocations,
  • A fork of Raylib-CsLo as the maintainer wished 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: 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, the Maintainer (jasonswearingen/Novaleaf) announced they wished to step down from the project and seeing as I use the project for a set a game-development 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 kind of 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 didn't 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.

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

Warning: The Linux build system only builds raylib, not the Vinculum project, to complete the build process you must use Windows, this is temporary.

<details>

<summary>Building for Windows</summary>

Prerequisites

  • Visual Studio 2022 with the following workloads:

    • .NET SDK (NET8+)
    • Visual C++ Toolset
    • MSVC v142 (or higher) x64/x86
  • 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

Building the library

  • 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

</details>

<details>

<summary>Building for Linux</summary>

Note: This build system is designed for Debian based distros.

Prerequisites

  • .NET SDK (NET8+)

    • You can find more info on how to install .NET on Linux here
  • Install Build-Essential for linux

    sudo apt install build-essential git
    
  • Install required libraries

    sudo apt install libasound2-dev mesa-common-dev libx11-dev libxrandr-dev libxi-dev xorg-dev libgl1-mesa-dev libglu1-mesa-dev
    
  • 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

Building the library

  • Run build.sh, wait for the build to complete
  • Compiled 'libraylib.so' will be in Source/Raylib-CSharp-Vinculum/runtimes/linux-x64/native

</details>

Differences from Raylib-CsLo

  • A namespace difference Raylib-CsLo > ZeroElectric.Vinculum.

  • Uses newer build of raylib that might have removed or changed some functions you use.

  • No macOS support.

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

Examples

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
		Raylib.SetTargetFPS(60);

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

			// Clear the background to white
			Raylib.ClearBackground(Raylib.RAYWHITE);

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

			// End drawing to the window
			Raylib.EndDrawing();
		}

		// Close the window
		Raylib.CloseWindow();
	}
}
  • View code example collection here
  • raylib 5.0 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 matricies to raylib for rendering, call Matrix4x4.Transpose(yourMatrix) first.

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?

  • Although the autogen bindings remain unchanged, convenience wrappers have been added. These wrappers typically work automatically via method overloads or helpers eg GetGestureDetectedAsGesture or Camera3D.Projection.

  • 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.
  • Although the RayMath helper methods have been translated into C#, making the code pretty fast, it is recommended, if available to use the corresponding method under System.Numerics, as the .Net CLR treats things under System.Numerics special and optimizes them 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# 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 window made with raylib 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, use that instead,
  • LogCustom() is ported but doesn't support variable length arguments,
  • The Text.Unicode example doesn't render unicode properly.
  • One of the overloads for the GuiCheckBox implementation returns bool like the Raygui 3.x API, instead of int.

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,455 1/14/2024
5.0.0 1,558 11/22/2023
4.5.2 2,247 5/12/2023
4.5.1 2,114 4/20/2023
4.5.0.1 2,152 4/8/2023
4.5.0 2,276 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:

----------------------------------------------
5.0.1 (Jan 14 2024), General Fixes & Improvements
----------------------------------------------

- Renamed `GetGestureDetected()` -> `GetGestureDetectedAsGesture()`
- Renamed `CreateYawPitchRoll()` -> `YawPitchRollAsVector3()`

- Fixed a bug where IsMouseButtonUp() would always return true
- Improvements to 5.0 wrappers

- Added new examples

----------------------------------------------
5.0 (Nov 22 2023), Raylib 5.0 | RayGUI 4.0
----------------------------------------------

Raylib and RayGUI Changes :

- Raylib 5.0
   - [BRAKING] REMOVED: GenImageGradientH() and GenImageGradientV()
   - [BRAKING] RENAMED: LoadFont*() parameter names for consistenc
   - ADDED: New Splines drawing and evaluation API
   - ADDED: IsKeyPressedRepeat() on PLATFORM_DESKTOP
   - ADDED: SetWindowMaxSize() for desktop and web
   - ADDED: LoadRandomSequence() / UnloadRandomSequence()
   - ADDED: DrawCircleLinesV()
   - ADDED: ExportImageToMemory()
   - ADDED: GenImageGradientSquare()
   - ADDED: GenImageLinearGradient()
   - ADDED: LoadSoundAlias()
   - ADDED: GetMasterVolume()
   - REDESIGNED: LoadOBJ(), to avoid mesh splitting by materials
   - REVIEWED: Support .vox model file version 200
   - REVIEWED: Optimized and simplified  the gesture system
   - And much much more

With over 95 function changed and additions be sure to read up on all of the changes over on raylib's' [CHANGELOG](https://github.com/raysan5/raylib/blob/master/CHANGELOG)!

- RayGUI 4.0
   - [BRAKING] REDESIGNED: Multiple functions and what they return, check out raygui 4.0's [CHANGELOG](https://github.com/raysan5/raygui/releases/tag/4.0) for a detailed list of changes
   - [BRAKING] REDESIGNED: All controls return result are now 'int'
   - ADDED: GuiToggleSlider()
   - ADDED: GuiColorPickerHSV() and GuiColorPanelHSV()
   - ADDED: Multiple new icons, mostly compiler related
   - ADDED: New enum values: GuiTextAlignment, GuiTextAlignmentVertical, GuiTextWrapMode

Vinculum Changes
- Added two new examples
   - SplinesDrawing
   - MixedAudioProcessing
- Created a Attributions file for example assets
- Optimized the layout of multiple of the examples
- Optimized port of rcamera, #6
- Fixed .obj example files being missing
- Fixed a crash on Linux with the TestingProgram
- Fixed all examples with freecamera to behave properly

Known Issues:

- GuiCheckBox wrapper implementation does not have correct API, returns bool like the raygui 3.x API and not int.
- Many of the new API's do not have a managed sbyte* wrapper implementations.

----------------------------------------------
4.5.2 (May 11 2023), Raygui 3.6
----------------------------------------------

- Better Linux support

Updated raygui to 3.6
- Added new icon: SAND_TIMER
- Added additional input support for `GuiTextBox()`
- Redesigned `GuiSlider*()` and `GuiScrollBar()` to support out-of-bounds
- Fixed a crash when moving the cursor on `GuiTextBox()`

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

4.5.0.1 (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](https://github.com/raysan5/raylib/blob/master/CHANGELOG) for a detailed list of changes in raylib 4.5

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, a C# binding for Raylib 4.2, supports Windows.