Incorrect Documentation for applyImpulse

Game Engine Game Engine Support and Discussion
1

According to the documentation:

applyImpulse(point, impulse)
Applies an impulse to the game object.
This will apply the specified impulse to the game object at the specified point. If point != position, applyImpulse will also change the object’s angular momentum. Otherwise, only linear momentum will change.
[TABLE=“class: docutils field-list”]
[TR=“class: field-odd field”]
[TH=“class: field-name, bgcolor: #EEDDEE, align: left”]Parameters:[/TH]
point (the point to apply the impulse to (in world coordinates)) – the point to apply the impulse to (in world coordinates)
[/TR]
[/TABLE]

Firstly, there are two parameters with only one listed.
Secondly, the point you apply the impulse to is in local co-ordinates.

Proof for for the second point:
Apply this script to a cube:

import bge

cont = bge.logic.getCurrentController()
own = cont.owner


own.applyImpulse([0,0,0] , [0,0,0.2])

According to the documentation, the impulse is being applied at the world centre. So if the cube is at [0,0,0] it will just go straight up. And if the cube is not at the world centre, it will spin.

But in practice, this script will never make the cube spin. It will only ever apply force straight up. Thus the position of the force is local rather than global.

On another tack:
It would be great to be able to apply a force at a desired location rather than an impulse. I’m busy trying to simulate basic aerodynamics and it is a pain having to divide everything by the number of frames per second.

2

Known issue: https://projects.blender.org/tracker/?func=detail&atid=127&aid=29419&group_id=9

3

If it’s been known since 2011, and there’s a patch attached, why hasn’t it been fixed. And even if you don’t want to fix it, then why not just update the documentation to match?

4

Personally, I think the code should match the documented behavior (that’s why I made the patch in the first place).

However, it seems that some people prefer the current behavior, and want to instead change the documentation to match … If that’s what they want, that’s what they should do, but I’m done even thinking about it at this point.

5

I do not know how many users created moon landers with this method ;). I used to use rigid body joints which did not even required Python.

But I was disappointed that it was so hard to create a billiard game because of the incorrect documentation.

How about two methods?
applyLocalImpulse(localPoint, localImpulse)
applyWorldImpulse(globalPoint, globalImpulse)

or an additional parameter:
applyImpulse(point, impulse, local=True)

I know this idea is missing the option to have both vectors in different coordinate systems.

6

Don’t mean to derail this thread but why aren’t the docs more Wiki-like, i.e. collaboratively editing/peer review/etc.?

7

Because they are meant to be consistent with the source code and not changed unless the code changes.
Wiki’s are more suited to slightly subjective topics, or at least ones that update regularly.

+1 for monsters suggestions. Probably the second one as it is similar to the applyForce and applyTorque. Makes sense that applyImpulse should be similar.

Next year I’m learning C as part of Uni. I may have to give myself a headstart and try prodding my way through the blender source…

8

Better start early and go for C++ too ;).