GTA Map Viewer - Scripting Interface Documentation
--------------------------------------------------

 2005 by Steve M. (http://www.steve-m.com)


Content: Introduction, Available Commands, Sample Scripts


Introduction
~~~~~~~~~~~~

With version 0.5 Alpha 4 the Map Viewer supports simple LUA scripting. The
current implementation is basically just for testing, and doesn't offer many
commands and possibilities, but still some nice things can be accomplished
already.

LUA is a popular, powerful and free scripting language. For information and
documentation, please visit http://www.lua.org/. (I'm not going to answer
general questions about the language, it's all documented!)
Also take a look at:
http://lua-users.org/wiki/TutorialDirectory
http://sourceforge.net/project/showfiles.php?group_id=32250&package_id=111829

If you want to use a script, name it the same as the viewer's executable, just
with the extention ".lua" (by default "MapViewer.lua") and place it in the same
directory as the viewer. The script is executed whenever you press F11. You may
modify it while the viewer is running, since the file loaded again every time.


Available Commands
~~~~~~~~~~~~~~~~~~

Usage of standard LUA commands is not restricted in any way, you may use the
commands from the basic, table, math, string, I/O and OS libraries.
The current version of Map Viewer doesn't use multithreading yet, so every
script will be processed until it ends (or an error occured) and cannot be
interrupted.
All messages the LUA interpreter or the executed scripts generate will be
output as debug message, just like all of Map Viewer's messages.

The following viewer-specific commands are available in this version:
(Note that these commands are subject to change in future versions!)

- Msg(...)

  Outputs a message. Variable parameters, most types allowed, otherwise 'nil'.
  Each parameter will generate a separate message.

- UpdateEngineTime()

  Updates the internal timer and time-related variables, should always be
  used before rendering, especially when looped. No parameters.

- Render()

  Updates the camera, dertermines the visibility of map objects, streams
  needed files, and renders the scene. No parameters.

- TakeScreenshot([fname])

  Grabs the current frame buffer content and stores it in a bmp file. You may
  specify a filename with the fname parameter. If no name is given, the viewer
  will generate a name automatically, including date and time.

- GetGameDir() (returns string)

  Returns the directory name of the currently loaded game map (which you
  specified in games.cfg). If no map is loaded, the result is empty. No
  parameters.

- SetMaxFilesPerFrame(num)

  Sets the MaxFilesPerFrame variable, the same you define in settings.cfg, so
  look there or in the readme for a description.

- SetCamera(cmd, ...)

  Provides several functions to set the camera, identified by the cmd value:

  - 0: SetCamera(0)
    Resets the camera and some related variables to the default values (same
    as F8 inside the viewer). No additional parameters.

  - 1: SetCamera(1, x, y, z)
    Puts the camera at the specified XYZ location inside the scene.

  - 2: SetCamera(2, angle, height)
    Defines the camera's rotation. Angle is the clockwise rotation angle about
    the Z axis, with 0 being North. Height is the rotation about the local X
    axis, thus defining the camera's pitch, with pi being up and -pi down. All
    angles in radians.

  - 3: SetCamera(3, pos_x, pos_y, pos_z, target_x, target_y, target_z)
    Moves the camera to the location specified by pos and makes it look at the
    location specified by target.

  - 4: SetCamera(4, DistCullEnabled)
    The boolean value DistCullEnabled defines whether distance culling is
    enabled (same as F5 inside the viewer).

  - 5: SetCamera(5, DistFact)
    Defines the draw distance multiplier.

  - 6: SetCamera(6, FOV)
    Sets the camera's field of view (in degrees), default is 45.

  - 7: SetCamera(7, Index)
    Loads a camera position from the slot defined by index.

  - 8: SetCamera(8, Index)
    Saves a camera position to the slot defined by index.

- SetGameTime(h, min)

  Sets the time of the simulation clock to the given hours and minutes.


Sample Scripts
~~~~~~~~~~~~~~

The Map Viewer comes with currently one test and two sample scripts, which can
be found in the \Scripts directory. To make use of them, open MapViewer.lua and
uncomment the appropriate dofile() commands, or alternatively replace the main
script.

- radar.lua

  This script is able to generate rendered radar images for use with your
  original or modified game. It sets a near-orthographic perspective, moves
  the camera to the first position, renders and saves as bitmap, moves to the
  next position and so on. With the default settings it generates 144 radar
  images for use with San Andreas. Each radar piece will show a 500*500 units
  map part. Before you start the viewer to execute the script, you should open
  settings.cfg and define a small window resolution, such as 128*128, and
  disable the window borders, to avoid black pixels on your images.

- flight.lua

  This script does a camera flight using the coordinates in the specified
  tracks*.dat file from SA. The moving speed isn't constant, since it's hard
  to create any wait commands. Also, the interpolation is very simple, but
  notably smoother than without. You have to define which file you want to use
  by editing the appropriate lines inside the script. This can easily be
  extended to use any other coordinates file. And remember, it's not possible
  to cancel a camera flight, you'll have to wait until it's over or kill the
  program.