neuromore Studio
State machine reference
A state machine holds the logic of an experience: what the Experience window shows, which media plays, what the classifier is told, and when the session ends. You build it in the State Machine window, from states joined by transitions. Open the window with Windows > Add > State Machine, or choose Windows > Layouts > State Machine Designer, if your account lists it. See Layouts.
This page lists every state, transition, condition and action with its default values. For a step-by-step introduction, see Getting Started.
How a state machine runs
Section titled “How a state machine runs”- You click Begin Session. A session needs a classifier. The state machine is reset, and every Start state becomes active.
- The state machine holds while the session prepares, then starts running when the session starts.
- On every update, Studio checks the outgoing transitions of each active state. More than one state can be active at the same time.
- When a transition’s conditions are met, it starts and leads to the next state.
- When any End state becomes active, the state machine stops and the session ends with the message “The session has ended.”
A state machine also runs outside a session. It starts as soon as it is opened, so its transitions and actions can fire then. Begin Session resets it and starts it again. After you end a session with the stop button, it keeps running until the next reset.
Pausing the session holds the state machine. No transitions start and no Timer ticks. Time Conditions and running transitions stop counting, and Continue picks up where they stopped. Timer states are different: after Continue, a Timer ticks straight away if its Interval has passed, counting the pause. See When a Timer ticks and Running a session.
In 1.7.3: Pause and Continue do not reach the state machine. Pausing a session leaves transitions, Timer states and Time Conditions running. The state machine also runs while the session prepares, before the session starts. See What changed since 1.7.3.
States
Section titled “States”To add states, a state machine must be open. In the Back-End File System window, create a file of type State Machine and double-click it to open it. See Creating the state machine. Until then, the State Machine window has no Add Node menu and ignores drops.
Add states with a right-click in the State Machine window and Add Node > General, or drag them from the General palette.
| State | What it does | Attributes (default) |
|---|---|---|
| Start | Becomes active when the state machine is opened, and again when the session begins. Stays active until one of its outgoing transitions starts. You can have more than one. | None of its own |
| Action | Runs its actions when entered and when left. | None of its own. Holds On-Enter Actions and On-Exit Actions |
| Timer | Ticks at a set interval. Its outgoing transitions can only start on a tick. | See Timer |
| End | Ends the session when it becomes active. It cannot be left. | Exit Status (0) |
Every state also has these:
| Attribute | Default | Meaning |
|---|---|---|
| Node Name | The state’s type | The name shown in the graph |
| Transition Mode | Select Highest Priority | What happens when several outgoing transitions are ready at once. The other options are Use All Transitions and Select Randomly. The source marks this attribute as deprecated, so prefer Priority on the transitions. |
Only Start states and Timers with Start Active on become active by themselves. Every other state needs an incoming transition.
Exit Status has no effect in Studio. If several End states are active, the highest value is passed on to apps that embed the Engine.
To force a state active by hand, right-click it and choose Activate. On an Action state, this runs its On-Enter Actions.
Action state
Section titled “Action state”Select the state, then click the plus next to Add Action under On-Enter Actions or On-Exit Actions. Actions run in the order listed.
- On-Exit Actions run when an outgoing transition starts.
- On-Enter Actions run when the incoming transition has finished, so after its Transition Time.
- If any outgoing transition has a Button Condition, the buttons are cleared when the state is left.
- An Action state with no enabled outgoing transition runs its On-Enter Actions, then its On-Exit Actions straight away, and goes inactive. What it showed stays on screen until another action changes it.
| Attribute | Default | Meaning |
|---|---|---|
| Interval (seconds) | 1.0 | Time between ticks. Use a value above 0. |
| Start Active | On | The Timer runs from the start of the session, with no incoming transition. Turn it off to have a transition start it. |
| Entry Mode | Start Timer | What an incoming transition does. See below. |
| Loop Mode | Loop forever | Also Don’t loop and Loop x times. See below. |
| Tick Count | 3 | The Timer stops after this many outgoing transitions have started. Shown only with Loop x times. |
| First Tick | Off | Also allows outgoing transitions to start right after activation, without a tick. This works only until the Timer’s first outgoing transition has started in the session. |
| Entry Mode | Effect |
|---|---|
| Start Timer | Starts a Timer that has not run yet, such as one with Start Active off. Once the session has run for at least one Interval, the Timer ticks almost at once, not one Interval later. A running Timer carries on. |
| Restart Timer | Clears the Timer’s tick count, but the clock still measures from the start of the session. Once the session has run for at least one Interval, the Timer ticks almost at once, and a ready outgoing transition starts. Do not use this mode to delay a tick. It does not start a stopped Timer, so keep Start Active on and Loop Mode looping. |
| Toggle Timer | Meant to switch the Timer on and off with each incoming transition. From the code, an incoming transition does not reliably switch it off, so do not rely on this mode to stop a Timer. |
| Loop Mode | Effect |
|---|---|
| Loop forever | The Timer stays active and keeps ticking. |
| Don’t loop | The Timer stops after the first tick that starts an outgoing transition. |
| Loop x times | The Timer stops after Tick Count outgoing transitions have started. |
A tick counts toward Loop Mode only when an outgoing transition starts on it. A tick with no ready transition passes without effect. Each outgoing transition started on a tick counts once, so two transitions starting on the same tick count as two. With a Tick Count of 3 and two ready transitions on each tick, the Timer stops on its second tick.
A Timer stopped by Don’t loop, or by Loop x times with a Tick Count of 1, cannot be started again in the same session. A transition into it does not start. If the source is an Action state, it runs its On-Exit Actions and then stays stuck, so the flow stops there. Use Loop forever if the Timer must be entered more than once. With Loop x times and a Tick Count of 2 or more, a Timer that has stopped still accepts a transition: Start Timer starts it again, and Restart Timer leaves it stopped.
When a Timer ticks
Section titled “When a Timer ticks”A Timer does not count from the moment it became active. Its clock follows the Engine’s time, which starts at zero when you click Begin Session and keeps advancing while the session prepares and while it is paused. The Timer ticks each time that time passes another multiple of Interval. If the state machine was held when that happened, or the clock was not running, the missed ticks arrive together as one tick when the clock next updates.
- Preparation. A Timer with Start Active on ticks as soon as the session starts if its Interval is shorter than the time spent preparing. With a longer Interval, the first tick comes less than one Interval after the session starts.
- Pause. With an Interval of 60 s, 10 s of running and a 55 s pause, the Timer ticks right after Continue, not 50 s later.
- Started or restarted by a transition. Once the session has run for at least one Interval, the Timer ticks almost at once. It does not wait one Interval.
To wait a set time after a state is entered, use an Action state with a Time Condition on its outgoing transition.
Transitions
Section titled “Transitions”To draw a transition, press the left mouse button on the outer rim of the source state, drag to the target state and release. Click the arrow to see its attributes and conditions.
| Attribute | Default | Meaning |
|---|---|---|
| Disabled | Off | A disabled transition is never used. |
| Priority | 0 | Higher numbers win when several transitions are ready. |
| Transition Time | 0.25 | Seconds from the start of the transition until the target state is entered. |
A transition is ready when all its conditions are true at the same time. A transition with no conditions is ready as soon as its source state is active.
If several outgoing transitions are ready at once, the default Transition Mode starts all that share the highest Priority. Two ready transitions with the default Priority of 0 therefore both start, and both target states become active. Set different priorities if only one should run.
When a transition starts into a state, the conditions on that state’s outgoing transitions are reset. A Time Condition starts counting again, and any earlier button click, URL or player event no longer counts.
Conditions
Section titled “Conditions”Click a transition, then click the plus next to Add Condition under Conditions.
| Condition | True when | Attributes (default) |
|---|---|---|
| Time Condition | The source state has been active for the set time. | Use Randomization (off); Count Down Time In Seconds (1.0). With randomization on, Min Random Time In Seconds (0.0) and Max Random Time In Seconds (1.0) replace the fixed time. |
| Feedback Condition | The test on a classifier feedback value passes. | Feedback Node Name (empty); Test Function (feedback > testValue); Test Value (0); Range Value (0, shown only for the range functions) |
| Button Condition | The user clicked the button this condition shows in the Experience window. | Text (“Default Text”) |
| Audio Condition | A Play Audio file has reached its end. | Audio URL (empty); Test Function (Reached End); Num Loops (1, shown only for Has Reached Max Num Loops) |
| Video Condition | A Play Video file has reached its end. See the note below. | Video URL (empty); Test Function (Reached End); Num Loops (1, shown only for Has Reached Max Num Loops) |
| URL Condition | The Chrome extension reported this page address. | Opened URL (empty) |
| Browser Player Started Condition | Media started playing in the connected browser page. | None |
| Browser Player Paused Condition | Media paused in the connected browser page. | None |
| Browser Player Stopped Condition | Media reached its end in the connected browser page. | None |
Note: In the Experience window, nothing reports the end of a video to the Video Condition, in 1.8.2 or 1.7.3, so it stays false. To leave a state after a video, use a Time Condition set to the video’s length, or a Feedback Condition. Apps that embed the Engine report the end of a video themselves.
Feedback Condition. Feedback Node Name must match exactly the name of a Custom Feedback node or a control node such as Volume Control, in the active classifier. The condition reads the node’s first channel. If the node does not exist or has no value yet, the condition is false, whatever the Test Function.
| Test Function | True when |
|---|---|
| feedback > testValue | Greater than Test Value |
| feedback >= testValue | Greater than or equal to Test Value |
| feedback < testValue | Less than Test Value |
| feedback <= testValue | Less than or equal to Test Value |
| feedback != testValue | Not equal to Test Value, within a very small tolerance |
| feedback == testValue | Equal to Test Value, within a very small tolerance |
| feedback INRANGE [testValue..rangeValue] | Between the two values, including both ends. Their order does not matter. |
| feedback NOT INRANGE [testValue..rangeValue] | Outside the two values |
Button Condition. The button appears in the Experience window when the source state is active. Buttons appear only there, not in the browser.
Audio Condition. Audio URL must match the Play Audio URL exactly. Reached End is true once the file has ended at least once. Has Reached Max Num Loops is true once it has ended Num Loops times.
URL Condition. The Chrome extension sends the page’s full address once, when you click Connect in its popup. Opened URL must match it exactly, including any trailing slash. If the extension connects before the source state is entered, the event no longer counts. See Chrome extension.
Browser player conditions. The Chrome extension sends these for play, pause and ended events on any <video> or <audio> element in the connected page.
Use each one once. Studio hands each media or browser event to the first matching condition in the state machine, even if that condition’s state is not active, and then stops looking. A match means the same URL for Audio, Video and URL Conditions, and the same type for browser player conditions. So name each URL on only one transition, and use each browser player condition on only one transition.
Actions
Section titled “Actions”Add actions to an Action state, as described in Action state. The menu shows short names such as Show Text. The attributes panel shows the full name, such as “#0: Show Text Action”.
Most actions take effect in Studio’s Experience window. The browser actions go over the WebSocket interface to the Chrome extension, and do nothing in the Experience window.
| Action | Attributes (default) | What it does |
|---|---|---|
| Play Audio | Audio URL (empty); Volume (1.0, range 0 to 1); Loop Forever (off); Num Loops (1, hidden with Loop Forever); Allow Streaming (off) | Plays the file. Several files can play at the same time. |
| Stop Audio | Audio URL (empty) | Stops the file. |
| Pause Audio | Audio URL (empty); Unpause (off) | Pauses the file. With Unpause on, resumes it. |
| Seek Audio | Audio URL (empty); Position (s) (1.0) | Jumps to the position. The file must have been played already. |
| Action | Attributes (default) | What it does |
|---|---|---|
| Play Video | Video URL (empty); Volume (1.0, range 0 to 1); Loop Forever (off); Num Loops (1, hidden with Loop Forever); Allow Streaming (off) | Plays the file. There is one video at a time. The Experience window ignores Volume and plays at full level. |
| Stop Video | None | Stops the video and clears it from the window. |
| Pause Video | Video URL (empty); Unpause (off) | Pauses the video. With Unpause on, resumes it. The URL is not used, because there is only one video. |
| Seek Video | Video URL (empty); Position (s) (1.0) | Has no effect in the Experience window. |
Media files
Section titled “Media files”When Studio opens a Design, it downloads the files named by Play Audio, Play Video and Show Image in Action states. With Allow Streaming on, it skips the download. The file plays directly from its URL, unless an earlier download is still in the cache. A file that was not downloaded also plays directly from its URL.
Show Image is different. The Experience window shows an image only if the download has it. Otherwise it shows nothing, with no message. Studio downloads files only when it opens a Design. A state machine opened on its own downloads nothing, so Show Image shows nothing unless the file was downloaded earlier. Play Audio and Play Video still play there, directly from the URL.
To use Show Image, put the state machine in a Design. See Create a Design. Use a web URL. After you change the URL, save the state machine and open the Design again. The attribute’s tooltip also offers a local filename, but such a file is not downloaded, so the image does not appear.
The state machine also has a Media Root attribute. Nothing in the code reads it, so enter the full URL in each action.
Image, text and buttons
Section titled “Image, text and buttons”| Action | Attributes (default) | What it does |
|---|---|---|
| Show Image | Image URL (empty) | Shows the image, and replaces any earlier one. Animated GIFs play. |
| Hide Image | None | Removes the image. |
| Show Text | Text (“Example text”); Color (RGB 0, 159, 227) | Shows the text, and replaces any earlier text. |
| Hide Text | None | Removes the text. |
| Show TextInput | Text (empty); ID (0, range 0 to 1000) | Shows a text box filled with Text. Nothing in Studio reads what is typed, and the Experience window does not use ID. |
| Hide TextInput | None | Clears and hides the text box. |
| Set Background Color | Color (RGB 0, 159, 227) | Sets the window’s background color. |
| Clear Buttons | None | Removes all buttons from the window. |
Show Text can include feedback values. Write ${name}, where name is the name of a Custom Feedback node or control node. Studio inserts the value with two decimals, once, when the action runs. If the text has a placeholder and no classifier is active, the text is not shown.
Parameter
Section titled “Parameter”The Parameter action changes a Parameter node in the active classifier.
| Attribute | Default | Meaning |
|---|---|---|
| Parameter Name | Empty | The name of the Parameter node. Must match exactly. |
| Parameter Channel Index | 0 | Which channel to set. Hidden for Set to Feedback Value (all channels). |
| Function | Set to Value | See below. |
| Value | 1.0 | The value for the first four functions. |
| Random Min Value | 0.0 | Shown only for Set Random. |
| Random Max Value | 1.0 | Shown only for Set Random. |
| Feedback Name | Empty | The name of the feedback node. Shown only for the feedback functions. |
| Feedback Channel Index | 0 | Which feedback channel to read. Shown only for Set to Feedback Value. |
| Function | Effect |
|---|---|
| Set to Value | Sets the channel to Value. |
| Increase by Value | Adds Value to the node’s current value. |
| Decrease by Value | Subtracts Value from the node’s current value. |
| Scale by Value | Multiplies the node’s current value by Value. |
| Set Random [MinValue, MaxValue] | Sets a random value in the range. |
| Set to Feedback Value | Copies one channel of a feedback node. |
| Set to Feedback Value (all channels) | Copies each feedback channel to the matching parameter channel, as far as both exist. |
Increase, Decrease and Scale read the node’s current value from channel 0, whichever channel they set. If the node, the channel or the feedback node is not found, the action writes a warning to the log and changes nothing.
Browser
Section titled “Browser”These go to the Chrome extension. See Chrome extension for what it does with them.
| Action | Attributes (default) | What it does |
|---|---|---|
| Open URL | URL (empty) | Opens the address in a new browser tab. The extension accepts http and https only. |
| Start Browser Player | Progress (s) (1.0, range 0 to 1); Fullscreen (off) | Seeks the first <video> in the page and plays it. Despite its label, Progress is a fraction of the media’s length, so the default seeks to the end. Set a lower value. |
| Pause Browser Player | None | Pauses the first <video> in the page. |
| Stop Browser Player | None | Studio sends it, and the extension ignores it. |
Command
Section titled “Command”The Command action has one attribute, Command (empty). It sends the text to the connected visualization. If no visualization is connected, nothing happens.
Two older forms do more. doSwitchStage <index> also tells the visualization to switch to that stage. doSwitchApplication <name> also asks a connected starter client to switch application.
Related pages
Section titled “Related pages”- Getting Started
- Running a session
- Nodes, for Custom Feedback and Parameter nodes
- How to Give Users Feedback?
- Chrome extension
- What changed since 1.7.3