Kenabil's Map Viewer

From Wurm Unlimited
Jump to navigation Jump to search
View over the Awakening server

About the Map Viewer

This is a tool which will make it possible to render the Wurm server map to a web page. The generated files needs to be uploaded to a web page server. If you run a dedicated server, you can setup automatic updating of the map, see below.

The map viewer software is open source, and the project is located on GitHub and is found here:

https://github.com/awakening-wurm/MapViewer/releases

Features

Zooming

Zooming is done with the mouse wheel, and will then zoom into or out of the tile the mouse is pointing at. Alternatively, zooming can be done in the left hand panel by clicking on the + and - buttons. Zoom ranges between 25% and 800%.

Map Types

The map viewer renders the map to three formats:

Flat terrain
This view will show each tile as a square.
Topographic
On top of the flat terrain image is drawn topographic lines, and each line represents 100 slopes above or below water level.
Isometric
The isometric view is rendered as a 3D projection, giving the feeling of looking at a 3D map.

The Pointer and Coordinates

Clicking on the map will place a pointer, in the shape of a red arrow. This also updates the URL with the coordinates of the pointer, so you can send the pointer to friends and let them know about the location. The tile coordinates are also shown in the left hand panel, and when you move your mouse you can also see which tile the mouse is hovering over and the distance in tiles between the mouse and the pointer in both horizontal and vertical directions, as well as a straight line between the points. This is useful for example when planning roads.

Layers

There are a number of layers that can be added on top of the map, and which can be switched on and off with a set of checkboxes:

Deeds
Shows or hides that are visible deeds, i.e. deeds whee the mayor haven't opted to hide the deed (typically PvP deeds).
Perimeters
Shows the perimeters of deeds as a dotted line.
Guard Towers
Displays all existing guard towers on the server with a small guard tower icon.
Kingdoms
Adds a layer of kingdom influence of the map.
Highways
All planted highway nodes are drawn as yellow lines, and waystones are marked as orange dots. When catseyes are placed in a straight line or zig-zag, only the end-point nodes are registered, to minimize amount of data being sent to the browser.
Signs
Shows signs planted by players, with the message on the sign. Only signs planted off deed are shown.

Info

When the mouse is hovering over a special area, the info box will show information of interest. For example, by hovering over a deed it will show who is the mayor, when the deed was created, it's size etc.

Search

The search field will look for matching deeds as you type. By clicking on a deed in the list you will be directed to the deed.

How to use the map viewer

Download the zip-file for the release you which to use. Extract the files, there should be a file named mapviewer.jar and a file named mapviewer.properties. You need to edit the properties-file and adjust it with the settings you wish to use for your server. It's possible to configure for more than one server.

To run the renderer, you need to open a terminal, also called command prompt, and type: java -jar mapviewer.jar

If you configure to run more than one server, you should name each server and then use the command: java -jar mapviewer.jar [name of you server]

You can use the logging settings in the properties-file, then change the command like this: java -Djava.util.logging.config.file=mapviewer.properties -jar mapviewer.jar [name of your server]

Properties

For all of these properties, you can add a suffix starting with a dash, then add the name of your server, e.g. server-name-MyAwesomeServer = My Awesome Server, and when you render the map you should use the command java -jar mapviewer.jar MyAwesomeServer, which will let the program know that you want to use properties with the MyAwesomeServer-suffix instead of the default values. The program will always use default values if one with your server name suffix is missing. If you use only one server and only want to render one map, then only use the properties as they are listed.

Name of server
server-name = [name]
This will be the name written as the name of the server, and is also used in the title of the web page.
Web page URL
web-page-url = [url]
URL to your main web page, which will be linked to when clicking on the server name in the panel. Defaults to "/".
Steam Server ID
server-id = [id]
The server ID, used when loading server data. If omitted, loads the first server.
Directory to the server data (static or relative path)
map-directory = [path]
Should be the the root directory where the map-files are located. Defaults to server-name, so will then look for a directory in the map viewer directory with the server name.
Original map directory, used for hiding terraforming on hidden deeds
original-map-directory = [path]
Should be the the root directory where the map-files of the original map are located. This is used for deeds that are hidden, which is a feature that requires the Awakening Server Mod installed on the server, where mayors can opt to hide their deeds. Defaults to server-name + "_original". This also requires that use-player-settings is set to true.
Directory where the generated files will be written
output-directory = [path] (default: "./mapviewer")
Output format of the index file
output-format = [html|php]
Whether the generated index-file will be HTML or PHP format.
Overwriting existing files
overwrite-existing-resources = [true|false] (default: false)
If set to true, already existing resource files, such as images and css and js files will be overwritten (not including config.js).
overwrite-existing-index = [true|false] (default: true)
If set to true, the file index.html (or index.php depending on output-format) will be overwritten.
overwrite-existing-config = [true|false] (default: true)
If set to true, the config.js file will be overwritten.
Set the default map type when map is first loaded
default-map-type = [terrain|topographic|isometric] (default: terrain)
Show layers in the sidepanel (this must be set to true for some addons to work)
show-layers = [true|false]
Show deeds on the map
show-deeds = [true|false]
Show guard towers on the map
show-guard-towers = [true|false]
Generate highway data, which is used by the Highways addon
show-highways = [true|false]
Show signs on the map
show-signs = [true|false]
Show deed borders on the isometric map
show-deed-borders-in-3d-mode = [true|false]
Show deed borders on the terrain and topographical maps
show-deed-borders-in-flat-mode = [true|false]
Use player settings
use-player-settings = [true|false]
This requires that the server has the Awakening Server Mod installed. Defaults to false.
Use addons
use-addons = [true|false]
Activates loading of addons.
addons-directory = [path] (default [output-directory]/addons)
Create a directory named "addons" in the output directory, and place addons files there.
addons-url = [url]
Set this to [web-page-url]/addons
Custom guard towers
guard-tower-ids = [ids]
Value should be a comma-separated list of template ids. Only set this property if your server has custom guard towers, for example if you have the Add Kingdom Items Mod installed.
Kingdom colours
kingdom-colors = [color-list]
The list of colours start at index 0, and should have a colour for each kingdom on the server, and also include any missing ids. If one kingdom has id 3 and one id 5, but 4 is missing you will have to include colours for 3, 4, and 5. When show-signs=false is set, this property can be omitted.

Addons

With version 1.2 came the option to create addons, and people are encouraged to write new and interesting addons and submit to the project. The addons are included in the zip-file when downloading release versions of 1.2 and higher. To install an addon, copy the files to an addons folder inside the output-directory, and point addons-directory to this dierctory, and the corresponding addons-url, you should also set use-addons to true.

  • Locate soul Assistant - By: Axeblade, 2021 - It draws the area on the map of anything that uses locate soul - or a similar method of finding a location, as a base to help you find the location faster.
  • Kingdoms - The kingdoms addon shows kingdom influence, which is useful on PvP servers where you only can deed within kingdom influence. Kingdom influence is based on guard towers.
  • Highways - The highways addon draws lines on the map showing where there are highways and highway signs. There's a checkbox in the layers panel for showing or hiding the highways. Highways in caves and on bridges have a different colour.

Setup Automatic Updating

This requires that you run a dedicated server. First step then is to install the map viewer on the server. Next you need to setup a scheduled task which calls the map viewer program, in Linux that can be done either using crontab or systemctl. This guide will not explain how to do that. The scheduled task should first make a backup of the Wurm data, both map files and sqlite-db-files, then in the properties-file point to that backup. Also, in the properties file, make sure to point output-directory to where the web page is located.

Styling the Map

You can style the map anyway you like by editing main.css. Remember though that the index-file will be generated each time the map is rendered, as will the script config.js and the map-image png-files; all other files can be edited or replaced and won't be over-written. If you wish to add functionality, you can do this by editing the map.js script. Guard tower icons can be replaced, but if the size is changed or the base point, which is at the base of the small door on the tower, they won't be positioned correctly on the map.

Releases

Note: When installing a new version of the map viewer (unless you've manually edited the script files or replaced the images), remove all previous files in the map directory. Those will be replaced by new files generated by the map viewer. Otherwise you may get the wrong version of map.js for instance, or not get the latest version of the styling. The map viewer will only replace config.js, index.html or index.php (depending on settings) and the map image files when rendering, all other files will only be exported if they don't exist. This is to permit that you edit the other files, replace images or re-style the CSS etc. without writing over those files every time you render the map. So remember: After you install an update, remove all generated files, before you run the program.

The two latest release versions can be downloaded here. Older versions have to be built from sources, or PM Kenabil in the forum or on Discord and I can build one version for you.

V1.2.2 Compass addon

The Compass addon places a small compass on the map, which can be used for setting the direction a player is facing. It's was added as support for other addons such as LSA, which also has been updated to read the compass direction.

V1.2.1 LSA addon update + addons: Highways and Kingdoms + Badges

Addon Locate Soul Assistant has been modified to replace the previous UI and instead you place a pointer on the map, and copy-paste the search message into the map viewer's search field. The message is recognized by the addon and will add a node. Each node draw's a search area on the map. In the layers list you can uncheck "Locate Soul Assistant" to clear nodes.

Two more addons have been extracted from the main map viewer's code: Kingdoms and Highways. For two reasons, first to make it easy for hosts to simply not install these addons to not have these map features (though you still have the show-highways property which is used to write the highway nodes to the config.js script). Secondly, to showcase how addons can be written, as practical examples.

A badge feature has been added, which is to visually show which addons are installed and when clicking on a badge allows addons a way to present itself and to give usage instructions. The badges are listed on the bottom right side of the map.

Fix: A bug in previous version caused a null pointer error, which was fixed.

Fix: Prevent mouse wheel from zooming when over the sidebar.

V1.2.0 Addons interface + LSA addon by Axeblade

Addons can be placed in a dedicated directory, js and css files will be added to the index-file and loaded in the mapviewer. Use the new properties use-addons, addons-directory and addons-url to configure.

Axeblade was kind to commit his addon "Locate Soul Assistant" (LSA), which can draw on the map the area where you can expect to find a location, given directions in Wurm.

New properties for enabling/disabling overwriting of files: overwrite-existing-resources for resource files such as images and scripts; overwrite-existing-index for the index file, in case it's been modified and should not be overwritten; overwrite-existing-config the config.js file (this contains all map data, including deeds etc.).

Fix: Only list kingdoms with at least one existing deed (Note: kingdoms may possibly have only hidden deeds, and will then be invisible).

V1.1.5 Added params for URL + improved UI

This minor update improves the UI by adding a menu button for all modes and a scrolling sidebar for smaller displays. Many fixes and updates to the CSS stylesheet.

The URL now stores both pointer and the center of the view. No pointer has to be set to share the exact view.

V1.1.4 State of map view in URL + responsive UI

The state of the view is stored in the URL, so copying the URL from the browser will retain zooming and selected layers. This way you can place a pointer or select a deed, zoom in and then easily share the view with friends.

The map view has been improved for viewing and using in mobile devices. The UI has been resized and is hidden by default with a "hamburger" button to slide the sidebar into view.

Fix: Kingdom influence has been corrected.

V1.1.3 Kingdom influence and Signs

Two added layers: kingdoms and signs.

Kingdoms will show the influence of each kingdom in the colour of each kingdom. Signs shows planted sign items, so that players can create and plant signs with messages that are visible on the map. Improved information in general, in the info box. Highways are all shown with the highways checkbox.

V1.1.2 Deed Perimeters

This small update adds a checkbox for displaying deed perimeters as a dashed border outside of deed borders.

A new property has been added neutral-land-name which defaults to server-name and which will show a name for neutral land instead of the previous "Awakening".

V1.1.1 Custom Guard Towers

I've added a property for loading custom guard towers. The property is named guard-tower-ids and should contain a comma-separated list of template ids for the custom guard towers.

If you don't use custom guard towers, then you won't need this update. For example: servers with the Add Kingdom Iitems Mod installed have custom guard towers.

Don't add vanilla guard towers to this list, only the custom guard towers. If you enter the template id of any other type of item, it will show as guard towers on the map too - for example setting the value 184 will show all large chests on the map as guard towers.

V1.1.0 Settings update

It's a minor update, but adds properties for setting up the map viewer on public servers. The Awakening Server mod isn't required, but adds setting for mayors for deed visibility on the map.

V1.0.3 Bridges and tunnels

Highways now also renders correctly in the isometric map, adding a height value to each node. Highways on bridges and in tunnels are rendered separately. Guard towers get a new image, with brighter colours for improved visibility.

V1.0.2 Highways

Checkbox for highways is enabled and highway nodes are extracted from db, and rendered to the map.

V1.0.1 HTML Overhaul

Mostly changes to HTML and CSS, and added some images.

V1.0.0 Guard Towers

Added guard towers, improved zooming, deed info, player settings, topographic map etc.

Retrieved from "https://wiki.wurm-unlimited.net/w/index.php?title=Kenabil%27s_Map_Viewer&oldid=243"