Dev:Source/GameEngine/2.49/Python API Clean Up

Introduction

ben2610, cyborg_ar and Moguri are working on cleaning up the BGE Python API, the following are some changes they are working on.

Goals

• Create properties to replace most of the get/set functions.
• Expose more logic brick properties to Python.
• Improve the quality and readability of the code.
• Clean up remaining Python functions.

Use properties instead of get/set functions for the bricks' settings

Take for example, the setDLoc() method of the motion actuator. All this does is change a property of the logic brick, so instead it should simply be a property, dLoc.

Now, to copy a setting from one actuator to another, instead of:

  motion.setDLoc(motion2.getDLoc()[:2],motion2.getDLoc()[3])

you simply have to use:

  motion.dLoc = motion2.dLoc

This is much cleaner and easier to understand.

Functions that represent actions for example "instantAddObject()" will be left as such. Some functions for getting read-only data (like getEventList()) will probably be left too.

Expose more logic brick properties to Python

There are a lot of properties that were never exposed. For example, ISensor now has usePosPulseMode, useNegPulseMode, frequency, level, and invert.

Improve the quality and readability of the code

Currently the code is unorganized and can be hard to sift through. Almost every file uses its own rules for organization (or none at all). We are working on making sure each file uses a similar format, and adding comments to make things easier to find.

We are also working to change stuff like this (yes, that's real code), to more proper code like this.

Clean up remaining Python functions

Not all functions will be replaced by properties. We will look at the remaining ones to make sure they are written well, such as using PyList when needed.

Progress

Here are a couple of tables showing our progress so far. Right now it only lists sensors and actuators found in source\gameengine\GameLogic and Ketsji. KX_GameObject is also being cleaned up, but it isn't in one of the tables since it isn't a sensor or actuator.

Finished also means the brick's PyDoc has been updated.

Note: Ben implemented a new property framework for us to use. This makes updating the API a lot easier. However, we have to go through and re-update the ones we've done ;)

Progress so Far (Sensors)

In Progress	Finished	Left To Do
Near Radar Delay Actuator ISensor ILogic_Brick Mouse	Always Keyboard Joystick Collision/Touch	Property Random

Progress so Far (Actuators)

In Progress	Done	Left
None	Action	2D Filter Scene Property Random

Backwards Compatibility

What about my old code?

Code written for 2.48 should still be usable. We are keeping the old functions around for few a little bit (see Timeline), but they will be marked as deprecated. Using these functions will output a warning in the console. To disable the warnings, choose Game > Ignore Deprecation Warnings.

Blender 2.49 ships with a utility that updates old scripts to use the new API: in the text editor, choose Text > Text plugins > Convert BGE 2.49. The utility can introduce errors in some circumstances, so be sure to keep a backup and carefully review the changes that are made.

Timeline

2.49

By 2.49 we hope to have the properties ready to go and include the deprecated methods. 2.49 will also include the cleaned up methods. Since 2.49 will support previous code, and code that will work in 2.50, 2.49 will act as a transition between 2.48 and 2.50.

2.50

For 2.50 we plan to remove all the deprecated functions. This will break old scripts that have not been adapted to the new API. Scripts that run in 2.49 without deprecation warnings will be able to run fine in 2.50.