Doc:Tutorials/Extensions/Python/BSoD/Scriptlinks

From BlenderWiki

      >

      >

Blender Summer of Documentation: Contents | Manual | Blender Version 2.41

[edit] Discussion of Scriptlinks

In a previous section, we moved an object across the view by repeatedly pressing Alt P to run a script. Experienced Blender users know they can do essentially the same thing automatically with an IPO curve. Since no one wants to repeatedly press keys when we can write scripts, let's try to make this happen automatically.

Scriptlinks come to our rescue. A Scriptlink associates a script with an event and an object. See Module API_Related doc.

Scriptlinks are created and managed using the Script context in the Buttons Window.

Right now, let's just focus on connecting a script with a Scene and the FrameChanged event. Start with our usual default scene with a cube named 'Cube'. In the Button Window, select the Script context (between the Logic and Shading) Create the following script and name it 'Move'. (You name your script in the dropdown box in the Text Window header in the TX:<text file name>" input area)

import Blender as B

NAME = 'Cube'

ob = B.Object.Get( NAME )
ob.LocX += 0.5

First:

• Test the script for errors by running it manually.

Then:

• Make sure the Enable Script Links is selected
• press Scene ScriptLink New and choose our script from the drop down menu
• select the FrameChanged event from the event menu

Notice there is no Redraw() in our script. Blender always does a redraw after a frame change.

Test the ScriptLink by pressing the RightArrowKey to advance one frame. Watch our cube move one half a Blender unit in the X direction.

What happens when you activate the animation with Alt A? The cube runs out of the view, advancing once per frame. If we want to run our animation a second time, we have a problem: the cube is already way off to the right. Let's fix it by doing some initialization. Change the 'Move' script as shown below:

import Blender as B

NAME = 'Cube'  # object to move
START = 1	   # initial frame

ob = B.Object.Get( NAME )
frame = B.Get('curframe')

if frame == START:
   ob.LocX = 0.0
else:
   ob.LocX += 0.5

When we run the animation, we see our cube move as before. Now however, when we reset back to frame one, the cube moves back to the origin.

A couple important points about writing scripts:

• Notice we put some constants, NAME and START at the beginning of the script. This makes them easy to find and change. Having magic numbers and names scattered throughout your script is a bad idea.

• We first wrote a simple script to solve a problem. Unfortunately, it was not a complete solution, so we added some new features. This is a common way to build scripts:
  • Solve part of the problem.
  • When that works, grow the script into a complete solution.

[edit] Types of Script Links

Scripts can be connected to Objects as well as Scenes.

Object scriptlinks can trigger on the following events:

• Frame Change
• Render
• Redraw

Scene scriptlinks can trigger on these events:

• OnLoad
• OnSave
• Render
• Redraw
• FrameChange

There is another type of scriptlink called a Space Handler, but we will save discussion of those for another section