Using SPi-V in Director

In this tutorial, you will learn how to use SPi-V inside Director. You will need intermediate Director knowledge for the basics, or full scripting knowledge to understand how to get the most out of the integration.

The required files can be downloaded here:
http://fieldofview.com/spv/download.php?filelist=integration.lst

In the archive, you will find two Director movies, as well as the latest version of the SPi-V engine. In order to use SPi-V in Director, you will always have to supply the SPi-V.dcr file with your Director projector or dcr file. This way, you can always update to the latest version of the engine simply by replacing that file.

The files have been written in Director MX 2004, but you should be able to open and use them with any version starting with Director 8.5.1. The scripts used have been written such that they work with Shockwave 8.5 and up.

The very basics

If you open the 'integration-basics.dir' file in Director, you will see the most basic use of SPi-V in Director; using the engine to display a panorama.
Play the Director movie, and you will see the cathedral scene playing.

In the score you will see that the SPi-V engine is a sprite, like any other sprite on the stage in Director. You can freely scale and move the sprite, and even animate it using keyframes in the timeline. The only limitations are that you can not rotate the SPi-V sprite, and the SPi-V sprite will always display on top of all other content. There is no way of having Director sprites on top of the SPi-V content.

Looking at the SPi-V sprite in the property inspector, you will see that there are two behaviors attached to the sprite.

behavior: Init

The first behavior, 'SPi-V: Init', should always be attached to the SPi-V.dcr sprite. It takes care of the nitty gritty behind the scenes work, and prepares the member before it can be used. It is not a good idea to edit the 'SPi-V: Init' behavior. If you want to add additional functionality, add additional behaviors to the sprite.

behavior: Load panorama

The other behavior loads a specified tour or simple mode panorama into the engine. You can change the panorama to load using the property inspector.

Integrating into your own movie(s)

First, you need to make sure the SPi-V.dcr file is copied to the same folder as your .dir file. The next step is to copy over the two behaviors. There's a trick to do this easily:

1. open the 'integration-basics.dir' movie in Director
2. select both behaviors in the cast window, and select 'Edit -> Copy castmembers' from the menu
3. now close this copy of Director and/or load your own movie into this copy of Director. You have to make sure the 'integration-basics.dir' file is no longer open
4. Paste the two behavior castmembers in one of the casts of your movie.

Now all that is left to do is to import the SPi-V.dcr file that you put alongside your Director movie file using 'File -> Import', create sprites with the SPi-V member, and attach the two behaviors. When you attach the 2nd behavior, you will be prompted for a file to open.

More advanced work

The 'integration-advanced.dir' file uses the exact same techniques, but adds some more functionality. There are a number of additional reusable behaviors.

log messages

The first two behaviors allow you to respond to messages sent by the SPi-V engine. These messages are the same messages you can see 'whizz' by in the status area of the browser window. You can always see a log of these messages by pressing 'd' while a SPi-V window has the focus. The messages are typically showing what SPi-V is doing.

Most messages are generated by the engine itself, but you can use the 'logMessage' action to create you own messages. See the included 'integration.xml' for an example using this action. Note that the included xml document uses 'silent' messages which don't show up on the messagelog (the 'd' popup). They are communicated to the director movie though, so behaviors can be set up to respond to them.

behavior: On message go to marker

This behavior makes the playbackhead go to a certain frame or marker when it is triggered by a certain message. In the demo movie, the message is created using an action when the user hovers over (or leaves) a hotspot. When playing back the movie, have a close look at the playbackhead in the score while hovering over and leaving the hotspots.

behavior: On message play sound

A similar behavior, only it plays a specified sound when it is triggered. In the demo movie, instances of the behavior are triggered by the engine reporting it is ready with the scene, and when it exits the current scene (to go to another scene).

Two of the other reusable behaviors can be attached to buttons (ie: not to the SPi-V sprite itself!)

behavior: Button set view

Lets you set the current view by pressing a button.

behavior: Button set property

A wrapper for the setProperty api function. Used to enabled/disable the hotspots in the demo.

The final behavior in the advanced movie shows you how to get a property from the SPi-V engine.