"Script Writer" Movie Script
Overview of the Script Writer Handlers
Using the Script Writer handlers is the easiest way to create dynamic elements or multi-sprites or families thereof. These handlers are for use during authoring mode. They write code that, when run, creates dynamic multi-sprites or elements or families thereof. They also write Lingo code that saves you from having to configure a lot of parameters in WFS handlers such as wfsCreateSprite and wfsAttachBehavior. Also, if you want to write your own code that creates dynamic entities, looking at the code generated by these handlers is instructive.
These handlers output handlers.
These handlers don't output handlers, but one or several lines of code.
Here are the steps to creating dynamic elements or multi-sprites or families of multi-sprites in WFS. For working examples of this process, look at the 'Examples' section of the documentation of the "Script Writer" public handlers (like here (wfsWriteMultiSprite) or here (wfsWriteMultiSpriteFamily) or here (wfsWriteElement)).
When your project is finished, you can delete the static model from the Score, if you like, because the generated code will create the element or multi-sprite or family regardless of whether the model is in the Score. But don't delete the model from the Score until you're sure you don't want to change it anymore. If you do delete the static model, it is recommended that you make a copy of the DIR that contains the static model for future editing purposes. You can keep the model in there if you like, however.
Delete the "Script Writer" script from your Cast at the end of your project, if you like. You don't need it in your DCR or EXE. It won't hurt to include it, but it just will add filesize. All the "Script Writer" handlers do is generate code during Author mode that allows you to create dynamic elements, multi-sprites, and families.
Editing code generated by the Script Writer handlers
EDITING CALLS TO WFSCREATESPRITE
if you want to create a dynamic multi-sprite or family via wfsWriteMultiSprite or wsfWriteMultiSpriteFamily and you want some of the dynamic sprites to have newly created (dynamic) members and other sprites to have the same member as used by sprites in the static multi-sprite you're copying, you edit the output code of wfsWriteMultiSprite or wfsWriteMultiSpriteFamily. This section is about how to edit the output of these two handlers to accomplish the above.
If you run any of the public handlers in the "Script Writer" script and then look at the returned Lingo code, you see calls to wfsCreateSprite. This handler creates a sprite, ie, populates a sprite channel with a cast member. It doesn't attach or initialize any behaviors to the sprite. It's this line we need to edit. wfsCreateSprite is called like so:
theNewSpriteNum = wfsCreateSprite(theMemberParams)
where theMemberParams is a linear list of information specifying the way that the member (and sprite) are to be configured.
theMemberParams = [memberNameOrNumber, castNameOrNumber, ink, blend, width, height, locH, locV, doNotCreateNewMember]
doNotCreateNewMember is the important parameter to look at concerning the current issue. If doNotCreateNewMember is not specified, or is 0 or VOID, then a new member will be created. If it is a positive integer value, then no new member will be created. Instead, the new sprite will use the member referred to in the call to wfsCreateSprite.
For examples of editing code generated by the Script Writer handlers, look in the 'Examples' section of the documentation on wfsWriteMultiSprite and wfsWriteMultiSpriteFamily.
EDITING CALLS TO WFSATTACHBEHAVIOR
As you see in the documentation of wfsAttachBehavior, you can optionally specify the aOverride parameter. This is a property list of the form
[#pProp1: value1, #pProp2: value2, #pPropn: valuen]
The Script Writer 'reads' the way that sprites are configured and constructs aOverride accordingly. aOverride is designed to initialize properties of behavior. The Script Writer looks at a behavior's getPropertyDescriptionList handler, if the behavior has one, and compares the default values of the properties in the getPropertyDescriptionList handler with the initial values (not necessarily the same as the current values). The initial values are the values you set when you configure the Parameter Dialog Box that pops up when you drop a behavior on a sprite.
If the initial value is the same as the default value, the Script Writer does not add the property to aOverride because wfsAttachBehavior will set getPropertyDescriptionList properties to their default values unless aOverride specifies a different value. Consequently, the aOverride parameter constructed by the Script Writer contains only properties that have initial values different from the default getPropertyDescriptionList value.
However, you can initialize any property of the behavior, whether it is in the getPropertyDescriptionList or not, by editing the aOverride property list and adding the property and its value to aOverride.