Guide to using Custom Expression and Instructions

I realize it is a bit confusing on how to use custom nodes in Vizzy at the moment, so here is a guide that will hopefully help you to get started.

There are two types of custom nodes: Custom Instructions and Custom Expressions. Custom Instructions can execute any number of instructions, run loops, change variables, etc. They are a bit like a mini program. Custom Expressions can only return a value and they cannot execute other instructions.

Right now, there is no UI to create a custom node, so you need to define it via XML. I do plan to add a UI after the winter break to make this part easier.

CUSTOM INSTRUCTIONS

Let's build a custom instruction that does a countdown. Edit your program's XML and insert this blob of XML just above the closing </Program> tag.

<Instructions>
   <CustomInstruction id="9999" format="countdown from |time|" callFormat="countdown from (0)" name="Countdown" style="custom-instruction" />
</Instructions>

Now load the XML in Vizzy and notice there is a purple block on the surface.

The format attribute above defines how this looks. The |time| indicates it can accept an input. This will be the starting time to countdown from. Now let's build the bulk of the custom instruction by dragging blocks out from the toolbox. It should loop and countdown from the specified time to zero. Here's what I ended up with.

Now this is just the definition, so we need to be able to actually call/execute it from our program. Notice there is a new Custom Instructions panel with a new block we can use in our program.

The callFormat attribute in the XML above defines how this looks. The (0) indicates the block takes an input. It passes this input into the time variable in the definition we just made. Finally, let's use this in our program:

CUSTOM EXPRESSIONS

Custom Expressions can be used to return a value. They can't execute other instructions, but they can be useful if you are often repeating the same calculations. For example, an expression that clamps a value between a min and max would be handy. Here's a definition for a clamp expression:

<CustomExpression format="clamp |x| between |min| and |max| return (0)" callFormat="clamp (0) between (1) and (2)" name="Clamp" style="custom-expression">
   <Constant number="0" />
</CustomExpression>

Insert this XML blob between the starting <Expressions> tag and the closing </Expressions> tag and open your program's XML. Notice the new purple, rounded definition block on the surface and the new addition to the toolbox.

Now we can easily define what the custom expression should return by dragging out other built-in expressions from the toolbox. Hopefully, I got it right!

Now that it's defined, we can use it in our program. I threw together a simple program that just displays the result in three different test cases to ensure it is working properly.

It outputs 10, 15, and 20 in the flight scene, so it appears to be working as expected.

That's it for custom instructions and expressions. I will try and get the user interface finished so you can easily create them without having to edit XML manually.