Building Blocks are used within Schematic Tasks or Functions to create custom behaviors. You can check the list of standard Building Blocks shipped with 3DVIA Studio here, but you may also want to create your own. In this article you will learn how.

Creation of a new Building BlockThe inner mechanics of Building BlocksEdition of a Schematic Building BlockEdition of a VSL Building BlockUsing custom Building Blocks

Creation of a new Building Block

Method 1

Let’s say you are currently working under the Schematic editor, simply right click an empty area and choose New Building Block, or type CTRL+ALT+K. You can choose between:

• Inner Graph
• Schematic Building Block
• VSL Building Block

In this article, we will focus on Schematic and VSL Building Blocks. For more information on Inner Graphs, please visit the dedicated reference section.

What is important to understand is that even if a Building Block’s end use is intended only in Schematic graphs, its inner logic can be specified in either Schematic or VSL.

Method 2

If you want to manage several custom Building Blocks under thematic folders, you may:

1. Click one of the new folder icons under the Building Block Libraries of the Behavior Workset;
2. Choose a folder name;
3. Click the relevant folder (“parser” in the following screenshot);
4. Right click the empty fields and select New Building Block;

The inner mechanics of Building Blocks

In summary, a Building Block is activated whenever one of its event inputs is triggered. It then processes optional input parameters, writes the result of this processing to optional output parameters and finally returns by activating one of its event output.

Please check the reference for more information on Building Block Types and all of their connection points (event inputs and outputs, parameter inputs and outputs, targets).

Now we are going to see how to define specific connection points, how to activate event outputs and how to process parameters.

Edition of a Schematic Building Block

Let’s create a new Schematic Building Block called OnKeyToggled by pressing CTRL+ALT+K in a Schematic graph (refer to the first paragraph for alternatives).

3DVIA Studio is shipped with a standard IsKeyToggled Building Block, so here we just want to build a helper on top of it to make it easier for the Building Block to be notified whenever a given key is pressed without having to loop outside the custom Building Block. The loop is runs as soon as On is triggered and until Off is in turn. You can download a project containing its implementation here. Below is an overall picture of the completed graph:

Click to enlarge

Here are some how-to explanations and comments on our design choices:

• We have authored this custom Building Block using standard ones: If, Identity, IsKeyToggled and vkIODeviceManager::Keyboard. We have dragged and dropped them from the Building Blocks Presets (see #1 in the image). An alternative option is to “CTRL+SHIFT double-click” in the graph, start typing the first letters of a given Building Block (“IsKey” for instance) and select the relevant one from the auto-completion list;
• We have specified a KeyIndex parameter in the Pin section (see #2 in the image) so that people using our Building Block will have the possibility to choose what key to listen to;
• We have also created a local variable named running in the Local section (see #2 in the image). It is used to manage the activated state of our Building Block, depending on which event input has been triggered. For instance, triggering Off sets this variable to false, so that the execution flow will be stopped at the If Building Block whose test is done on running value. Members of the Local section are used to store local variables necessary to the inner logic of a Building Block.
• We want our Building Block to loop automatically, which is why the IsKeyToggled event outputs both loop back to If, which tests the running variable;
• We have renamed the Out event output to Toggled so that it understands what has happened when this output is activated. Adding semantics to event inputs and ouputs is considered good practice since it helps the users (you first) understand how to use a custom Building Block. Using True and False for Building Block performing tests is another good example.

Edition of a VSL Building Block

Now we are going to create a VSL Building Block called LifeGauge (refer to the first paragraph to see how). 3DVIA Studio automatically opens a VSL editor tab with a Building Block skeleton:

// Definition of the building block LifeGauge
buildingblock LifeGauge
{
/*
bIn {
eIn
};
*/
/*
bOut {
eOut
};
*/
/*
pLocal plocal {
};
*/
pIn pin {
};
pOut pout {
};

EExecutionResult Execute(const BBContext& iContext)
{
return eExecutionFinished;
}
};

The goal of this Building Block is to manage health points of a game character, and thus activate the GameOver event output whenever they fall to zero. Starting from the given skeleton, we declare two Cured and Hurt event inputs (filling and emptying the bIn section) and the event output (bOut section). We use the pLocal to store the number of health points (the lives variable) between each call of these Building Block. Since we have neither parameter inputs nor outputs, we have deleted the pIn and pOut sections. An extension of this Building Block could be used to specify the initial number of health points as a parameter input. The result is:

// Definition of the building block LifeGauge
buildingblock LifeGauge
{
bIn {
Cured, Hurt
};
bOut {
GameOver
};
pLocal plocal {
int lives = 3;
};
EExecutionResult Execute(const BBContext& iContext)
{
if(iContext.IsInputActive(Hurt)) {
plocal.lives = plocal.lives – 1;
if(plocal.lives <= 0) {
iContext.ActivateOutput(GameOver);
}
} else {
plocal.lives = plocal.lives + 1;
if(plocal.lives > 3) {
plocal.lives = 3;
}
}
return eExecutionFinished;
}
};

We can see testing an activated event input and activating an event ouput is done through the iContext variable. The Execute task is called whenever an event input is activated, which is why we must test if it was the Hurt or Cured input to decide if we add or deduct health points. Lastly, if you return with an eExecutionFinished, the Building Block processing is considered finished. If you want the processing to continue to the next frame (without having to trigger an event input again), you simply have to return eExecutionPending.

Using custom Building Blocks

You can download a sample project using these two Building Blocks here. Here is the global graph using them, within the IntegrationTest task of the BBTester behavior:

Play the experience, press Up to gain health points, Down to lose some. When you go down to zero, “Game Over” is displayed in the Event Console (thanks to the Log standard Building Block) and the OnKeyToggled is disabled through its Off inputs. Note that nothing is displayed in the 3D View for this sample project.