% Macros for usage information

\newenvironment{extraopts}{\\[0.5\baselineskip]Additional options: \begin{nicelist}}{\end{nicelist}}

% End of macros

\lchapter{Using \package{}}

\package\ is split up into utilities according to the types of file each
processes.  Currently there are four: \archiver\ to handle \reallive\ scenario
files (see section \ref{sec:scenarios}), both as archives and separately,
\compiler\ to handle Kepago source code, \converter\ to handle conversions of
bitmap files, and \dataxml\ to handle conversions of certain other data formats
(as of 1.21, just \file{GAN} animations).

All utilities have certain things in common: running them without arguments will
display a help screen, and the options \cllong{help} (displays the same help
screen), \cllong{version} (displays a brief copyright notice), and
\clboth{v}{verbose} (increases the amount of diagnostic information printed) are
always available.

\lsection{\archiver: the archiver/disassembler}

  \begin{quote}
    Synopsis: \file{kprl} \metavar{options}
    \textit{(}\metavar{files} \textbar\ \metavar{archive}
              \metaopt{ranges}\textit{)}
  \end{quote}

  \noindent One option is always required, to select the operation to perform.
  Which of \metavar{files} and \metavar{archive} is used, and what other options
  (if any) are available, depends on the operation.

  Where \metavar{archive} is used, in all cases other than for the \clopt{a}
  command, \metavar{ranges} is a list of integers between 0 and 9,999.  Ranges
  can be specified, e.g.\ `\file{414-416}'.  The files actually processed
  will be the intersection of the set specified on the command line and the set
  of files present in the archive.  Omitting \metavar{ranges} causes all files
  to be processed.

  \lsubsubsection{Common operations}
  \begin{nicelist}
  \item[\clboth{a}{add}]
    Updates files in \metavar{archive}; if the files listed are not present,
    they will be added, and if the archive does not exist, it will be created.
    \metavar{ranges} should be one or more filenames, which are taken to be the
    names of scenarios to add.  Their names must begin \file{seen}\metavar{N},
    where \metavar{N} is an integer between 0 and 9,999.
  \item[\clboth{k}{delete}]
    Removes the files indicated by \metavar{ranges} from \metavar{archive}.  If
    all files are removed, the archive will be deleted; to prevent accidents,
    \metavar{ranges} may not be omitted.
  \item[\clboth{l}{list}]
    Lists files in \metavar{archive}, printing names, sizes, and compression
    ratio where applicable.  The files listed can be restricted with
    \metavar{ranges}.
    \begin{extraopts}
    \item[\clboth{N}{names}]
      Instead of sizes, print a list of characters appearing in the scenario
      (not available in \avgns).
    \end{extraopts}
  \item[\clboth{d}{disassemble}]
    Disassembles files, producing Kepago source code corresponding to their
    \reallive\ bytecode.  If an \metavar{archive} and \metavar{ranges} are
    given, files will be extracted from the archive automatically; otherwise
    \metavar{files} will be treated as a list of separate scenarios to be
    disassembled.
    \begin{extraopts}
    \item[\clbarg{o}{outdir}{DIR}]
      Places output in \metavar{DIR}
    \item[\clbarg{e}{encoding}{ENC}]\label{opt:enc}
      Selects a character encoding for output.  Valid options always include
      \texttt{cp932}\footnote{CP932 is Microsoft's version of Shift\_JIS; this
      is \reallive's native character encoding.}, \texttt{euc-jp}, and
      \texttt{utf-8}.  The default is normally \texttt{cp932}, but this may be
      configured differently depending on the settings used to build \package.
    \item[\cllong{bom}]
      If the output encoding is UTF-8, causes a BOM (byte-order mark) to be
      prepended to all output files.  The default is to leave the BOM out, but
      some programs (notably Microsoft's text editors) can not edit UTF-8 files
      without it.
    \item[\clboth{s}{single-file}]
      By default, \archiver\ puts text strings into a separate resource file; this
      makes it much easier to translate text without being distracted by
      implementation details.  If this option is supplied, all strings are
      included in the source code instead.
    \item[\clboth{S}{separate-all}]
      Normally the only strings placed in the resource file are those which
      \archiver\ can identify as part of the game's script.  If this option is
      supplied, all strings containing Japanese text are separated.  This
      usually catches any parts of the game's script that the default mode might
      miss, but it can also clutter up resource files with false positives.  It
      obviously cannot be used with \clopt{s}.
    \item[\clboth{u}{unreferenced}]
      By default, all code is disassembled, even where it can be proven that it
      is never executed (for example, code immediately following a
      \lstinline|goto| or \lstinline|end()|).  Enabling this option will
      suppress any code that is provably unreferenced; this is normally safe.
    \item[\clboth{n}{annotate}]
      Adds copious comments to the generated code.  Two types of comment are
      created: offsets in the bytecode to each command are noted, and some
      function parameters are given labels that roughly indicate their meaning.
    \item[\clboth{r}{no-codes}]
      By default, a number of functions which primarily affect text display are
      disassembled as control codes within string literals.  Enabling this
      option will disable this behaviour.
    \item[\clboth{g}{debug-info}]
      The official \vas\ \reallive\ compiler puts a large amount of strictly
      unnecessary data in the bytecode for debugging purposes.  By default it is
      ignored, but this flag causes \archiver\ to read it and include information
      from it in the source code generated.\footnote{In practice this just means
      the source will be cluttered up with \dirref{line} directives giving
      the lineation of the original code from which the game was compiled,
      which is probably not incredibly useful.}
    \item[\clbarg{t}{target}{TARGET}]
      Specifies the format of the data to disassemble (one of \file{reallive},
      \file{avg2k}, or \file{kinetic}).  By default, \disassembler\ detects a format
      automatically.  It is normally only necessary to use this option when
      disassembling code from a Kinetic Novel that uses \file{kinetic.exe},
      since the \file{kinetic} format is subtly different from the \file{reallive}
      format but is always detected as the latter.
    \item[\clbarg{f}{target-version}{VER}]
      Specifies the version of the bytecode to disassemble (either as a version
      number consisting of up to four integers separated by dots, or as the name
      of an interpreter executable to query for a version number).  By default,
      \disassembler\ detects a version automatically.
    \end{extraopts}
  \end{nicelist}

  \lsubsubsection{Less common operations}
  \begin{nicelist}
  \item[\clboth{x}{extract}]
    Decompresses and decrypts files.  As with \clopt{d}, \clopt{x} can process
    archives or standalone scenarios.  The suffix \file{.uncompressed} is added
    to all file extensions, to prevent inadvertent clobbering.
    \begin{extraopts}
    \item[\clbarg{o}{outdir}{DIR}]
      Places output in \metavar{DIR}
    \end{extraopts}
  \item[\clboth{b}{break}]
    Extracts files from \metavar{archive}, without decompressing them.
    \begin{extraopts}
    \item[\clbarg{o}{outdir}{DIR}]
      Places output in \metavar{DIR}
    \end{extraopts}
  \item[\clboth{c}{compress}]
    Compresses and encrypts files.  \metavar{files} must be a list of
    uncompressed scenarios.  It is normally not necessary to compress files
    manually; \compiler\ compresses the bytecode it generates by default, and
    \archiver\ compresses files if necessary when archiving them.  When
    compressing, \archiver\ removes the suffix \file{.uncompressed} from the file
    extension, if present.
  \end{nicelist}

\clearpage
\lsection{\compiler: the compiler}

  \begin{quote}
    Synopsis: \file{rlc} \metaopt{options} \metavar{file}
  \end{quote}

  \noindent\metavar{file} is the name of a Kepago source file to compile.  Only
  one main file can be processed at a time, though it may include code from other
  files.  It will be compiled to \reallive\ bytecode in a standalone scenario, 
  which can either be interpreted directly or added to a scenario archive.

  The following options are recognised:

  \lsubsubsection{Files and Directories} 
  \begin{nicelist}
  \item[\clbarg{o}{output}{FILE}]
    Sets name of output file to \metavar{FILE}.  If no name is specified on the
    command line, \compiler\ will look for a \dirref{file} directive in the
    source code; if none is found, the output file will be called
    \file{rlas\_output.txt}.
  \item[\clbarg{d}{outdir}{DIR}]
    Places output file in \metavar{DIR}.
  \item[\clbarg{r}{resdir}{DIR}]
    Specifies a directory in which resource files are located.  If provided, 
	\metavar{DIR} will be prepended to the filename provided by a #resource 
	directive.
  \item[\clbarg{i}{ini}{FILE}]\label{usage:inifile}\index[concept]{gameexe.ini}
    Specifies a \gameexe\ to use, or the directory containing one.  Access to 
    the \gameexe\ that will be used at runtime is required in order to read 
    various configuration data.  If none is specified on the command line, 
    \compiler\ will look for an environment variable \file{GAMEEXE}; failing 
    that, it will look in the directory containing the source file being 
    compiled.    
  \end{nicelist}

  \lsubsubsection{Text Encoding and Transformation}
  \begin{nicelist}
  \item[\clbarg{e}{encoding}{ENC}]
    Selects a character encoding for the input.  The options and default are the
    same as in the disassembler (see above).
  \item[\clbarg{x}{transform-output}{ENC}]
    Selects a character encoding transformation for the output. See 
    \ref{sec:encodings} for details.
  \item[\clbarg{}{force-transform}{BOOL}]
    If true, warning messages are issued when input text cannot be represented
	using the encoding specified for the scenario generated in the output.
	If false, transformation failures result in an error message is displayed
	and compilation is aborted.  Non-fatal warnings are issued by default.

  \item[\clbarg{t}{target}{TARGET}]
    Specifies the output target (one of \file{reallive}, \file{avg2k}, or
    \file{kinetic}).
    
    By default, \compiler\ attempts to detect the target automatically by 
    looking for an interpreter executable in the directory containing the 
    \gameexe\ being used; failing that, it falls back on \reallive\ as the 
    most likely option.  The \dirref{target} directive can also be used to set a 
    different target.  This option takes precedence over the directive, which in 
    turn takes precedence over auto-detected targets.
  \item[\clbarg{f}{target-version}{VER}]
    Specifies the version of \reallive\ bytecode to compile for; see section
    \ref{sec:targver} for the distinction between target and version.  \metavar{VER}
    may be either a version number (between one and four integers separated by
    dots) or the path to an interpreter executable which will be queried for
    its version.
    
    By default, \compiler\ attempts to detect a suitable version automatically 
    by looking for an interpreter executable in the same way as for the 
    \cllong{target} option and querying its version number.  If this fails, it 
    defaults to version 1.0 (if the target is \avgns) or 1.2.6 (for other 
    targets). You can always use the \dirref{version} directive to override 
    this; unlike the \dirref{target} directive, \dirref{version} also overrides 
    explicit version specifications.
  \end{nicelist}

  \lsubsubsection{Low-level Compiler Options}
  \begin{nicelist}
  \item[\clboth{u}{uncompressed}]
    Disables automatic compression and encryption of output.  The output will be
    given a \file{.uncompressed} suffix, as though it had been compiled normally
    and then decompressed with \file{kprl -x}.  This is only useful if you need
    to examine the generated bytecode.
  \item[\clboth{g}{no-debug}]
    Strips debugging information and calls to debugging functions from the 
    compiled bytecode.  The output will be smaller and marginally faster.
  \item[\cllong{no-assert}]
    Disables assertions (see \fnref{assert}).
  \item[\cllong{safe-arrays}]
    Enables runtime bounds checking for Kepago arrays.  This option has no effect 
    if \cllong{no-assert} has also been specified.
  \item[\cllong{flag-labels}]
    \emph{This feature is experimental and incomplete.}

    Enables automatic generation of the \file{flag.ini} symbol information file 
    used by the \reallive\ debugger.  Variables declared with the 
    \texttt{labelled} directive will be added to \file{flag.ini} automatically.  
    
    Currently, \file{flag.ini} is created automatically in the same directory as 
    the \gameexe\ in use; any existing \file{flag.ini} will be deleted 
    automatically without confirmation, and you will have to make your own 
    arrangements if you wish to combine labels from more than one source file or 
    to make use of \file{flag.ini} features other than basic variable labels. 
    The generated labels consist of the variable's name (and, in the case of 
    arrays, its length).  All labels are placed in flag group 0.    
  \end{nicelist}

  \lsubsubsection{Game-specific Options}
  \begin{nicelist}
  \item[\clbarg{G}{game}{GID}]
    Specify the \compiler game using an id which can be used to look up game
	specific information that may be useful, if not critical, for producing
	compatible bytecode and handling those special cases where custom encryption
	keys are employed to keep your precious bytecode data \emph{in} and those
	armies of perverts who want to put their hands on your privates \emph{out}.
	
	To this end, the modern \compiler developer is armed with a potent 
	\file{game.info} file, a private groping hentai's worst nightmare.
  \item[\clbarg{c}{compiler}{LONG}]
	Provide a somewhat cryptic compiler version number (eg 10002, 110002, etc)
	as a long integer.
	Or pass a game id from \file{game.info} using \clopt{G} instead.
  \item[\clbarg{k}{key}{KEY}]
	Provide a hex string representing a game specific encryption key to further
	obfuscate the generated scenario data.
	Or pass a game id from \file{game.info} using \clopt{G} instead.

  \end{nicelist}

  \lsubsubsection{Obsessive-compulsive Minutae}
  \begin{nicelist}
  \item[\clbarg{F}{from}{LINE}]
	Indicate the line number within the script file at which to begin compilation.
  \item[\clbarg{T}{to}{LINE}]
	Enumerate a line number within the script file at which compilation will cease.
  \item[\clbarg{}{kfn}{FILE}]
	Demand that the compiler use a specific RealLive Function Definition File
	(the default is lib/reallive.kfn.
  \item[\clbarg{}{ext}{EXT}]
	Decree that script files to be compiled to bytecode will include have
	the specified file extension (default is 'org' in order to make use of
	the source code debugger available in debug mode).
  \end{nicelist}

\clearpage
\lsection{\converter: the graphic converter}

  \begin{quote}
    Synopsis: \file{vaconv} \metaopt{options} \metavar{files}
  \end{quote}

  \noindent\metavar{files} is the names of the bitmap files to convert.

  The following options are recognised:

  \begin{nicelist}
  \item[\clbarg{d}{outdir}{[DIR]}]
    Places output files in \metavar{DIR}.  Passing this option without
    specifying \metavar{DIR}, or giving it the special value \lstinline|PRESERVE|,
    causes output files to be placed in the same directory as their respective
    inputs.  If this option is not passed at all, output files are placed in the
    current working directory.
  \item[\clbarg{o}{output}{FILE}]
    Sets name of output file to \metavar{FILE}.  The default is the base name
    of the input file with an extension selected according to the target
    format.  Note that this option can only be used when only one input file
    is supplied.
  \item[\clbarg{f}{format}{FMT}]
    Sets output format to \metavar{FMT}.  Possible formats are PDT, G00, and
    PNG.

    The default behaviour depends on the extension of the first input file: if it
    is \file{.g00}, the default output format is PNG, otherwise it is G00.
  \item[\clbarg{g}{g00}{FMT}]
    Allows you to select the G00 format to use (0, 1, or 2); see
    \ref{sec:bmpformats}.  The default behaviour is to select an appropriate
    format automatically based on the data.

    This option implies \lstinline|-f G00|; you should not use \clopt{f} and
    \clopt{g} together.
  \item[\clbarg{i}{input-format}{FMT}]
    If \converter\ is failing to recognise the format of the source file, you
    can bypass the auto-detection by specifying the format manually.  Legal
    values of \metavar{FMT} are the same as for \clopt{f}.
  \item[\clbarg{m}{metadata}{FILE}]
    For G00 output, allows you to supply a metadata file to specify features
    like regions; see \ref{sec:advancedg00}.  If no metadata file is specified,
    \converter\ looks for one accompanying the source file with the same base
    name and the extension \file{.xml}.  If this is not found, default
    values are used.

    For G00 input, allows you to override the name to be used if a metadata
    file is generated.

    As with \clopt{o}, this option can only be used when only one input file is
    supplied.
  \item[\clboth{q}{no-metadata}]
    For G00 output, causes \converter\ to ignore all metadata.  For G00 input,
    disables metadata output even where this would lead to loss of information.
  \item[\clboth{b}{best}]
    Maximise compression.  Where this has any effect, it runs significantly
    slower (by an order of magnitude in the worst cases) than the default
    algorithm; for G00 output in format 0, however, where the regular algorithm
    is particularly inefficient, I have seen file sizes almost halved, so it may
    be worth using for releases.
  \end{nicelist}

  \lsubsection{Bitmap formats}\label{sec:bmpformats}

    \reallive\ makes use of two proprietary bitmap formats: PDT and G00.

    The PDT format is a holdover from the older AVG32 system, and is the
    standard bitmap format in \avgns: it stores 8-bit paletted or 24-bit RGB
    bitmaps, together with an optional 8-bit alpha mask.  In \reallive\ proper
    it is normally used only for cursor images.\footnote{\converter's
    implementation can read all PDT images, but it cannot write paletted PDTs.
    The paletted format is extremely rare, however.}

    G00 is the true native format, used for most graphics in \reallive\ games.
    There are three G00 formats, each (naturally) with their own advantages
    and disadvantages:

    \begin{tabular}{r@{\hs}l}
    \textbf{0} & 24-bit RGB, no mask \\
    \textbf{1} & 8-bit paletted; palette is ARGB \\
    \textbf{2} & 32-bit ARGB, plus extra features (see below)
    \end{tabular}

    \noindent Formats 0 and 1 are usually the most efficient, depending on the
    type of data; format 2 is the most flexible.  By default, \converter\ attempts
    to select the most appropriate format automatically when converting to G00.

  \lsubsection{Advanced G00 features}\label{sec:advancedg00}

    Format 2 G00 bitmaps can contain multiple sub-bitmaps, termed ``regions''.
    These are used in some object functions (see \ref{sec:objects}) to create
    objects with multiple states, such as buttons; such functions generally have
    a parameter \metavar{pattern} which references a G00 region.

    When creating a G00 bitmap, regions are defined by supplying an XML metadata
    file along with the source image.  The format is very simple, and an example
    should be sufficient documentation.  This is for one of the CG mode thumbnails
    in \opus{Clannad}:
    \begin{lstlisting}
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE vas_g00 SYSTEM "vas_g00.dtd">
      <vas_g00 format="2">
        <regions>
          <region x1="0" y1="0"  x2="114" y2="86" />
          <region x1="0" y1="0"  x2="114" y2="86" />
          <region x1="0" y1="87" x2="114" y2="173"/>
          <region x1="0" y1="87" x2="114" y2="173"/>
          <region x1="0" y1="0"  x2="114" y2="86" />
        </regions>
      </vas_g00>
    \end{lstlisting}
    \noindent Here five selectable regions are defined, but only two real
    regions.  These are selectable in-game with commands such as
    \begin{lstlisting}
      objOfFile (0, 'SCGMA00') // Initialises object 0.
      objPattNo (0, 1)         // Selects region 1 (this is the same as 0, so has
                               // no visible effect).
      objPattNo (0, 2)         // Selects region 2 (switches to display the other
                               // sub-image).
    \end{lstlisting}

\clearpage
\lsection{\dataxml: the auxiliary data converter}

  \begin{quote}
    Synopsis: \file{rlxml} \metaopt{options} \metavar{files}
  \end{quote}

  \noindent\metavar{files} is the names of the files to convert.  Their format 
  will be determined automatically from their extension.  If they are \reallive\ 
  data files, they will be converted to a human-readable XML format; if they are 
  XML files, they will be converted back to the appropriate \reallive\ binary 
  format.
  
  Currently only two formats are recognised: \file{GAN} animation files (extension
  \file{.gan}), and their corresponding XML versions (extension \file{.ganxml}).

  The following options are recognised:

  \begin{nicelist}
  \item[\clbarg{o}{output}{NAME}]
    The meaning of this option depends on the number of files being converted. 
    If only one is being converted at a time, then \clopt{o} specifies the path
    and name of the converted file; if multiple files are being converted at 
    once, \clopt{o} specifies the directory in which the converted files should 
    be placed, and their names will be derived automatically from the input 
    files' names.
    
    If the option is not given at all, then output is placed in the current 
    working directory with automatically-generated names.
  \end{nicelist}

    
\lchapter{Getting started}

Ease of use is a function of time, and I haven't had that much time to feed into 
it, so you'll have to do a bit of work to start a project with \package. 
Moreover, what's required will change (hopefully for the better) over time, so 
be sure to check this section again with each new release.

\lsubsection{The project header file}

  If there is a file called \file{global.kh} in the same directory as a source
  file, \compiler\ will automatically include it, as though every source file
  began with the line \lstinline|#load 'global'|.  Placing configuration
  options and common definitions in such a file will automatically share them
  among every source file in the directory.
  
  You can of course use a different name for your project header, but if you do,
  you will have to load it manually.
  
  Overriding or extending the project header on a script by script basis may be
  useful as well.  Auto inclusion of a script header file will occur immediately
  after the project header where a corresponding global header \file{global****.kh}
  can be found in the same directory as the script source file sharing the same
  four digit index.
  
  Sample Output:
  
    Loading project header 'global.kh'
    Loading script header 'global0010.kh'
    Compiling script file 'seen0010.org'
  

\lsubsection{Memory allocation}\label{sec:allocation}

  You must identify two sections of memory for \compiler\ to use to allocate 
  temporary variables.  At a minimum you must provide a block of 100 local 
  integers and a block of 10 local strings.
  
  By default, \compiler\ uses the whole \lstinline|C[]| array for temporary 
  integers, and \lstinline|S[1900]| to \lstinline|S[1999]| for temporary 
  strings.  If you are writing a program from scratch, you can either avoid 
  using these memory areas manually, or change them to something more 
  convenient.  If you are modifying an existing program, you will have to 
  analyse its memory usage yourself to discover whether these defaults are 
  suitable, and modify them if they are not.  Be warned that any direct access 
  or modification of a variable in a space that has been assigned to \compiler\ 
  could cause your program to malfunction, but \compiler\ has no way to detect 
  such conflicts automatically.
  
  To modify the settings for memory allocation, call the 
  \fnref{rlcSetAllocation} function.  You must call this function at the start 
  of \emph{every} file in your project\,\textemdash\,it is evaluated at 
  compile-time, so it is not enough simply to call it at the start of the first 
  scenario.  The easiest thing is just to place it in your \file{global.kh} (see 
  above), which is automatically included at the start of every scenario.