Overview
The Traveller Map site works by having a browser-based client application written
in JavaScript call
various APIs provided by the web site to render map tiles, provide search results,
look up coordinates, and so forth. The browser provides the HTML+CSS rendering, layout
and interaction engine, the web site provides the content, and the script glues it together.
All of these APIs may be called by other applications. In addition, several other
APIs have been exposed specifically for external applications or users to take
advantage of.
If you start developing against these APIs in any form, please let me know!
Email me at inexorabletash@hotmail.com.
In addition, the blog is a good
source of news and discussion around the site and APIs.
NOTE: Many APIs take x and y parameters.
The coordinate system for those values varies depending on the API. See the
Coordinate Systems documentation for more details.
Different APIs use different coordinate systems. Future API updates may attempt to unify them,
but the different coordinate systems will always be required, as different APIs provide
different views on the site dataset.
Named Location
Some APIs support simple named locations, namely the name of a sector followed by a four-digit hex
number (in xxyy form). This is inefficient, as the sector must be looked up by name,
but is supported for convenience in APIs likely to be specified as URLs directly by humans
rather than automatically generated.
The Traveller Map database of sector names accepts multiple spellings and languages for sector
names ("Far Frontiers"/"Afachtiabr", "Dagudashaag"/"Dagudashag", etc) and is case-insensitive.
Remember to URL-encode non-alphanumeric characters (e.g. spaces are %20 or
+).
The Coordinates API will look up a sector/hex location and produce sector/hex
coordinates suitible for further calculations. For convenience, the JumpMap API,
Credits API, IFRAME API, and Permalinks all accept named locations using
sector and hex parameters.
Example: Regina is "Spinward Marches" "1910"
Sector/Hex Coordinates
Sector/Hex are the simplest numeric coordinates. These must be specified as a quartet of (sx, sy, hx, hy).
The Core sector is at (0,0), with positive x being Trailing and positive y being Rimward.
Hex coordinates are 1...32 and 1...40. Note that hx and hy must be specified separately. Developers should
be aware that many languages (C/C++, JavaScript, etc) will parse numbers with leading 0's as octal, so
08 and 09 are treated as erroneous and gives bogus results.
Use an appropriate parsing function with an explicit radix.
The Coordinates API will map a sector/hex name (such as "Spinward Marches", "1910")
to the numeric quartet in this coordinate space. The JumpMap API and Credits API
accept these coordinates using
sx, sy, hx and hy parameters.
Example: Regina (Spinward Marches 1910) is (sx=-4, sy=-1, hx=19, hy=10)
World-Space Coordinates
World-space coordinates are more compact than Sector/Hex coordinates, requiring just two numbers. The
transformation is simple, and based around Reference (Core 0140). In this scheme, Reference is at 0,0,
positive x is Trailing and positive Y is Rimward. To convert Sector/Hex to world-space coordinates, simply
compute the distance to Reference:
x = ( ( sx - ReferenceSectorX ) * SectorWidth ) + ( hx - ReferenceHexX )
= ( ( sx - 0 ) * 32 ) + ( hx - 1 )
= ( sx * 32 ) + hx - 1
y = ( ( sy - ReferenceSectorY ) * SectorHeight ) + ( hy - ReferenceHexY )
= ( ( sy - 0 ) * 40 ) + ( hy - 40 )
= ( sy * 40 ) + hy - 40
This scheme allows trivial conversions to the canonical Traveller ring/ray system, but
is far more convenient given that the origin is within charted space. This coordinate system is used by the
Credits API and the JumpMap API, which require selection of a
specific hex. The coordinates are specified as x and y parameters
Example: Regina is (x=-110, y=-70)
Map-Space Coordinates
While world-space coordinates make a lot of sense for describing hexes, the fractional positioning required
for precisely positioning the map dictates an additional map-space coordinate system. The conversion from
world-space to map-space coordinates requires two steps:
-
Account for "odd" hexes being further corward than "even" hexes - i.e. hex 1910 is further coreward than hex 2010.
Also note that odd/even switch places between Sector/Hex and World-space since Reference is at 0140 and (0,0) respectively.
-
Account for hexes being packed more tightly horizontally than vertically, at a ratio of 0.868:1 (h:v), and the
y axis is inverted. (This is the only coordinate system with an inverted Y axis. I can't explain that;
I must have been asleep at the keyboard.)
ix = ( world_x - 0.5 ) *
iy = world_y - 0.5 // if world_x is even
iy = world_y // otherwise
x = ix * ParsecScaleX
= ix * 0.868
y = iy * -ParsecScaleY
= iy * -1.0
= -iy
This coordinate system is used by Permalinks and the IFRAME API when a precise view
point is required. The coordinates are specified as x and y parameters.
Example: Regina is (x=-95.914, y=70.5)
Tile-Space Coordinates
Coordinates used by Tile API are designed so that the basic operations
of dragging the map around and requesting new tiles are as simple as possible. If the tile
scale, width and height remain constant, the tiles at (0,0) and (0,1) are adjacent, and
the origin is the same as map-space coordinates. Positive x is Trailing, positive y is Rimward.
x = map_x * scale / width
y = -map_y * scale / height
NOTE: since this is effectively an image-space coordinate system, standard graphics tricks
can be used. For example, to center a tile rendering on a map-space coordinate, use:
x = ( map_x * scale - ( width / 2 ) ) / width and
y = ( -map_y * scale - ( height / 2 ) ) / height
This coordinate system is only used by the Tile API
Example: Regina would be centered in a 512x384, 48px/pc tile at
(x=-9.4919375, y=-9.3125)