Symbol Commands

With Commands, you can order a Symbol to do something.

Watch tutorial

Download Example

For example, imagine you have 3 scenes that display a stack of cards. First scene displays a single card, the second scene displays two cards, and the third scene displays 3 cards:

Now, let's imagine that the first of these scenes (named "Cards.1") is displayed as a symbol in another scene (named "Composition"), which also includes an "Add Button" layer:

When we click on the "Add Button" layer, we want the symbol displaying the stack of cards to add another card. To do this, we'll use Commands. We'll "teach" the card scenes how to listen to command "Add Card", and then, we will make the "Add Button" send the command "Add Card" to the symbol ("Symbol 1") that is displaying the cards.


Receiving Commands

First, let's look at how to configure your scenes to receive (or listen to) commands. By default, scenes do not listen to any commands.

To add a new command event:

  1. Select the "Cards.1" scene

  1. Click on the yellow event circle displayed in the top right corner of the scene.

  2. Pick "New Command..." event from the displayed menu. This will add a new event that will be activated when this scene receives command named "Command 1" - we'll change the name of this command to "Add Card" later.

  1. Click on "Cards.2" to indicate that we want the "Cards.1" scene to transition to "Cards.2" scene when "Cards.1" receives the new command.

  1. A new event will appear in the Inspector. As you can see, this event will be triggered when "Cards.1" receives the "Command 1" command. After being triggered there will be a Magic Move transition to scene "Cards.2".

  1. Let's change the command name to something meaningful like "Add Card".

We can now follow similar steps to also add "Add Card" command to "Cards.2" scene, and transition to "Cards.3" in such case. So, when sending the "Add Card" command to "Cards.1", it will transition to "Cards.2", and when sending "Add Card" command to "Cards.2", it will transition to "Cards.3":

After that, both "Cards.1" scene and "Cards.2" scene should properly respond to receiving the "Add Card" command. To see what commands a scene responds to, simply select the scene and look into the Events section in the Inspector. Commands are always indicated by the green speech bubble symbol:


Sending Commands

In previous section, we discussed how to make scenes listen to commands and react to them. Now, let's look at how to send these commands.

First, let's use a scene that listens to a command (such as "Cards.1") as a symbol on another scene named "Composition". The "Composition" scene also contains an "Add Button" layer:

We want the "Add Button" to send the "Add Card" command to the symbol that is displaying the stack of cards. To send the command:

  1. Select the "Add Button" layer

  1. Click on the yellow event circle displayed in the top right corner of the selected "Add" button layer.

  2. Pick "Click" event from the list. This means that we want to add a new event that will be triggered by clicking on the "Add" button.

  1. Next, click on the Symbol that is displaying the "Cards.1" scene. While hovering it, you will see a green indication appear:

  1. Drama will now ask you which Command you wish to send to the symbol. Pick "Add Card" from the menu. Generally, all commands received by all scenes that are connected to "Cards.1" scene via transitions will be displayed here. In this case, only the "Add Card" command is available, but if you add more commands to the scene, they will all appear here.

That's it! We've just added a new click event for "Add Button" layer that will send command "Add Card" to the symbol that shows a stack of cards. When you try this in simulator, clicking the "Add Button" will now add a card onto the stack.

Download Example

Commands are a very powerful concept. This example was pretty simple, but you can create really advanced controls with complex internal behavior using commands. Actually, the most advanced interactions can be created by combining commands with notifications. To learn more about notifications, please read the "Symbol Notifications" chapter.