I can't make out the blender python API

Oh, bge py-api… guess I misread that too.

Can’t really say what state that’s in since I don’t ever use it myself.

I think most of if not all of that is pretty well covered, I remember in the beginning that part making sense to me, learning how to implement blender/python functionality is another. The API has everything in it already but its hard to make sense of. Doing a print(dir(bpy.types)) in Python Console in blender is hard to make out as well, at least for me. Its hard to discern what ties into what or how it is supposed to be used. I think I’m a good basis to judge how effective the docs are for non-programers. I’ve studied programming but lack natural ability, so If I could understand and make sense from the docs then I’d say you were good to go. Sense I can’t make sense of it right now I’d say the API probably scares a lot of people away. My blender experience started from first using ubuntu and saw it was a 3d modeler and game engine. It has been about 4 years I think, and I now I am a proficient user that can do most things but I still need reminding every now and then. The game engine has been the most difficult to learn, its a different animal all together yet very powerful, giving you the ability to use everything you’ve modeled, animated, and textured in blender render the only hold up is getting more functionality out of the logic bricks, which requires python scripts to access the bge module. I’m not sure if how much can be done though scripting that can’t be done via logic bricks, the general notion has been scripting provides more functionality. Why is this so? Can anything be done on the game engine side to get rid of the need? Of coarse I’m talking off topics for this thread, but what are the limits of blender development, Where does blender want to be in 4 years? What if anything is stopping blender from exceeding new heights. It is already loved by blender heads but why stop there? It is beyond me…I can contribute ideas and feedback but in the end is a talented programmer that would have to sit down and code any new functionality, and that can be a HUGE en devour.

Sorry to rant

as far as splitting the docs, again there pretty well separated but still the main problem for me is seeing the bigger picture I think having a control flow diagram and some example usage could go a long way. I hear that the API docs are automatically generated and so having to go back and hand key in examples for every single thing would be labor intensive but making at least the API more explicit could go a long way.

At the end of the day I’m just a rookie so I can offer no real technical advise like kilon can because he’s on another level but I hope I can contribute something to project by providing what I hope to be valuable feedback.

Thanks Ideasman

I’ve coded in over a dozen languages and learned more APIs than I care to recall, but I don’t understand the Blender Python interface. Maybe once it settles down (it’s far from finished), conventions are locked into place (they’re still shifting and settling into the couch) and documentation becomes more comprehensive, the other shoe will drop, so to speak.

But I see your point regarding the gap between developers and users. Without a dumb-it-down-for-management phase in development, I’m sure new ideas rarely have to be stated in plain language before being assigned to a developer. As a result, the user is trained rather than taken into account.

I’m also an artist and designer (yeah, trained and all, not just self-proclaimed) and there are parts of Blender I can assure you don’t use any artistic language I’ve ever encountered even though there may be one available for that part of Blender.

Even the age-old debate about which way is up leaves me wondering how anyone who knows math could ‘get it wrong,’ but there you go. Two of the biggest names in 3D these days did and there’s no telling them otherwise.

It all comes down to this: things are the way they are and the world doesn’t always make sense. Blender is no different. Of the seven billion or so people on this planet, there are seven billion ways to interpret the afterlife and how to work in 3D. The best we can hope for is enough overlap so we can have a decent conversation.

Replied to each of your points…

A few points. firstly - blender is just a really big application, dont try make sense of it all (not to begin with at least).
A lot of the reference API is just data access. But not everything, and some of the important areas get swamped by the shear number of datatypes.

I thaught the addon tutorial would help a bit here.

The thing is - we dont really have a “supposed to be used” – many of the parts that are commonly used together are more-or-less incadental.
For common use cases there is the ‘Templates’ menu in the text editor where I’ve tried to keep nice examples for new users,

I think you have to be careful assunubg your own experience is somehow an example of your-average-programmer.

Some programmer deciedes to do SOME_TASK in Blender.

  • Maybe they luck out a find great example first up maybe not…
  • Maybe blenders docs/templates have examples of what they need to do… maybe not.
  • Maybe what they want to do is a well supported use case by blender… but its possible that the functionality they need just isnt there (yet).
  • Maybe the area they first look into has a maintainer (for code/docs), or possible its not so well maintained.
  • Maybe they hit a bug in our code…

So! - a lot of this just depends on the kinds of problems you try to tackle, and weather blender supports you well.
… I hear totally different opinions from developers based on how they find blender performs for the first tasks they try to accomplish.

Sure, its hard to keep full API in your head, I also dont remember large areas and need to read up on them before using at times.

Logic bricks are C++ which gives them some areas that python doesnt have access too (physics, opengl, internal logic… etc).
So short andswer is no- there is not complete overlap in functionality here.
Ill add that BGE is also one of the less-well maintained areas of Blender - The Blender foundation isnt funding its development, its basically community maintained.

Blender only has 3-4 devs employed to work on it at the moment, fixing bugs and maintaining the software just takes time even without fancy-cool stuff, Of-course we have 100s of volunteer contributors who work on many interesting projects - so Im not worried as to blenders future, quite the opposite!

Blender 2.7 plans a re-written depsgraph and Im sure many other areas will be improved too. (Drawing API, android support, adding bullet integration, dyntopo… more modifiers)…
We have many people giving feedback, it IS appreciated- but main issue is that we need people who can realize these projects.

No nood to apologise! :slight_smile:

Im not sure what a flow diagram for blenders api would look like… (api hierarchy? - steps to execute some task?).
While docs are generated - hand written sections can be added to each page, or entirely hand written sections added - I dont think thats a problem if some new page needs adding.

If you can outline what docs you think are missing I could check on getting pages added.

Your welcome, I would like to attempt to resolve the issue you found,
however I think the answer may be as simple as

BGE docs are not well maintained...
So we need to improve docs for Vector/Matrix types in the BGE & include some more examples..

for eg.

In my experience, which is rather considerable with bpy but zero with bge, the api is absolutely amazing. Compared to the old 2.49 api, where things were named in an ad hoc way and lots of stuff was missing, the 2.5x api is really complete and regular. Apart from the big redefinition of 2.54 and the introduction of bmesh in 2.63, changes that break my scripts have been rare and easy to fix.

The one quirk that irritates me most is the treatment of vertex groups. Why are they located in the object rather than in the mesh, and why add a single-element list of vertnums? If you want performance, add could accept a list of (vertnum,weight) tuples that can be looped in C.

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

AddonPreferences right?

I really waited for this, as it becomes handy if you wanna export to a game’s model asset folder and need to provide a way to specify the path. Who wants to enter it on every export?

Sure, there are presets, but they require 2 extra clicks and not everyone knows about them.

But i dislike the way the prefs are stored: in the actual .blend file! So if i set up a path and received a .blend with its own addon path property, it would overwrite my own - which would be pretty stupid in case of a path which is specific to my computer.

There should be a way to prevent addons from overwriting existing preferences, preferably a property flag ‘DONT_OVERWRITE’… But i’d actually prefer to have preferences stored as separate file, as settings would be kept even if I disabled and re-enabled the addon.

first thank you for your detailed responses.

A few points. firstly - blender is just a really big application, dont try make sense of it all (not to begin with at least).
A lot of the reference API is just data access. But not everything, and some of the important areas get swamped by the shear number of datatypes.

so your saying there isn’t a one size fits all and there could be many different ways to use a given function

I think you have to be careful assunubg your own experience is somehow an example of your-average-programmer.

Sorry ideasman I meant that i was a good example of someone that doesn’t program at all might be intimidated and that if someone that doesn’t program could easily understand it, a programmer would easily be able to.

I thaught the addon tutorial would help a bit here.

theres a tutorial addon? I didn’t know that, will have to see what thats all about.

Logic bricks are C++ which gives them some areas that python doesnt have access too (physics, opengl, internal logic… etc).
So short andswer is no- there is not complete overlap in functionality here.

so are you saying the logic bricks actually have some functionality than a python script doesn’t.
I’m confused, I’m not sure if writing a python script is any different then using the logic bricks.

Im not sure what a flow diagram for blenders api would look like… (api hierarchy? - steps to execute some task?).
While docs are generated - hand written sections can be added to each page, or entirely hand written sections added - I dont think thats a problem if some new page needs adding.

yes a hierarchy if you will if that is even possible. if there are infinite possibilities that would be a problem tho. But adding some notes in the pages wouldn’t be a bad idea or even just creating a different layout could help too.

After going back over my notepad API I created from running print(dir(bge.logic)) , .constraints, .textures, . render and cross referencing the online API mainly the bge.constraints API I noticed that the documentation shows you everything that can be used after constraints dot and shows you the parameters it takes as well as the return type and what its returning. I think this is exactly the information a programmer would need.

So I’m thinking its not the API its me. The API itself seems to be just that, the API. Yes I am still not sure the context of how to implement each function but I think information like that could be created a part from the API itself. I think what it boils down to is I need to study more If I hope to write bge scripts.

I will still be talking notes as I progress it will take some time but maybe by the time I’m done it will still be relevant. Time to hit the books. :slight_smile:

This isnt really a Python API issue - its how blender stores the data, python just exposes it.
(index, weight) pairs are stored in the mesh, group-names in the object, This can be confusing for users too.

It could be changed to be all stored in the mesh.

Note that BMesh gives quite nice access to manipulating deform-verts from python.

Are you sure of this? - Recently added ‘AddonPreference’ are like regular preferences and wont load with regular files. I just checked with povray and loading files doesnt overwrite existing prefs.

http://www.blender.org/documentation/blender_python_api_2_65_3/bpy.types.AddonPreferences.html

Nope, I didnt mean that, infact we attempt not to have many different ways to do the same thing,
Blender is just a big/complex application - video-eding, sculpting, masking, compositing, open-shaging-language, python scripting, game engine scripting, mesh shape-keys, mask-shape keys, grease pencil frames, multiple node system types, 2 rendering engines…
len(dir(bpy.types)) –> 2834.

So I agree its nice to make things easier where possible, but blender just is complex, we cant hide that while maintaining access to all this.

You listed it as one of the pages you read through in your first post.
http://www.blender.org/documentation/blender_python_api_2_65_8/info_tutorial_addon.html

Short answer - it is different.
Logic bricks are fast but limited, python is slow but flexible. Take the collision logic-brick for example - you wouldnt want to write this in python.
in practice you normally use logic bricks and scripts - Python can change logic bricks but not add/remove them at runtime.

This info is too vague for for me to do anything about it - what notes are missing on which pages specifically?

Yes - api reference only gets you some of the way. sounds your after for some quality introductory tutorials for scripting in the BGE?

Definitely agree with you on this and it looks like we’re getting our wish (scroll down to Split User Preferences and Startup File)

.

You listed it as one of the pages you read through in your first post.
http://www.blender.org/documentation…ial_addon.html

oops I misread your original comment though it said tutorial addon not addon tutorial

After doing more reading and some bge python scripting tutorials I think I have found the main problem with the bge API

when you do a search for bge.logic.getCurrentController you are shown this

bge.logic.getCurrentController()
Gets the Python controller associated with this Python script.
[TABLE=“class: docutils field-list”]
[TR=“class: field-odd field”]
[TH=“class: field-name”]Return type:[/TH]
bge.types.SCA_PythonController
[/TR]
[/TABLE]

directly below it is

bge.logic.getCurrentScene()
Gets the current Scene.
[TABLE=“class: docutils field-list”]
[TR=“class: field-odd field”]
[TH=“class: field-name”]Return type:[/TH]
bge.types.KX_Scene
[/TR]
[/TABLE]
bge.logic.getCurrentController() can take these items after it… mainly owner and some other stuff I’m not sure yet what it does so if it had a __ i left it out.

activate
actuators
deactivate
executePriority
invalid
mode
name
owner *
script
sensors
state
useHighPriority

and after bge.logic.getCurrentController().owner one can put things like
bge.logic.getCurrentController().owner.localPosition.z = 10
bge.logic.getCurrentController().owner.applyRotation([0.0,0.0,1.0] , True)
bge.logic.getCurrentController().owner.applyForce([0.0,0.0,100.0], False)

The API for the bge should be written in such a way that when you search for bge it has a folder basicly
with Constraints, Logic, Render, Texture, and Types

Then when you Click into the Logic folder it should bring up all the items that fall under logic which at this point it does.
The problem though is it doesn’t go beyond the logic folder it stops there. You can’t click on getCurrentController() to see it has the above options, and sense you can’t do that your not able to say click on owner to be able to see all the options that owner has available to it which is the following

actuators
alignAxisToVect
angularVelocity
applyForce
applyImpulse
applyMovement
applyRotation
applyTorque
attrDict
children
childrenRecursive
color
controllers
disableRigidBody
enableRigidBody
endObject
get
getActionFrame
getAngularVelocity
getAxisVect
getDistanceTo
getLinearVelocity
getPhysicsId
getPropertyNames
getReactionForce
getVectTo
getVelocity
groupMembers
groupObject
invalid
isPlayingAction
life
linVelocityMax
linVelocityMin
linearVelocity
localAngularVelocity
localInertia
localLinearVelocity
localOrientation
localPosition
localScale
localTransform
mass
meshes
name
occlusion
orientation
parent
playAction
position
rayCast
rayCastTo
reinstancePhysicsMesh
removeParent
replaceMesh
restoreDynamics
scaling
scene
sendMessage
sensors
setActionFrame
setAngularVelocity
setCollisionMargin
setLinearVelocity
setOcclusion
setParent
setVisible
state
stopAction
suspendDynamics
timeOffset
visible
worldAngularVelocity
worldLinearVelocity
worldOrientation
worldPosition
worldScale
worldTransform

There is no association made with getCurrentController(). Each item should have a seperate page with just the things that would come after it in the workflow. Now I understand that getCurrentScene() and getCurrentController() can both use some things like “applyForce” and thats great but what would be the problem with having applyForce or anything eles show up multiple times in however many areas it would show up in?

I think by creating a folder within folders within folders type of structure…well you get the point. Hope this clarifies
things a bit more.

Blender BGE texture doc is pure garbage.

They just throw in a few words with no examples, at least some syntaxes, none of that.

Welcome to blender docs.

Image for loading images
Pixels for loading pixels.
and crap for loading lots of crap.

Have fun with our documentation.
No brief tutorials.

I’ll briefly paste some of their documentation.

getWeight (id )

Get image source weight.

image

Image data. (readonly)

refresh ()

Refresh image - invalidate its current content.

scale

Fast scale of image (near neighbour).

Type: bool

size

Image size. (readonly)

type or paste code here

Okay how do I use these ? in what contex, can you please show some form of putting this in a syntax.
You got to come here and beg like a homless man that begs for money on the street to get some answers, and most of the time there is no answer, google has limited answers on some of these, so basicly you cannot learn blender api the proper way because there is limited documentation on it.

How the heck do you use Image ? or Load

No answers ? do you do Image hocus pocus = Image Magic.
They just say image and then add read only, like that is suppose to help.

Some say it’s for programmers in mind, I must ask where is the newb documentation.
Any sane programmer will need some refrence points like a valid sintax formula.
I worked as HTML PHP web master and I must say I don’t understand Blender Api.

Image read only, what the heck is this, a UFO.
For Html and PHP there a manual with clear examples, not for blender API tho.

It’s clear that it’s hard to learn the API python for blender because there is no real documention for it, just ask here and maybe get an answer or not

there’s plenty of documentation, and lots of people have made tutorials- maybe not for BGE since it’s discontinued, I have no idea about that- maybe try the BGE support forum, there will be more like-minded people there.

It’s not discontinued, upbge are the same people from blender, a branch of them.
It’s why everything is out of date, because the lack of documentation from them.
Examples are years old, you reply to posts that are from 2,3,4 years old.

Information regarding blender game class is without examples, it does not provide syntax use often, and there are no examples on the forums because everything is limited and outdated.

Let me save you some time- you don’t need to try and convince me, I don’t actually care one way or the other. I’m trying to redirect you to a place where people actually use BGE and you might not need to necro 8 year old threads.

Thanks testure, I will look at BGE support forum. All good, and good day to you.