I can't make out the blender python API

Coding Python Support
1

I’m really confused with the API at this point. I have read though

and it even says in there

Being an API reference, this link often gives little more information then the tool-tip, though some of the pages include examples (normally at the top of the page).

My problem is for example

bge.logic.getCurrentController().owner.worldPosition.x +=1

I can see this code moves the object in the x direction by 1 blender unit.
However if I go on the blender API reference and search for worldPosition it will show

then when I click on the first one it takes me to

worldPosition
The object’s world position. [x, y, z]

[TABLE=“class: docutils field-list”]
[TR=“class: field-odd field”]
[TH=“class: field-name”]Type :[/TH]
mathutils.Vector
[/TR]
[/TABLE]

If it were not for

bge.types.SCA_PythonController

cont = bge.logic.getCurrentController()

bge.types.KX_GameObject

obj = cont.owner obj.worldPosition.z += 1

I would have never have known that the above is the correct way to call the function.
The world position API only says

worldPosition
The object’s world position. [x, y, z]

[TABLE=“class: docutils field-list”]
[TR=“class: field-odd field”]
[TH=“class: field-name”]Type :[/TH]
mathutils.Vector
[/TR]
[/TABLE]

which would make me think you would enter it in as ~foo.bar.worldPosition[1,1,1] or somthing.

Does the API assume I know how a given function is supposed to be used? So I guess my question is really
what am I doing wrong here? Am not interpreting the information in the API correctly and if so,
Where can I get information that can show me how worldScale for example is supposed to be used or
how I can get that infromation by understanding the API better.

Like I said I’m just confused at this point and don’t know where else to turn so I’m hoping someone
is able to provide a sound explanation for me so I can move forward. Thanks for reading. Peace

2

If you read this, you should know why there’s only bpy.types.* in the docs, but you actually access objects in a different way.

http://www.blender.org/documentation/blender_python_api_2_65_5/info_api_reference.html

http://www.blender.org/documentation/blender_python_api_2_65_5/bge.logic.html
http://www.blender.org/documentation/blender_python_api_2_65_5/bge.types.html

3

Part of the problem with Blender’s API is that it was designed with programmers in mind. Average user’s will find it far too complicated to comprehend. Sometimes, I just wish that the developers could comprehend this simple fact. Python, though touted as easy to use is in reality not designed for common use by 95% of casual Blender user’s.

4

There is not much you can do with documentation like that. You are not reading it incorrectly, the docs just don’t exist.

Your best bet is to follow some game tutorials and see how other people are using the methods. Once you get a feel for the conventions that the library is using then the reference becomes slightly more helpful.

5

You do realize that python is a programming language and therefore inherently “designed with programmers in mind”, right? There’s not much that can be done to change that…

The trick to the py-api is to understand that you’re operating on the .blend database (bpy.data – which I believe is ‘Main’ in bpy.types) and all the methods/properties are setup around this model.

Well, I guess other than ‘context’ (which is based on the window manager state) but that’s really just a wrapper around the underlining bpy.data objects.

6

I thought that might be the case, then it is my mission to put together this documentation I will start scavenging the internet in search of proper uses of each method and piece them together. I have already started this on my computer I have bge Constraints, logic, Render, Texture and types now I just need note what each one does and if and how there connected or interconnected and the proper usage, really I was only interested in the bge modules for game dev because logic bricks quickly become cluttered but given the circumstances I think i will do the bpy modules as well, this however will take some time.

7

I think what BNG means is that the API itself is a coded language and only understandable by coders, not that python itself is made for programmers.

I get model so to speak, of how the modules are accessed for instances bge.module.module or bpy.module.module I just don’t know what I can do with the module itself after i’ve accessed it.

8

Agreed, I’ve been using python itself for awhile been a hobbyist programmer for some years now and I still don’t get it. I’m not that great of a programmer mind you, at least when it comes to memorizing names of functions to access or what have you, but I don’t have a solid understanding of the key concepts. Regardless there seems to be a lack of basic information for blender api for a beginner to make use of. If you look up other python modules they normally show the proper usage for example “lists”
listOfWords = [“this”,“is”,“a”,“list”,“of”,“words”]

this shows you how to make a list, and what it is supposed to look like.

another example

>>> def functionname(arg1,arg2): … return arg1+arg2 … >>> t = functionname(24,24) # Result: 48

show’s you how a function is supposed to be setup

def myfun(a,b,c):
return a * b - c
myfun(2,4,6)

so Idk guess I’ll have to figure it out.

Thank you everybody for your responses

9

Scientists have discovered an alien race called “coders” , they come from the planet “Programora” , they are super smart , wear huge glasses and speak in a language nobody understands but them.

As you can imagine there is nothing more further from the truth.

And to make matters worse there is also this “You do realize that python is a programming language and therefore inherently “designed with programmers in mind”” from Uncle Entity. Is python a programming language ? YES .Ιs it made with programmers in mind , ABSOLUTELY NOT ! Its easy to prove that by the way , just open any kind of python console and type “import this”. The “this” module print the very fundamental principle python is based on. Notice that nowhere does it speak about programmer needs , or advanced programming concepts. To the contrary , its speak about 3 things

a) Simplicity
b) Simplicity
c) and you guessed it … Simplicity

The exact things any begineer coder begs for. It turns out its the same things a super experience coder begs for too.
Is it ironic, how stereotypes collapse on themselves. But then hardly suprising.

And make no mistake this module is no joke, not only those principles described in there are extremely important for python itself as a programming language but there are so essential that any python library is judged from these principles as “pythonic” or “non pythonic” library. As you can imagine very few libraries want to fall under the second category.

We are all here admirers of blender , we find awesome the things it can do, we find awesome that offers all these things for free and we find even more awesome the fact that is open source and anyone is allowed to contribute. The fact that python is used as the scripting language of blender makes it even more awesome. The fact that API give you so much access to the blender internals giving birth to a huge array of usefull and much needed addons cannot be praised enough.

But as we are entitled to find something awesome and declare it out loud , we are entitled to find somethig sucky. And it sucks that the Blender API is not pythonic. Its something that makes unhappy not only people like you that have just started coding in python, but even people like me that code in python for years and in other languages for more than a decade.

Also going back to my aliens remark. There are a lot of stereotypes about coders, but let me tell you something loud and clear, its all BS. Coders are normal human beings, there is nothing special or exceptional about them. They just love to code. Thats pretty much it. If coding looks complex is because it is, if coding looks ugly is because it is, if coding looks annoying is because it is. But all that is just plain bad coding. Because languages like python which were designed by the way for users and not coders or coders that wanted to feell like users show beyond any reasonable doubt that when you apply complex solutions you are doomed to fail on so many diffirent levels. And because failure is the only guarantee in this world, failing as less as possible should be the goal.

As a matter of fact if you search around the places coders lurk the principle that comes up in most case in known as KISS. Keep It Simple Stupid.
As you may imagine is the most fundamental coding principle for me too.

So to sum up, API is great in the amount of power it gives, its sucks at code level because its complex to use. The API needs a redesign ASAP to even be called a “pythonic” library, and its unlikely that to happen if more people do not join in extending and redisigning the API. Its also NOT easy to do so, having a huge set of features and offering a simple architecture is two elements that are in constant battle with each other. But still its a crusial improvement.

As a closing comment let me give one and only advice as experienced coder

“Never , absolutely NEVER !!! understimate the power of a noob”

Hang in there, and remember each time you are frustrated with something its more likely that you have every right to be frustrated at it than it is your own fault. In then end, its all about learning and never giving up. There is nothing more about it.

if you dont feel so comfortable with python I have made a book to help people even with no prior experience in coding to grasp what python basics is all about . I call it “python book of magic” and it can be found here -> http://wiki.blender.org/index.php/User:Kilon/Python_book_of_magic

1 Like
10

well put, kilon!

a redesigned BGE api would be great, as all the other blender scripting changed drastically after 2.4x. But it’s not just about renaming functions, all the available features need a regrouping to make bge api more intuitive. And there are certainly functions missing which need to get implemented. The most important task, however, will always be the documentation of all the great stuff. And I believe this is actually up to the community, not the devs.

Two more things that need a change IMO to make BGE more attractive:

  • state-of-the-art gfx with high performance
  • bundled templates, like a generic script for racing games plus a car model and setup (armature, constraints, etc.)

A BGE webplayer utilizing CSS3 / WebGL would be hilarious of course, but especially WebAudio doesn’t work that well yet (Chrome Canary got a whole bunch of features, but with my built-in sound chip i get a lot of audio glitches and WebGL performance seems quite poor)

11

I’m not really understanding the direction this thread is taking.

If the api gets improved people complain it breaks their scripts.

If the api doesn’t get improved people complain it isn’t pythonic enough.

…yet nobody will spend the time and effort to work on it except Campbell (though occasionally myself and others do poke at it a bit here and there).

12

lets be sincere

First APi brakes scripts in each release anyway.

Second even if you do a major breakage to do a major redesign , people will hapily welcome it. Not Convinced ? Well remember 2.5

Third , blender developers are not that “open” to new ideas. I proposed a multi label idea. Its basically a label on steroids that allows you to display multiple lines of text and even allow to wrap the text. I was ignored largely, and Ton himself told me that he was not interested in using blender " to read emails". I said to myself “fair enough , I find it this useful anyway , lets do this !” I went to make my own python hack of multi label which I used to display small documentation on the blender gui. And I am not the only one to go through this experience.

Forth I have already lost loads of time developing for blender to realise as much awesome it is at user level, at developer level its a mess and it will require a hell of redesign or improvement to clean it up. And frankly I dont have the time or the motivation to fight such code.

Fifth and last if you really want to hack blender, then C is the only way. And I hate C , for the troubles it can causes. Add to that that blender source has close to zero documentation and close to zero comments. So I will just pass the great opportunity to really frustrate myself on my free time. Afterall if I find the python side messy, I dont even dare to think how bad the C side of Blender is.

Its easy to blame those who complain that do not help. But you have to remember all of us here are blender developers and we have created tools that help the community. So its not difficult to do the math and see that something wrong going with blender.

My latest project actually was a complete redesign to the blender GUI , with offering more simplicity and yet more flexibility. Used bgl , proved buggy and slow. I lost a year trying other technologies finally only these past week settled with hmtl5/js . I hate both html and js but you know what they are so well documented and so efficiently designed that get thing I want to do way faster , more reliable and with may third party libraries than I would ever dreamed inside blender. And yet I am still interested in bringing my project closer to blender maybe via websockets.

So in the end its definetly not that we dont care and we only care about complaining. Our code is uploaded, our contribution to the community well documented. We have earned our right to complain as much we want. And I am not talking just about myself.

13

Well my hope is to start making good documentation for the API though examples, where the devs take blenders code from here is beyond me. I’m just trying to figure out how to make fun games through python scripts simply through tinkering with the code trying to figure out what does what.
There are features in blender that I haven’t even touched yet I just discovered what a 2d camera filter does and I still can figure how anyone can model a 3d head from a front view and a side view tho, so I am always learning something new. Working alone however slows progress down simply because there is so much to learn and do to create a rich game with all the bells and whistles. Without python scripts however this endeavor has been fruitless witch is why I’ve focused my efforts there, which is why I created this thread. Sure there’s the logic bricks but that gets messy tho I do appreciate it being there. And of course there are the bge python tutorials but the only problem I’ve found with most of those is the focus being on what there trying to do like rotate a cube or what have you, instead of it being on the key concepts and API usage.

No worries tho I have an idea for a thread to solve this problem please tell me if you all agree
Simply put create a thread asking people to contribute one liners that show the usage of a given method like “world position”
and the different parameters that function can take worldPosition.x worldPosition.y etc. then I can compile them into one text doc and re-post all the information on one page. This way anyone can contribute.

I am open to suggestions tho so by all means contribute if you agree on needing to make documentation and have a better idea of how to do so. Thanks guys

14

I dont think you will find anyone telling you that more documentation is not welcomed with opened arms.

A few things about the API. The API documentation is generated automagically from python doc strings via Sphinx library. Thats means that the documentation is stored with the API source code and this is why you cannot edit it online and it is not part of the Blender wiki. So the only way to update the API is either , a) ping the man behind blender python and many other blender areas , ideasman and request some text to be added to the doc strings, providing that text b) ask for commit access to blender source and edit those doc strings manually yourself.

Of course you can do example tutorials as well if you want to.

Howevere before doing anything documentation orientated first make sure that you know blender well enought so you dont give bad advice.

About creating a thread for each advice. Sincerely , not necessary. Already if you do a google search on the site (dont use the search function of the forums its not good enough in many cases) you probably find already answers to most of your questions. Its easy to mistakenly believe that blender has not enough documentation , but the problem is that once again , things are messy and documentation is scattered all over the place.

My advice to anyone is to frequent this website as much as possible it contains millions of useful info and use google search passing the website adress as a parameter to his searches. Google then focus the search only on this website , saving you trouble of going to another website with partial or bad info.

Threads are the worst way to document software. A much better approach is to use stackoverflow website where each answer is rated and can even be edited and improved by senior member of the community . The best ansers earn you reputation that raises you to the status of senior member. Also best answers , are the ones that rise to the top and you dont have to browser pages upon pages to find the best answer as it happens in forums and threads.

Stackoverflow is easily the best place to get answers on anything and there are also a lot of diffirent subcommunities , on gaming , 3d graphics, web development and much more.

Each question also gets tags to make it even easier to search or browse questions and answers with only the tags that interest you.

If i had one request for this website , it to move the forums to a stackoverflow format. I think that they would massively benefit the community at large.

15

interesting, I’ll check out stack overflow. I think I might do like “Monster” did and make a useful links page somewhere, It makes life easier when you can get all the information you need pertaining to what your looking for right in one spot.

16

thats a very good idea too

In that case its better to use blender wiki. Its easy to edit. I have improved blender wiki in several occasions and used it for releasing my book.

I edited this pages for example to add my book and code snippets book and several other info -> http://wiki.blender.org/index.php/Dev:2.5/Py/Scripts

17

Hi kilon!

The API certainly is a pretty complicated issue. With regard to needing a full rewrite of the API to make it more Pythonic, are you referring to bpy, bge or both? If it’s for bpy could you give a couple of small examples? Not sure if I’ll be able to help, but maybe I can.

Cheers,
Truman

18

Hi @andthewicked, I wrote/maintain most of the docs linked in the initial post and am left wondering what I should do to avoid new-dev-confusion.

Possibly There could be a Blender/Python/API doc called…


The Big Picture
===============

For new scripters who are not sure what to make of blender python.

- Blender embeds standard Python environment.

- Python is a scripting language, this means you can
  write Python inside blenders text editor and run it,
  without downloading special developer tools.
  
- Blender uses python for most of the interface button layout and some tools too.

- Regular python scripts can also run inside blender.

- Blender exposes its self to Python through 'modules' that can be imported.
  These modules work like any other python module,
  they just happen to contain Blender data & functions.

- Blender a number of modules, most of them can be used together however there are some exceptions,
  Blenders GameEngine his its own Python module -
  'bge' which can only be imported and used while the game engine is running.
  ... for everything else there is the 'bpy' module which is used while
	  blender runs and can be used to automate user operations.

- Python standard modules like 'os', 'sys', 'time' and 'math'
  expose basic functionality and are considered part of Python, they can be used in any Blender script.
19

After re-reading the initial post, we could have the BGE docs split out into their own page (with own search)- the BGE is really a separate API and confusing to mix in with ‘bpy’.

20

Its funny because you just exposed just the very first big confusion in Blender python. Bge vs Bpy. I dont think they should be seperate , I dont think it makes sense to have game engine seperate from blender itself. Because the game engine itself could work very well together with bpy.

Another things I am totally against is that whole idea of blender defining its own type system, I find it unecesseray , clumsy and certainly not pythonic. Python type system is great and works very nicely in practice, blender should fully support it and based on it.

I dont like context , the idea that an operator runs depending on where the mouse is focused on is another area that makes little sense to me. Context is usually a source of big confusion and not necessary to blender.

I dont like registration and unregister. It introduces one further step and one more worry to the coder again with no obvious benefits.

I also vaguely remember that I dont like how bmesh is used and called from inside blender python. Again if I remember correctly, it seems to be seperate from traditional mesh , they should be one entity.

I dont like how limited blender is in saving custom data, scene props and objc props are unsafe way to store your data. Again this goes back to me dont liking Blender properties and types in general.

I dont like the latest change where you can create or load custom props on script load. Again makes our lives more difficult.

I dont ike the fact that some props are read only and some are not, again this amounts in wasted time with looking back and forth between your code and the api reference and coding becomes something like performing acrobatic on a mine field.

I think its also the time to find how to resume , or reload scripts safely after an error without the fear of crashing blender. Restarting blender is annoying and slow.

And I dont like many other small things.

I dont think however a whole rewrite would make any sense, I think overall blender python apis are in a very good state and should left unchanged.

Personally I am totally against the philosophy of braking the api in every single version or any other version. So I dont intend to give a helping hand.

However I do intend as part of my project Ephestos to create a wrapper around the api. A wrapper that would be more simple and much less likey to change. The wrapper will handle any API change , making sure addons made with the wrapper will continue to function even years or maybe even decades afterwards in latest blender versions. Ephestos will run as web app inside the browser and will be able to control blender locally , or even remotely from internet or wifi using a tablet .But those things as you imagine take a lot of time and effort and I dont have anything concrete to show at the moment.

My main focuse is Bpy first, maybe BGE later on.