Director FAQ || Notes ~ Short Index ~ Full Index ~ Search || Prev ~ Next ||

[11] Puppets

• 11.1 What are puppet sprites for?
• 11.2 When should I set puppets on and off?
• 11.3 Why do my puppets keep reverting to the score or behaving strangely?
• 11.4 Can I do transitions and stuff without using the score?
• 11.5 Can I puppet a channel that has nothing in it?

The default puppet state is false. This means that initially, all sprites act under the control of the score. When you issue a

  puppetSprite channelNum, true

  puppetSprite channelNum, false

So, whenever you want to control sprites via lingo, you need to make them puppets, and this tends to be necessary for anything but the most rudimentary interactivity.

First of all, score control includes all those places where you jump to some other frame and want the stage to look the way you set it up in that frame. If you do this with some of your sprites set as puppets, they generally won't change in the way you want, but will stay as your scripts have left them. In general, therefore, you should unpuppet things before any major "go to" commands.

Secondly, the score only asserts its control if there's something for it to do, such as a transition or a loop. If there's a sprite onstage which doesn't move or change in the score, your lingo scripts may be able to move it around and manipulate it for a while even though it isn't a puppet. In general this isn't a good idea, since as soon as the score finds something to do with the sprite all your changes will be lost.

Thirdly, puppetness is a property of a channel, rather than a sprite, so lingo will quite happily let you puppet a channel that doesn't have anything in it. This is almost invariably a bad thing to do and leads to unpredictable and frequently ugly behaviour. Always make sure there's something in a channel before puppeting it.

As mentioned above, another thing which can make puppets behave strangely is if they were declared puppets with nothing in the channel.

The puppetPalette command can be used to change the current palette and to create transitions between the current palette and the one being changed to:

  puppetPalette "myPalette", 20 -- 20 represents the rate if transition

  puppetPalette 0

Other palette channel effects, like Fade To Black, cannot be directly performed from Lingo.

Transitions can be generated with the puppetTransition command:

  puppetTransition 37, 0, 8, false

The transition will occur on the next frame entry. This includes re-entering the current frame. If you are paused on the frame, you could force the transition to occur by adding

  go the frame

The sound channel can be puppeted using the puppetSound command, for which the official syntax is:

  puppetSound mySoundCast

  puppetSound 0

However, an undocumented feature is the use of puppetSound with multiple sound channels:

  puppetSound channelNumber, cast mySoundCast

The volume of individual sound channels can be varied independently by using the volume of sound property:

  set the volume of sound channelNumber = 255

Finally, the tempo can be changed using the puppetTempo command:

  puppetTempo 30

Other tempo channel effects (waiting for a specific time or for a particular event) must be scripted explicitly. This is commonly done by looping on the frame until the required event takes place, eg to wait for a mouseClick:

-- you probably shouldn't do this this way with a slow frameRate... 
  on exitFrame
    if not the mouseDown then go the frame
  end exitFrame

-- puppetizing a sprite with nothing in the score

on insertNonPuppet stageSprite, cstNum, where
  -- first puppet the channel
  puppetsprite stagesprite,true

  -- set its properties
  set the castNum of sprite stageSprite = cstNum
  set the type of sprite stageSprite = 16
  set the ink of sprite stageSprite = 0
  set the foreColor of sprite stageSprite = 255 
  set the backColor of sprite stageSprite = 0

  -- in this case we'll just place our new cast 
  -- and keep it at it's natural size, but in theory 
  -- we may want to adjust its rect
  set the loc of sprite stageSprite = where 
  set the stretch of sprite stageSprite = false

  -- update it
  updatestage
end insertNonPuppet

Director Web: Director FAQ [11]: Puppets

URL: http://www.mcli.dist.maricopa.edu/director/faq/faq11.html