System Map
by phkb

This mod adds a "System Map" view to either the F7 System Data screen (for Oolite 1.92) or the F4 Interfaces screen.
To access the map on the F7 screen, simply press "S". On the F4 Interfaces screen, select the "View system map" item.

What is shown
=============
The system map will show the following items for the current system:
    Sun
    Witchpoint beacon
    All planets and moons
    Most non-mobile stations with traffic
    Your current position

The main station will the coloured blue to distinguish it from other stations.

Planets are numbered in the following way:
    The main planet is "1".
    Other planets are numbered from 2-9 based on their distance from the sun.

Planets can be either green (for a normal planet) or purple (for a gas giant).

If the PlanetFall/PlanetFall2 mod is installed, planets and moons that have landing points will be marked with a hexagon.

The map will show the position the various entities in relation to one another.

Note: Changing the system viewed on the F7 screen will not show the system map for that system. The system map will only show the map for the current system.
Note: The system map is unavailable in interstellar space.

Map controls
============
When accessed from the F7 screen, the following controls are available:
    Arrow keys: Rotate the map in the given direction.
    Ctrl+Arrow keys: Move the map up/down/left/right on the screen
    Page Up/Down: Zoom in/out.
    F: Change the current map focus.
    R: Reset the map back to the initial view.
    H: Hide the control information

When access from the F4 Interfaces screen, the following menu will be available:

    Movement>>: Switch to the movement controls
    Move Up: Move the map up the screen
    Move Down: Move the map down the screen
    Move Left: Move the map to the left
    Move Right: Move the map to the right
    Rotation>>: Switch to the rotation controls
    Rotate Up: Rotate the map up
    Rotate Down: Rotate the map down
    Rotate Left: Rotate the map to the left
    Rotate Right: Rotate the map to the right
    Zoom In: Zoom the map in
    Zoom Out: Zoom the map out
    Change Focus: Changes the current map focus.
    Reset View: Reset the map back to the initial view
    Hide Controls: Hide most of the controls
    Show Controls: Un-hide all the controls.

When you rotate the map, it will continue to rotate in the given direction until you issue another rotation command.

Changing the map focus will change the color of all entities to grey except for the focused entity. The name of the focused entity will be displayed at the top of the screen. Repeating the focus command will cycle through all entities and then return to "None", when no entities are the focus. Resetting the view will also reset the focus.

3rd Party access
================
It is possible for other mods to add extra points of interest to the map. To do so, use the following code:

  var sm = worldScripts.SystemMap;
  
  // if you have an ship/station entity you want to show
  sm.$addCustomMarker({
    ent: myCustomShip,
    map: "markerimage.png",
    col: 1
  });
  
  // if you just want to mark a position
  var myPos = Vector3D(0.0, 0.0, 0.5).fromCoordinateSystem("wpu")
  sm.$addCustomMarker({
    pos: myPos,
    map: "markerimage.png",
    col: 2
  });

When using the "ent" (entity) option, and this item becomes the map focus, the text displayed for it will follow the following logic:
    If a "displayName" property has been included in the definition for the marker, that will be used.
    If the entity has a displayName, that will be used.
    Otherwise, the entity name will be used.

When using the "pos" (position) option, and this item becomes the map focus, the text displayed for it will follow the following logic:
    if a "displayName" property has been included in the definition for the marker, that will be used.
    The text "Point of interest" will be used.

When included, the "map" should be an image in the Textures folder, 128x128 in size. Included with the System Map OXP are:
    map_planet.png
    map_planet_1-9.png
    map_planet_pf1-9.png
    map_moon.png
    map_moon_pf.png
    map_point.png
    map_question.png
    map_station.png

Some others can be found in the Library OXP.

If "map" is not included, it will default to "map_station.png".

When included, the "col" should be a number between 0-9
    0 or not included: white
    1: red
    2: green
    3: blue
    4: purple
    5: gray
    6: aqua
    7: amber
    8: gold
    9: UV
    10: brown
    11: dark gray
    12: yellow

Requirements
============
The Library OXP is a requirement of this mod.

Settings
========
There is one setting available via Library Config.

Value - Display units: This value allows the units used on the map to be changed. The available options are:
    0 = OU (1 OU roughly equals the distance between the planet and sun in Lave in an unmodified game)
    1 = km (default)
    2 = m
    3 = CZ (Cavezzi) (1 CZ = 0.47929218 m)

License
=======
This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 4.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/

Version History
===============
0.7
- Added distance to player to focused entity.
- Distance unit type can be selected with Library Config.
- For planets and moons that have a beacon attached (eg via Planetary Compass), the beacon label will be used for the display name.
- Switched to using the custom marker system for the Tianve Pulsar.

0.6
- Added current system name to the title of the System Map screen, to make it clear it's for the current system only.

0.5
- Added some more error checks for the custom markers.
- Reordered the way items are added to the array, so similar items (eg planets, stations) are always grouped together.
- Added compatibility with PlanetFall v1.

0.4
- Tweak to script name to try to fix missing interface entry.

0.3
- Initial release.
