PyHelper is a module created for UPBGE 0.2.5b that adds small new features to make a developer’s life easier when writing Python scripts.
Importing the module
The first thing you need to do is import the module, but you need to also call the “init” method from the module to properly initialize the module.
This is necessary because UPBGE/Blender keeps the module loaded in memory, which makes things a bit difficult to handle, so I had to create a function to reload the PyHelper submodules.
# import the module
import pyhelper
# call the initialization method
pyhelper.init()
Then you can use PyHelper normally without breaking your python components and ge (That’s what I hope.).
Module Features:
PyMouse
A new class that “extends” the SCA_PythonMouse class.
- New attribute “deltaPosition” that returns the mouse delta position as a vec2.
Example:
import pyhelper
pyhelper.init()
# the mouse is now stored in: "bge.logic.pymouse"
mouse = bge.logic.pymouse
print(mouse.deltaPosition) # a mathutils vec2: <Vector (0.0000, 0.0000)>
- New method “reCenter” that centers the mouse cursor in the window.
Example:
# whenever you want to center the cursor, just use this method
bge.logic.pymouse.reCenter()
- Access mouse buttons directly through the class
Yes, now you can access mouse buttons directly via the class, without having to call “mouse.inputs” and “bge.events”. Just call the class with the button name you want, and it will return the SCA_InputDevice, allowing you to access its attributes normally, like active or activated.
Example:
left_mouse_button = bge.logic.pymouse.LEFTMOUSE # SCA_InputDevice
# check if LMB is activated (pressed)
if left_mouse_button.activated:
print("LeftMouseButton was pressed!")
PyKeyboard
Just like PyMouse, PyKeyboard adds new members to your class, which are the keyboard keys, making them much easier to access without writing too much code.
Here’s a quick comparison between the standard way of accessing a key and the way the new PyKeyboard class allows it.
Standard method:
import bge
if bge.logic.keyboard.inputs[bge.events.WKEY].active:
print("W key is active!")
With PyKeyboard:
import pyhelper
pyhelper.init()
if bge.logic.pykeyboard.WKEY.active:
print("W key is active!")
This way, accessing keys becomes much simpler, with fewer lines of code.
Delta Time
Delta time is essential for any project and any game engine you use. It helps keep your game stable across different machines and frame rates (FPS). Since UPBGE doesn’t natively offer a method that returns delta time, here it is!
By importing the PyHelper module, a new method is added to the “bge.logic” module. This new method is called deltaTime and has an optional parameter called scaled. The scaled parameter accepts a boolean value and defaults to True.
The new method bge.logic.deltaTime() returns a float value representing the time passed between frames.
Here’s a simple example of using delta time:
import pyhelper
pyhelper.init()
def main(self):
ob = self.owner
# rotate the object at a constant speed
# regardless of frame rate...
ob.applyRotation((0,0,2.5 * bge.logic.deltaTime()),1)
Decorators
Some decorators to alter method behavior.
once_per_tick: Ensures the function executes only once per tick, even if called 300 times, it will run just once per tick.
set_frequency: Used to limit the method’s frequency, e.g., you can force a method to run at 60Hz by setting set_frequency to 60.0.
Utils
This is where general tools go; useful features that don’t belong to a specific category. Currently, it only contains a clamp and a lerp method. The clamp method limits a value within a specific range, useful to limit the camera’s X-axis to 90 degrees for example.
First Person Controller (FPC)
This is a very simple first-person control template that can easily be expanded into something more complex. I updated it to use the latest version of pyhelper, and it is available in the download section.
Preview:
