State-saving

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 can be loaded, 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.)

What is saved?

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.

Special, non-saved variables

There are currently three special GgrTF variables, which you have to set yourself in your TF's startup configuration (".tfrc"-file). 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 3.2. 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-

How to setup TF for state-saving

Getting GgrTF's state-saving to work requires some changes to your TF configuration, namely the ".tfrc"-file. First of all, you need to set the special variables, so that the loading and initialization work correctly. Secondly, a special module ggrtf-pre.tf must be set to load before any other GgrTF components are to be loaded (this special module loads the pre-init settings). Third, after all GgrTF modules have been loaded, /gload macro must be issued so that previously saved settings will be restored.

A simplified example configuration layout is presented below, 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 special variables before loading scripts

;; Player character name (notice the case, "Ggr" instead of "ggr" or "GGR")
/set set_plrname=Ggr

;; Path of directory where savefiles will be stored, empty is CWD
/eval /set set_datapath=%{HOME}/ggrtf/
/def -i gloadmod = /eval /load %{HOME}/ggrtf/%{*}

;; Prefix string for savefile names
/set set_saveprefix=bat-


;; Load the special pre-init module
/gloadmod ggrtf-pre.tf

;; Load GgrTF core
/gloadmod ggrtf.tf

;; Load other additional modules
/gloadmod ggrtf-misc.tf
/gloadmod ggrtf-magical.tf
/gloadmod ggrtf-rais.tf
/gloadmod ggrtf-tarma.tf
/gloadmod ggrtf-druid.tf
/gloadmod ggrtf-pssmangle.tf
/gloadmod ggrtf-pplacer.tf
/gloadmod ggrtf-spellnames.tf
/gloadmod ggrtf-tf5.tf

;; Perhaps load some key bindings
/gloadmod kbd-xterm.tf

;; Restore previously saved settings
/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:

  1. Edit TF configuration: Add required settings, "ggrtf-pre.tf"-module and /gload directive.

  2. Re-start TF: In order to save initial settings, you need to (re-)start TF, so that the save-state system is enabled.

  3. Change settings: Change GgrTF settings (listed via /opts etc.) to accommodate your desires.

  4. Save initial settings: Issue "/gsave" to get settings saved.

  5. 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.

How to make state-saving automatic

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

Macro commands

<> = required argument, [] = optional argument

Table 3.3. Macro commands

Command Description
/gsave Save all GgrTF settings and other certain variables.
/gload Load GgrTF settings.
/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 loaded on next /gload.