You are viewing PyUnity docs under the
As such, they are only applicable if you installed from source.
Go to https://docs.pyunity.x10.bz/en/latest/ for the most recent
Information on specific functions, classes, and methods.
- pyunity.physics package
- pyunity.scenes package
- pyunity.values package
- pyunity.window package
Version 0.9.0 (in development)¶
PyUnity is a pure Python 3D Game Engine that was inspired by the structure of the Unity Game Engine. It aims to be as close as possible to Unity itself. This does not mean that PyUnity are bindings for the UnityEngine. However, this project has been made to facilitate any programmer, beginner or advanced, novice or veteran.
As we have said above, this is not a set of bindings for the UnityEngine, but a pure Python library to aid in making 3D games in Python.
To install PyUnity for Linux distributions based on Ubuntu or Debian, use:
> pip3 install pyunity
To install PyUnity for other operating systems, use:
> pip install pyunity
Alternatively, you can clone the repository
to build the package from source. Then use
setup.py to build. Note that it will install
Cython to compile.
> pip install .
The latest builds are on the
which is the default branch. These builds are
sometimes broken, so use at your own risk.
> git clone https://github.com/pyunity/pyunity > pip install .
Its only dependencies are PyOpenGL, PySDL2,
Pillow and PyGLM. Microsoft Visual
C++ Build Tools are required on Windows
for building yourself, but it can be disabled by
cython environment variable to
0, at the cost of being less optimized.
GLFW can be optionally installed if you would
like to use the GLFW window provider.
To start using PyUnity, you must import it. A standard way to import is like so:
>>> from pyunity import *
Debug information is turned on by default. If
you want to turn it off, set the
PYUNITY_DEBUG_MODE environment variable to
This is the output with debugging:
Loaded config Trying GLFW as a window provider GLFW doesn't work, trying PySDL2 Using window provider PySDL2 Loaded PyUnity version 0.9.0
If debugging is off, there is no output:
>>> import os >>> os.environ["PYUNITY_DEBUG_MODE"] = "0" >>> from pyunity import * >>> # No output
All PyUnity projects start with a scene. To add a scene, do this:
>>> scene = SceneManager.AddScene("Scene 1")
Then, let’s move the camera backwards 10 units.
>>> scene.mainCamera.transform.position = Vector3(0, 0, -10)
Finally, add a cube at the origin:
>>> cube = GameObject("Cube") >>> renderer = cube.AddComponent(MeshRenderer) >>> renderer.mesh = Mesh.cube(2) >>> renderer.mat = Material(RGB(255, 0, 0)) >>> scene.Add(cube)
To see what you have added to the scene, call
>>> scene.List() /Main Camera /Light /Cube
Finally, to run the scene, call
scene.Run(). The window that
is created is one of FreeGLUT, GLFW or PySDL2. The window is
selected on module initialization (see Windows subheading).
To create your own PyUnity script, create a class that inherits
from Behaviour. Usually in Unity, you would put the class in its
own file, but Python can’t do something like that, so put all of
your scripts in one file. Then, to add a script, just use
AddComponent(). Do not put anything in the
instead put it in
Update() function receives one
dt, which is the same as
Time.deltaTime in Unity.
The window is provided by one of three providers: GLFW, PySDL2 and FreeGLUT. When you first import PyUnity, it checks to see if any of the three providers work. The testing order is as above, so FreeGLUT is tested last.
To create your own provider, create a class that has the following methods:
__init__: initiate your window and check to see if it works.
start: start the main loop in your window. The first parameter is
update_func, which is called when you want to do the OpenGL calls.
Check the source code of any of the window providers for an example. If you would like to contribute a new window provider, then please create a pull request.
Here is a list of environment variables used by PyUnity:
PYUNITY_TESTING (default: unset) When set, the following features are either disabled or ignored:
Window provder selection
PYUNITY_DEBUG_MODE (default: 1) Disables debug output if set to “0”. Debug output has the code |D| in the log file.
PYUNITY_AUDIO (default: 1) If set to “0”, sdlmixer won’t be loaded and
config.audiois set to
PYUNITY_GL_CONTEXT (default: unset) Set when the OpenGL context is enabled. Usually not used except by wrapper scripts as Behaviours only update while a valid context exists.
PYUNITY_CHECK_WINDOW (default: 0) If set to “1”, forces window provider selection regardless if
windowProvideris set in
settings.json. If set to “0”, window provider selection is triggered only if
windowProviderdoesn’t already exist in
PYUNITY_INTERACTIVE (default: 1) If set to “0”, window providing is disabled and scenes are run without any OpenGL rendering.
PYUNITY_SPHINX_CHECK (default: unset) Used by sphinx to fix some bugs that occur during documentation generation.
PYUNITY_CHANGE_MODULE (default: 1) Change the
__module__attribute of all imported objects to
pyunity. If set to “0”, this is disabled.
Examples are located at subfolders in pyunity/examples so do be sure to check them out as a starting point.
To run an example, import it like so:
>>> from pyunity.examples.example1 import main Loaded config Trying FreeGLUT as a window provider FreeGLUT doesn't work, trying GLFW GLFW doesn't work, trying PySDL2 Using window provider PySDL2 Loaded PyUnity version 0.9.0 >>> main()
Or from the command line:
> python -m pyunity 1
1 just means to load example 1, and there
are 9 examples. To load all examples one by
one, do not specify a number. If you want to
contribute an example, then please
create a pull request.