Skip to content

Configuring the Plugin

Jump to bottom
silverwolfg11 edited this page May 26, 2021 · 7 revisions

Configuring the Plugin

After running the plugin once, there will be three files in the plugin's directory (/plugins/Pl3xMap-Towny): config.yml, click_tooltip.html, and hover_tooltip.html. Each one will be discussed in more detail below. You do not need to stop the server to make changes to any of the files. Simply make changes to a file(s), save the file(s), and then execute /pl3xmaptowny reload (with the correct permissions).

Config.yml

The config contains all of the settings for rendering a town claim. Any changes to the config file should be verified with a YAML validator (such as this). If an incorrect value is entered, the plugin will spit out an error in console and resort to using the default value. Only the most important properties will be discussed on this page.

Default Config.yml

NOTE: This config may not be the latest one!

# Worlds that should display town claims.
enabled-worlds:
- world

# How often should the plugin render all towns? (In minutes)
update-period: 5

# Layer Properties
layer:
  # Name of the layer
  name: Towny
  # Should the layer be toggleable by users?
  show-controls: true
  # Should the layer be invisible by default?
  default-hidden: false
  # Layer Priority.
  # Don't need to touch this unless other Pl3xMap add-ons are interfering with the layer.
  layer-priority: 5
  # The z-index on which the layer will display.
  # Decrease if you want the layer to be more blended in with the map.
  z-index: 250

# Fill Style.
# Properties about how claims should look on the map
fill-style:
  # Whether to fill the claim with color
  fill: true
  fill-color: '#3388ff'
  fill-opacity: 0.2
  # Use specified nation color as the fill color instead?
  use-nation-color-fill: true
  
  # Whether to draw a stroke along the claim path.
  stroke: true
  # Stroke width in pixels
  stroke-weight: 3
  stroke-color: '#3388ff'
  stroke-opacity: 1.0

# Icon Properties:
# Icons are placed at the center of a town's homeblock.
icon-info:
  # Icon for the town's homeblock. Icon must be a valid image URL.
  # Default Icon created by icon king1 licensed under Creative Commons 3.0
  # https://creativecommons.org/licenses/by/3.0/
  town-icon: https://pics.freeicons.io/uploads/icons/png/20952957581537355851-512.png
  # Icon for a town if they are the capital of the nation. Icon must be a valid image URL.
  # Put 'default' to use the town icon image.
  capital-icon: default
  # Icon for an outpost claim that will appear at the location of outpost spawns. Icon must be a valid image URL.
  # Put 'default' to use the town icon image.
  # Put 'empty' to not place icons at outposts.
  outpost-icon: default
  # Height of the icon
  icon-height: 35
  # Width of the icon
  icon-width: 35
# Do not touch!!!
config-version: 0.55

The plugin works out of the box for the most part, however the one thing that may need to be adjusted is the enabled-worlds setting. Make sure to add all the worlds you want to have town claims show up for.

The update-period property is how often the render task will execute. The render task is what makes the town claims appear, and updates the town information when a town is clicked or hovered over. The value is represented as minutes and its default is set to 5 so the task executes every 5 minutes. The value is an integer (whole number), so no decimals allowed. If you want more frequent renders, you can reduce the value, and the task will execute more often. The render task does do some computational work which may be expensive depending on the number of total towns and total townblocks on the server, so please be mindful of that when adjusting the update-period.

The fill style properties affect the visual aspect of the claim and style of how the claim is drawn. Both fill-color and stroke-color only accept hexadecimal values. Please feel free to mess around with the fill-style to see what looks best for you.

The last set of properties is the icon info. Each icon is essentially just a picture, so you can use any picture that you think will make a good icon. All you need is a valid URL for the image. Please keep in mind that if you're using an URL that has https, that the security certificate is not expired. If it is, the image will not work (and errors will show up in console). The nation and outpost icons both have a default value of default which uses the town-icon image. If you do not want outpost icons to appear at the outpost spawns, you can specify empty for the outpost-icon property.

All in all, the config should be very user-friendly, and please don't be afraid to mess around with the values to see which ones you like. Most (all except one) config values do not affect performance and only affect visuals.

Click_tooltip.html and Hover_tooltip.html

The click_tooltip.html file is used to generate the information every time you click on a town claim or a town icon. The hover_tooltip.html file is used to generate information every time you hover over a town claim or a town icon. Obviously, both files accept HTML so please play with the formatting that suits your needs best.

Default Click_tooltip.html

Warning: The file below may not be up-to-date!

<!--
Placeholders:
%town% = Town Name
%nation% = Nation Name (if it exists or empty)
%nationstatus% = If capital, "Capital of [Nation]", otherwise "Member of [Nation]" or empty if not in nation.
%mayor% = Name of Mayor
%board% = Town Board
%founded% = Formatted date of when the town was founded.
%rank_{rank name}% = Comma-separated list of residents that have the specified town rank or "None" if none exist.
%residentcount% = Number of residents in the town.
%residents% = Comma-separated list of all residents in the town or none
%residentdisplaynames% = Comma-separated list of resident display names if resident online or town formatted names if offline.

If economy is enabled:
%tax% = Town Tax
%upkeep% = Town Upkeep
%bank% = Cached Town Balance

%pvp% = Boolean (true/false) whether pvp is enabled in the town
%firespread% = Whether firespread is enabled in the town
%mobs% = whether mobs are enabled in the town
%explosion% = whether explosions are enabled in the town
-->
<div class="infowindow">
    <span style="font-size:120%;">%town% (%nation%)</span>
    <br/>
    Mayor:
    <span style="font-weight:bold;">%mayor%</span>
    <br/>
    Assistants:
    <span style="font-weight:bold;">%rank_assistant%</span>
    <br/>
    PVP:
    <span style="font-weight:bold;">%pvp%</span>
    <br>
    <bold>Residents: </bold><span>%residents%</span>
</div>
Default Hover_tooltip.html

Warning: The file below may not be up-to-date!

<!--
Placeholders:
%town% = Town Name
%nation% = Nation Name (if it exists or empty)
%nationstatus% = If capital, "Capital of [Nation]", otherwise "Member of [Nation]" or empty if not in nation.
%mayor% = Name of Mayor
%board% = Town Board
%founded% = Formatted date of when the town was founded.
%rank_{rank name}% = Comma-separated list of residents that have the specified town rank or "None" if none exist.
%residentcount% = Number of residents in the town.
%residents% = Comma-separated list of all residents in the town or none
%residentdisplaynames% = Comma-separated list of resident display names if resident online or town formatted names if offline.

If economy is enabled:
%tax% = Town Tax
%upkeep% = Town Upkeep
%bank% = Cached Town Balance

%pvp% = Boolean (true/false) whether pvp is enabled in the town
%firespread% = Whether firespread is enabled in the town
%mobs% = whether mobs are enabled in the town
%explosion% = whether explosions are enabled in the town
-->
<div>
    <bold>%town% (%nation%)</bold>
</div>

The files also accept a few placeholders described in the files themselves and here below. Each placeholder is usually surrounded by % signs. Warning: Placeholders below may not be up-to-date!

Placeholder Description Example Replacement
%town% The town name. %town% -> TestTown
%nation% or (%nation%) Name of the nation the town being rendered is in. If the town is not in a nation, the placeholder will be empty. Town test belongs to Antartica. %nation% -> Antartica. The town abc does not have a nation. %nation% -> . If the placeholder is (%nation%), and the town does not have a nation, then the parentheses will also be replaced. E.g. for abc, (%nation%) -> .
%nationstatus% Returns the relationship of the town with its nation. If town is capital: %nationstatus% -> Capital of [Nation]. If town is a member of a nation: %nationstatus% -> Member of [Nation]. If town doesn't have a nation: %nationstatus% -> .
%mayor% Name of the town's mayor %mayor% -> Steve
%board% Town Board. E.g. town's board is "Hello world!". %board% -> Hello World!
%founded% Formatted date of when town was founded. E.g. town was founded October 28, 2020. %founded% -> Oct 28 2020
%residentcount% Number of residents in the town. E.g. town has 26 residents. %residentcounts% -> 26
%residents% Comma-separated list of all residents in the town. %residents% -> Steve, Alex, Notch
%residentdisplaynames% Comma-separated list of resident display names if resident online or town formatted names if offline. %residentdisplaynames% -> Count Von Bob, Jester Notch
%rank_{rank name} Comma-separated list of all residents with the rank specified. %rank_assistant% -> Bob, Charlie
%pvp% Whether PVP is enabled in the town. %pvp% -> true or %pvp% -> false
%firespread% Whether fire-spread is enabled in the town. %firespread% -> true or %firespread% -> false
%mobs% Whether mobs are allowed to spawn in the town. %mobs% -> true or %mobs% -> false
%explosions% Whether explosions are toggled in the town. %explosions% -> true or %explosions% -> false

Some placeholders require that economy to be enabled:

Placeholder Description Example Replacement
%tax% The town tax. E.g. 5% town tax. %tax% -> 5%
%upkeep% Town Upkeep. E.g. Town upkeep is 500, currency format is $. %upkeep% -> $5
%bank% Cached Town Balance. Towny updates the balances every 5-10 minutes. E.g. town has $10. %bank% -> $10
Clone this wiki locally