Skip to content
Bit Quirky Round Trip
Visual Scripting

Search documentation

All topics and APIs

Close returns focus to Search.

What are you looking for?

Try a common topic or a C# feature.

Browse the reference instead

Esc closes · Tab reaches results · Enter opens the focused link

v1.0.0
Menu

Return and throw

Place an EXIT node to stop a method early or hand back its result, and place a throw node to stop it with an error.

Every place a method can stop is a magenta node titled EXIT. Put one on the side of a branch that should give up, and the nodes after it never run on that path.

An EXIT node ends the method as soon as the white wire reaches it. In a method that hands back a result, the node has a value pin for that result; in a method that hands back nothing, it has only its Exec input.

A throw node, titled THROW, also ends the method, but with an error: Unity stops the work and reports it in the Console, and any catch wrapped around the call gets a chance to handle it. Inside a catch, a RETHROW node passes on the error that catch received.

Because each stop is its own node, a glance at the canvas shows every way out of the method. The four shapes below are CoinsStillNeeded, OpenGoalOnce, SetCoinsToUnlock, and SaveCheckpointOrFail in FlowExamples, a class in the Platformer sample that holds one small method per flow shape so you can open the same diagrams yourself.

Reach for an EXIT node when a method should do nothing in some situations:

  • A coin pickup that should stop if the coin is already collected.
  • A door that should stop if the player arrives while it is still locked.
  • A stomp that should stop if the enemy is already defeated.

Put each of those checks at the start of the method, each with an EXIT node on its stopping side, and the real work sits on one straight white wire after them. Use EXIT with a value at the end of a method that answers a question, such as “can the player jump?”. Use a throw when continuing would leave the game in a broken state, such as a required reference that was never assigned.

These are separate example methods, not steps in one edit. Compare the value handed back by EXIT with the exception passed on by RETHROW. The early-return and new-exception examples are paired with C# in What it writes.

Compare a returned value with a rethrown error

Select a screenshot to enlarge it.

CoinsStillNeeded wires SUBTRACT into the value input of EXIT.
Figure 1. Return an answer: CoinsStillNeeded The white wire reaches EXIT, and the subtraction supplies its value. A void method has no value pin to fill.
SaveCheckpointOrFail routes catch IOException through ReportSaveFailure into RETHROW.
Figure 2. Pass on the caught error: SaveCheckpointOrFail The catch reports the failure, then reaches RETHROW. No new exception is constructed: the same caught error continues to the caller.

Start in a method whose canvas holds only its magenta entry node, the node titled with the method’s name that has an Exec pin and a self pin. To compare each step with a finished diagram, open FlowExamples in the Platformer sample beside it; the steps name the example that shows each piece.

Build a stop, a chained check, and a throw

  1. Place the check

    Place the check first. Right-click empty canvas, pick branch under flow control, and wire it from the entry node’s Exec output. Wire the question into its red Condition pin, as described in Branch.

    Clip: the whole Graph view window with the Variables list in the left rail. The pointer right-clicks empty canvas beside the entry node, types branch in search and clicks the matching row: a yellow BRANCH node lands there with a hollow condition pin. It then drags a white wire from the entry node's exec output to the branch's exec input, drags _goalUnlocked from its row in the Variables rail onto empty canvas, chooses get, and drags from the pill's dot into the branch's condition pin. In turn the highlight marks the branch row in the menu, the entry node's exec output, the branch's exec input, the _goalUnlocked row of the rail, the get row of the menu, the pill's dot and the condition pin, each with an arrow pointing at it.
  2. Place EXIT

    Right-click empty canvas beside the branch and pick return under flow control, or type return in search and pick the return row. A magenta node titled EXIT lands where you clicked.

    Clip: the pointer right-clicks empty canvas beside the branch, types return in search, and clicks the matching row: a magenta EXIT node lands where it clicked. While the menu is open, the return row is highlighted with an arrow.
  3. Wire the stopping side

    Drag from the branch output that means “stop”, often true, to the EXIT node’s Exec input. A white wire joins them.

    Clip: the pointer drags a white wire from the branch's true output to the EXIT node's exec input; a white wire joins them. The true output is highlighted with an arrow before the drag, then the EXIT node's exec input during it.
  4. Wire the continuing side

    Wire the real work from the branch’s other output.

    Clip: the pointer drags a white wire from the branch's false output onto empty canvas; the statement menu opens, the pointer types Log in search and clicks the matching row, and a Log call lands there, wired from false. The false output is highlighted with an arrow during the drag, then the Log row in the menu.
  5. Chain another check

    For more reasons to stop, chain another branch on that continuing wire and give it its own EXIT node.

    Clip: the pointer drags a white wire from the branch's false output onto empty canvas and types branch in search, inserting a second yellow BRANCH in Log's old place and rewiring Log to its false output. The pointer then right-clicks empty canvas to place a second magenta EXIT node and drags the new branch's true output into it. The control in use is highlighted with an arrow at each moment: the false output, the branch row, the new branch's false output, Log's exec input, the return row, the new branch's true output, and the new EXIT node's exec input.
  6. Return a value

    In a method that returns a value, place an EXIT node at the end of the work too, and fill its value pin: drag a wire into it from a pill or a node’s result, or type a value straight into the pin when it offers a text box or a checkbox.

    Clip: on a fresh int-returning NewValueMethod draft whose only work is an unused SUBTRACT fed by the _coinsToUnlock and _coins pills, the pointer drags a white wire from the entry node's exec output onto empty canvas, types return in search, and a fresh EXIT node lands at the end of the work, wired in, with a value pin for the int result. The pointer then drags a wire from the SUBTRACT node's result dot into the EXIT node's value pin: that expression is the returned value. The control in use is highlighted with an arrow at each moment: the entry exec output, the return row, the SUBTRACT result dot, and the value pin.
  7. Place THROW

    To stop with an error instead, place throw under exceptions, then click the new THROW node.

    Clip: the whole Graph view window, with the Previewing your changes notice and the right rail visible. On a draft whose entry node is wired to a branch, the pointer right-clicks empty canvas to the right, types throw in search, and clicks the matching row under exceptions: a THROW node lands with an exec input and an exception pin. The pointer then clicks the node, and the right rail's Throw section reads Throws Not set. The throw row of the menu, then the Throw section of the right rail, are highlighted in turn, each with an arrow pointing at it.
  8. Place and name the exception

    Place Exception under exceptions. Click the node it creates, open the Type list in the right rail’s Exception section, and pick the kind of error, such as System.InvalidOperationException. Drag from its output to the throw node’s Exception pin.

    Clip: the whole Graph view window, with the right rail visible. The pointer right-clicks empty canvas beside the THROW node, types exception in search, and clicks the matching row under exceptions: a node that builds an error appears. The pointer clicks the node and the right rail's Exception section shows its Type; the pointer rests on the Type field while the type changes to System.InvalidOperationException (the list itself is a Unity popup that the clip does not draw). It then drags a wire from the exception node's output to the THROW node's exception pin. The highlight marks, in turn, the exception row of the menu, the Exception section of the right rail, the Type field, the exception node's output and the THROW node's exception pin, each with an arrow pointing at it.
  9. Wire the failing side

    Wire the throw node from the path that should fail, just as you wired the EXIT node in step 3.

    Clip: the pointer drags a white wire from the third branch's true output to the THROW node's exec input; a white wire joins them. The true output is highlighted with an arrow before the drag, then the THROW node's exec input during it.
  10. Compile

    Press Compile, beside Revert in the Previewing your changes notice at the top right of the window.

    The Previewing your changes notice at the top right of the window, with the Compile button highlighted beside Revert. It is shown here on another method; the notice looks the same on any draft.
    The reloaded canvas after Compile: NewMethod's exec leads into a BRANCH fed by _goalUnlocked, whose true output reaches an EXIT; its false output continues to a second BRANCH, whose true output reaches a second EXIT; its false output continues to a third BRANCH, whose true output reaches a THROW node fed by a new System.InvalidOperationException, and whose false output reaches a Log reading Keep going.

If you also work in C#, this is what lands in the script. FlowExamples.OpenGoalOnce and FlowExamples.SetCoinsToUnlock are written as:

An EXIT node writes return, plus the value on its value pin when it has one. Compile writes it on the line after the node it is wired from, so an EXIT wired after a statement inside an existing if lands inside that if. A chain of new set, return, or throw nodes wired from the entry node is written before the first statement it leads into, or at the end, and that works in a method added in the same Compile. A throw node writes throw plus the exception on its Exception pin. A bare throw; inside a catch rethrows the error that catch received, and a throw can also sit inside a value, such as input ?? throw new ArgumentNullException(nameof(input)).

When it goes wrong

SymptomCheckFix
The EXIT node has no value pin.Click empty canvas and read the method's return type in the identity header at the top of the right rail.A method that returns nothing has no value to hand back. Add an output in the right rail's Outputs section if the method should return one.
Work after a check never runs.Follow the white wire from the branch. The EXIT node may be on the output that should continue.Drag the wire to the EXIT node from the other output, and wire the work from the one that should continue.
Compile refuses a throw outside a catch.Click the throw node. The Throw section reads not set when nothing is wired into exception, and a throw with nothing wired only works inside a catch, where it passes on the caught error.Place an exception node, pick its type, and wire it into the exception pin, or move the throw onto a catch output.
Full-size image