\lchapter{The \reallive\ system}

\lsection{Overview}

  \reallive\ is an engine designed to power \textit{bish\omac jo} games such as
  visual novels and simple simulations; it is based around a fast
  Turing-complete bytecode interpreter, and provides functionality for text and
  graphics, sound, music, and simple animation, along the lines that such games
  require.  Notable products based on the \reallive\ engine include Key's
  \opus{Clannad}, \opus{Planetarian}, and \opus{Kanon Standard Edition}, and
  130cm's \opus{Princess Bride} (not to be confused with the book/film of the 
  same name).

  \index[concept]{gameexe.ini} A \reallive\ game is made up of four main parts:
  the interpreter (\file{avg2000.exe}, \file{reallive.exe}, or
  \file{kinetic.exe}), the configuration file (\gameexe), the scenario
  file (typically \file{seen.txt}\footnote{While other names are possible, I
  don't know of any games that use them.  The name `seen' appears to derive from
  a misunderstanding\,\textemdash\,the word intended is clearly `scene', and in
  Japanese the two are of course not only homophones but homographs as well.}),
  and accompanying data files, which vary in type and number, but typically
  include graphics (in the \file{g00} and \file{pdt} formats), animations (in
  the \file{gan} and \file{anm} formats), and music (in the \file{nwa} format).
  Of these parts, \package\ deals only with the scenario file and graphics,
  although \compiler\ reads certain settings from \gameexe\ when
  compiling.\footnote{Utilities to handle the remaining proprietary formats are
  planned, but at present those wishing to modify resources other than bytecode
  and bitmaps must look elsewhere.}

  Note that in the case of DRM-protected games, the configuration and data files
  are further compacted into a single file (typically \file{kineticdata.pak}),
  which is encrypted using a rather stronger method that I have not yet
  discovered how to unlock.  It is not possible to access the files this
  contains directly with \package, although it is simple enough to extract the
  contents manually from a memory dump of a running game.

  There exists a clone of the \reallive\ interpreter, Jagarl's \file{xclannad} 
  (currently at \mbox{\url{http://www.creator.club.ne.jp/~jagarl/xclannad.html}}).
  The latest version at the time of writing, 0.06, did not implement enough 
  features to be a viable replacement, but it promises to become such with 
  time.

  \lsubsection{Targets and versions}\label{sec:targver}
  
    The family of interpreters I refer to here as \reallive\ actually comprises 
    three more-or-less distinct interpreters: \avgns, \reallive, and Kinetic. 
    While the API and basic bytecode format used by all three is essentially 
    identical, they are not compatible: \avgns\ (the original successor to 
    AVG32, later renamed to \reallive) uses a different scenario header and 
    encoding scheme, and Kinetic (a special DRM-enabled interpreter used only 
    for the Kinetic Novel series) reassigns a large number of fundamental 
    operations in what appears to be a futile attempt to make 
    reverse-engineering harder.
    
    To complicate matters, however, the API itself is under constant 
    development.  There are significant differences between versions.  For 
    example, the \fnref{grpRotate} functions were introduced in 1.1.5, and auto 
    mode early in the 1.2 series.  There is no fixed mapping between the 
    API/bytecode version (the ``version'') and the header/basic operation types 
    (the ``target''): the \avgns\ interpreter was retired at around version 
    1.0.0.8, and the Kinetic interpreter introduced at version 1.2.6.4, but 
    \reallive-proper interpreters can be found at all stages of development.
    
    When compiling for a \reallive\ interpreter, therefore, the target and 
    version must both be chosen separately.  Bytecode compiled for a 
    1.1-series \reallive\ will normally run perfectly on a 1.3-series 
    \reallive,\footnote{There have been several cases of API breakage, though; 
    the DLL interface was changed incompatibly around version 1.2.5, and the 
    \fnref{grpDisplay} function around 1.0.9, to name but two.} but the converse 
    is not true, and bytecode compiled for \reallive\ 1.2.7.0 is incredibly
    unlikely to run in Kinetic 1.2.7.0.  Since different versions of games 
    sometimes use incompatible interpreters, you will probably have to 
    recompile code with different flags or directives if you are working on 
    such a game.  In most cases, however, \compiler\ will manage to 
    generate suitable code for any interpreter from any source code, given 
    the correct compilation settings.
  
    Except where otherwise specified, the version documented here is basically 
    1.2.6.8 (as supplied with \opus{Kanon Standard Edition}).  Other versions 
    have not been exhaustively tested: differences and limitations are 
    documented where I'm aware of them, but in general you should not assume 
    that any feature mentioned in this manual is necessarily available, 
    particularly if you're working with a 1.0- or 1.1-series interpreter. Note 
    that very few tests have been carried out with the 1.0.0.8 interpreter, and 
    practically none with \avgns.
      
  
\lsection{Scenarios}\label{sec:scenarios}\index[concept]{scenarios}

  The scenario file contains the game logic.  It is a simple archive of up to
  9,999 individual compilation units, termed `scenarios', which are named
  \file{seen0001.txt} to \file{seen9999.txt}; each of these is an individually
  compressed and self-contained block of \reallive\ bytecode.

  The scenarios represent the major divisions of a program; only code from one
  scenario can be accessed at any one time, though switching between them can
  easily be done with the \fnref{jump} and \fnref{farcall} functions, and up to
  100 entrypoints may be defined within each scenario, effectively permitting
  access to arbitrary locations.  A common idiom is to define several related
  functions (particularly where they share code) in one scenario, and use
  \fnref{farcall} with an entrypoint index to access them from the rest of the
  game; this works on the same principle as linking a library into a C program,
  but in \compiler\ it must be done by hand.

  It is not necessary to build a scenario file in order to run code: if a file
  of the form \file{seenNNNN.txt} exists in the same directory as the scenario
  file, its contents will override the scenario of that number.  This can be
  convenient when debugging, and is the only trivial way to inject custom code
  into a DRM-protected game.

\lsection{Debugging}\index[concept]{debugging}

  The \reallive\ interpreter contains a convenient debugger, which can be 
  enabled by defining \ivarref{MEMORY} in \gameexe.  The various debugging 
  features can be accessed with function keys or from drop-down menus. Of 
  particular use are the single-step execution mode (\texttt{F3}), the memory 
  editor (\texttt{F5}) and the graphics DC viewer (\texttt{F7}).

  Debug mode also enables a number of runtime warning messages relating to
  matters such as memory management; these do not always represent problems, but
  it's probably wise to try to eliminate them anyway.
  
  Finally, there are various message-box and input-related functions which are 
  only processed in debug mode.  See \ref{sec:debugfunctions} for a full list.
  
  From version 1.3 onwards, single-step mode is replaced with a simple source 
  debugger.  This is usable with Kepago - you must rename your source file to 
  have the extension \file{.ORG} and set up the path to that file in the 
  debugging options dialog within the interpreter - but does not work very well 
  with Kepago features like header files, and it is \emph{not} likely to be 
  usable with disassembled code (in which lineation information is never 
  preserved), so its utility to developers using \package\ is limited.  It 
  does, however, provide a slightly more intrusive form of single-step 
  execution regardless of whether source code is available or not.

\lsection{Memory}\label{sec:memory}\index[concept]{memory}

  Only statically allocated memory is available, in the form of a number of
  arrays of variables; there is no stack.

  Variables are divided into `local' and `global' types.  The values of local
  variables are reset when the program is executed, and stored in saved games.
  Global variables are persistent, and their values are shared between all saved
  games.

  \lsubsection{Integers}\label{sec:integers}

    \lsubsubsection{Integers}\index[concept]{variables!integer memory}

      \reallive\ provides unsigned 1, 2, 4, and 8-bit integers, and signed
      32-bit integers; these share the same memory, so individual bits and bytes
      can be examined and modified without resorting to bitwise operators and
      shifts. There are eight separate integer spaces, each of 8,000 bytes.

      Local 32-bit integers are stored in \lstinline|A[0]| to
      \lstinline|A[1999]|, and likewise \lstinline|B[]| to \lstinline|F[]|;
      \lstinline|G[]| and \lstinline|Z[]| are global equivalents.

      The smaller elements are accessed through arrays \lstinline|A8b[]|,
      \lstinline|A4b[]|, \lstinline|A2b[]|, \lstinline|Ab[]|, and similarly
      named equivalents for \lstinline|B[]| to \lstinline|G[]| and
      \lstinline|Z[]|. Indexing is based on the element size: the 8-bit arrays
      have elements from 0 to 7,999, arranged such that the four bytes of
      \lstinline|A[100]| can be accessed as \lstinline|A8b[400]| to
      \lstinline|A8b[403]|, in the little-endian order; this pattern is
      consistent, so for example \lstinline|Gb[42784]| shares the same memory
      as the least significant bit of \lstinline|G[1337]|.

      These memory spaces are accessed through variables, either those that you 
      define yourself, or a set of built-in arrays that correspond directly to 
      the memory spaces.  To avoid restricting useful single-character 
      identifiers, \compiler\ adds the prefix `int' to the names in declaring 
      these arrays.  For example, the memory cell \lstinline|A[100]| may be
      accessed by referencing the variable \lstinline|intA[100]|.

    \lsubsubsection{The store register}\label{sec:store}\index{store}\index[concept]{variables!store}

      There also exists a special integer variable \lstinline|store|.  This is a
      register used to return values from functions such as \fnref{strlen} and
      \fnref{select}; in all other respects it behaves exactly like any other
      variable.

      While technically these functions do not have return values, Kepago
      permits you to treat them as though they did: for example, the code that
      \reallive\ bytecode represents literally as
      \begin{lstlisting}
        strlen(strS[100])
        intA[10] = store
      \end{lstlisting}
      can also be written
      \begin{lstlisting}
        int x -> MEMARR_A.10
        str s -> MEMARR_S.100
        x = strlen(s)
      \end{lstlisting}
      It is sometimes more efficient to access \lstinline|store| directly:
      \begin{lstlisting}
        strlen(s)
        if store > 5 && store < 10...
      \end{lstlisting}
      \noindent generates code marginally more efficient than either repeating
      the \fnref{strlen} call or assigning its value to a variable would.  Note 
      however that \compiler\ makes no guarantee that it will not generate
      code that affects the value of \lstinline|store|; in general you cannot
      assume that its value will remain unchanged between two statements.

  \lsubsection{Strings}

    \lsubsubsection{String variables}\index[concept]{variables!string memory}

      \reallive\ strings are null-terminated character arrays; allocation is
      handled automatically.  Their length is not limited at runtime, but only
      up to 10,000 characters are stored in saved games.

      The array \lstinline|S[0]| to \lstinline|S[1999]| holds local string
      variables. In \reallive\ (but not in \avgns) there is also an array
      \lstinline|M[]|, of the same size, the contents of which are global.
      
      As with integers, this memory can be accessed either through variables
      you declare or through two built-in arrays, \lstinline|strS[]| and
      \lstinline|strM[]|.

    \lsubsubsection{Name variables}\label{sec:namevars}\index[concept]{variables!name variables}\index[concept]{name variables}

      In addition to the normal string variables, there also exist some special
      variables designed primarily to hold character names.  These cannot be
      accessed directly in source code, but they can be included inline in
      strings.

      There are 702 global name variables; they can each hold between 12 and 20
      characters, depending on the \ivarref[NAME:MAXLEN]{NAME\_MAXLEN} setting. 
      Their default values are set in \gameexe\ with the \ivarref{NAME} 
      variables (\inivar{NAME.A}, \inivar{NAME.B}, and so on).  Their values can 
      be read and modified with the \fnref{GetName} and \fnref{SetName} 
      functions. Within strings, they are included with the control code 
      \ccref{m}: the first is \lstinline|\m{A}|, the second \lstinline|\m{B}|, 
      through \lstinline|\m{Z}|, \lstinline|\m{AA}| to \lstinline|\m{AZ}|, and 
      so on up to \lstinline|\m{ZZ}|.

      Names can also be accessed numerically, such that 0 is A, 26 is AA, and 
      701 is ZZ.  The numerical form is valid everywhere but in \gameexe, and 
      the letter form is valid everywhere but in function 
      parameters.\footnote{You will almost invariably find yourself having to 
      use both forms at some point in a project. It may help to think of the 
      letter form as using letters for numbers in a base-26 encoding. Or then 
      again it may not.}
      
      In \reallive\ (but not in \avgns) there is a parallel set of local name 
      variables, which are to the normal set as \lstinline|S[]| is to 
      \lstinline|M[]|. These are introduced inline with \ccref{l} in place of 
      \ccref{m}, the getter/setter functions are \fnref{GetLocalName} and 
      \fnref{SetLocalName}, and the \gameexe\ variables defining their default
      values are called \ivarref{LOCALNAME}.

      For example, \opus{Clannad} uses the global names A and B for the player's
      family name and personal name respectively, and various local names for
      certain addresser/addressee combinations that have to change over the
      course of the game, such as the way the player addresses Nagisa
      (\lstinline|\l{C}|).

  \lsubsection{Call variables}\label{sec:callvars}\index[concept]{variables!call variables}\index[concept]{call variables}
  
    Version 1.3 of RealLive introduced a set of ``call variables'': these are 
    \lstinline|K[]| (three string variables) and \lstinline|L[]| (40 integer 
    variables).  These can be used as ordinary variables, but they are intended 
    for use with the functions \fnref[gosub:with]{gosub\_with} and 
    \fnref[farcall:with]{farcall\_with}.
    
    They can be accessed from Kepago with two more built-in arrays, 
    \lstinline|strK[0]| to \lstinline|strK[2]| and \lstinline|intL[0]| to
    \lstinline|intL[39]|.

\lsection{The system command menu}\label{sec:syscom}\index[concept]{menus}\index[concept]{saved games}\index[concept]{settings}

  \reallive\ provides a context menu system to handle most actions and 
  configuration settings.  The system command menu is configured with the 
  \ivarref{SYSCOM} variables in \gameexe.  It can be disabled by setting 
  \ivarref[SYSCOM:USE]{SYSCOM\_USE} to 0, and if a \ivarref{CANCELCALL} hook is 
  defined it will never be used at all (\opus{Clannad} does this, although it 
  uses the internal flags associated with the system command menu to control its 
  own menu system).

  The menu is displayed manually by right-clicking or pressing Escape.  It can
  be displayed from code with the \fnref{ContextMenu} function.

  The shape of the menu is determined by the \gameexe\ variables 
  \ivarref[SYSCOM:MOD]{SYSCOM\_MOD}, \ivarref[SYSCOM:MOD2]{SYSCOM\_MOD2},
  and \ivarref[SAVELOADDLG:USE]{SAVELOADDLG\_USE}.
  
  The system commands, and their equivalents in code, are listed below.  They 
  can be managed with the functions described in \ref{sec:syscomfuns}. Items 
  marked with an asterisk have standard dialog boxes which can be accessed with 
  \fnref{InvokeSyscom}; items marked with a plus sign have settings which can be 
  modified with \fnref{InvokeSyscom} and retrieved with \fnref{ReadSyscom} (this 
  category may be incomplete).  Functions related to settings come in sets 
  including a getter, a setter, and sometimes a function to get the default 
  value.  For example, the getter function \fnref{MessageSpeed} is accompanied by 
  \fnref{SetMessageSpeed} and \fnref{DefMessageSpeed}.  Refer to the individual 
  functions in the API reference for full details.

  \begin{syscom}
      0 &\ifhevea~~~\fi& {\raggedright Save\\
            \fnref[menu:save]{menu\_save}}

  \\  1 & & {\raggedright Load\\
            \fnref[menu:load]{menu\_load}}

  \\  2 &*& {\raggedright Message speed\\
            \fnref{MessageSpeed}}

  \\  3 &*& {\raggedright Window attributes\\
            \fnref{GetWindowAttr}; also \fnref{WindowAttrR}, etc.}

  \\  4 &*& {\raggedright Volume settings\\
            \fnref{BgmVolMod}, \fnref{PcmVolMod}, \fnref{KoeVolMod}, and
            \fnref{SeVolMod}; likewise \ifhevea\else\\\fi\fnref{BgmEnabled}, etc.}

  \\  5 &+& {\raggedright Display mode (full-screen or windowed)\\
            \fnref{ScreenMode}}

  \\  6 &*& {\raggedright Miscellaneous settings\\
            \fnref{CursorMono}, \fnref{SkipAnimations}, \fnref{LowPriority},\ifhevea\else\\\fi{}
            \fnref{ConfirmSaveLoad}, \fnref{ReduceDistortion}, and
            \fnref{SoundQuality}}

  \\  8 & & {\raggedright Voice settings (whether to use text, voice, or both)\\
            \fnref{KoeMode}}

  \\  9 &*& {\raggedright Font selection}

  \\ 10 &*& {\raggedright BGM fade (whether to fade out when voice is playing)\\
            \fnref{BgmKoeFade}, \fnref{BgmKoeFadeVol}}

  \\ 11 & & {\raggedright BGM settings (DirectSound or CDDA)}

  \\ 12 & & {\raggedright Window decoration style\\
            \fnref{GetWakuAll}}

  \\ 13 &*& {\raggedright Auto mode settings\\
            \fnref{AutoCharTime}, \fnref{AutoBaseTime}}

  \\ 14 & & {\raggedright Return to previous selection point\\
            \fnref{ReturnPrevSelect}}

  \\ 15 & & {\raggedright Enable/disable character voices\\
            \fnref{UseKoe}}

  \\ 16 &*& {\raggedright Display game version}

  \\ 17 & & {\raggedright Enable/disable environmental effects\\
            \fnref{ShowWeather}}

  \\ 18 & & {\raggedright Show/hide object 1\\
            Meaning is application-defined; in \opus{Clannad}, this is the date window setting.\\
            \fnref{ShowObject1}}

  \\ 19 & & {\raggedright Show/hide object 2\\
            Meaning is application-defined.\\
            \fnref{ShowObject2}}

  \\ 20 & & {\raggedright Enable/disable colour-based text classification\\
            Meaning is not fully understood, but it may be something to do with displaying text in
            a different colour if it has already been viewed, or using different colours for
            different characters.\\
            \fnref{ClassifyText}}

  \\ 21 & & {\raggedright Generic setting 1\\
            Meaning is application-defined.\\
            \fnref{Generic1}}

  \\ 22 & & {\raggedright Generic setting 2\\
            Meaning is application-defined.\\
            \fnref{Generic2}}

  \\ 24 & & {\raggedright Open file\\
            Opens the file named by \ivarref[MANUAL:PATH]{MANUAL\_PATH} in
            \gameexe.\\
            This function is not available in all \reallive\ builds; it was 
            introduced between versions 1.2.3 and 1.2.6.  It is not clear 
            whether it can be accessed other than through the right-click menu.}

  \\ 25 & & {\raggedright Skip read text\\
            \fnref{SetSkipMode}}

  \\ 26 & & {\raggedright Enable auto mode\\
            \fnref{AutoMode}}

  \\ 28 & & {\raggedright Return to main menu\\
            \fnref{MenuReturn}}

  \\ 29 & & {\raggedright Exit game\\
            \fnref{end}}

  \\ 30 & & {\raggedright Hide menu}

  \\ 31 & & {\raggedright Hide text window\\
            \fnref{ShowBackground}}
  \\
  \end{syscom}

\lsection{Extension DLLs}\label{sec:dlls}\index[concept]{DLLs}

  Version 1.2 of \reallive\ introduced a plugin system to permit arbitrary 
  code to be called from external DLLs.  (This feature does not exist in 
  \avgns\ or earlier versions of \reallive.)

  To write an extension DLL, simply write regular C++ code that conforms to
  the interface documented here, and load it into the game as described below.

  \lsubsection{Using an extension DLL}

    The method for telling \reallive\ to use functions from a DLL depends on the 
    version of the interpreter in use.
    
    For versions between 1.2 and 1.2.5, you must load it at runtime with the 
    \fnref{LoadDLL} function.  These versions only support the use of one DLL at 
    a time.
    
    From version 1.2.5 onwards, the preferred method is to use a \ivarref{DLL} 
    variable in \gameexe; such DLLs will then be loaded automatically and kept 
    in memory throughout execution, which is generally more useful.  The 
    \fnref{LoadDLL} interface is deprecated in these versions, and indeed is 
    removed altogether from version 1.3.2 onwards.
    
    It is possible for a DLL to be useful simply by being in memory; an example 
    of this is the rlBabel library (\ref{lib:rlBabel}) supplied as part of 
    \package.  However, it is more usual for it to be used to provide an 
    extended API to \reallive\ bytecode.  This is accessed using the standard
    function \fnref{CallDLL}.
  
%BEGIN LATEX
\lstset{language=[Visual]C++}
%END LATEX
  \lsubsection{The extension DLL interface}
  
    There are two distinct interfaces used by different versions of \reallive. 
    \package\ provides an abstraction which will enable the same source code to 
    be compiled against both interfaces, within limits.
    
    To write an extension DLL, include the header \file{rlplugin.h} found in the 
    \file{lib/} directory of your \package\ installation. By default, the new 
    interface is used; to use the old interface, define the symbol
    \lstinline|OLD_INTERFACE| when compiling your code.
    
    Follow the instructions provided with your compiler to produce a DLL.  If 
    you need a definition file, two are provided: \file{rlplugin.def} (for the 
    new interface) and \file{rlpluginf.def} (for the old interface).
    
    \lsubsubsection{OnLoad function}\fnidx{OnLoad}
      The \lstinline|OnLoad| function is called once when the DLL is loaded
      into memory.
      
      \begin{lstlisting}
        long OnLoad(RealLiveState *State, size_t cbSize);
      \end{lstlisting}
      \noindent
      \begin{nicelist}
      \item[\lstinline|*State|]
        Pointer to a RealLiveState structure (see below, 
        \ref{sec:reallivestate}) containing the internal state of the 
        interpreter. The values this contains remain valid until the DLL is 
        unloaded.
      \item[\lstinline|cbSize|]
        The size of the structure, in bytes.
      \item[Return value]
        The function should return a non-zero value to indicate that the DLL
        was loaded successfully.
      \end{nicelist}
      
    \lsubsubsection{OnFree function}\fnidx{OnFree}
      The \lstinline|OnFree| function is called once when the DLL is unloaded.
      
      \begin{lstlisting}
        long OnFree();
      \end{lstlisting}
      \noindent
      \begin{nicelist}
      \item[Return value]
        The function should return a non-zero value to indicate that the DLL
        was unloaded successfully.
      \end{nicelist}

      In \reallive\ 1.2.5 and up, the unload event happens only when the DLL is 
      explicitly unloaded with \fnref{UnloadDLL}, or when the interpreter closes.
      
      In older versions, however, the DLL is unloaded whenever the interpreter 
      is reset.  Unfortunately, actions that trigger a reset include the loading
      of a saved game, and any DLL that had been present when the game was saved
      is \emph{not} reloaded.  This can be problematic if your code relies on 
      the DLL being persistent.  The simplest workaround is to ensure that any
      call to the DLL returns only non-zero values: a zero return value is then
      a certain indication that the DLL needs reloading.
   
    \lsubsubsection{OnInit function}\fnidx{OnInit}
      In \reallive\ 1.2.5 and up, the \lstinline|OnInit| function is called 
      each time the interpreter is reset (see immediately above).

      This function does not exist in older versions of \reallive.
      
      \begin{lstlisting}
        void OnInit();
      \end{lstlisting}
      \noindent
      \begin{nicelist}
      \item[Return value]
        This function does not return a value.
      \end{nicelist}
  
    \lsubsubsection{OnCall function}\fnidx{OnCall}
      The \lstinline|OnCall| function is the entrypoint for calls from
      \reallive\ bytecode (see \fnref{CallDLL}).
      
      \begin{lstlisting}
        long OnCall(long arg1, long arg2, long arg3, long arg4, long arg5);
      \end{lstlisting}
      \noindent
      \begin{nicelist}
      \item[\lstinline|arg1| .. \lstinline|arg5|]
        The arguments passed to the \fnref{CallDLL} function. Any arguments
        that were not provided will default to 0.
        
        The meaning of these arguments is entirely up to you. Typically the 
        first argument will be used as a function identifier, and the 
        \lstinline|OnCall| function will dispatch control to other functions in 
        your DLL accordingly.
      \item[Return value]
        The value returned by this function is entirely up to you.  It will
        be used as the return value to the \fnref{CallDLL} call.
        
        You may wish to reserve the value 0 as an error code to indicate that
        there is no DLL loaded.
      \end{nicelist}
      
    \lsubsubsection{RealLiveState structure}\fnidx{OnLoad!RealLiveState structure}\label{sec:reallivestate}
      The \lstinline|RealLiveState| structure is the official interface by
      which extension DLLs can access the internal state of the interpreter.
      
      \begin{lstlisting}
        struct RealLiveState {
          size_t cbSize;
          HWND hMainWindow;
          long *intA;
          long *intB;
          long *intC;
          long *intD;
          long *intE;
          long *intF;
          long *intG;
          long *intZ;
          char* *strS;
          char* *strM;
          struct {
            void* *pData;
            long *pWidth;
            long *pHeight;
          } BankInfo[16];
          char* szGamePath;
          char* szSavePath;
          char* szBgmPath;
          char* szKoePath;
          char* szMovPath;
          char* szDataPath;
        };
      \end{lstlisting}
      \noindent
      \begin{nicelist}
      \item[\lstinline|dwSize|]
        The size of the structure, in bytes.
      \item[\lstinline|hMainWindow|]
        Handle to the main game window.
      \item[\lstinline|*intA .. *intZ|]
        The integer memory space.  Accessing \lstinline|intA[1000]| has exactly 
        the same meaning in an extension DLL as it does in Kepago.
      \item[\lstinline|*strS|, \lstinline|*strM|]
        The string memory space.  Each element is a pointer to a null-terminated 
        string.  It is unclear whether it is safe to make any assumptions about 
        the size of the buffer pointed to, or whether it is safe to reallocate 
        the memory.
      \item[\lstinline|BankInfo|]
        An array of internal structures that provide direct access to the game's
        graphics DCs.  \lstinline|*pData| is a pointer to the raw pixel data,
        and the other two members are pointers to the dimensions of that data,
        probably in pixels.
      \item[\lstinline|szGamePath|]
        The game root directory (i.e.\ the path of \gameexe).
      \item[\lstinline|szSavePath|]
        The save directory.
      \item[\lstinline|szBgmPath|, \lstinline|szKoePath|, \lstinline|szMovPath|]
        The directories where music, voice, and movie data are stored (that is,
        the root for the \inivar{FOLDNAME} paths for them).
      \item[\lstinline|szDataPath|]
        The base directory where all other resources are sought (that is,
        the root for the \inivar{FOLDNAME} paths for them).
      \end{nicelist}
        
%BEGIN LATEX
\lstset{language=kepago}
%END LATEX
