Template:Map/doc

This is a documentation subpage for Template:Map. It contains usage information, categories, and other content that is not part of the original template page.

Template:Map invokes function map in Module:Map using Lua.

The Map template is used to easily create interactive maps or inline links to interactive maps. To find coordinates of a specific map square, use a tool such as https://mejrs.github.io/osrs. For a guide on how to manually define maps, see RuneScape:Create Map.

Usage

Basic map

A map with no arguments will default to Lumbridge. Provide an X/Y coordinate to define where the map is centered.

{{Map}}	{{Map|3165,3494}}

Pins

In the following sections are various map features, such as pins, that are defined with an mtype. Multiple coordinates can produce multiple single-point features.

Pins are mostly used to mark things that take up a 1x1 space or otherwise have an exact X/Y location.

One pin	Multiple pins
{{Map|mtype=pin|2965,3381}}	{{Map|mtype=pin|2638,3300|2661,3308}}

Dots

Like pins, dots are also used to mark precise locations. However, dots are better suited for marking many tightly packed coordinates.

Tightly packed dots	Cluttered pins
{{Map|mtype=dot ... }}	{{Map|mtype=pin ... }}

Text

A text feature is another way to mark a precise location but with a label describing the subject. Though there are configurable popups, a text feature provides a more immediate and obvious label for something.

{{Map|mtype=text|2512,3466|label=Dead tree}}

Circles and squares

Circles and squares are defined by a single point and a radius r. The point defines the centre of the shape and, for squares, r defines half the length of the square's edges—i.e., the shortest distance from its centre to one of its edges.

Circle	Square
{{Map|mtype=circle|r=18|3165,3490}}	{{Map|mtype=square|r=3|3316,3163}}

Rectangles

Like circles and squares, rectangles are also defined by a single point. Its side lengths, though, are defined with rectX and rectY.

{{Map|mtype=rectangle|rectX=11|rectY=15|3185,3440}}

Lines and polygons

Lines and polygons are defined with a series of coordinates. Unlike lines, polygons are automatically closed—i.e., the start and end points are attached.

Lines are used to draw a walkable path or general route, while polygons are used to outline a map location (e.g., building) or mark a complex area.

Line
{{Map|mtype=line|3243,3735|3226,3737|3222,3754|3238,3764|3252,3752}}
Polygon
{{Map|mtype=polygon|3243,3735|3226,3737|3222,3754|3238,3764|3252,3752}}

Each point of a line is centered on its respective tile. This is because lines should represent points that a player can stand on. Polygons, on the other hand, have points aligned to the south-west corner of their respective tile. This allows map locations to be outlined exactly.

Combos

Combo features are a combination of a single-point feature and a multi-point feature. One example is pin-line, where pin is the single-point feature and line is the multi-point feature. Combos will generate a single-point feature per coordinate and a multi-point feature using all coordinates together.

Pins and polygon	Dots and line
{{Map|mtype=pin-polygon ... }}	{{Map|mtype=dot-line ... }}

Combos should be used sparingly and only when multiple coordinates have some kind of relationship. A good example is the map of tasks throughout One Small Favour, where the tasks must be completed in a specific order. Another example is the map of canoe stations, where each station represents a point along the River Lum.

Maplinks

Any map can be rendered as a maplink instead of a mapframe by using |type=maplink. With this, the |text= argument can be used to change the text of the link.

{{Map|type=maplink}} Maplink	{{Map|type=maplink|text=Maplink Text}} Maplink Text
{{Map|type=maplink|text=}}	{{Map|type=maplink|mtype=pin|2613,3294}} Maplink

Plane, map ID, and zoom

Plane, map ID, and zoom are three essential options used to control the map view in many cases.

• Plane—set with plane—controls the Z value of a feature and corresponds to the floor something is on. For example, if a feature is on the 1^st floor^[UK]2^nd floor^[US] of a building, set plane to 1.
• Map ID—set with mapID—controls which area of the game map to render. Setting this value is similar to changing the world map's map selection.
• Zoom—set with zoom—overrides the automatically calculated zoom amount for a map. If the area you want to mark appears too large or small at the default zoom level, set it to a value that will better represent that area.

Advanced usage

Anonymous features

Multiple map features can be defined through anonymous features, which have the general form:

|option1:value1,optionN:valueN,x1:y1,xN:yN

You can provide as many options and coordinates as you want for a single anonymous feature. Each option/value and x/y must be separated by a colon (:), and each of these pairings must be separated by a comma (,).

The options available to use in anonymous features are exactly the same as regular named arguments, meaning the two are entirely interchangeable. If a named argument is also provided as an anonymous argument, the anonymous value will override the named value.

One small difference with anonymous features—because they are comma- and colon-separated—is the need to escape extra commas and colons with \ backslashes in certain options. These are mentioned in the table of feature options below.

{{Map|mtype:pin,3211:3247,desc:A comma \, and a colon \:|mtype:rectangle,rectX:6,rectY:5,3246,3246}}

Because the anonymous feature syntax is used solely to create features, map-only options cannot be used as feature options.

Offsetting the view

With at least one feature on a map, the view will be centered on the average X and Y coordinates of all points provided. To override this behaviour and offset the view, provide named x and y arguments.

Offset	No offset
{{Map|2990,9935|y=9955|x=2975 ... }}	{{Map|2990,9935 ... }}

Popups

By default, all features are clickable to show their X/Y coordinates. For multi-point features, this coordinate is the first coordinate provided. However, more details can be added.

• Add a title with title.
• Add a description with desc.
• Add detailed info with ptype if the feature represents an item, object, monster, or NPC.
  • For any ptype, the subject's name will default to the current page's title. Set name to change this. Specify the subject's internal ID with id if needed.
  • For items, set qty and respawn if needed.
  • For monsters and NPCs, set levels and respawn if needed.

Keep in mind that the page a map is placed on may already provide these details, in which case it may not be necessary to repeat them in the popup.

SMW

The Map module provides functionality that allows other pages, templates, and modules to interact with its data. More specifically, by setting smw=yes on a map, the final map options and GeoJSON for each feature will be stored in SMW for other resources to consume. See Property:Location JSON for example data.

In some cases, a page will have multiple maps that relate to specific instances of the page's subject. For example, Forestry Shop has three maps that each relate to one of its locations. To handle this, you can set smwName along with smw to tell the Map module to store each map's data in a "subobject" on the page; Otherwise, each of the maps would overwrite each other. The value of smwName should match the subject's instance name if possible ("Draynor Village", "Seers' Village", or "Prifddinas" in the Forestry Shop example).

Note that you should only provide these arguments if you know exactly what you're doing.

Arguments

Map options

Map options are named arguments that define how the map itself behaves and how it is rendered on the page. These options cannot be used as feature options.

Argument					Optional?
type	Sets the map type on the page.
	Values	mapframe maplink	Default	mapframe
width	Sets the map width on the page.
	Values	Any number >=1	Default	300
height	Sets the map height on the page.
	Values	Any number >=1	Default	300
align	Sets the map's alignment on the page.
	Values	left center right	Default	center
x	Sets the X coordinate of the map view if at least one feature is defined.
	Values	Any number >=0	Default	3233
y	Sets the Y coordinate of the map view if at least one feature is defined.
	Values	Any number >=0	Default	3222
zoom	Sets the zoom amount. A higher number means a closer zoom.
	Values	Any integer -3–3	Default	2
mapID	Sets the map ID.
	Values	Any map ID	Default	0
caption	Adds a caption to the map if type is unset or set to mapframe.
	Values	Any text
text	If type is set to maplink, changes the text of the link.
	Values	Any text
smw	Enables Location JSON or Historic Location JSON data for the current page. This should only be used if the map directly describes the page subject.
	Values	yes hist
smwName	Changes the SMW data to a subobject on the current page with the provided value as the subobject name. This should only be used if the map does not directly describe the page subject.
	Values	Any Text
nopreprocess	Outputs the final map element with GeoJSON as raw text instead of a rendered map.
	Values	True

Feature options

Feature options are named or anonymous arguments that define features on the map.

Argument					Optional?
mtype	Sets the type of a feature.
	Values	pin rectangle square circle dot text line polygon or a combo type	Default	pin
x	Sets the X coordinate of a feature. Can also be set with coordinate shorthand.
	Values	Any number >=0	Default	3233
y	Sets the Y coordinate of a feature. Can also be set with coordinate shorthand.
	Values	Any number >=0	Default	3222
plane	Sets the plane (Z value) a feature is on.
	Values	Any integer >=0	Default	0
r	Sets the radius of a circle or square.
	Values	Any number >=1	Default	10
rectX	Sets the X length for a rectangle.
	Values	Any number >=1	Default	20
rectY	Sets the Y length for a rectangle.
	Values	Any number >=1	Default	20
icon	Sets the icon for a pin feature using a built-in value.
	Values	greenPin redPin bluePin cyanPin magentaPin yellowPin greyPin	Default	greenPin
iconWikiLink	Sets the icon for a pin feature using an image from the wiki. File extension must be included.
	Values	Any file name
iconSize iconSizeX iconSizeY	Sets the icon size for a pin feature. If one number is provided (e.g., 5), that number is used as the X and Y sizes. If two numbers are provided (e.g., 2,3), the X and Y sizes are set separately. Separate values can also be provided with iconSizeX and iconSizeY.
	Values	Any number >=1
iconAnchor iconAnchorX iconAnchorY	Sets the icon position for a pin feature relative to the map point. [0,0] is at the top-left corner of the image. If one number is provided (e.g., 5), that number is used as the X and Y. If two numbers are provided (e.g., 2,3), the X and Y are set separately. Separate values can also be provided with iconAnchorX and iconAnchorY.
	Values	Any number
popupAnchor popupAnchorX popupAnchorY	Sets the popup position for a pin feature relative to the icon. [0,0] is at the top-left corner of the image. If one number is provided (e.g., 5), that number is used as the X and Y. If two numbers are provided (e.g., 2,3), the X and Y are set separately. Separate values can also be provided with popupAnchorX and popupAnchorY.
	Values	Any number
group	Sets the group for a pin feature.
	Values	Any text	Default	pins
label	Sets the label text of a text feature. Only required on text features. In an anonymous feature, all commas and colons within must be escaped with \ backslashes.
	Values	Any text
position	Sets the position of a text feature's label.
	Values	left right top bottom center	Default	top
title	Sets the popup title of a feature. In an anonymous feature, all commas and colons within must be escaped with \ backslashes.
	Values	Any text
desc	Sets the popup description of a feature. In an anonymous feature, all commas and colons within must be escaped with \ backslashes.
	Values	Any text
ptype	Sets the feature's subject's type for providing extra popup details.
	Values	item monster npc object
name	Sets the feature's subject's name if ptype is set.
	Values	Any text	Default	The page's title
id	Adds the feature's subject's internal ID to the popup if ptype is set.
	Values	Any integer
qty	Adds the feature's subject's quantity to the popup if ptype is set to item.
	Values	Any integer
respawn	Adds the feature's subject's respawn time to the popup if ptype is set to item, npc, or monster.
	Values	Any text
levels	Adds the feature's subject's list of levels to the popup if ptype is set to monster or npc.
	Values	Any text
stroke	Sets the stroke color of a feature with a stroke.
	Values	Any hexadecimal color code	Default	#3388ff
stroke-opacity	Sets the stroke opacity of a feature with a stroke.
	Values	Any number 0–1	Default	1
stroke-width	Sets the stroke width of a feature with a stroke.
	Values	Any number >=0	Default	3
fill	Sets the fill color of a feature with a fill.
	Values	Any hexadecimal color code	Default	#3388ff
fill-opacity	Sets the fill opacity of a feature with a fill.
	Values	Any number 0–1	Default	0.2
Anonymous	Any number of anonymous features.
	Values	See Anonymous features

Definitions

• Named argument - An argument with the form |arg=value.

  • Named feature - A feature defined entirely with named arguments.
• Anonymous argument - An argument with the form |value.

  • Anonymous feature - A feature defined entirely or partially with anonymous arguments. Uses the format |option1:value1,optionN:valueN,x1:y1,xN:yN.
• Single-point feature - A feature defined by a single point.

  • Pins
  • Rectangles
  • Squares
  • Circles
  • Dots
  • Text
• Multi-point feature - A feature defined by multiple points.

  • Lines
  • Polygons
• Combo type - An mtype that combines a single-point mtype with a multi-point mtype. Examples: pin-line, dot-line, and pin-polygon.
• Coordinate shorthand - A more compact way to provide X/Y coordinates for a feature. Allows multiple coordinates to be provided.

  • For named features, this could look like |1000,1000|2000,2000.
  • For anonymous features, this could look like |1000:1000,2000:2000.

See also

• Map module API