Creating Scripts with the 3DPI. Docs | Last

B. Using the scripts.

What to do with the scripts, that have been created by the 3DPI, of course depends on the situation. Scriptlines, that only need to run once (e.g. for creating a scene), have to be copied into different handlers than scriptlines, that need to run all the time (e.g. for animating a model). Furthermore there are many ways how to handle the scripts, but the following description should give an idea, what can be done with them in general.
What to do with scripts. top

Scriptlines, that only need to run once when starting the movie, can be copied to the following places (among others):

  • into a "startMovie" handler of a moviescript
  • into a "beginSprite" handler of a framescript
  • into a "beginSprite" handler of a behavior, which is attached to a 3D sprite

As an example here comes a description how to create a behavior:

  1. Open the score window.
  2. Select a 3D sprite.
  3. Set the Sprite Toolbar to visible (if it isn´t already) by selecting "Sprite Toolbar" from the "View" Menu.
  4. Open the "Behavior" PopUp.



  5. From the PopUp select "New Behavior".

Now a new behavior will be created and attached to the shockwave3D sprite, and its window will immediately open. Within this window an empty "mouseUp" handler was generated automatically.

For pasting scriptlines, that only need to run once at the beginning, one can change the existing "mouseUp" handler into a "beginSprite" handler, and paste the scripts inside, so between the line "on beginSprite me" and the line "end".

Scriptlines, that need to run all the time, e.g. for animations, can be copied to the following places (among others):

  • into an "exitFrame" handler of a framescript
  • into an "exitFrame" handler of a behavior, which is attached to a 3D sprite

For more informations about Lingo scripts in general, please read from the following sources:

  • Director Online help -> "Using Director" -> "Behaviors" and "Writing Scripts with Lingo"
  • Director manual "Using Director 8.5 Shockwave Studio" -> Chapter 5 "Behaviors" and Chapter 6 "Writing Scripts with Lingo"
Example for using scripts. top

The following example will demonstrate, how to create a simple box, how to rotate it, and how to get and use the scripts for recreating the scene with Lingo. The final result can be saved and even uploaded to play online.

      1. Create a new movie.
      2. Create a new shockwave3D member.
        Either select the menu Insert > Media Element -> Shockwave3D
        or click on the "New..." Button within the Member-Tab of the 3DPI.
      3. Drag the new created member on the stage.
      4. Select the "Trace Changes" function of the 3DPIs Trace Button.
        The function has to be selected and activated, so the Button should appear pressed.
      5. Select the Member-Tab of the 3DPI.
      6. Click on the "resetWorld()" Button.
      7. Select the ModelResource-Tab of the 3DPI.
      8. Click on the "New..." Button.
        A dialog will open.
      9. Within the dialog type "myBox" for the name and select #box for the type.
      10. Click on the "OK" Button to close the dialog and to create the new ModelResource.
      11. Select the Model-Tab of the 3DPI.
      12. Click on the "New..." Button.
        A dialog will open.
      13. Within the dialog type "myCube" for the name and select 'box("myBox")' for the Resource.
      14. Click on the "OK" Button to close the dialog and to create the new Model.
      15. Click on the "Rotate..." Button.
        A dialog will open.
      16. Within the dialog type "5" for the y-increment.
      17. Click "OK" to close the dialog and to rotate the Model.

Now watch the message window, the following scriptlines did appear:

-- "*********** 3DPI Tracing ***********
member(1, 1).resetWorld()
-- "
-- "*********** 3DPI Tracing ***********
theMember = member(1, 1)
theModelResource = theMember.newModelResource("myBox", #box)
-- "
-- "*********** 3DPI Tracing ***********
theMember = member(1, 1)
theModelResource = theMember.modelResource("myBox")
theModel = theMember.newModel("myCube", theModelResource)
-- "
-- "*********** 3DPI Tracing ***********
theModel = member(1, 1).model("myCube")
theModel.rotate(0.0000, 5, 0.0000, #self)
-- "

The first 3 parts of the script are to recreate the scene, the last part is to animate the model. Of course the script can be optimized, but before going into the details of optimization you can try the script as it is.
The script parts only have to be placed in the correct handlers: Create a new behavior, which is attached to the sprite (see "What to do with scripts"). Change the default "mouseUp" handler to "beginSprite", and paste the first 3 parts inside. Add an "exitFrame" handler and paste the last part inside. After deleting all unnecessary line, those that start with the command delimiter '--', the behavior now should look like this:

-- first version of creating and rotating a Cube

on beginSprite me
  member(1, 1).resetWorld()
  theMember = member(1, 1)
  theModelResource = theMember.newModelResource("myBox", #box)
  theMember = member(1, 1)
  theModelResource = theMember.modelResource("myBox")
  theModel = theMember.newModel("myCube", theModelResource)
end

on exitFrame me
  theModel = member(1, 1).model("myCube")
  theModel.rotate(0.0000, 5, 0.0000, #self)
end

In fact this is now a working script, which does not need to be changed. You can start your movie and test it. Nevertheless I want to show you how this script can be optimized:

In the beginSprite handler a line appears double, the one which keeps the reference to the 3d member in the variable 'theMember'. The second one can be deleted. Furthormore the 3DPI has forgotton to use such a variable for the 'resetWorld' function, which in this case can be corrected easily:

on beginSprite me
  member(1, 1).resetWorld()
  theMember = member(1, 1)
  theMember.resetWorld()
  theModelResource = theMember.newModelResource("myBox", #box)
  theModelResource = theMember.modelResource("myBox")
  theModel = theMember.newModel("myCube", theModelResource)
end

The reference to the ModelResource has already be stored in the variable 'theModelResource' when it was created, and so it is not necessary to get the reference a second time. Another line can be cut out:

on beginSprite me
  theMember = member(1, 1)
  theMember.resetWorld()
  theModelResource = theMember.newModelResource("myBox", #box)
  theModelResource = theMember.modelResource("myBox")
  theModel = theMember.newModel("myCube", theModelResource)
end

4 lines are left to recreate the scene, the first to store the member reference, the second to reset the member, the third to create the ModelResource, and the fourth to create the model. All this lines will only be executed once, when the sprite begins.

For animating the Cube the exitFrame handler is the interesting one, because it will be executed every frame. In the exitFrame handler of the first script version the only little 'ugly' thing is that the reference to the model will be created every time. Much better is to store this reference somewhere constantly, which in case of a behavior can be done by a property. Because a reference to the model already exists in the beginSpriteHandler, lets use this variable 'theModel' and declare it as property, so that all handlers in this behavior know who 'theModel' is:

property theModel

on beginSprite me
  theMember = member(1, 1)
  theMember.resetWorld()
  theModelResource = theMember.newModelResource("myBox", #box)
  theModel = theMember.newModel("myCube", theModelResource)
end
on exitFrame me
  theModel = member(1, 1).model("myCube")
  theModel.rotate(0.0000, 5, 0.0000, #self)
end

The only left thing to do is to loop the movie, that it will not stop running at the last frame. In this example it simply can be done by adding "go to the frame" at the end of the exitFrame handler:

on exitFrame me
  theModel.rotate(0.0000, 5, 0.0000, #self)
  go to the frame
end

Here is now the final script at once:

-- optimized version of creating and rotating a Cube

property theModel

on beginSprite me
  theMember = member(1, 1)
  theMember.resetWorld()
  theModelResource = theMember.newModelResource("myBox", #box)
  theModel = theMember.newModel("myCube", theModelResource)
end

on exitFrame me
  theModel.rotate(0.0000, 5, 0.0000, #self)
  go to the frame
end

One can now close the 3DPI, save the movie, and even create a shockwave movie out of it to present the 3d scene online.
The movie will be extremely small, because it only contains an empty shockwave3D member and a few scriptlines.
Last: A. Getting scripts Docs