Using the Behavior Library -- General Usage and Notes
The purpose of this document is to outline some general design principles behind the behaviors shipped with the Instructional Software Development Kit (ISDK).
Much of the difficulty in designing the behavior system was addressing how to get multiple actors to "talk" to each other. As an example, suppose I implement a button and a label. When I push the button, I want the button's text to be copied to the label. How does the button know which label to modify?
The standard approach in Stencyl is to use the Actor Inspector. Indeed, this is the approach used for many of the behaviors. However, there is one notable downside: referencing multiple actors at once. To address this issue, the ISDK uses a "Unique Identifier" system.
The Unique Identifier is a special behavior that allows the developer to give the actor a unique name. This identifier is already enabled on many of the actors, but can also be added using the Actor Inspector. The Unique Identifier is designed to work with "Targets" and "Events".
Events
A button's behavior listens for a mouse click. When this click has been received, the button triggers an event (typically "ButtonPush"). This event is sent to all behaviors attached to the actor. However, we need to trigger events in other actors, as well.
Many of the behaviors have an "Event Trigger" parameter. This is a text field, in which events are listed. The format of this string should be:
Event1 | Unique ID1 , Event2 | Unique ID2, ...
When the button has been pushed, the event "Event1" is triggered for every actor which has Unique Identifier "Unique ID1". The event "Event2" is triggered for every actor which has Unique Identifier "Unique ID2", and so forth.
As another example, suppose I want the user to click a button to submit data to a server, then display a "Submitted!" image on the screen. I have an image actor with Unique Identifier "picture", and the Simple Clicker actor with Unique Identifier "clicker". I would load a button with the behavior "Push Button Behavior", then set the Event Trigger to:
SendData | clicker , LoadInstance | picture
When the button is clicked, both events would be triggered (in the order they're listed).
Targets
Suppose I want to submit some data to another actor. For example, I want the user to be able to enter a function into an input box, then graph that function. This can be accomplished by the "Targets" system.
I'll place three actors on the screen. A "2D Graph Output" actor, with Unique Identifier "graph", a "Basic Input Field" with Unique Identifier "input", and push button that will act as the submit button.
I configure the "Events Trigger" for the push button to be:
SendContents | input , DrawGraph | graph
The behavior "SendContents" is part of the Basic Input Field behavior. When the button is clicked, this event is triggered. This event will submit the contents of the input field to the graph.
The Basic Input Field Behavior has an attribute called "Targets". This is a list of variables that the Basic Input Field should copy its contents to. The string format for "Targets" is:
Unique ID1.Behavior1.Variable1 , Unique ID2.Behavior2.Variable2 , ...
In our example, we want this string to read:
graph.2D Graph Output Behavior._Expression
When the button is clicked, the contents of the user input box is copied into this variable. The button will then send the DrawGraph event to the graph, and the function will be plotted.
Constructors
Many of the actors are "constructors", meaning their purpose is to draw a graph, display an image, etc. The actor itself shouldn't be seen. Rather, its icon is merely present to show the developer that it is in the scene.
The "Hide Actor" utility is a behavior that hides the actual actor, since we don't want that to be visible. The image, text, etc., that the actor generates will still be visible.
|
