State-saving is an awfully awkward name for GgrTF's functionality for saving your settings and other interesting data for later retrieval. Settings get saved and thus restored later, but this functionality is not automatic by default, you have to set it up so if you wish - GgrTF only provides you the functions for loading and saving, making it to happen automagically is up to you. How to do this is discussed further below.
Almost all settings (hidden or visible) get saved, but there are certain global settings that you have to set yourself in your TF configuration. These settings are discussed in sub-section below.
It should also be noted, that there are actually two different types of data (or variables) that is saved into two different files. In GgrTF, these two types of data are called pre- and post-init settings, and the two savefiles are named accordingly. Pre-init settings are variables that need to be defined before the main modules of GgrTF are loaded in TF's startup configuration (certain functionality depends on this). Post-init variables can (and sometimes must) be set after loading of all modules.
There are currently three special GgrTF variables, which you have to set yourself in your TF's startup configuration (.tfrc). These variables MUST be set before loading of ANY GgrTF modules, otherwise things start breaking and the state-saving system does not work correctly.
Table 4.3. Special, non-saved variables
| Variable | Description | Example |
|---|---|---|
| set_plrname | Your character's name, written in correct case. | /set set_plrname=Ggr |
| set_datapath | Path to the directory where you want your savefiles to reside. If left empty, current working directory is used (the directory you started TF from.) | /set set_datapath= |
| set_saveprefix | This string is used as prefix of the two savefiles, so the actual savefiles are "<prefix>pre.tf" and "<prefix>post.tf". This is useful, if you play regular BatMUD and HCBat, so you can use different values for either. | /set set_saveprefix=bat- |
Getting GgrTF's state-saving to work requires some changes to your TF configuration, and possibly setting up a savefile directory
A simplified example configuration layout is presented below with only the state-saving related parts, please refer to setup-section of this manual for a more detailed example. Pay close attention to the order how things are done, it is very important!
;; Set directory path where savefiles will be stored
/eval /set set_datapath=%{HOME}/.ggrtf/
;; Set prefix string for savefile names
/eval /set set_saveprefix=bat-
;; Load the special pre-init module which loads pre-init
;; settings from the savefiles. This needs to be done
;; before loading any other GgrTF modules.
/gloadmod ggrtf-pre.tf
;; Load GgrTF core module
/gloadmod ggrtf.tf
;; Load other additional modules
/gloadmod gm-magical.tf
; etc etc.
;; Load and restore other previously saved settings.
;; This should be done after loading any GgrTF modules.
/gload
When you have edited your TF configuration, you need to (re-)start it, change settings the way you want them to be and finally issue "/gsave" command to get settings saved. After saving, you may also want to examine the pre-init -savefile, because it contains certain settings that cannot be changed run-time . So, here are the steps in short again:
Edit TF configuration (see example above): Add set_datapath, set_saveprefix settings and add commands to load ggrtf-pre.tf module and /gload command.
Re-start TF: In order to create the initial savefiles with default settings, you need to (re-)start TF, so that the save-state system is enabled.
Change settings: Change GgrTF settings (listed via /opts etc.) to accommodate your desires.
Save initial settings: Issue "/gsave" to get settings saved.
Optionally edit pre-init settings: Certain settings are saved into the pre-init savefile (actual filename is dependant on what you set "set_saveprefix" to). GgrTF does not offer any special interface to change these settings, you have to edit this file by hand, if you wish to change the defaults.
In previous example, I only described how settings get restored (as TF loads and initializes GgrTF), but how to get settings saved automatically too?
The answer lies in TinyFugue's event hooks. It is possible to define a hook, which is executed when TF disconnects from a world. By setting this hook to perform "/gsave", we can automatize the process of saving settings. Add following line to your TF configuration: /def -hDISCONNECT mydisconnect = /gsave There is one gotcha: if you don't want to keep saving the statistical values, but
only the settings, you may want to add a "/greset" in the soup: /def -hDISCONNECT mydisconnect = /greset%;/gsave
<> = required argument, [] = optional argument
Table 4.4. Macro commands
| Command | Description |
|---|---|
| /gsave | Save all GgrTF settings and certain other TF variables. |
| /gload | Load GgrTF settings. Only post-init settings get loaded by this command, to get pre-init settings in effect, you will have to restart TF. |
| /greset | Reset all skill/spell counters and statistics. Notice that issuing this command also requires executing of "/gsave" if you want to save the zeroed statistics, otherwise the currently saved statistics will be restored on next /gload. |