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

Try, catch, and using

Place a try catch node, wire the risky work to try and the recovery to catch, add clauses and finally from the right rail, and recognize a using node.

A try catch node puts the work that might fail on one white wire and the recovery on another. You build it by placing the node, wiring the risky work to try, and wiring what to do on failure to its catch output.

The node is orange-brown and titled TRY CATCH. On its right edge it has a try output for the work that might fail, one catch output per kind of error it handles, named by that error’s type (a new node has catch Exception, which handles any error), an optional finally output, and Completed for whatever runs after the whole node. When a catch names a variable for the error, the node also has a data output of that error’s type.

When the game runs, the nodes on try run first. If one of them fails, the rest of the try path is skipped and the first catch whose error kind and filter match runs instead. The nodes on finally run as control leaves the handler, whether the work succeeded or an error was thrown. If the handler finishes normally, the method carries on from Completed; an unhandled or rethrown error propagates instead.

The four shapes below are LoadCheckpoint, SaveCheckpoint, RetryCheckpoint, and WriteScore 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 a try catch node when something can fail for reasons outside your control and the game should keep going:

  • Loading a save file that might be missing or damaged: show a “new game” screen instead of freezing.
  • Reading a settings file a player edited by hand: fall back to the defaults.
  • Asking a web service for a leaderboard: show “offline” when the request times out.

Use finally for cleanup that must happen whether the work succeeded or not, such as hiding a loading spinner.

Compare these separate methods from FlowExamples. finally and catch-filter examples are paired with their source in What it writes; these two views distinguish an error-handling path from a resource scope with a visible body.

Compare recovery and resource scopes

Select a screenshot to enlarge it.

LoadCheckpoint routes try to ReadCheckpointFile and catch IOException to ReportLoadFailure, with an exception data wire.
Figure 1. Follow the handler: LoadCheckpoint The try and catch outputs own different white paths. The purple exception output supplies the error to ReportLoadFailure only on the handler path.
WriteScore opens a resource, then the blue USING node routes its body to WriteLine and its exit to RefreshHud.
Figure 2. Follow a resource scope: WriteScore OpenScoreFile supplies the resource. The USING node sends its body to WriteLine and its exit to RefreshHud; the writer output supplies WriteLine’s target.

The try catch node uses the try/catch family color, orange-brown #CD6133. A using node, described at the end of the steps, uses blue #2E86C1. The labels on each output carry the meaning when color is hard to tell apart.

In FlowExamples from the Platformer sample, start a new method with only its magenta entry node. This walkthrough calls it SaveCheckpointSafely.

Handle a checkpoint save failure

  1. Place try catch

    Right-click empty canvas to the right of the entry node. Search for try catch and pick it.

    A try catch node is placed from the canvas action menu. While the menu is open, its try catch row is highlighted with an arrow.
  2. Wire the entry

    Drag the entry node’s white Exec output to the try catch node’s Exec input.

    The entry Exec output is dragged to the TRY CATCH Exec input. The entry node's Exec output is highlighted with an arrow before the drag, then the TRY CATCH node's Exec input during it.
  3. Add the risky work

    Drag try onto empty canvas and choose WriteCheckpointFile.

    The try output is dragged to empty canvas and WriteCheckpointFile is selected. While it is dragged, the try output is highlighted with an arrow.
  4. Add recovery

    Drag catch Exception onto empty canvas and choose ReportSaveFailure.

    The catch Exception output is dragged to a ReportSaveFailure call. While it is dragged, the catch Exception output is highlighted with an arrow.
  5. Choose the error kind

    Select TRY CATCH. In the right rail’s Exception handling section, open Exception on Catch 1, search for IOException, and pick System.IO.IOException.

    The exception type picker, with the Exception dropdown on Catch 1 and the IOException result with System.IO beneath it highlighted.
    The catch card after the pick: the Exception dropdown reads IOException, the Variable box reads ex and is highlighted, and the node has a typed error output.
  6. Filter the catch

    Under When, choose Message contains and enter checkpoint in Contains.

    The catch card with the When dropdown set to Message contains and the Contains box reading checkpoint, both highlighted.
  7. Add and order catches

    Press Add catch. Use ↑ and ↓ to reorder the clauses and × to remove one. Return the narrower catch to the first position, then drag the broad catch Exception output to another ReportSaveFailure call so it reports other errors too.

    A second catch is added, moved, moved back, and an extra clause removed in the right rail. While that happens, the Exception handling section of the right rail, with the Add catch button and the clause controls, is highlighted.
  8. Add cleanup

    Press Add finally, then drag finally to CloseCheckpointFile.

    Add finally is pressed and its output leads to CloseCheckpointFile. While it is pressed, the Add finally button in the right rail is highlighted.
  9. Continue afterwards

    Drag Completed to RefreshHud for the work that follows the whole handler.

    The Completed output is dragged to a RefreshHud call. While it is dragged, the Completed output is highlighted with an arrow.
  10. Compile and reload

    Press Compile, beside Revert in the Previewing your changes notice at the top right of the window. Then look over the handler and its paths after the canvas reloads.

    The Previewing your changes notice at the top right of the window, with the Compile button highlighted beside Revert.
    The reloaded handler shows its try, catch, finally and continuation paths.

You can do the same clause work in a popover: right-click the try catch node and choose Edit catch clauses. The Catch clauses popover lists each clause with boxes for its exception type and variable, plus its when filter, and buttons for Add clause, Remove, Move up, Move down, Add finally and Remove finally. On a try catch node that came from the script, the right rail lets you change each clause’s error kind, variable and filter, but adding, removing or reordering clauses is only offered on a node you placed.

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

A try catch node with two clauses, a filter on the first, and a finally writes this shape. This one is drafted on the calls of CollectCoin on PlayerController in the Platformer sample:

Clause order, error kind, variable, filter and the nodes on each output come from the node. finally is written only when the node has a finally output. A throw node with nothing wired into it, placed on a catch path, writes the bare throw; that passes the caught error on. A using scope can be regenerated when its recorded resource declaration and acquisition inputs can be composed; unsupported shapes are refused rather than guessed.

When it goes wrong

SymptomCheckFix
Add catch, Add finally and Edit catch clauses are missing.Read the note at the bottom of the Exception Handling section. It says when the node came from the script.Change clause content in the rail, or place a new try catch node when you need to add or reorder clauses.
The when row reads (needs a variable).Look at the Variable box on that catch card.Type a name into variable, then choose the filter.
A narrow catch never runs.Read the catch order in the rail. A catch for System.Exception above it handles every error first.Move the narrow catch up with ↑.
Cleanup runs on only one path.Follow the cleanup node's white wire back. It may hang off try or a catch output.Press Add finally and wire the cleanup from the finally output instead.
Full-size image