startup.txt is one of the two default text files (the other being choicescript_stats.txt) required by every ChoiceScript game, which cannot be renamed and must follow a prescribed format.
startup.txt can be found in the "scenes" (..\web\mygame\scenes) folder of your ChoiceScript directory.
NB: All other text files you create for your game (collectively referred to as its "scene files") should also be placed in the "scenes" folder. However, you are free to name additional scene files whatever you like, provided that there are no spaces or capital letters used in the file name and that each name is unique.
What is startup.txt used for?
startup.txt serves three main purposes. The first is to name your game using the *title command and identify the Author using the *author command. These should be the first two commands used in that file (with the only exception being any *comment inserted at the very top).
The second essential purpose of startup.txt, and the next command listed in this file, should be your game's *scene_list. Immediately below this command (and indented accordingly) is where you list the new scene files as you add them to your game, which tells ChoiceScript in what sequence your scenes are intended to appear in the game. Think of them as Chapters in an ordinary book: ChoiceScript needs to know that chapter2 (or whatever you choose to call your scene) follows chapter1, in sequence. Then, when ChoiceScript hits an end-of-scene *finish command in one scene file, it will know -- from the *scene_list in startup.txt -- exactly which scene file it should load next.
Declaring permanent variables
The third important purpose of startup.txt is to "declare" the permanent variables that your game will use to store necessary information -- game data, in essence -- for use in your story scripting and on the game's Stats Screen. This essential information includes the unique name of each variable, its data type (either numeric, string or boolean) and the default starting value each will contain. Default variables are declared in startup.txt using a series of *create commands: there is no real limit to the number of these you may use.
*title My First ChoiceScript Game *author Jane Doe *scene_list startup chapter1 *create name "Unknown" *create gold 0 *create backpack false
In this example, our startup.txt file has the game *title and *scene_list commands properly preceding the list of starting game variables. Our first two scene files - startup and chapter1 - are also listed as required (and that list will grow as we create new scene text files for our game and add them to the *scene_list in sequential order).
In addition, we have created and named the first three of our game variables, each of which is using a different data type, although there is no real limit to the number of variables we may create and add here as our game grows and develops -- which is one of the reasons why it's generally a good idea to begin the story itself in the next scene file in the *scene_list (in this case 'chapter1').
Although the example game which comes with your ChoiceScript download also uses startup.txt to immediately launch into the first part of the example story scripting, note that this is not strictly necessary. For your own game, you may prefer, as some experienced authors do, to limit the use of startup.txt to just the three vital requirements described above, and to start your actual story / game scripting in the first proper scene file. However, startup should still be the very first 'scene' listed under *scene_list, regardless.
Note that you do not need to use a *finish command in startup.txt if it does not contain any actual story scripting; if the last line in this file is a *create it will automatically load the next scene in the *scene_list.