Script - System Viewer

The System Viewer is a LUA script that allows a modder to create a map that can be used for reference purposes or for in-game navigational purposes. The configuration files are done in JSON and I would recommend using this site to edit them.

This page will assist modders to install it, configure it, and use it.

Download Link

LINK

Required Files

All required files are included in the above download, including some sample files for demonstration and to inspire. The following files are the required files needed to make the script work if the modder wishes to remove the other files.

• /config/
  • imonitor.cfg (if imonitor-sct.tbm is to be used)
• /interface/
  • axui_box1.png
  • axui_cancel.png (+c and h variants)
  • axui_exit.png
  • axui_jumpto.png (+c and h variants)
  • axui_return.png (+c and h variants)
  • cb_sidetab.png (+c and h variants)
• /scripts/
  • dkjson.lua [[1]]
• /tables/
  • axui-sct.tbm
  • imonitor-sct.tbm
  • parsecfg-sct.tbm
  • sysviewer-sct.tbm
  • zLoadFirst-sct.tbm (written by Nuke)

Demonstration Files

• /interface/
  • nav_asteroids.png
  • nav_node.png
  • nav_node_big.png
  • nav_orion.png
  • nav_planet_b.png
  • nav_planet_g.png
  • nav_planet_p.png
  • nav_planet_r.png
  • nav_planet_y.png
  • nav_planet_b.png
  • nav_star_b.png
  • nav_star_r.png
  • nav_star_w.png
  • nav_star_y.png
  • nav_sys_vega.png

Configuration Files

The system viewer requires 2 configuration files (3 if an out-of-mission interface is desired). These files must be placed in the /config/ directory.

Interface Monitor

imonitor.cfg is a JSON configuration file for imonitor-sct.tbm which allows the player to access different custom interface screens. Full documentation can be found in Script - Interface Monitor.

Campaign Configuration File

Used to decide which system config that gets loaded during a campaign.

System Configuration File

Contains all the information to draw systems

Campaign Configuration File

A file with the format

sysview_[CAMPAIGN_FILENAME]_config.cfg

placed in the /config/ folder will be loaded when the System Viewer starts. Eg: sysview_Freespace2_config.cfg. The file is a JSON file with 2 required fields.

"File":

This will tell the script which system file to look at and load.

"Default":

This will load the specified system that the script will load by default.

"[missionfilename].fs2":

This will load the specified system when the mission's filename matches the one being played (or to be played next if the script was activated in the mainhall screen)

"sm01-01.fs2": Vega1

System Configuration File

This file contains the information the script uses to draw the system.

"[Internal Name]"

Object. The name of the object that contains the system configuration is used internally to change to keep track of the different systems in the file

"Name"

String, the displayed name. Drawn in the upper left corner in large text

"Description"

String, a subtitle to the name. Drawn below name in slightly smaller text

"Background"

Filename, the background that will be used in the system viewer screen. The view will be bound to this image (so its a good idea to make this a large image).

"Elements"

Object, this contains all the visible elements the player can interact with.

"[Internal Name]"

Object, this contains all the information to draw this element. The object's name will be the internal name for this element. This will be the name that gets written to a SEXP variable, navsys_destination, if the modder is using this as a navigational system. If this element is named "Player" it will be moved to navsys_destination as well.

"Name"

String, the name that will be drawn below the bitmap.

"Visible"

Boolean, if true it will draw this element.

"Bitmap"

Filename, should be in a folder with other graphic files (effects or maps etc). This is the bitmap that will be drawn. The script will also attempt to use the filename plus _h and _c for highlighted and clicked graphics.

"LargeBitmap"

Filename, will be drawn in the middle of the screen if this element is clicked.

"ShipClass"

String, if LargeBitmap is absent and ShipClass has a valid ship class, a rotating tech room style model will be rendered when an element is clicked on.

"ModelOrientation"

Array, 3 integers: pitch, bank, heading. If ShipClass was specified, this will be the default orientation in degrees that the model will be rendered as. Default is 17,0,180

"RotationSpeed"

Integer, the rotation speed of a model being rendered. No effect on Bitmaps. The Y-Axis is used as the rotation axis. Value is in degrees/second. Default is ~30 degrees/second.

"ShowOrbit"

Boolean, if true it will draw the circular orbit for this element. This does not allow hyperbolic or elliptical orbits. Optional.

"Selectable"

Boolean, if true the player can click on the object which will bring up detailed information about this object. Optional.

"CanJump"

Boolean, if true the player can click a "Jump To" button if this was activated during gameplay. Upon clicking JumpTo, the internal name for the element will be written to the SEXP Variable, navsys_destination, if it exists. It will also close the viewer. Optional.

"ForceJump"

Boolean, if true and the player clicks the "Jump To" button, it will force the player to jump out, ending the mission. Optional.

"Orbits"

String, internal name of another element. This will cause this element to have its orbit centered on the specified parent's orbit.

"Orbit"

Object. Defining, in polar coordinate terms, where to draw the element. Optional, but leaving this out will cause the element to be drawn in the middle of the screen.

"Distance"

Integer, the orbital radius in pixels.

"Angle"

Integer, the orbital angle in degrees. 0 degrees is the direction to the right side of the screen and goes clockwise.

"Color"

Array, 4 integers: red, green, blue, alpha. Color of the orbit path. Default is 192,192,192,255

"Width"

Integer, the width of the orbit path. Default is 3.

"Offset"

Object. Fine tuning a bitmap's placement. Optional.

"X"

Integer, this will move this object to the right by X pixels (negative values will move it to the left). This is in addition to the orbital distance and angle. (You could have two elements sharing the same orbital distance and angle, but have different offsets to place them differently)

"Y"

Integer, same as the X above, just for vertical placement.

"Icon"

Object. Draws a secondary bitmap over the element. Optional.

"Bitmap"

Filename, graphic file to be drawn

"X"

Integer, x coordinate of where the bitmap will be drawn relative to the top left of the element's bitmap. Two special values, "-" and "+" can be used instead to automatically move the icon to the left most or right most part of the element's bitmap.

"Y"

Integer, same as X above, just for vertical placement.

Using In-Game

There are a few things the player needs to take care of before they can use this effectively. First, the player should have No Subspace Drive. Check mark it in the ship editor or as a sexp. While in gameplay mode, the System Viewer will not be enabled by default, you can enable the script by using:

script-eval
 "SystemViewer.Allowed = true"

The System Viewer should now be able to be called up by going Alt-J. The script behaves just like it does outside the mission, except now there is a "Jump To" button available if the "CanJump" property was set in the config file.

When the "Jump To" button is selected, the object name (not the name property!) will be written to a sexp variable, "navsys_destination". (From the Vegalancer campaign, some examples would be "Norica" or "89thTF") If the ForceJump property was set, the player will automatically jump out.

Actually ensuring the player arrives at the next mission through the campaign file is now up to you. Since you can't use variables directly, you will need to use events that trigger to when a variable equals a certain string.

If an element in the system config file is named "Player", the script will automatically move it to the contents of "navsys_destination". This is handy so the player can see where he should be without the FREDder needing to make a thousand almost similar maps.