-
-

Python Bindings for Raylib 5.0

- -

Chatroom: Discord or Matrix

-

New CFFI API static bindings.

+
+

Python Bindings for Raylib 5.5

+
+

Libraries: raymath, raygui, rlgl, physac and GLFW

+
+
+

Backends: Desktop, SDL, DRM, Web

+
+
+

Platforms: Windows, Mac, Linux, Raspberry Pi, Web

+

PyPI - Downloads

+

Chatroom: Discord

+

HELP WANTED: writing examples

+

Features:

    +

  • CFFI API static bindings.

  • Automatically generated to be as close as possible to original Raylib.

  • Faster, fewer bugs and easier to maintain than ctypes.

  • Commercial-friendly license.

  • Docstrings and auto-completion.

    • -

  • Now includes extra libraries: raymath, raygui, rlgl, physac and GLFW

    • +

  • Type checking with Mypy

Full documentation

+

Quickstart

-

pip3 install raylib

-
from pyray import *
-init_window(800, 450, "Hello")
-while not window_should_close():
-    begin_drawing()
-    clear_background(WHITE)
-    draw_text("Hello world", 190, 200, 20, VIOLET)
-    end_drawing()
-close_window()
+
pip3 install raylib==5.5.0.2 --break-system-packages

+
from pyray import *
+init_window(800, 450, "Hello")
+while not window_should_close():
+    begin_drawing()
+    clear_background(WHITE)
+    draw_text("Hello world", 190, 200, 20, VIOLET)
+    end_drawing()
+close_window()

Installation

-

First make sure you have the latest pip installed:

+

If you are on a modern Linux you will probably want to create a venv:

+
python3 -m venv venv
+source venv/bin/activate
+
+
+

Then make sure you have the latest pip installed:

python3 -m pip install --upgrade pip

Then install

python3 -m pip install setuptools
-python3 -m pip install raylib
+python3 -m pip install raylib==5.5.0.2
-

On most platforms it should install a binary wheel (Windows 10 x64, MacOS 10.15 x64, Linux Ubuntu1804 x64).

-

If yours isn’t available then pip will attempt to build from source, in which case you will need to have Raylib development libs installed, e.g. +

On most platforms it should install a binary wheel. If yours isn’t available then pip will attempt to build from +source, in which case you will need to have Raylib development libs installed, e.g. using homebrew, apt, etc.

+
+

Windows

+

Binaries require x64 Windows 10 or newer. (For x86 or older Windows you will have to build from source.)

+

Use an official Windows Python release rather than WSL, MSYS, etc.

+
+
+

MacOS

+

Binaries require:

+
    +

  • arm64 MacOS 14

    • +

  • x64 MacOS 10.13, or newer.

    • +
+

Older MacOS requires building from source but this is usually simple:

+
brew install pkg-config
+brew install raylib
+python3 -m pip install raylib==5.5.0.2
+
+
+

(I do have binaries for arm64 MacOS 11, 12 and 13 but I have no way of testing they work, so post an issue +if you want to test them.)

+
+
+

Linux

+

Binaries require OS newer than Ubuntu 2020, x64 or arm64. Otherwise build from source. +(Pip should attempt automatically but will need Raylib itself installed and also pkg-config.)

+

The arm64 binaries are built on Raspberry Pi arm64 Bullseye with OpenGL 2.0 +so may not work on other boards.

+

Raspberry Pi

-

Using on Rasperry Pi

+

Using on Rasperry Pi

+
+
+

Backends

Dynamic binding version

There is now a separate dynamic version of this binding:

-
python3 -m pip install raylib_dynamic
+
python3 -m pip uninstall raylib
+python3 -m pip install raylib_dynamic
 

 

 
It works on some systems where the static version doesn’t, but be sure to read these caveats before using it

+
You can’t have multiple raylib packages installed at once.
-
-

Beta testing

-

If you find a bug, it may be fixed in the latest dev release. -You can install an alpha or beta version by specifying the exact version number like this:

-
python3 -m pip install raylib==4.2.0.0.dev4
+

+
SDL backend

+
This is not well tested but has better support for controllers:

+
python3 -m pip uninstall raylib
+python3 -m pip install raylib_sdl
 

 

+
You can’t have multiple raylib packages installed at once.

+

+

+
DRM backend

+
This uses the Linux framebuffer for devices that don’t run X11/Wayland:

+
python3 -m pip uninstall raylib
+python3 -m pip install raylib_drm
+

+

+
You can’t have multiple raylib packages installed at once.

 

 

 
Problems?

-
If it doesn’t work, try to build manually..  If that works then submit an issue
+
If it doesn’t work, try to build manually..  If that works then submit an issue
 to let us know what you did.

-
If you need help you can try asking on Discord.

+
If you need help you can try asking on our discord.  There is also a large Raylib discord
+for issues that are not Python-specific.

 
If it still doesn’t work, submit an issue.

How to use

-

There are two APIs, you can use either or both:

+

There are two modules in the raylib package, raylib and pyray. (There is no separate package for +pyray. Do not pip install pyray). You can use either or both:

If you are familiar with C coding and the Raylib C library and you want to use an exact copy of the C API

-

Use the C API.

+

Use the raylib module.

-
-

If you prefer a slightly more Pythonistic API and don’t mind it might be slightly slower

-

Use the Python API.

+
+

If you prefer a more Pythonistic API

+

Use the pyray module.

Running in a web browser

-

Pygbag >=0.8.7 supports running in a web browser.

+

Pygbag >=0.8.7 supports running in a web browser. Usually the latest git version +is recommended.

Make a folder my_project with a file main.py:

-
# /// script
-# dependencies = [
-#     "cffi",
-#     "raylib"
-# ]
-# ///
-import asyncio
-import platform
-from pyray import *
+
# /// script
+# dependencies = [
+#     "cffi",
+#     "raylib"
+# ]
+# ///
+import asyncio
+import platform
+from pyray import *
 
-async def main():   # You must have an async main function
-    init_window(500, 500, "Hello")
-    platform.window.window_resize()  # You must add this line
-    while not window_should_close():
-        begin_drawing()
-        clear_background(WHITE)
-        draw_text("Hello world", 190, 200, 20, VIOLET)
-        end_drawing()
-        await asyncio.sleep(0) # You must call this in your main loop
-    close_window()
+async def main():   # You MUST have an async main function
+    init_window(500, 500, "Hello")
+    platform.window.window_resize()  # You MAY want to add this line
+    while not window_should_close():
+        begin_drawing()
+        clear_background(WHITE)
+        draw_text("Hello world", 190, 200, 20, VIOLET)
+        end_drawing()
+        await asyncio.sleep(0) # You MUST call this in your main loop
+    close_window()
 
-asyncio.run(main())
+asyncio.run(main())
 

 

 
Then to create the web files and launch a web server:

 
python3.12 -m pip install --user --upgrade pygbag
-python3.12 -m pygbag --PYBUILD 3.12 --ume_block 0 --template noctx.tmpl my_project
+python3.12 -m pygbag --PYBUILD 3.12 --ume_block 0 --template noctx.tmpl --git my_project
 

 

 
Point your browser to http://localhost:8000

+
Some features may not work, so you can disable them like this:

+
if platform.system() != "Emscripten":  # audio may not work on current version of emscripten
+    init_audio_device()
+

+

 
This is all done by Pygbag rather than by me, so you should probably contact them with any issues.
 Carefully read all their documentation.

 
It does work for most of these examples

App showcase

+

Tempest-raylib

+

KarabinerKeyboard

+

PyTaiko

+

DOOM-Clone

Tanki

Alloy Bloxel Editor

+

Eidolon

Add your app here!

@@ -242,9 +324,9 @@ Carefully read all their -

License (updated)

-

The bindings are now under the Eclipse Public License, so you are free to +

+

License

+

Eclipse Public License, so you are free to statically link and use in non-free / proprietary / commercial projects!

@@ -255,7 +337,7 @@ statically link and use in non-free / proprietary / commercial projects!

  • Every call to C is costly, so it’s slightly faster if you use Python data structures and functions when calculating in your update loop and then only convert them to C data structures when you have to call the C functions for drawing.

    • -

  • The raylib.* functions are potentially 1.5x faster than the pyray.* equivalents, so if you need a tiny bit more performance +

  • The raylib.* functions are potentially slightly faster than the pyray.* equivalents, so if you need a tiny bit more performance you can switch your inner loop functions to these.

  • There is a version of Python that is faster than Pypy: GraalPy. However it’s not fully compatible with all Python packages. It doesn’t work with CFFI and so doesn’t work with this binding. But it is compatible with the diff --git a/docs/RPI.html b/docs/RPI.html index 0c0edfb..b54e020 100644 --- a/docs/RPI.html +++ b/docs/RPI.html @@ -1,3 +1,5 @@ + + @@ -5,20 +7,16 @@ Raspberry Pi — Raylib Python documentation - - - + + + - - - - - - - + + + + + @@ -46,15 +44,16 @@