JourneyMap Client API v1 DRAFT

/*///////////////////////////////////////////////////////////////////////
This is a draft.  Feedback/comments welcome on Espernet IRC #journeymap
//////////////////////////////////////////////////////////////////////*/

package journeymap.api.v1;

import java.util.List;

/**
 * JourneyMap Client API v1 DRAFT (Dec 10, 2015 18:00)
 */
public interface JourneymapClientAPI
{
    /**
     * Whether the JourneyMap client mod is loaded.
     *
     * @return true if loaded
     */
    public boolean isModLoaded();

    /**
     * Whether the JourneyMap client mod loaded has a compatible
     * version of the API.
     *
     * @return true if mod is loaded and API is compatible
     */
    public boolean isModAPICompatible();

    /**
     * The API version of the JourneyMap client mod.
     *
     * @return 0 if client mod isn't loaded, otherwise the API version.
     */
    public int getModAPIVersion();

    /**
     * Check whether player will accept waypoint additions/removals by your mod.
     *
     * @param modId Mod id
     * @return Unknown: Player hasn't decided how to respond to waypoint suggestions.
     * Prompt:  Player will be prompted to add/remove each suggested waypoint.
     * Allow:   Player will automatically add/remove suggested waypoints
     * Block:   Player will not receive waypoints from your mod.
     */
    public PlayerResponse checkPlayerWaypointOptIn(String modId);

    /**
     * Check whether player will accept map overlays (markers and polygons) from your mod.
     *
     * @param modId Mod id
     * @return Unknown: Player hasn't decided how to respond to map overlays.
     * Allow:   Player will receive and automatically see map overlays.
     * Hide:    Player will receive map overlays but is currently hiding them.
     * Block:   Player will not receive map overlays from your mod.
     */
    public PlayerResponse checkPlayerMapOverlayOptIn(String modId);

    /**
     * Suggest a waypoint to the player. The outcome is based on what the PlayerResponse is
     * regarding your mod and waypoint suggestions.  Note that just because a player accepts
     * a suggested waypoint, doesn't mean they'll keep it forever.
     *
     * @param modId          Mod id
     * @param specification  Specification for the waypoint to display.
     * @see #checkPlayerWaypointOptIn(String)
     */
    public void addWaypoint(String modId, WaypointSpec specification);

    /**
     * Remove a player's waypoint, if it exists. The outcome is based on what the PlayerResponse is
     * regarding your mod and waypoint suggestions.
     *
     * @param modId      Mod id
     * @param waypointId A unique id (within your mod) for the waypoint.
     * @see #checkPlayerWaypointOptIn(String)
     */
    public void removeWaypoint(String modId, String waypointId);

    /**
     * Check whether the player has a waypoint with the given waypointId associated with your mod.
     * If the PlayerResponse regarding waypoints from your mod is Block, this will always return false.
     *
     * @param modId      Mod id
     * @param waypointId A unique id (within your mod) for the waypoint.
     * @return true if a waypoint with the id exists.
     */
    public boolean getWaypointExists(String modId, String waypointId);

    /**
     * Gets a list of player waypoint ids associated with your mod.
     * If the PlayerResponse regarding waypoints from your mod is Block, an empty list will be returned.
     *
     * @param modId Mod id
     * @return A list, possibly empty.
     */
    public List<String> getWaypointIds(String modId);

    /**
     * Attempt to show a marker on one or more map views.  The outcome is based on
     * what the PlayerResponse is regarding your mod and map overlays.
     * <p/>
     * If a marker with the provided featureId already exists, the new one will replace the old one.
     *
     * @param modId            Mod id
     * @param specification    Specification for the map marker.
     * @see #checkPlayerMapOverlayOptIn(String)
     */
    public void addMarker(String modId, MarkerSpec specification);

    /**
     * Gets a list of map marker ids associated with your mod.
     * If the PlayerResponse regarding map overlays from your mod is Block, an empty list will be returned.
     *
     * @param modId Mod id
     * @return A list, possibly empty.
     */
    public List<String> getMarkerIds(String modId);

    /**
     * Remove a map marker, if it exists. The outcome is based on what the PlayerResponse is
     * regarding your mod and map overlays.
     *
     * @param modId    Mod id
     * @param markerId A unique id (within your mod) for the map marker.
     */
    public void removeMarker(String modId, String markerId);

    /**
     * Check whether the player has a map marker with the given markerId associated with your mod.
     * If the PlayerResponse regarding map overlays from your mod is Block, this will always return false.
     *
     * @param modId    Mod id
     * @param markerId A unique id (within your mod) for the map marker.
     * @return true if a waypoint with the id exists.
     */
    public boolean getMarkerExists(String modId, String markerId);

    /**
     * Attempt to show a polygon on one or more map views.  The outcome is based on
     * what the PlayerResponse is regarding your mod and map overlays.
     * <p/>
     * If a polygon with the provided featureId already exists, the new one will replace the old one.
     *
     * @param modId            Mod id
     * @param specification    Specification of the polygon to display
     * @see #checkPlayerMapOverlayOptIn(String)
     */
    public void showPolygon(String modId, PolygonSpec specification);

    /**
     * Gets a list of polygon ids associated with your mod.  If the PlayerResponse regarding map overlays from your
     * mod is Block, an empty list will be returned.
     *
     * @param modId Mod id
     * @return A list, possibly empty.
     */
    public List<String> getPolygonIds(String modId);

    /**
     * Remove a polygon, if it exists. The outcome is based on what the PlayerResponse is
     * regarding your mod and map overlays.
     *
     * @param modId     Mod id
     * @param polygonId A unique id (within your mod) for the polygon.
     */
    public void removePolygon(String modId, String polygonId);

    /**
     * Check whether the player has a polygon with the given markerId associated with your mod.
     * If the PlayerResponse regarding map overlays from your mod is Block, this will always return false.
     *
     * @param modId     Mod id
     * @param polygonId A unique id (within your mod) for the polygon.
     * @return true if a polygon with the id exists.
     */
    public boolean getPolygonExists(String modId, String polygonId);
}

////////////////////////////////////////////////////////////////////

/**
 * A MapPoint is a triple of world coordinates.
 */
public class MapPoint
{
    public int x;
    public int y;
    public int z;
}

////////////////////////////////////////////////////////////////////

/**
 * A MapPolygon is a sequence of at least 4 points, the first and last being equal.
 */
public class MapPolygon extends ArrayList<MapPoint>
{
}

////////////////////////////////////////////////////////////////////

/**
 * Options defining how a map Marker should be displayed.
 */
public class MarkerSpec
{
    /**
     * A unique id for the marker which can be used to remove/update it.
     */
    public String markerId;

    /**
     * A suggested group or category name used to organize map overlays.
     */
    public String overlayGroupName;

    /**
     * Location of the marker.
     */
    public MapPoint point;

    /**
     * Rollover text to be displayed when the mouse is over the polygon.
     */
    public String title;

    /**
     * Label text to be displayed in the center of the polygon.
     */
    public String label;

    /**
     * Font color (rgb) of the label and title.
     */
    public int color;

    /**
     * Resource location of an icon to display
     */
    public String iconResourceLocation;

    /**
     * X offset for icon (necessary for sprite sheets).
     * Leave as 0 for default.
     */
    public int iconOriginX;

    /**
     * Y offset for icon (necessary for sprite sheets).
     * Leave as 0 for default.
     */
    public int iconOriginY;

    /**
     * Icon width in pixels from iconOriginX.
     */
    public int iconWidth;

    /**
     * Icon height in pixels from iconOriginY.
     */
    public int iconHeight;

    /**
     * Number of pixels to offset the icon laterally from the point on the map.
     */
    public int iconAnchorX;

    /**
     * Number of pixels to offset the icon vertically from the point on the map.
     */
    public int iconAnchorY;

    /**
     * If true, a click event (from fullscreen map or web map) will be generated via the API.
     */
    public boolean clickable;

    /**
     * The minimum zoom level (0 is lowest) where the polygon should be visible.
     */
    public int minZoom = 0;

    /**
     * The maximum zoom level (8 is highest) where the polygon should be visible.
     */
    public int maxZoom = 8;

    /**
     * All features are displayed on the map in order of their zIndex, with higher values
     * displaying in front of features with lower values. Default is 1000.
     */
    public int zIndex = 1000;

    /**
     * Whether the polygon should be displayed in the Minimap.
     */
    public boolean inMinimap = true;

    /**
     * Whether the polygon should be displayed in the Fullscreen map.
     */
    public boolean inFullscreen = true;

    /**
     * Whether the polygon should be displayed in the Web map (when enabled).
     */
    public boolean inWebmap = true;
}

////////////////////////////////////////////////////////////////////

/**
 * Describes the player's response to the attempt by your mod to
 * display waypoints or map features.
 */
public enum PlayerResponse
{
    /**
     * Player hasn't decided how to respond.
     */
    Unknown,

    /**
     * Player will be prompted to accept/reject each item.
     */
    Prompt,

    /**
     * Player will automatically accept or display each item.
     */
    Allow,

    /**
     * Player will recieve item but has elected to hide them.
     */
    Hide,

    /**
     * Player will not receive the item at all.
     */
    Block;
}

////////////////////////////////////////////////////////////////////

/**
 * Specification defining how a polygon map overlay should be displayed.
 */
public class PolygonSpec
{
    /**
     * A unique id for the polygon which can be used to remove/update it.
     */
    String polygonId;

    /**
     * A suggested group or category name used to organize map overlays.
     */
    String overlayGroupName;

    /**
     * Rollover text to be displayed when the mouse is over the polygon.
     */
    public String title;

    /**
     * Label text to be displayed in the center of the polygon.
     */
    public String label;

    /**
     * A polygon of the outer area to be displayed.
     */
    MapPolygon outerArea;

    /**
     * (optional) A list of polygons treated as holes inside the outerArea
     */
    List<MapPolygon> holes;

    /**
     * If true, a click event (from fullscreen map or web map) will be generated via the API.
     */
    public boolean clickable;

    /**
     * Line thickness of the polygon edges.
     */
    public float strokeWidth;

    /**
     * Line color (rgb) of the polygon edges.
     */
    public int strokeColor;

    /**
     * Line opacity (between 0 and 1) of the polygon edges.
     */
    public float strokeOpacity;

    /**
     * Fill color (rgb) of the polygon.
     */
    public int fillColor;

    /**
     * Fill opacity of the polygon.
     */
    public int fillOpacity;

    /**
     * The minimum zoom level (0 is lowest) where the polygon should be visible.
     */
    public int minZoom = 0;

    /**
     * The maximum zoom level (8 is highest) where the polygon should be visible.
     */
    public int maxZoom = 8;

    /**
     * All features are displayed on the map in order of their zIndex, with higher values
     * displaying in front of features with lower values. Default is 1000.
     */
    public int zIndex = 1000;

    /**
     * Whether the polygon should be displayed in the Minimap.
     */
    public boolean inMinimap = true;

    /**
     * Whether the polygon should be displayed in the Fullscreen map.
     */
    public boolean inFullscreen = true;

    /**
     * Whether the polygon should be displayed in the Web map (when enabled).
     */
    public boolean inWebmap = true;
}

////////////////////////////////////////////////////////////////////

/**
 * Specification defining how a waypoint will be suggested to a user.
 */
public class WaypointSpec
{
    /**
     * Unique id (scoped to your mod)
     */
    String waypointId;

    /**
     * (Optional) Group or category name for the waypoint.
     */
    String waypointGroupName;

    /**
     * Waypoint name.
     */
    String waypointName;

    /**
     * Waypoint location.
     */
    MapPoint point;

    /**
     * Dimensions where waypoint should be displayed.
     */
    int[] dimensions;

    /**
     * Color of the waypoint.
     */
    public int color;

    /**
     * Resource location of an icon to display
     */
    public String iconResourceLocation;

    /**
     * X offset for icon (necessary for sprite sheets).
     * Leave as 0 for default.
     */
    public int iconOriginX;

    /**
     * Y offset for icon (necessary for sprite sheets).
     * Leave as 0 for default.
     */
    public int iconOriginY;

    /**
     * Icon width in pixels from iconOriginX.
     */
    public int iconWidth;

    /**
     * Icon height in pixels from iconOriginY.
     */
    public int iconHeight;
}