Is a small addon script for ChoiceScript to allow control over persistent (hard) saves.
It provides both a Visual Novel-esque quick save menu, and some additional ChoiceScript commands, in order to give you the greatest flexibility over how and where you game can be saved.
As the ChoiceScript save plugin is an unofficial 'addon' for ChoiceScript, there are a few technical steps required to get it up and running.
First and foremost, you'll need to download the latest copy of the JavaScript file here. Next, you'll need to add that file to your game's 'web' folder, next to the other script files, as shown below.
Now you'll need to make two small edits to your game's index.html file (the one in the 'mygame' folder, not the one located in the 'web' folder).
The first edit is to include the script you just downloaded, so that the game knows where to find it.
If you've got the previous steps correct and have the right index.html file, this should be a simple copy and paste of the following line: <script src="../ChoiceScriptSavePlugin.js"></script>. The positioning is important, so make sure to place it between navigator.js and mygame.js, as shown below.
Last, but not least, you'll need to provide a unique name to identify your game and its saves, as shown below. Note that this should be something that is unlikely to change or clash with another game's. "MY_GAME" is a bad example, as is "MY_WIP".
Also note that if you ever wish to disable the 'persistent session' behaviour in ChoiceScript, you can set this back to window.storeName = null;, though this will also disable the saving mod.
Unlike the previous save plugins (save.js, smPlugin.js and smPluginMenuAddon.js) this plugin leverages heavily on save behaviour that is already present within the ChoiceScript interpreter. Whilst this greatly simplifies and improves the stability of the plugin, it does come with a few caveats. Most notably is the requirement to enable the 'persistent storage' behaviour of ChoiceScript games. This is where the game will 'remember' where you left off, should you leave and return to the page. Much the same as the games published on the choiceofgames.com site. Whilst helpful when playing, this behaviour can prove rather detrimental during development. It is suggested that you disable this when developing your game, via setting window.storeName back to null.
Though both built upon the system mentioned above, the ChoiceScript save plugin provides two different interfaces for handling saving and loading in your ChoiceScript game.
The recommended way to use the plugin is via 'quick save menu' and its associated controls.
If you've installed the plugin correctly then this menu should appear automatically, and will self-populate with any saves based on the window.storeName you provided. Aside from the obvious UI injection, this interface is relatively non-invasive and shouldn't heavily effect your development workflow.
Unlike the quick save menu, the sm_ commands (sm_load, and sm_save) are a highly invasive way of interfacing with the save/load functionality provided by the plugin and ChoiceScript interpreter. As they are new and unofficial commands, they will at the very least, cause issues with QuickTest and RandomTest (and will likely require commenting out). Usage of these commands may also produce some unexpected behaviour, such as load/save loops, or duplicate saves (when loading/refreshing into a page containing a save command).
Note that unlike the previous smPlugin.js addon, the *sm_save command will not save the game at the exact position it appears, but will rather in effect save from the start of the current visible page (regardless of where it is placed in the code).
That said, usage of these commands does still allow for more developer flexibility over how saving/loading is implemented in the game. Some examples being the implementation of autosaves, or restricting saving/loading to certain menus or game segments.
You can see the save.txt file in this repostiory's examples folder for inspiration on how to use the following commands.
Creates a new save at the point of the last 'page' turn. Optionally, a string name for the save can be provided.
*sm_save, *sm_save "My Save Name" or *sm_save my_string_var etc.
Loads the game with the given id.
*sm_load my_save_id or *sm_load 1390323109 etc.
Deletes the save with the given id.
*sm_delete my_save_id or *sm_delete 3211245125 etc.
Due to the nature of ChoiceScript execution (synchronous) and the nature of saving/loading (asynchronous), it is difficult to guarantee the accurate population of these variables in time for ChoiceScript's execution. The recommendation thus is to use *sm_update way in advance of requiring it, to ensure you don't encounter stale information or unintalized variables.
Populates (or updates) the following helper variables:
- (number)
_sm_save_count: The number of saves detected. - (array of numbers)
_sm_save_id_x: These variables hold the ID (used for loading and deleting) of the given save. - (array of strings)
_sm_save_name_x: These variables hold the name for the given save (if it has one). - (array of strings)
_sm_save_date_x: These variables hold a string formatted date marking the save time.
Disable (hide) or enable (show) the quick save menu.
*sm_menu true enables (shows).
*sm_menu false disables (hides).
*sm_menu toggles the current state.