SCRIPTS IN BLENDER

Author : N.tox
Version : 0.02
Summary

Summary:
1 Scripts types

1.1 Classic scripts

1.2 PyDrivers
1.3 PyConstraints
1.4 Linked scripts
1.5 Common Blender scipts

2 The ‘little bit complicated’ scripts how to

2.1 PyConstraints
2.2 Linked scripts

2
Summary

1 Scripts types :
1.1 Classic Script :
The classic scripts are scripts written as regular self executeted python
scripts. To execute them, you must open a text window inBlender, and
open the script (as you would do with a text file), then you can execute
them by a Right Click and ‘Execute Script’ or by pressing Alt+P.

1.2 pydrivers :
Pydrivers are scripts which define functions and variables, they are used as
a module in python drivers expression command line. The functions defi-
ned in those scripts must be real functions, not routines, ie that the defined
functions must return values -integer or float, or at least those which will be
called from expression-, not only execute instructions. they must be named
pydrivers.py, and there only can be one pydrivers.py opened in a .blend
file.

Usage example :

we have defined a pydrivers.py with the function ‘dummyFunc’, which

does not take any parameter, and a variable DUMMY_VAR, which is
integer type. As a python expression we’re gonna use the following ex-
pression (without quotes):
«p.dummyFunc()+p.DUMMY_VAR»

1.3 pyConstraints :
PyConstraints are scripts used as constraint for script constraints :-p. They
can be really usefull because they are executed each frame and are better
managed than pyDrivers, except in version 2.4.5 where they didn’t exist yet
and where pydrivers are really better managed, this remark is avaible for
now (actual version 2.4.7), but maybe not in the future.

They need to be load in the text window buffer, ie in the text window (even
if not the displayed one). They don’t need a specific name but, they need to
have as first line, the following one :

#BPYCONSTRAINT

We will study them later.

3
Summary

1.4 linked scripts :

Linked scripts are scripts which are aded to a scene object by their method
addScriptLink(text,event), scripts must be opened in Text Window buffer,
please see the Python Blender API docs (module Scene.Scene) for more
details.

1.5 common blender scripts :

They are those scripts you can find sparsed a bit evrywhere in Blender, or
regrouped in the Script Window. Once launched they are red as normal
scripts, which mean that if you only define functions and never call them
in the script, it will do nothing. They can be named as you wish, but must
obey to this template :

#!BPY
‘‘‘
Name: ‘Script Name Displayed in Blender’
Blender: 247
Group: ‘The parent group (category) of this script, like Wizards for exam-
ple case is still important’
Tooltip: ‘the short description displayed when mouse cursor will be over
the script name displayed’
‘‘‘
__author__ = ‘Your name ;p’
__url__ = (‘Your site‘)
__version__ = ‘Version of your script’
__bpydoc__ = ‘‘‘\
The «how to» of your script...
‘‘‘
#From her you can write your script like you usually do

4
Summary

2 The ‘litle bit complicated’ scripts how to

2.1 The pyconstraints
As we’ve seen earlier, pyconstraints must have as first line «#BPYCONS-
TRAINT» (without quotes) to be considered as script constraint by Blender.
But it is not enough, we are going to study the internal working of those
special scripts...

We know that at each frame the script will be executed, but it is not really
true, I mean that in fact, precise expected functions (with expected name
so) are called, with always the same number (and types) of parameters. if
those functions are not present (or at least, the essentials one) the script
will not be considered as valid and nothing will happend.

Actually, I compared two simple pyconstraints and executed an «identifica-

tion script» which was in fact, a basic pyconstraint which printed the types
and content of used parameters to deduce the internal working. So please,
be warned that all I can say about this type of script are only my assump-
tions and consequently may not be accurate, or even true.

doConstraint(obmatrix, target_matrices, idprop)

doConstraint is the main function, ie the function which return the matrix
which will be applied to the constraint’s owner object. Only a 4x4 matrix
object (see Blender.Mathutils.Matrix docs) can be returned.

obmatrix :

obmatrix is the matrix of the constraint’s owner object (or sub-object in

case of a bone)

target_matrices :

target_matrices is a list of target’s matrices.

idprop :

idprop is a Blender IDPorperty type object, this parameter contain ge-

nerally (it depends of you) the user parameters value which was defi-
ned in the option menu of the constraint. it is accessed like a classic
dictionary and is defined in the getSetting routine (see further), but you
can change its values whenever you want in the script.

5
Summary

doTarget(target_object, subtarget_bone, target_matrix, id_properties_

of_constraint)

doTarget is the function Blender will automatically call do get desired

data of target(s) (matrices). In scripts I’ve seen, they always return tar-
get_matrix, and I don’t think it can return anything else, like doConstraint
only takes three parameters, and one of them is a list of all collected
target_matrix. I’m sure you understood that the returnde value of this
function is next added to the target_matrices list

target_object :

target_object is the same result of the expression : «Blender.Ob-

ject.Get(‘NameOfTarget’)». So, its value is an Object object
(Blender.Object.Object in python Blender API docs).

subtarget_bone :

subtarget_bone is the same result of the expression : «Blender.

Object.Get(‘NameOfArmatureTargetObject’).getPose().
bones[‘NameOfTargetBone’]». So if the target is a bone, its value
is a PoseBone object (Blender.Object.Pose.PoseBone in Pyhon Blen-
der API docs) , else I guess its value is None.

target_matrix :

well, target_matrix is the matrix of the target.

(Blender.Mathutils.Matrix in python Blender API docs)

id_properties_of_constraint :

Another Blender IDProperty object, but I think we don’t really care

about this one.

getSettings(idprop):

getSettings is the routine (ie do not return anything) which will be called
when the user click on the option button. this is here where we define
keys and values of idprop which is at the beginning a virgin dictionnary
(well, actually a blender IDPoperty object...). we define here too the UI
which will be displayed once this routine called. The two scripts I’ve seen
draw a PupBlock. I won’t explain you how to do, for it, see the Bpython
API docs ... I prefer show you an extract of one of the two script ana-
lysed (Constraint_Noise-1.0.py):

6
Summary

def getSettings(idprop):
# Define user-settable parameters.
# Must also be defined in getSettings().
if not idprop.has_key(‘u_loc’): idprop[‘u_loc’] = 1
if not idprop.has_key(‘u_rot’): idprop[‘u_rot’] = 0
if not idprop.has_key(‘u_scale’): idprop[‘u_scale’] = 0
if not idprop.has_key(‘u_locamount’): idprop[‘u_loca-
mount’] = 1.0
if not idprop.has_key(‘u_rotamount’): idprop[‘u_rota-
mount’] = 30.0
if not idprop.has_key(‘u_scaleamount’): idprop[‘u_sca-
leamount’] = 1.0
if not idprop.has_key(‘u_speed’): idprop[‘u_speed’] =
1.0

# create temporary vars for interface

uloc = Draw.Create(idprop[‘u_loc’])
ulocamount = Draw.Create(idprop[‘u_locamount’])
urot = Draw.Create(idprop[‘u_rot’])
urotamount = Draw.Create(idprop[‘u_rotamount’])
uscale = Draw.Create(idprop[‘u_scale’])
uscaleamount = Draw.Create(idprop[‘u_scaleamount’])
uspeed = Draw.Create(idprop[‘u_speed’])

# define and draw pupblock

block = []
block.append((‘Speed’, uspeed, 0.0000001, 1000.0, ‘The
speed of animation’))
block.append(‘‘)
block.append((‘Location’, uloc, ‘Randomly modify the ob-
ject’s location’))
block.append((‘Amount’, ulocamount, 0.0000001, 1000.0,
‘The amount of location randomness’))
block.append(‘ ‘)
block.append((‘Rotation’, urot, ‘Randomly modify the ob-
ject’s rotation’))
block.append((‘Amount’, urotamount, 0.0000001, 1000.0,
‘The amount of rotation randomness’))
block.append(‘ ‘)
block.append((‘Scale’, uscale, ‘Randomly modify the ob-
ject’s scale’))
block.append((‘Amount’, uscaleamount, 0.0000001, 1000.0,
‘The amount of scale randomness’))

7
Summary

retval = Draw.PupBlock(‘Noise Constraint’, block)

# update id-property values after user changes settings

if (retval):
idprop[‘u_loc’]= uloc.val
idprop[‘u_locamount’]= ulocamount.val
idprop[‘u_rot’]= urot.val
idprop[‘u_rotamount’]= urotamount.val
idprop[‘u_scale’]= uscale.val
idprop[‘u_scaleamount’]= uscaleamount.val

idprop[‘u_speed’]= uspeed.val

8
Summary

2.2 Linked scripts

Animations script are added via the method addScriptLink of Blender.
Scene module. if you have read thdocs, you already know ther is two other
methods related to the script links : getScriptLinks and clearScriptLinks. I
won’t give technical detail as the docs do it very well. This method link a
script of your choice present in the Text window buffer to an event.

events :

‘FrameChanged’:

Each time a frame change, the script is execute before new positions
of objects -if animated- or at least bones, being actualize. So, if you
have many Python IPO Drivers to set, i encourage you to do the same
thing in an animation script rather than in a python driver. why ?
¤ a) because python drivers are quite weak, few manipulations
with action datablock often break them
¤ b) in an linked script you have a quick overview of all links, so it
is quickest to access them.

‘Redraw’:

Each time there is a Redraw Call (and this is far more often than a
FrameChanged), the animation script is called, I advise you to not link
to that event too much and/or too «heavy» scripts. A ptyhon transform
link (what the python drivers do...) placed here has some advantages
: the effects will be visible even when acting in 3D view, but it has a
price, if you’re not carefull or your scene has a lot of polygons, cons-
traints, calculations (etc...) to do, the display performances will dras-
tically decrease, and you will suffer several lag. That is why a good
management of layers can help, and if you’re a bit tricky, you can quite
simply create systems of dynamical script linking.

‘OnLoad’:

No comments

‘OnSave’:

No comments

‘Render’:

I don’t have tested yet, so I don’t know if in the case of an animation

render the script would be executed for each frame, or once at the
beginning...