It has come up in the discussion forum that people find the API hard to read. I don’t, I find it rather easy, but maybe that’s just through practice.
I though I’d create this thread to show how to use the API.
All access to the API can be summarized as looking for a method or property of, well, something. You may want to know whether it’s obj.localPosition or obj.localLocation. Or you may want to know what said method or property returns. Either way, you have to find that thing in the API.
There are two ways to find the methods and properties relating to something.
First, here is the API
***Chaining:
This is just remembering how you got said object in the script. Let’s say we have the script:
import bge
cont = bge.logic.getCurrentController()
own = cont.owner
How can we find the methods/properties of “own”?. Well, to get there we used bge.logic, then getCurrentController, then owner.
So we can do:
And there we have a list of all the properties/methods of “own”
***Types
Each object has a type, and this allows us to find objects via a more direct route, as chaining doesn’t work in long scripts.
Let’s use the same code, but this time, we’ll add something:
own = cont.owner
print(type(own))
Now when we run the script, in the terminal, we get printed the text:
<KX_GameObject>
Now we know exactly what it’s called in the API. We’ve used the function type, so it makes sense to look in bge.types:
***Subclassing:
Now you may notice that it seems some are missing. The documentation for a controller gotten via bge.logic.getCurrentController (SCA_PythonController) doesn’t have sensors or actuators as properties, yet people definitely use them!
This is because the SCA_PythonController is a subclass of something. Notice how at the top it says:
“class bge.types.SCA_PythonController(SCA_IController)”
The last part in brackets contains more information. So if we find the SCA_IController, we will find the sensors and actuators. The reason for this heirachy is because the python controller shares a lot in common with other controllers, so it makes sense to put them together. So to find all the attributes of an object, we can:
Anything listed under all these pages is accessible through the thing you have.
Now, I’ve haven’t clicked on CValue. That’s because there’s generally nothing of interest below it, just the name and whether the thing you have is valid or not.
***You can get some help straight from python itself, by typing:
help(own)
It will hang the game engine, but in the console you can scroll through everything the object contains, without using the API. I’m not a big fan of this though.
***Some things are functions, some things are properties. As a rule of thumb, if the item in the API has brackets after it, then so should your code!
And that’s all there is to the API. No mystery in how things are laid out, no magic involved.
Have fun.