Repository files navigation

In 2023 I made the decision to stop C# development using Raylib:

• Raylib is made for Cpp, and it's evolution over time results in many breaking changes for bindings such as Raylib-CsLo
• A bug in NVidia OpenGL drivers caused frame stutter when using Raylib. Troubleshooting/solving this took a month, and was an incredible burnout. (TLDR; Turn NVidia Thread Optimization off)
• Godot 4.x supports C# reasonably well

During 2023-2024 I attempted to find anybody in the community interested in taking over the project. While a few people decided to fork CsLo, nobody expressed interest in taking it over directly.

• Table of Contents
• Mac M1 is now supported
• About
  • What isRaylib?
  • Super easy to use for 2d
  • High performance for 3d! (butunsafe to use)
• How to use/install
  • via Nuget
  • via sources
• Linux / OsX / other platform support
• Examples
• Differences fromRaylib-Cs
• Extras (1st person, 3rd person cameras)
• Usage Tips, FAQ
• Known Issues
• TROUBLESHOOTING your game
  • Frame stutters, hitching, spikes
• How to Contribute
• Want to build from scratch?
  • yoink the native binary instead
• License options: MPL or PCL
  • Mozilla Public License 2_0 (MPL)
  • Private Commercial License (PCL)
• ChangeLog

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.

Managed C# bindings toRaylib, 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 abstraction
  • raygui : An Imperitive Gui
  • physac : A 2d physics framework
  • easings : for simple animations (Managed Port)
  • raymath : game math library (Managed Port)
• Minimal bindings + convenience wrappers to make it easier to use.
• Tested and verifiedALL 100+ Raylib examples. Theseported examples are available to you in the GitHub Repo
• Requiresunsafe for 3d workflows.
• Supportsnet5+,Mono 6.4+,NetCore3+ (vianetStandard 2.1)
• Tested onWin10. User ReportsArch Linux works. Please test on other platforms andraise 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 orview the 100+ examples
• Full source code included inThe GitHub Repository, including native sources, allowing you to compile for any platform you wish.
• A Nuget package is avalable

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 toXna orMonoGame 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.

If you stick with 2d, you don't need to use anyunsafe (pointer) code, which lets 2d users feel at home and useRaylib-CsLo as an awesome 2d game framework.

3d inCsLo requires theunsafe keyword. If you use 3d, you need to understand a bit of how pointers work. Raylib uses these to link things likeModel,Mesh, andMaterial. 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 useMatrix4x4.Transpose() when sending matricies to Raylib.

1. add the latest version ofThe Raylib-CsLo Nuget Package to your project
2. Create an example project using it, the following code is coppied fromThe StandAlone Example's Program.cs

usingRaylib_CsLo;namespaceStandaloneExample{publicstaticclassProgram{publicstaticasyncTaskMain(string[]args){Raylib.InitWindow(1280,720,"Hello, Raylib-CsLo");Raylib.SetTargetFPS(60);// Main game loopwhile(!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();}}}

1. clone/download thegithub repository
2. open./Raylib-CsLo-DEV.sln in Visual Studio 2022.
3. build and run.
   • theRaylib-CsLo.Examples project will run by default, and will run through all (aprox 100+) examples.
4. For a stand-alone example that uses the Nuget Package, see the./StandaloneExample folder

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 underhttps://github.com/NotNotTech/Raylib-CsLo/tree/main/Raylib-CsLo/runtimes for more info.

Here are links to most the examples.

Core	Shapes	Textures	Text	Models	Shaders	Audio	Physics

If you need a custom camera, check out theRaylib-Extras-CsLo project, which contains a custom First Person Camera and Third Person Camera.https://github.com/NotNotTech/Raylib-Extras-CsLo

• How do I doSOME_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.
• DoesRaylib-CsLo include theSOME_FUNCTION_YOU_NEED() function?
  • Raylib-CsLo has bindings for everything in the Raylib 4.0 release, including extras likeraygui andphysac, but with the exception of things in theKnown Issues section further below.
• Why didn't you add a wrapper for functionSOME_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 involvingstring marshalling), but some involving pointers have been left as-is. If you come across a function that you feel needs more wrapping, you canraise an issue or perhapssubmit a PR
• How do I convert a string tosbyte* or vice-versa?
  • All API's that takesbyte* havestring wrappers, so be sure to look at the overload you can call.
• Do I have to really cast my Enum toint?
  • 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).
• I ran the examples in a profiler. What are all thesesbyte[] arrays being allocated?
  • A pool ofsbyte[] is allocated for string marshall purposes, to avoid runtime allocations.
• Can I, Should I useRayMath?
  • Raylib_CsLo.RayMath contains a lot of super helpful functions for doing gamedev related maths.
  • TheRayMath 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, callMatrix4x4.Transpose(yourMatrix)

• Audio:v4.2 Regression Bug. There is a state corruption bug in thenative audio subsystem if you dispose of streaming audio. You may encounter this if you use multiple windows and audio streaming. see thistracking 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.

• TheText.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: useSystem.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.csglobal 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;```

• 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" toOFF.

0. assume you are using Visual Studio (or maybe rider?) and can rundev.sln
1. fork the repo, build and try out the example project
2. Pick something to do

• test/improve support on linux and/or OsX
• improve wrappers for ease of use
• ???? check issues

check out the readme under thebinding-gen folder

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.

By default, this repository is licensed under theMozilla 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 hasa great overview of the MPL 2.0 here.

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 upstreamraylib 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 for major releases.

• 4.2.0.5 (2023/01/31): Includes Mac arm64 (M1) binaries (ThanksShpendicus).
• 4.2.0.3 (2022/09/22): Includes Mac x64 binaries (ThanksShpendicus).
• 4.2.0 (2022/09/20): Includes Linux binaries (ThanksPeter0x44).
• 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#20
• 4.2.0-alpha0 (2022/09/19): Update toRaylib4.2. Bugs:
  • Native binaries only build for Win_x64. No binaries for linux or osx. Use the4.0 nuget package until someone contribs the Raylib native build for those platforms. (fixed 4.2.0.3)
  • [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. seeraysan5/raylib#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 (addingRayMath,RlGl)
• 4.0.0-alpha.1 (2021/11/16): allCore examples ported, so "feature complete" for the workflows used in those examples (and, complete only for those workflows)