Summary: In Isadora v1.x there was an inconsistency in the way values were passed from one Actor to another. This article explains in detail how that behavior has changed in Isadora 2.0.
Who Needs To Read This: If you are an experienced user of Isadora v1.x, and have upgraded to Isadora v2.0, you should read this article so fully understand the new behavior.
There has been an inconsistency in Isadora since the very beginning with regard to the way values were passed from one Actor to another. We've made important changes to this behavior for version 2.0 that rectify this inconsistency, and this article goes explains the differences.
Let's start with the problem. Consider this simple setup:
Currently, the Calculator actor shows the correct output: 0 + 1 = 1. But then we set enable the "Initialize" value to 2. Using Isadora v1.x, if you deactivate and then re-activate this Scene, you'll see this:
which is obviously incorrect. If the inputs are 2 and 1, the output should be 3. But it's not; it's 1.
When I first created Isadora, my instinct about the "Initialize" function was that it should simply to force an input to a particular value, i.e., to prepare the initial state but not to actually do anything. So, the value was set in the Actor internally, but did not cause the actor to execute and produce a new output. The next number to arrive at 'value 1' or 'value 2' would produce the correct result. This worked in most situations, but later started to become noticeably problematic. For instance, consider a User Actor with these four actors:
We click on the 'value1' input of the Calculator to show the Inspector, and then enable the "Initialize" checkbox and set the value to 4 like this:
This will cause the Calculator's 'value1' input to be initialized to 4. So far so good.
Next, we close the User Actor editor, click on its 'value1' input to show the Inspector, and then enable the "Initialize" checkbox and set the value to 5 like this:
If you were to now deactivate and reactivate the scene, you would expect this:
- The 'value1' input of the Calculator actor inside the User Actor would be initialized to 4 – though it doesn't matter because that value will soon be replaced by the value coming from the first User Input.
- 'value1' of the User Actor is initialized to '5'
- 'value2' of the User Actor is set to its current value, which is '1'.
- These two values are now passed into the User Actor via the two User Inputs.
- The Calculator receives the two numbers from the User Inputs, adds them together, and produces a result of 6.
- The result is sent to the User Actor's output
But, in Isadora v1.x, the User Actor's output would not change – it would still be 1. Why? Because, as mentioned above, values passed into an actor using the "Initialize" function did not cause the actor to execute and produce a new output.
Because of this, one ended up having to code some funky workarounds when this behavior didn't give you what you wanted. In User Actors, I was often forced to create setups like this:
The Enter Scene Value was a workaround that ensured the last value received at the User Input would always be sent into the Calculator when you activated the scene. I think we can agree this is not very pretty.
So, I've recoded this whole mechanism to solve this problem once and for all. For those interested in the gory (but useful) details, the "pseudo-code" for executing actors now goes like this:
- For every Actor in a Scene that is at the end of a chain of Actors, perform step 2.
- Loop through all the Actor's inputs, performing either step 3 or step 4 for each one
- If no links (wires) are connected an input, then:
- if the Initialize value is enabled, store that value into "save-result."
- Otherwise store the current input value into "save-result".
- If one or more links are connected to an input, then execute all of the "upstream" actors, i.e., the actors with links to this input. Take the value from the last Actor that produced a new value and store it into "save-resullt". (Remember, when multiple actors are connected to the same input, the Actor's vertical position in the patch determines the order of execution: actors are processed from top to bottom.)
- Pass "save-result" to the Actor input selected in step 2, which may lead the output value(s) to change.
This is really how it should have been done from the beginning. But there were no User Actors in Isadora 1.0, and the initial behavior wasn't really a problem way back then.
Isadora veterans are going to experience behaviors that may be unexpected based on the old ways of working. For instance, consider the following patch:
The current 'value1' input is 2, and 'value2' is 1. If you deactivate this scene and then reactivate it, the Initialize value will be fed to the 'value1' input, causing the Calculator to generate a new output of 5+1 = 6. This will trigger the Counter and increment its output. This would not have happened in previous versions.
To quote Shakespeare: "Aye, there's the rub." Because of the differences in the two methods, it's clear that I can't impose this new method on older patches because it will introduce many subtle and hard to find bugs that will drive people crazy. It's also clear that this new method is the way it really should be and is where we must go in the future.
To make this transition less problematic, Isadora v2.0 will automatically use the old, v1.x behavior when you open older patches. Any new patch you create in Isadora 2.0 (i.e., by choosing New from the File menu) will use the new, v2.0 behavior.
You can tell if the new system is active by examining the menu item 2.0 Actor Processing Mode in the Actors menu. If that item is checked, then the new, v2.0 method is active. If it is unchecked, Isadora will use the v1.x method.
You can choose to enable the new method with an older patch. Just go to the actors menu and choose 2.0 Actor Processing Mode to enable it. After receiving a warning dialog, you're patch will now use the new method. This setting will be saved with the file by v2.0, so it will continue to use the new method if you open the file in v2.0 or later.
For new patches created in v2.0, we strongly advise you to leave 2.0 Actor Processing Mode enabled.
My final bit of advice is for people who move between older versions and the current version. The 2.0 Actor Processing Model will be disabled if you save your file in a version prior to v2.0 because Isadora v1.x does not know about the new setting. So if you move between versions frequently, it will be up to you to you to check the 2.0 Actor Processing Mode in the Actors menu to ensure your patch is using the system you desire.