*gosub_scene is an extension of the basic *gosub command.
Whereas an ordinary *gosub requires that its subroutine be located somewhere within the same scene file, *gosub_scene grants the ability to 'call' (i.e. load and run) a subroutine from any game file, further reducing the need to duplicate reusable code across multiple files.
For a fuller explanation of what a subroutine is, and how they actually work, please see the basic *gosub command page.
In the following example, the player is faced with a small group of hostile enemies and has a simple choice to make.
*choice #Strike the first blow. *set enemy_type "orc" *set enemy_group 4 *gosub_scene combat *finish #Flee! You very sensibly take to your heels and escape your pursuers. *finish
Should the player choose to engage in combat we are setting the type and number of enemies they face followed by *gosub_scene combat to 'call' a subroutine, thereby negating the need to include actual combat scripting in the current scene file.
The 'combat' file referenced by this command would essentially contain all the scripting and narrative required to handle this fight and describe it for the player, perhaps even in detailed blow-by-blow terms with choices along the way (if that is the nature of the game design). In addition, that combat routine could potentially handle all manner and types of enemies, perhaps in varying numerical strengths, and may even take all sorts of additional factors into consideration such as the protagonist's own armaments & skills.
Using the *gosub_scene command all of this scripting need be written just the one time, in a file of its own, and so be more easily refined and expanded as the game develops. More to the point, it can then also be 'called' - using *gosub_scene combat - at any point in any scene file, without needing to be duplicated in any other game file.
Of course, not every game will feature detailed combat of this nature (or perhaps similar features requiring extensive, reusable scripting of their own), but many will use a number of different, smaller subroutines for a variety of purposes such as Stats checks or providing conditional narrative responses. As *gosub_scene also allows us to reference a specific *label name if desired, it also allows us to keep all of our different subroutines in just a single file, effectively negating the need to include various minor subroutines in each & every individual scene file. For example:
*choice #Train body. *set strength +10 *set dexterity +10 *gosub_scene routines cap_stats You train your body. *finish #Train mind. *set intelligence +10 *set wisdom +10 *gosub_scene routines cap_stats You sharpen your mind. *finish
In this example we are 'calling' the subroutine cap_stats, which would be a particular *label section located somewhere in the file named routines. When it hits this *gosub_scene line, ChoiceScript will load the routines file behind-the-scenes, jump straight to the *label cap_stats line within that file, and immediately run the scripting there until it hits a *return command. At that point it will return to the current scene file's *gosub_scene line shown above, and continue on from there to display the appropriate narrative response below it.
To see what actual scripting the cap_stats subroutine might contain, see the *gosub command page.
Difference between Gosub_scene and Goto_scene
It is the basic nature of ChoiceScript to "unload" one scene when it loads another (i.e. when using either the *finish or *goto_scene commands), meaning that any existing scene-specific *temp variables and #option _reuse states (*hide_reuse, *disable_reuse & *allow_reuse) are lost from memory - mostly because they're no longer actually needed once the game advances to a new scene file.
*gosub_scene, however, essentially (if briefly) loads the indicated file behind-the-scenes and does not actually "unload" the current scene file in the process, meaning that unlike for a *goto_scene, all of the current scene's *temp variables and #option _reuse states are retained in memory and will still apply after the subroutine has been used.
|Choice||*choice, *fake_choice, *disable_reuse, *hide_reuse, *allow_reuse, *selectable_if|
|Variable||*create, *temp, *set, Arithmetic operators, *delete, *input_number, *input_text, *print, *rand|
|Conditional||*if, *elseif, *else|
|Goto||*label, *goto, *goto_scene, *goto_random_scene, *gosub, *gosub_scene, *finish|
|Formatting||Bold text, Italic text, *image, *line_break, *page_break, *link, *stat_chart|
|Miscellaneous||*comment, *scene_list, *title, *author, *achieve, *achievement, *check_achievements, *bug, *ending, *more_games, *share_this_game, *show_password, *script|