Awesome
![]() |
---|
Table of Contents
- Table of Contents
- Mac M1 is now supported
- About
- How to use/install
- Linux / OsX / other platform support
- Examples
- Differences from
Raylib-Cs
- Extras (1st person, 3rd person cameras)
- Usage Tips, FAQ
- Known Issues
- TROUBLESHOOTING your game
- How to Contribute
- Want to build from scratch?
- License options: MPL or PCL
- ChangeLog
Mac M1 is now supported
v4.2.0.5
should now include full osx support, both x64 and arm64, which includes supporting the M1.
If you test on the M1 and have problems, please raise an issue.
About
Managed C# bindings to Raylib
, a friendly 2d/3d game framework similar to XNA / MonoGame.
- Win/Linux/OsX supported.
- All Raylib features, including Extras bindings
raylib
: Core features, including Audio.rlgl
: OpenGl abstractionraygui
: An Imperitive Guiphysac
: A 2d physics frameworkeasings
: for simple animations (Managed Port)raymath
: game math library (Managed Port)
- Minimal bindings + convenience wrappers to make it easier to use.
- Tested and verified ALL 100+ Raylib examples. These ported examples are available to you in the GitHub Repo
- Requires
unsafe
for 3d workflows. - Supports
net5+
,Mono 6.4+
,NetCore3+
(vianetStandard 2.1
) - Tested on
Win10
. User ReportsArch
Linux works. Please test on other platforms and raise an issue if any problems occur. - A focus on performance. No runtime allocations if at all possible.
- No intellisense docs. read the raylib cheatsheet for docs or view the 100+ examples
- Full source code included in The GitHub Repository, including native sources, allowing you to compile for any platform you wish.
- A Nuget package is avalable
What is Raylib?
Raylib is a friendly-to-use game framework that includes basic scenarios to meet your needs: audio, 2d, 3d, fonts, animation, 2d physics. Somewhat similar to Xna
or MonoGame
but friendlier. However, Raylib
is a C/CPP framework. Raylib-CsLo
is a C# Wrapper over the top, which lets you gain raylib's powers to quickly prototype your game ideas.
Super easy to use for 2d
If you stick with 2d, you don't need to use any unsafe
(pointer) code, which lets 2d users feel at home and use Raylib-CsLo
as an awesome 2d game framework.
High performance for 3d! (but unsafe
to use)
3d in CsLo
requires the unsafe
keyword. If you use 3d, you need to understand a bit of how pointers work. Raylib uses these to link things like Model
, Mesh
, and Material
. Writing wrappers over these is possible but it would basically be creating a an entirely new framework. I suggest leaving this as-is, as it avoids object allocation (GC Pressure).
Additionally, 3d users: Be sure you check the Usage Tips section below, especially on how you need to use Matrix4x4.Transpose()
when sending matricies to Raylib.
How to use/install
via Nuget
- add the latest version of The Raylib-CsLo Nuget Package to your project
- Create an example project using it, the following code is coppied from The StandAlone Example's Program.cs
using Raylib_CsLo;
namespace StandaloneExample
{
public static class Program
{
public static async Task Main(string[] args)
{
Raylib.InitWindow(1280, 720, "Hello, Raylib-CsLo");
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("Raylib is easy!!!", 640 , 360, 50, Raylib.RED);
Raylib.EndDrawing();
}
Raylib.CloseWindow();
}
}
}
via sources
- clone/download the github repository
- open
./Raylib-CsLo-DEV.sln
in Visual Studio 2022. - build and run.
- the
Raylib-CsLo.Examples
project will run by default, and will run through all (aprox 100+) examples.
- the
- For a stand-alone example that uses the Nuget Package, see the
./StandaloneExample
folder
Linux / OsX / other platform support
The following platforms are shipped in the nuget package:
win-x64
: confirmed working onWin10, x64
. This is the platform used for dev/testing ofraylib-cslo
.linux-x64
: confirmed working onArch
Linux. Binaries built underUbuntu 20.04
so that shold also work.osx-x64
: not confirmed yet. Please let me know if you try.
You can build the native binaries for whatever platform you need. Please see the readme under https://github.com/NotNotTech/Raylib-CsLo/tree/main/Raylib-CsLo/runtimes for more info.
Examples
Here are links to most the examples.
Core | Shapes | Textures | Text | Models | Shaders | Audio | Physics |
---|---|---|---|---|---|---|---|
![]() | ![]() | ![]() | ![]() | ![]() | ![]() | ![]() | ![]() |
![]() | ![]() | ![]() | ![]() | ![]() | ![]() | ![]() | ![]() |
Differences from Raylib-Cs
Raylib-Cs | Raylib-CsLo |
---|---|
An artisanal, bespoke binding+wrapper. | A cold, calculating robo-binding. |
Each binding is hand crafted with carefull design | Exact Bindings (Autogen) with wrappers to make C# usage nice. |
Bindings for Raylib and extras RayMath , RlGl . | Bindings for Raylib and all extras (RayGui , Easings , Physac , RlGl , RayMath ) |
Optimized for normal C# usage | Optimized for maximum performance and might require unsafe |
New Raylib version? Harder to detect breaking changes | New Raylib version? Breaking changes are easy to spot and fix |
includes Intellisence docs | No docs. Use the Cheatsheet / Examples |
Born 2018-07 | Born 2021-11 |
Lots of examples | ALL 100+ Raylib examples |
zlib Licensed | MPL 2.0 Licensed |
Nuget Package | Nuget Package |
Raylib 4.0 | Raylib 4.2 |
lots of contribs | few contribs |
Extras (1st person, 3rd person cameras)
If you need a custom camera, check out the Raylib-Extras-CsLo
project, which contains a custom First Person Camera and Third Person Camera. https://github.com/NotNotTech/Raylib-Extras-CsLo
Usage Tips, FAQ
- How do I do
SOME_IDEA
?- All the Raylib examples (100+) have been ported successfully. Please refer to them here: ALL 100+ Raylib examples. If you need more help, ask on Discord.
- Does
Raylib-CsLo
include theSOME_FUNCTION_YOU_NEED()
function?- Raylib-CsLo has bindings for everything in the Raylib 4.0 release, including extras like
raygui
andphysac
, but with the exception of things in theKnown Issues
section further below.
- Raylib-CsLo has bindings for everything in the Raylib 4.0 release, including extras like
- Why didn't you add a wrapper for function
SOME_OTHER_FUNCTION_YOU_NEED()
?- Raylib-CsLo uses a manual marshalling technique, as the built in PInvoke marshalling is not very efficienct. Most API's have wrappers (and all involving
string
marshalling), but some involving pointers have been left as-is. If you come across a function that you feel needs more wrapping, you can raise an issue or perhaps submit a PR
- Raylib-CsLo uses a manual marshalling technique, as the built in PInvoke marshalling is not very efficienct. Most API's have wrappers (and all involving
- How do I convert a string to
sbyte*
or vice-versa?- All API's that take
sbyte*
havestring
wrappers, so be sure to look at the overload you can call.
- All API's that take
- Do I have to really cast my Enum to
int
?- The autogen bindings are left untouched, however convenience wrappers are added. Usually these will automagically "work" via function overloads, but where this is not possible, try adding an underscore
_
to the end of the function/property. For example:Camera3D.projection_ = CameraProjection.CAMERA_ORTHOGRAPHIC;
orGesture gesture = Raylib.GetGestureDetected_();
. - If all else fails, yes. Cast to
(int)
.
- The autogen bindings are left untouched, however convenience wrappers are added. Usually these will automagically "work" via function overloads, but where this is not possible, try adding an underscore
- I ran the examples 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.
- A pool of
- Can I, Should I use
RayMath
?Raylib_CsLo.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 underSystem.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)
- Raylib/OpenGl uses column-major matricies, while dotnet/vulkan/directx uses row-major. When passing your final calculated matrix to raylib for rendering, call
Known Issues
-
Audio
: v4.2 Regression Bug. There is a state corruption bug in the native audio subsystem if you dispose of streaming audio. You may encounter this if you use multiple windows and audio streaming. see this tracking issue for more info. -
RayGui
: be sure to callRayGui.GuiLoadStyleDefault();
right after youInitWindow()
. 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 forTexture
so use that instead. You might want to useusing
aliases like the following```cs //usings to make C# code more like the raylib cpp examples. //to see more stuff like this, look at Raylib-CsLo.Examples/program.cs global using Camera = Raylib_CsLo.Camera3D; global using RenderTexture2D = Raylib_CsLo.RenderTexture; global using Texture2D = Raylib_CsLo.Texture; global using TextureCubemap = Raylib_CsLo.Texture; global using Matrix = System.Numerics.Matrix4x4; ```
TROUBLESHOOTING your game
Frame stutters, hitching, spikes
- Make sure the Garbage Collector isn't overwhelmed
- Ensure your graphic drivers are up to date
- If using an Nvidia card, read this: https://stackoverflow.com/questions/36959508/nvidia-graphics-driver-causing-noticeable-frame-stuttering
- TLDR: Poor driver support for OpenGl games. In your driver settings, turn "Threaded Optimization" to
OFF
.
- TLDR: Poor driver support for OpenGl games. In your driver settings, turn "Threaded Optimization" to
How to Contribute
- assume you are using Visual Studio (or maybe rider?) and can run
dev.sln
- fork the repo, build and try out the example project
- Pick something to do
- test/improve support on linux and/or OsX
- improve wrappers for ease of use
- ???? check issues
Want to build from scratch?
check out the readme under the binding-gen
folder
yoink the native binary instead
If there is a platform that doesn't work due to no native binary being shipped with the Raylib-CsLo nuget package, you should just be able to yoink the official raylib native library ...like from here and if it's put in the right folder location (output folder), raylib-cslo can use it, assuming it's named properly. If you do this you need to be aware that the various raylib-extras will not be available, but everything else should work.
License options: MPL or PCL
Mozilla Public License 2_0 (MPL)
By default, 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.
Private Commercial License (PCL)
If for some reason you or your organization really, REALLY can not open source your modifications to this project, I am willing to offer a PCL for USD $1000, half of which will be donated to the upstream raylib
project. Payment can be made via github donations. Yes $1000 is a lot of money, so just try to accept the MPL terms and move on with life!
If you still think a PCL is what you need, raise an issue or email JasonS aat Novaleaf doot coom to discuss.
ChangeLog
changelog for major releases.
- 4.2.0.5 (2023/01/31): Includes Mac arm64 (M1) binaries (Thanks
Shpendicus
). - 4.2.0.3 (2022/09/22): Includes Mac x64 binaries (Thanks
Shpendicus
). - 4.2.0 (2022/09/20): Includes Linux binaries (Thanks
Peter0x44
). - 4.2.0-alpha1 (2022/09/19):
- fix marshalling of null strings passed to native code. was marshalling as empty strings but instead should have been marshalling as NULL. fixed. see https://github.com/NotNotTech/Raylib-CsLo/issues/20
- 4.2.0-alpha0 (2022/09/19): Update to
Raylib4.2
. Bugs:Native binaries only build for Win_x64. No binaries for linux or osx. Use the(fixed 4.2.0.3)4.0
nuget package until someone contribs the Raylib native build for those platforms.- [Raylib Native Regression Bug] Memory corruption in the Streaming Audio system. Causes corruption of Native Raylib state upon closing a streaming session. This is a bug in the native code, so we need to await an upstream fix. see https://github.com/raysan5/raylib/issues/2714
- 4.0.0-rc.5.0 (2021/12/15): No breaking changes. Broaden DotNet support to Net5+, etc (via NetStandard 2.1)
- 4.0.0-rc.4.0 (2021/12/04): No breaking changes. Cleanup and change license from LGPL to MPL, because LGPL doesn't allow private static linking.
- 4.0.0-rc.3 (2021/11/29): No breaking changes. Improve Boolean Marshalling.
- 4.0.0-rc.2 (2021/11/28): Rollup all native code into single binary. Improve bindings compat.
- 4.0.0-rc.1 (2021/11/24): Support for Linux and OsX (hopefully).
- 4.0.0-rc.0 (2021/11/22):
physac.dll
and bindings for it added.Physics
andAudio
examples ported. Allraylib
examples complete! - 4.0.0-beta.2 (2021/11/22):
RayGui
, andEasings
Raylib.extras ported to managed code.Shapes
,Textures
, andText
examples ported. - 4.0.0-beta.0 (2021/11/20):
Model
, andShader
examples ported. - 4.0.0-alpha.2 (2021/11/18): Model examples ported. AutoGen Bindings expanded to include all api's exposed by Raylib.dll (adding
RayMath
,RlGl
) - 4.0.0-alpha.1 (2021/11/16): all
Core
examples ported, so "feature complete" for the workflows used in those examples (and, complete only for those workflows)