Tutorial 5: Visual programming with WiMi5
Visual programming elements
In this tutorial, we explain the elements we are going to use to create a game following WiMi5’s visual programming approach. We are also explaining the basic WiMi5 editor concepts and mechanics.
It is the basic composition element of our game logic, visually displayed as a box. It represents a process that can be run at will and combined with others to build more complex processes. Consists of two types of elements:
- connectors. The connectors are used to manage the execution of the blackbox. They are subdivided into:
- input connectors. The input connectors are used to start or stop the execution of a blackbox (in the image below would be “on” and “off” of TouchListener, which as you can guess are used to start and stop the blackbox, and “do” of CreateText) .
- output connectors. The output connectors serve to notify other blackboxes that a significant event has happened (in the image below would be “touch 1 start”, “touch 1 end”, “touch 1 move” of TouchListener, and “done” of CreateText.). Thus, if we link the output connectors of a blackbox with other blackbox input connectors, we will create a thread that will ultimately be our game logic. The output connectors are in turn divided into two types depending on how they behave:
- synchronous. They differ because they are round and orange. An output connector is synchronous when it is launched immediately after the activation of a blackbox input connector. In the picture you can see that the output connector “done” of CreateText is synchronous, which means that when the input connector “do” is activated, immediately after the process of the blackbox, it will launch “done”. If all the output connectors are synchronous, we say the blackbox is synchronous, distinguishing it with an orange peak in its upper left corner.
- asynchronous. They differ because they are blue and shaped like a teardrop. In the picture below you can see that “touch 1 start”, “touch 1 end”, “touch move” of TouchListener are asynchronous. This means that when the input connector “on” is enabled, no output connectors will be triggered immediately, but it will be the blackbox who manages this process. There are situations, such as that of TouchListener, managing an activity that is not sequential, as a touch screen. That is, the blackbox can not predict when the user will touch the screen. Asynchronous output connectors are used for those situations where the output or can not be determined a priori, or outputs differs in time for other reasons. When a blackbox contains at least one such asynchronous output connector, we say the blackbox is asynchronous, distinguishing with a blue peak in its upper left.
- parameters. Parameters are data containers that are used to manage the information the blackbox consumes and produces. There are two types:
- input parameters. Some blackboxes require data to run. For example, if you want to clone a character in your game, the blackbox needs to know what that character is in order to clone it. The way to inform the blackbox about this is using an input parameter which will deposit the character to be cloned. Then the blackbox can read and clone it.
- output parameters. The blackbox output parameters are used to deposit the information produced as a result of being executed. However, keep in mind that a blackbox can have only input parameters or only output ones, or have both. In the figure below you can see that the blackbox TouchListener only has output parameters, which in this case are for the blackbox to deposit coordinates of the user’s touch coordinates whenever he or she touches the screen.
For more information about the blackboxes, check the technical documentation of blackboxes.
Blackboxes using parameters container, used to define it’s actions or to give the result of it’s actions. These parameters can have own properties or values that can be used in new Params to be used as parameters for the blackboxes. They are yellow coloured in the blackboxes.
Parameter lists to be used in the blackboxes. They have a number of contained parameters and an index indicating which parameter is shown. This is why a Collection can be used a simple parameter based on the index value it has. Their colour in the blackboxes is orange.
Script input or output point. These are joined to Blackboxes to determine the execution flow. The OnLoaded connector is very important: is the input point for the execution of any script after loading the Level owning it. Execution order is based on the inside Level Script hierarchy, deep executing first the first son and all it’s descendents, after this execute the second son and all it’s descendents and so on. Input Connectors are green, blue for onLoaded and output Connectors are red.
A link is a logic join between a Connector or a Blackbox output(trigger) with another Connector or the Blackbox activator it triggers. It’s represented by a line which joins the elements. It’s property “call order” defines the triggering order for the same output of Blackboxes (trigger) or a Connector.
Block containing Blackboxes and scripts with their joins and used parameters. They define new execution units.
Loadable and unloadable scripts used to control the load and unload of used assets. The lock icon identifies how the level is depending on if it is loaded or unloaded.
Overview of the elements used in the WiMi5 editor
On load concept (onLoad connector)
The beginning of every execution depends on the Level´s loading ending. This load finishes when the last asset of the level is loaded. In this moment, the Level Connectors’ onLoaded are triggered, executing first the Level onLoaded, then the first Script son’s onLoaded and all it’s descendents, then the second Script son’s onLoaded and all it’s descendents and so on.
Activators (inputs) & triggers (outputs)
Blackboxes have some inputs and outputs, which are the joining elements to chain an execution. The inputs are in charge of activating the Blackboxes inner functions. The outputs are the Blackboxes’ reactions to the execution triggers by the activation of their inputs. Thus, the way to build a Script is triggering inputs and outputs forming a logic action flow.
The path to follow when building a Visual Script in PengoJS is to chain events(outputs-triggers) with actions(inputs-activators) of elements called Blackboxes, which based on those actions trigger new events.
It is very important to know which action goes before and which goes after. Thus, it’s important to be aware that all the execution happens while a triggered activation(activator) triggers an event(trigger).
Because of that, when an event handles various activations to trigger, each one will be deeply executed secuentially. This way, while an activation triggers new events and these trigger new activations, next activations won’t be triggered. That is why it is said that Visual Scripting execution is deep. If from an event(trigger) various activations are handled, the execution order is defined by “Call order” property, begining in 0.
An example to see it in context: When the Level which has the next Script load finishes, the Script onLoaded Connector activates.
This triggers the activations connected to the Connector. First the ActivateScene Blackbox’s set activation triggers, due to the Link call order is 0, which is the first one, and all the trigger chain it produces.
After that the next activation whose “Link” has the “call order” 1 will be shot.
Blackboxes are elements that execute action and based on those, trigger the execution of new actions. There are two types of blackboxes, the immediate, which directly triggers when engaged, and the persistent, whose execution remains persistent, triggering actions immediatly and delayed but always on update cycles. Depending on the Blackbox, the input, output and parameter number can be set. This kind of Blackbox is identified with an + after the Blackbox type. The setting is made via a dropdown menu, popping it out when right clicking on the Blackbox.
There are also Blackboxes with setting properties which define it function. These are noted with a gearwheel after the Blackbox type. Accessing these properties is done like with the rest of the elements, selecting and having them in the properties panel.
Each blackbox´s documentation can be found in the help section.
CodeRunner: RawBlackbox: (soon as possible)
Params are elements used in the Blackboxes to input execution action parameters, giving values or objects to act. They can be also other parameters properties or even a parameter list, which uses the element at the set index. When selecting a Blackbox assigned param, the type of the encapsuled parameter class is shown(value, resource, reference or collection), the instances, the Scripts where it is used(in scripts), the type,it’s name and the encapsuled parameter’s exposed properties(value).
Params are used dragging and dropping them to the Blackboxes, from the resource panel(Asset manager) or dragging and dropping from the element panel(side toolbar) in it’s Parameters tab. They can also be assigned to the Blackboxes’ Params connectors via the dropdown menu popped out when right clicking on them, in case they are unique.
Params bar, exposed (“E”) and shared (“S”)
In the logic chart, there is an upper bar in every script, where params are shown. In this bar the name, type and the number of params that are being shared between scripts are shown. There are two tabs in the bar, exposed(e) and shared(s). Depending on it different parameters are shown. In the S tab, parameters used in the actual script and in others are shown. It is automatic, so params cannot be dragged and dropped manually.
In the E tab, outside the script exposed parameters are shown. Adding is made by dragging and dropping the assigned parameter or remove them by erasing them from the tab.
Collections, parameters lists
Certain type parameter list. They are created dragging the Collection from the element panel (side toolbar) in it’s parameters tab, from the desired type of Collection icon.
Selecting a Collection will show the parameters it has. In this case, it is a Param from the Collection class, the number of uses it has, named instances, the contained paramenters type, it’s name, the amount of parameters it has, named item count, the exposed parameters, named item number, and the value parameter is shown. To manually remove the exposed element from the list via the trash icon.
Param component, reference to a property of a parameter
It is a param that contains as value a property from another Param. The creation is made by dragging the desired property to use as parameter to the Blackbox . It will be a reference to the original property, so if the original value changes, this will change too and vice versa.
A Link is the line that joins an event(output/trigger/connector) and an activation(input/activator/connector), representing their chain. It has the “call order” property, which determines the call order to the inputs from the event output. It is created by clicking in the output and in the input.
Wireless Event, Behaviors, Entities or Prefabs (soon)
Back to Help29/04/2014 / No Comments
- connectors. The connectors are used to manage the execution of the blackbox. They are subdivided into: