{"id":15161305,"url":"https://github.com/touilleman/godot-python","last_synced_at":"2025-05-14T07:09:50.015Z","repository":{"id":38375316,"uuid":"69164674","full_name":"touilleMan/godot-python","owner":"touilleMan","description":"Python support for Godot 🐍🐍🐍","archived":false,"fork":false,"pushed_at":"2025-05-09T07:37:28.000Z","size":7495,"stargazers_count":1990,"open_issues_count":127,"forks_count":151,"subscribers_count":89,"default_branch":"master","last_synced_at":"2025-05-10T09:37:29.510Z","etag":null,"topics":["binding","godot","hacktoberfest","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/touilleMan.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-09-25T13:03:54.000Z","updated_at":"2025-05-09T13:55:26.000Z","dependencies_parsed_at":"2023-10-16T14:22:21.459Z","dependency_job_id":"22444f7f-6a55-415b-85d0-2c2993bc84ea","html_url":"https://github.com/touilleMan/godot-python","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touilleMan%2Fgodot-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touilleMan%2Fgodot-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touilleMan%2Fgodot-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touilleMan%2Fgodot-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/touilleMan","download_url":"https://codeload.github.com/touilleMan/godot-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092788,"owners_count":22013290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binding","godot","hacktoberfest","python"],"created_at":"2024-09-27T00:02:49.970Z","updated_at":"2025-05-14T07:09:45.005Z","avatar_url":"https://github.com/touilleMan.png","language":"Python","readme":".. image:: https://github.com/touilleMan/godot-python/actions/workflows/build.yml/badge.svg\n    :target: https://github.com/touilleMan/godot-python/actions\n    :alt: Github action tests\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n   :target: https://github.com/ambv/black\n   :alt: Code style: black\n\n\n================================================\nGodot Python, because you want Python on Godot !\n================================================\n\n\n🚧🚨 **Heavy refactoring in progress** 🚨🚧\n\nThe project is under heavy refactoring to support Godot4 (which is totally incompatible\nwith the current codebase).\n\nDevelopment is done on the `godot4-meson branch \u003chttps://github.com/touilleMan/godot-python/tree/godot4-meson\u003e`_\nuntil things start getting usable.\n\n\n.. image:: https://github.com/touilleMan/godot-python/raw/master/misc/godot_python.svg\n   :width: 200px\n   :align: right\n\nThe goal of this project is to provide Python language support as a scripting\nmodule for the `Godot \u003chttp://godotengine.org\u003e`_ game engine.\n\n\nQuickstart\n==========\n\nBy order of simplicity:\n\n- Directly download the project from within Godot with the asset library tab.\n- Download from the `asset library website \u003chttps://godotengine.org/asset-library/asset/179\u003e`_.\n- Finally you can also head to the project `release page \u003chttps://github.com/touilleMan/godot-python/releases\u003e`_ if you want to only download one specific platform build\n\n\n.. image:: https://github.com/touilleMan/godot-python/raw/master/misc/showcase.png\n   :align: center\n\n\nAPI\n===\n\nexample:\n\n.. code-block:: python\n\n\t# Explicit is better than implicit\n\tfrom godot import exposed, export, Vector2, Node2D, ResourceLoader\n\n\tWEAPON_RES = ResourceLoader.load(\"res://weapon.tscn\")\n\tSPEED = Vector2(10, 10)\n\n\t@exposed\n\tclass Player(Node2D):\n\t\t\"\"\"\n\t\tThis is the file's main class which will be made available to Godot. This\n\t\tclass must inherit from `godot.Node` or any of its children (e.g.\n\t\t`godot.KinematicBody`).\n\n\t\tBecause Godot scripts only accept file paths, you can't have two `exposed` classes in the same file.\n\t\t\"\"\"\n\t\t# Exposed class can define some attributes as export(\u003ctype\u003e) to achieve\n\t\t# similar goal than GDSscript's `export` keyword\n\t\tname = export(str)\n\n\t\t# Can export property as well\n\t\t@export(int)\n\t\t@property\n\t\tdef age(self):\n\t\t\treturn self._age\n\n\t\t@age.setter\n\t\tdef age(self, value):\n\t\t\tself._age = value\n\n\t\t# All methods are exposed to Godot\n\t\tdef talk(self, msg):\n\t\t\tprint(f\"I'm saying {msg}\")\n\n\t\tdef _ready(self):\n\t\t\t# Don't confuse `__init__` with Godot's `_ready`!\n\t\t\tself.weapon = WEAPON_RES.instance()\n\t\t\tself._age = 42\n\t\t\t# Of course you can access property \u0026 methods defined in the parent\n\t\t\tname = self.get_name()\n\t\t\tprint(f\"{name} position x={self.position.x}, y={self.position.y}\")\n\n\t\tdef _process(self, delta):\n\t\t\tself.position += SPEED * delta\n\n\t\t...\n\n\n\tclass Helper:\n\t\t\"\"\"\n\t\tOther classes are considered helpers and cannot be called from outside\n\t\tPython. However they can be imported from another python module.\n\t\t\"\"\"\n\t\t...\n\n\nBuilding\n========\n\nTo build the project from source, first checkout the repo or download the\nlatest tarball.\n\nGodot-Python requires Python \u003e= 3.7 and a C compiler.\n\n\nGodot GDNative header\n---------------------\n\n\nThe Godot GDNative headers are provided as git submodule:\n\n.. code-block:: bash\n\n\t$ git submodule init\n\t$ git submodule update\n\nAlternatively, you can get them `from github \u003chttps://github.com/GodotNativeTools/godot_headers\u003e`_.\n\n\nLinux\n-----\n\n\nOn a fresh Ubuntu install, you will need to install these:\n\n.. code-block:: bash\n\n\t$ apt install python3 python3-pip python3-venv build-essential\n\nOn top of that build the CPython interpreter requires development headers\nof it `extension modules \u003chttps://devguide.python.org/setup/#install-dependencies\u003e`_\n(for instance if you lack sqlite dev headers, your Godot-Python build won't\ncontain the sqlite3 python module)\n\nThe simplest way is to uncomment the main deb-src in `/etc/apt/sources.list`:\n\n.. code-block:: bash\n\n\tdeb-src http://archive.ubuntu.com/ubuntu/ artful main\n\nand instruct apt to install the needed packages:\n\n.. code-block:: bash\n\n\t$ apt update\n\t$ apt build-dep python3.6\n\nSee the `Python Developer's Guide \u003chttps://devguide.python.org/setup/#build-dependencies\u003e`_\nfor instructions on additional platforms.\n\n\nMacOS\n-----\n\nWith MacOS, you will need XCode installed and install the command line tools.\n\n.. code-block:: bash\n\n\t$ xcode-select --install\n\nIf you are using CPython as your backend, you will need these. To install with Homebrew:\n\n.. code-block:: bash\n\n\t$ brew install python3 openssl zlib\n\nYou will also need virtualenv for your python.\n\n\nWindows\n-------\n\n\nInstall VisualStudio and Python3, then submit a PR to improve this paragraph ;-)\n\n\nCreate the virtual env\n----------------------\n\nGodot-Python build system is heavily based on Python (mainly Scons, Cython and Jinja2).\nHence we have to create a Python virtual env to install all those dependencies\nwithout clashing with your global Python configuration.\n\n\n.. code-block:: bash\n\n\t$ cd \u003cgodot-python-dir\u003e\n\tgodot-python$ python3 -m venv venv\n\n\nNow you need to activate the virtual env, this is something you should do\nevery time you want to use the virtual env.\n\nFor Linux/MacOS:\n\n.. code-block:: bash\n\n\tgodot-python$ . ./venv/bin/activate\n\nFor Windows:\n\n.. code-block:: bash\n\n\tgodot-python$ ./venv/bin/activate.bat\n\n\nFinally we can install dependencies:\n\n.. code-block:: bash\n\n\tgodot-python(venv)$ pip install -r requirements.txt\n\n\nRunning the build\n-----------------\n\n\nFor Linux:\n\n.. code-block:: bash\n\n\tgodot-python(venv)$ scons platform=x11-64 release\n\nFor Windows:\n\n.. code-block:: bash\n\n\tgodot-python(venv)$ scons platform=windows-64 release\n\nFor MacOS:\n\n.. code-block:: bash\n\n\tgodot-python(venv)$ scons platform=osx-64 CC=clang release\n\nValid platforms are `x11-64`, `x11-32`, `windows-64`, `windows-32` and `osx-64`.\nCheck Travis or Appveyor links above to see the current status of your platform.\n\nThis command will checkout CPython repo, move to a pinned commit and build\nCPython from source.\n\nIt will then generate ``pythonscript/godot/bindings.pyx`` (Godot api bindings)\nfrom GDNative's ``api.json`` and compile it.\nThis part is long and really memory demanding so be patient ;-)\nWhen hacking godot-python you can heavily speedup this step by passing\n``sample=true`` to scons in order to build only a small subset of the bindings.\n\nEventually the rest of the source will be compiled and a zip build archive\nwill be available in the build directory.\n\n\nTesting your build\n------------------\n\n.. code-block:: bash\n\n\tgodot-python(venv)$ scons platform=\u003cplatform\u003e test\n\nThis will run pytests defined in `tests/bindings` inside the Godot environment.\nIf not present, will download a precompiled Godot binary (defined in SConstruct\nand platform specific SCSub files) to and set the correct library path for\nthe GDNative wrapper.\n\n\nRunning the example project\n---------------------------\n\n.. code-block:: bash\n\n\tgodot-python(venv)$ scons platform=\u003cplatform\u003e example\n\nThis will run the converted pong example in `examples/pong` inside the Godot\nenvironment. If not present, will download a precompiled Godot binary\n(defined in SConstruct) to and set the correct library path for the GDNative\nwrapper.\n\n\nUsing a local Godot version\n---------------------------\n\nIf you have a pre-existing version of godot, you can instruct the build script to\nuse that the static library and binary for building and tests.\n\n.. code-block:: bash\n\n\tgodot-python(venv)$ scons platform=x11-64 godot_binary=../godot/bin/godot.x11.opt.64\n\n\nAdditional build options\n------------------------\n\nYou check out all the build options `in this file \u003chttps://github.com/touilleMan/godot-python/blob/master/SConstruct#L23\u003e`_.\n\n\nFAQ\n===\n\n**How can I export my project?**\n\nCurrently, godot-python does not support automatic export, which means that the python environment is not copied to the release when using Godot's export menu. A release can be created manually:\n\nFirst, export the project in .zip format.\n\nSecond, extract the .zip in a directory. For sake of example let's say the directory is called :code:`godotpythonproject`.\n\nThird, copy the correct Python environment into this folder (if it hasn't been automatically included in the export). Inside your project folder, you will need to find :code:`/addons/pythonscript/x11-64`, replacing \"x11-64\" with the correct target system you are deploying to. Copy the entire folder for your system, placing it at the same relative position, e.g. :code:`godotpythonproject/addons/pythonscript/x11-64` if your unzipped directory was \"godotpythonproject\". Legally speaking you should also copy LICENSE.txt from the pythonscript folder. (The lazy option at this point is to simply copy the entire addons folder from your project to your unzipped directory.)\n\nFourth, place a godot release into the directory. The Godot export menu has probably downloaded an appropriate release already, or you can go to Editor -\u003e Manage Export Templates inside Godot to download fresh ones. These are stored in a location which depends on your operating system. For example, on Windows they may be found at :code:`%APPDATA%\\Godot\\templates\\ `; in Linux or OSX it is :code:`~/.godot/templates/`. Copy the file matching your export. (It may matter whether you selected \"Export With Debug\" when creating the .zip file; choose the debug or release version accordingly.)\n\nRunning the Godot release should now properly execute your release. However, if you were developing on a different Python environment (say, the one held in the osx-64 folder) than you include with the release (for example the windows-64 folder), and you make any alterations to that environment, such as installing Python packages, these will not carry over; take care to produce a suitable Python environment for the target platform.\n\nSee also `this issue \u003chttps://github.com/touilleMan/godot-python/issues/146\u003e`_.\n\n**How can I use Python packages in my project?**\n\nIn essence, godot-python installs a python interpreter inside your project which can then be distributed as part of the final game. Python packages you want to use need to be installed for that interpreter and of course included in the final release. This can be accomplished by using pip to install packages; however, pip is not provided, so it must be installed too.\n\nFirst, locate the correct python interpreter. This will be inside your project at :code:`addons\\pythonscript\\windows-64\\python.exe` for 64-bit Windows, :code:`addons/pythonscript/ox-64/bin/python3` for OSX, etc. Then install pip by running:\n\n.. code-block::\n\n\taddons\\pythonscript\\windows-64\\python.exe -m ensurepip\n\n(substituting the correct python for your system). Any other method of installing pip at this location is fine too, and this only needs to be done once. Afterward, any desired packages can be installed by running\n\n.. code-block::\n\n\taddons\\pythonscript\\windows-64\\python.exe -m pip install numpy\n\nagain, substituting the correct python executable, and replacing numpy with whatever packages you desire. The package can now be imported in your Python code as normal.\n\nNote that this will only install packages onto the target platform (here, windows-64), so when exporting the project to a different platform, care must be taken to provide all the necessary libraries.\n\n**How can I debug my project with PyCharm?**\n\nThis can be done using \"Attach to Local Process\", but first you have to change the Godot binary filename to include :code:`python`, for example :code:`Godot_v3.0.2-stable_win64.exe` to :code:`python_Godot_v3.0.2-stable_win64.exe`.\nFor more detailed guide and explanation see this `external blog post \u003chttps://medium.com/@prokopst/debugging-godot-python-with-pycharm-b5f9dd2cf769\u003e`_.\n\n**How can I autoload a python script without attaching it to a Node?**\n\nIn your :code:`project.godot` file, add the following section::\n\n  [autoload]\n  autoloadpy=\"*res://autoload.py\"\n\nIn addition to the usual::\n\n  [gdnative]\n  singletons=[ \"res://pythonscript.gdnlib\" ]\n\nYou can use any name for the python file and the class name\n:code:`autoloadpy`.\n\nThen :code:`autoload.py` can expose a Node::\n\n  from godot import exposed, export\n  from godot.bindings import *\n\n  @exposed\n  class autoload(Node):\n\n      def hi(self, to):\n          return 'Hello %s from Python !' % to\n\nwhich can then be called from your gdscript code as an attribute of\nthe :code:`autoloadpy` class (use the name defined in your :code:`project.godot`)::\n\n  print(autoloadpy.hi('root'))\n\n**How can I efficiently access PoolArrays?**\n\n:code:`PoolIntArray`, :code:`PoolFloatArray`, :code:`PoolVector3Array`\nand the other pool arrays can't be accessed directly because they must\nbe locked in memory first. Use the :code:`arr.raw_access()` context\nmanager to lock it::\n\n  arr = PoolIntArray() # create the array\n  arr.resize(10000)\n\n  with arr.raw_access() as ptr:\n      for i in range(10000):\n          ptr[i] = i # this is fast\n\n  # read access:\n  with arr.raw_access() as ptr:\n      for i in range(10000):\n          assert ptr[i] == i # so is this\n\nKeep in mind great performances comes with great responsabilities: there is no\nboundary check so you may end up with memory corruption if you don't take care ;-)\n\nSee the `godot-python issue \u003chttps://github.com/touilleMan/godot-python/issues/84\u003e`_.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftouilleman%2Fgodot-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftouilleman%2Fgodot-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftouilleman%2Fgodot-python/lists"}