py4godot

To build py4godot on Linux (tested on Ubuntu 20.04.4 LTS), follow these steps:

1. Set up a virtual environment (optional but recommended):

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

   Note: If using Python 3.12, you must run pip install setuptools and python copy_distutils.py first to resolve distutils dependencies.

2. Generate files:

   python generate.py

   Note: For faster development builds, use python generate.py -dev_build=True.

3. Cythonize files:

   python cythonize_files.py

   Note: For faster development builds, use python cythonize_files.py -mode="dev".

4. Compile the project:

   python build.py --target_platform=linux64 --compiler=gcc

   The compiled output will be located in build/py4godot.

To build py4godot on Windows, follow these steps:

1. Set up a virtual environment (optional but recommended):

   python -m venv virtual_python
   .\virtual_python\Scripts\activate
   pip install -r requirements.txt

2. Generate files:

   python generate.py

   Note: For faster development builds, use python generate.py -dev_build=True.

3. Cythonize files:

   python cythonize_files.py

   Note: For faster development builds, use python cythonize_files.py -mode="dev".

4. Compile the project:

   python build.py --target_platform=windows64 --compiler=msvc

   The compiled output will be located in build/py4godot.

To install py4godot in your Godot project, download the .zip file from the project's Releases page, extract the contents, and copy the resulting folder into the addons folder located at the root of your Godot project.

mkdir addons
cp -r py4godot addons/

Before using or building py4godot, ensure you have the following installed:

• Python: Version 3.11 or higher.
• pip: Must be installed alongside Python.

You can define a signal within a class by using the @signal decorator. This decorator inspects the function name and its arguments to register the signal with the underlying system. When using this decorator, you can optionally pass a list of SignalArg objects to specify argument names and types.

from py4godot.signals import signal, SignalArg

class MyClass:
    @signal(args=[SignalArg("value", int)])
    def my_signal(self, value):
        pass

Use get_singleton(name: str) to access Godot engine singletons or specific nodes in the scene tree.

The function follows this lookup priority:

1. Engine Singletons: It first checks if the provided name is a registered singleton within the Engine instance.
2. Scene Tree Nodes: If no engine singleton is found, it attempts to find a node with the matching name starting from the root of the scene tree (useful for custom singletons defined in Globals).

Returns the Object if found, or None if the name does not correspond to a singleton or a node.

from py4godot.singletons import get_singleton

# Example: Accessing the Input singleton
input_singleton = get_singleton("Input")

# Example: Accessing a custom node/singleton in the scene tree
my_node = get_singleton("MyGlobalNode")

if input_singleton:
    # Use the singleton
    pass

The gdproperty function is an experimental decorator/helper used to define properties that are bound to Godot. It allows you to specify a type, a default value, and an optional hint. It uses inspection to determine the variable name from the assignment context.

Note: This is marked as very experimental.

@gdproperty(int, 0)
def my_property(self):
    pass

# Or as a direct assignment (experimental behavior):
my_val = gdproperty(float, 1.0)

A GDSignal (which inherits from Signal) allows you to connect Python functions to a signal. The connect method automatically handles the conversion of the Python function into a Godot-compatible Callable object. You can also use disconnect to remove a connection using the same function reference.

# Assuming 'sig' is an instance of GDSignal
def _on_my_signal(value):
    print(f"Signal received: {value}")

sig.connect(_on_my_signal)
# ... later
sig.disconnect(_on_my_signal)

A BuiltinSignal represents a signal that already exists on a Godot object. It provides methods to interact with the signal's connection state on the parent object:

• connect(function, flags=0): Connects a Python function to the builtin signal.
• disconnect(function): Disconnects a Python function from the signal.
• is_connected(callable_obj): Checks if a specific callable is connected to the signal.
• get_connections(): Returns the list of current connections for this signal.
• get_object(): Returns the Godot object that owns this signal.
• get_object_id(): Returns the instance ID of the owner object.

# Assuming 'builtin_sig' is an instance of BuiltinSignal
def _on_event(event):
    pass

builtin_sig.connect(_on_event)

if builtin_sig.is_connected(Callable.new2(parent, "_on_event")):
    print("Connected!")

print(f"Owner ID: {builtin_sig.get_object_id()}")

The SignalArg class is used to provide metadata about a signal's arguments, specifically the name and the type. The type is automatically converted to a Godot variant type.

from py4godot.signals import SignalArg

arg = SignalArg("my_arg", int)
# arg.name is "my_arg"
# arg.variant_type is the Godot variant type for int