Reading the Blender API

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.

Attachments




Useful post, perhaps this should be stickied?

Yeah, I also agree to sticky…although I don’t know how to vote for that (or vote for 5 star, for that matter)
As a half–python-beginner, I find that the API is sort of hard, sort of not… It does not seem to user-friendly, but I got used to that while coding java and using oracle api

I think that the python API definitely could be updated to be more…clear or concise, instead of taking me to 2 or 3 other pages for me to find what I’m looking for (if I ever look for something ) maybe they should create a directory or something?

great post i didn´t know all that thanks.