**(go-to: // [[harlowe:String|String]]//) -> //[[harlowe:Command|Command]]//**

This [[harlowe:Command|Command]] stops passage code and sends the player to a new passage.
If the passage named by the [[harlowe:string|string]] does not exist, this produces an error.

=== Example usage: ===

''%%(go-to: "The Distant Future")%%''

=== Rationale: ===

There are plenty of occasions where you may want to instantly advance to a new
passage without the player's volition. (go-to:) provides access to this ability.

(go-to:) can accept any expression which evaluates to
a string. You can, for instance, go to a randomly selected passage by combining it with
[[harlowe:either|(either:)]] - ''%%(go-to: (either: "Win", "Lose", "Draw"))%%''.

(go-to:) can be combined with [[harlowe:link|(link:)]] to accomplish the same thing as [[harlowe:link-goto|(link-goto:)]]:
''%%(link:"Enter the hole")[(go-to:"Falling")]%%'' However, you
can include other macros inside the hook to run before the (go-to:), such as [[harlowe:set|(set:)]],
[[harlowe:put|(put:)]] or [[harlowe:save-game|(save-game:)]].

=== Details: ===

You can attach [[harlowe:changer|changers]] like [[harlowe:t8n-depart|(t8n-depart:)]] and [[harlowe:t8n-arrive|(t8n-arrive:)]] to this to
alter the transition animation used when (go-to:) activates. Other kinds of changers
won't do anything, though.

If it is performed, (go-to:) will "halt" the passage and prevent any macros and text
after it from running. So, a passage that contains:

<code>
(set: $listen to "I love")
(go-to: "Train")
(set: $listen to it + " you")
</code>
will //not// cause ''%%$listen%%'' to become ''%%"I love you"%%'' when it runs.

Going to a passage using this macro will count as a new "turn" in the game's passage history,
much as if a passage link was clicked. If you want to go back to the previous passage,
forgetting the current turn, then you may use [[harlowe:undo|(undo:)]].

=== See also: ===

[[harlowe:link-goto|(link-goto:)]], [[harlowe:undo|(undo:)]], [[harlowe:loadgame|(loadgame:)]]