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
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 ;)
| In Progress | Finished | Left To Do |
|
|
|
| In Progress | Done | Left |
|
|
|
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.
