Uploading Content


Deity is still a work-in-progress.  We beg your patience while development continues.  If you have problems, please let us know. Anybody can upload content and have it be instantly visible all users of Deity.  You will need a Google Account (if you’re a GMail user, you already have one) but no other sign-up or registration is necessary.  Then just go to http://deity-online.riverworth.com/regionadmin.jsp to see the regions you have uploaded and/or create new ones.

New Regions

The “create a new region” link on the admin page will allow you to mark a new area in the world.  The name should be a path that describes the hierarchy of its location.  This is not (currently) enforced, but it’s a good idea just to keep things organized.  If you’re expanding upon a region you’ve already created, the “create sub-region” link will auto-fill some information for you.

  • World/Era: The world on which this region resides.  There are only a few top-level worlds and new ones cannot be created arbitrarily.
  • Region Name: A unique “path” identifier for this region.  Only letters, numbers, and dashes are allowed.  Use dashes to separate path components and CamelCase to differentiate words within a path-element.
  • Region Title: A short, descriptive name of the region.  It’s UTF-8 so special characters can be included.
  • Snippet HTML: Some text, including basic HTML formatting, that is displayed to the user when they long-press within a region boundary.  This is your “cover page” and your only chance to “sell” the region to the user.  If the region will be made available on a subscription basis, the text here needs to justify the subscription price.

 

Changing a Region

Once a region has been created, the world, era, and region-name cannot be changed.  They are the unique identifier for this region among all others.  The other fields can be changed via the region editor.  In addition, these other options are also available:

  • Editors: This is the list of people who are allowed to make changes to the region information and upload new content for it.  There is currently no UI for managing this list.
  • Subscription:  If it is desired that this region be available only via a paying subscription, the rate and free-trial period can be set here.  Changes to these values do not take effect immediately as they require some manual operations by RiverWorth staff.

 

Content:

Regions uploaded to Deity consist of two pieces: a map and a set of information for that map.  These are held separately in the database and are updated independently, which means you can add new markers or update descriptions without uploading a complete new set of map tiles.  Tools provided by us convert your information into a format that can uploaded and submitted.

Map

A map is one or more identically-sized rectangular PNG images, with or without transparency.  Each image is an independent layer that can be turned on or off by the user and so must be of identical size and cover identical space on the world.  It’s recommended that you keep all related layers in the same Photoshop or GIMP file and then export each layer independently to a PNG file for processing by our tools.

caer-burzyn-0caer-burzyn-1caer-burzyn-C

Player View: When preparing indoor maps, including dungeons, that are to support a player-view, an additional image needs to be created for each layer colored white where it is not possible to see through and black (or transparent) where it is.  Deity will use this information to render what is visible for any given point-of-view and thus provide a map to players of exactly what they can see and have seen.  The “opaque” mask must use a a solid line of at least 2-pixels wide in order to ensure there are no way to look through the jagged edge of an angled line.  If this image is scaled, larger or smaller, be sure that any “smoothing” does not turn important white pixels to black.

Information

A general description of the region can be written in simple, UTF-8 encoded HTML and verified with any web browser.  The body of this file is extracted and will be displayed to users when they press the “map information” button at the bottom of the screen.  CSS and Javascript are not extracted, and complex formatting like tables will not work.

<html>
<head>
 <title>My-Region</tile>
</head>
<body>
<h1>Introduction</h1>
  <p>MyRegion is the name of the small kingdom centered on Snafu castle in the InterestinglyNamed valley. It is bounded to the north by the region of Hither, to the east by Yawn, to the south by OverHere, and to the west by OverTHere. The natural vegetation is mostly mixed woodland and forest with tracts of cropland and pasture.</p>
  <p>The lands surrounding the kingdom are home to three tribal nations. They are seldom troublesome but...</p>
  <p>MyRegion controls ...</p>
  <p>MyRegion relations with Foo and Bar are peaceful, if somewhat strained. Both ...</p>
<h2>Military</h2>
  <p>Other than the Royal Guard, the feudal levy in MyRegion is very important. There are a large number of land holding knights ...</p>
<h2>Revenue</h2>
  <p>The annual net revenue (gross minus normal expenses) of a fief may be assumed to be 1d per gross acre. To this must be added the net revenue provided by vassal fiefs; if held by a bailiff or constable, they will provide all their own net revenue; if held by a clan in fee simple, they will provide one-half their net revenue (reflecting aids, scutage, and other feudal taxes).</p>
</body>
</html>

Each point of interest on each layer needs to be described.  The information is placed in a single text file (UTF-8 encoded) as a series of records, formatted as such:

marker: {
  name: "a simple, short name of the location",
  xpos|longitude: a number indicating the X position on the world1,
  ypos|latitude: a number indicating the Y position on the world1,
  rpos|radius: a number indicating how large, in degrees, the location is1,
  icon: "name of icon to display in map markers"2,
  image: "name of image to display in big info-window"3,
  stats: { "List":"of", "Interesting":"information", "About":"location" }4,
  snippet: "a short, one-line description of the location",
  info: "<p>A full description of the location, in as much detail as you wish.  All valid UTF-8 characters are allowed though double-quote marks (\") must be escaped with a backslash.  Like the description, basic HTML tags are allowed, including <b>bold</b> and <i>italic</i>.  Individual paragraphs can also be defined.</p><p>This information is displayed as a scrollable, pop-up dialog when the user taps the POI bubble."
}

1) These values can all be found using the on-line tools (see Tools:On-Line below) but the xpos, ypos, and rpos values can also be found using the original map simply by locating the center of the POI and dividing the x-coordinate by the width and the y-coordinate by the height.  The rpos value is the number of pixels from that point to the outer-most boundary of the POI, divided by the width.  Use whatever method is easiest.

2) An icon should be small, generally no more than 72×72 pixels in size but may be as large as an “image” if it is also being displayed there.  A hollow map marker will appear if no “icon” is provided. (optional)

3) An image is a picture of the location and is probably unique to that location — use an “icon” if it applies to a general class of buildings — and should be limited to 256×256 pixels in size.  If no “image” value is supplied, an enlarged version of the “icon” will be displayed instead, or nothing if that is also not present. (optional)

4) These bits of point-form text information are displayed (alphabetically) in table-format when viewing the information about a map marker.  It’s recommended that the words of the keys be capitalized. (optional)

 

Glue

The final piece is a small .info file that tells the tools how to find all of this information and where it belongs in the greater scheme of things. Empty lines and lines beginning with “#” are ignored. It begins as such:

World: worldname  (known worlds are: Earth, Kethira, and Toril)
Era: worldera  (depends on world; Earth is modern, past, future; Kethira is 720TR; Toril is 1500DR)
Name: Region-Path-Name1
Title: a simple, short name of the region
ThumbnailFile: filename-of-region-thumbail.jpg2
DescriptionFile: filename-of-description.html
MoreInfoURL: http://www.example.com/info-about-my-fantastic-region.html
StackOrder: where does this regions display among the stack of all regions3
Projection: map projection, flat|equirectangular|mercator4

TopLat: number indicating the latitude of the top of the region5
BottomLat: number indicating the latitude of the bottom of the region
LeftLng: number indicating the longitude of the left of the region
RightLng: number indicating the longitude of the right of the region
     ... or ...
CenterLat: number indicating the latitude of the center of the region6
CenterLng: number indicating the longitude of the center of the region
WidthMeters: number indicating the width of the region in meters
HeightMeters: number indicating the height of the region in meters

1) The world name, era, and region-pathname must match exactly (case-sensitive) with what was provided when creating the region on the region-admin console.

2) A small version of the entire region map, 512×512 maximum size, in JPEG or WebP format.

3) In general, world=0, continent=100, country=200, region/state=300, district/county=400, city/town=500, suburb=600, block=700, building=800, room=900

4) The view presented to the user is always “mercator”.  Large regions should likely be also marked “mercator” in order to appear on-screen exactly like the original with no transformations.  “Equirectangular” is also supported which will stretch the original vertically (and non-linearly) to match the Mercator view, though for small areas not too far north or south there will be no discernible difference. “Flat” maps are also supported but are defined by a center latitude & longitude plus width and height in meters; these should not be used for areas exceeding a few kilometers to preserve accuracy.  Note: all maps for the Kethira world should be marked “mercator” (or “flat”) because of the unusual way the top-level world map is presented that has no projection distortion.

5) These four numbers are required for “mercator” and “equirectangular” map projections.  See the Tools:On-Line section below for more information on how to get these numbers.

6) These four numbers are required for “flat” map projections.

After that general information comes a block repeated once for each map layer.

Layer: layername1
TileFile: filename-of-image.png
OpaqueFile: filename-of-image+opaque.png2
MarkerFile: filename-of-markers.markers

1) Allowed layers are currently “base” and “floor:n” (where n is a positive or negative integer, zero being ground-level).

2) A white & black mask of the layer with the white areas indicating areas that block line-of-sight.  If omitted, the line-of-sight is unlimited.  (optional)

Lastly comes all the icons and images that are referenced by the markers provided above.  Both icons and images draw from the same namespace so don’t re-use names (which shouldn’t be a problem since the former is generic and the latter is specific).  The total size for all icons and images of a region must be less than 750KiB.  Supported formats are PNG, JPEG, and WebP, the latter being recommended for the smallest file sizes.

IconFile: name1:path/of/image.webp

 1) This is the name put into the marker files.  By default, it is private to this region but if it is prefixed with “Qualifier/” then it is public and can be referenced within any region by including that qualifier in the icon/image name within their own marker files.  This is useful when defining things common to a large region that should be re-used by more detailed works within that area.  For example, if guild signs are common across a continent, the region defining that continent can provide the icons for those guilds and the regions that details the towns and cities can use those ensuring a consistent representation.  A dynamically-generated list of public icons is in the works.

 

Tools:

Some of our tools are available through your web browser and some have to be installed and run on a local computer.

On-Line

Some of the information required in the description files can be determined by using our on-line web client.  Like the Android and iPad version of the program, you can explore, search, and learn about the world.  The web version is a little limited in comparison but also has some extra features specifically for publishers.  These are found down the left side of the screen.

  • Add Map:  The icon that looks like a camera shutter will allow you to select an image from disk and position it on the display.  It’s not necessary for the image to be large.  An image 1000 pixels on its longest edge is more than sufficient for this task.  Once you’ve selected it, you can grab it in the center to move it around or grab any edge/corner to change its size.  The mouse wheel will rotate the image should that be necessary1.  When it is perfect, copy down the numbers and close… or pin it to the map for marker positioning.
  • Marker Positioning:  The icon that looks like a map marker with a circle will provide map coordinates for points on the map.  Just position the circle over the desired spot and click to get the center coordinates, plus the radius in degrees, necessary for positioning POIs in the description file.  Scrolling the mouse wheel will grow or shrink the circle so that it can be sized to just enclose the desired area and no more.  If a map has been pinned in the previous step, both absolute longitude/latitude/radius values and relative xpos/ypos/rpos values will be present.  Use one set or the other, not both.  The latter “pos” values are preferred because they are the same regardless of the map’s size and position on the globe meaning that you can move or stretch it (but not shear or rotate it) without having to recalculate all the POI positions (makes it easier if the owner of the map above yours decides to move things around).

1) If you know your map will need to be rotated to match the position of the place on a more general map, be sure to leave enough transparent space around the edge so that it will not get clipped during rotation.  Don’t skimp — extra transparent space will be automatically removed during tile generation.  Once the required rotation is known, perform that same rotation around the center on all layers of the original without changing the image size and export it.  Use that exported version for tile generation.  If the image cropping changes in any way, the previously determined latitudes, longitudes, and positions will no longer be accurate and will need to be found again.

If you are unable to accurately place a new region because the map just up from yours is not available, like a building in a city when no map of that city exists, you can email us a reduced-resolution version of your map (1000×1000 pixels maximum size) and we’ll do our best to place it for you using the full information we have.

Command-Line

Once you have all your information, you can use other tools we provide to convert it to a format suitable for upload.  Our tools are written in command-line-driven Python because that allows them to run on all platforms and, for the most part, they “just work”.  They’re somewhat slower than a pure native application would be but, in general, speed is not an issue since map images are updated relatively infrequently.  Aside from the actual Python interpreter, you’ll also need a PIL, the Python Imaging Library and possibly a WebP creation utility.  This will make for the best user experience since the graphics are better compressed and thus the maps display more quickly. The tool package is available for download in ZIP format.  Just unzip it into a directory somewhere; no complex installation is required.  dmapmaker.py is the actual tool; any other files are just support.

Windows & Mac
  • Python: http://www.python.org/download/releases/ Get the the latest 2.x.x version (not any 3.x.x version), either the 32 or 64-bit version but remember which as other libraries must match.
  • PIL: https://pypi.python.org/pypi/Pillow/  Get the latest version with the edition matching the version of Python installed above.  There is also the original PIL but here is no 64-bit version of it and it does not include WebP support.
  • WebP: http://developers.google.com/speed/webp/download  If not using the original PIL, this stand-alone encoder can be used instead to provide WebP support.  It comes as a .zip file you can just extract anywhere (like C:\Packages).  The path to the binary will then be something like \Packages\libwebp-0.4.0-windows-x86\bin\cwebp.exe.
Linux (and CygWin)
  • Using your system’s package manger, find and install the latest 2.x version of “python” and the latest “python-imaging” packages.
  • If “libwebp” isn’t available, you can download it from Google’s download page (above) and install it manually.  CygWin can call the Windows binary by full path or an appropriate symlink.

Running the Tools

Change to the directory containing all your files and run the following commands.  These examples are given using forward-slashes (/).  If you’re using Windows, change them to back-slashes (\).

/path/to/python /path/to/dmapmaker.py --emit=info my-region.info my-region-upload.dinf
/path/to/python /path/to/dmapmaker.py --emit=tiles my-region.info my-region-upload.dmap

(add –cwebp=/path/to/cwebp to the above “tiles” line if you’re using the stand-alone WebP conversion tool from Google)

The first will collect description and all markers to create the “information” file while the second will process the images to create a set of map tiles.  The first command is very fast; the second command may take hours depending on the size of your image.  Later, if you’re updating the descriptions, you need run only the first command and upload that one output file. The map-display user interface is quite specific in its requirements for map tiles so when map generation begins, it may display a warning stating that the image is being re-sized to a different resolution.  Re-sizing the image manually with a tool like Photoshop or GIMP before starting may make for a slightly better image and will make the encoding process a bit faster.  The tile file contains the map broken down into square tiles for display but also creates down-sampled resolutions with the width and height being reduced by 1/2 each time.

Uploading:

The Deity system reads the generated files directly from Google Drive; just upload the .dinf and .dmap files to your personal space.  Every Google Account is automatically given 15GB of free space and since a Google Account is required in several other places, this is a simple way to put the content on-line.  In addition, Google provides tools that can make Google Drive appear as a local folder so it becomes just a matter of moving the generated files to that location and waiting for the upload to complete.  Don’t generate the files directly to a sync’d location, though; growing files seem to cause problems with auto-sync.

Submitting The Content

Once the content has been uploaded to your personal Drive account, go to the region upload utility, authenticate yourself, select all the files you wish to send, and submit.  The actual processing of the content will happen in the background and you’ll receive an email as each one completes.  With the exception of the very first upload, this does not make the new content visible to the public.

Activating The Content

After submitting new content, only “editors” (which includes the person doing the submission) will see the most recent data.  To publish the new version, go to the region administration console and find the region to which you’ve added new content.  For convenience, a direct link to the region’s admin page is included in the “completed” email you will receive. On that page, you can see which versions of maps and info are “released”, in “canary”, or shown to “developers”.  You can select a new version for any of the three and “update” to make it live.  Note that maps with a subscription fee have a restriction on “release” in that only a roll-back to an older version can be done instantly.  To release a more recent version, paid content must go through the “canary” process. With the very first upload, content is released automatically but it may take up to 24 hours after both the .dinf and .dmap files are submitted before the new region becomes available within the App. Canaries:  Like the traditional canaries used in coal mines to detect the presence of dangerous gases before the concentration was sufficient to affect the miners, a “canary” roll-out is a graduated roll-out intended to find problems before too many users are affected.  When a canary is first set, that version is made available to 1% of all subscribers on a random basis.  Every night, that percentage is doubled.  A complete roll-out is done over the course of 7 days.  If, for example, a new version was set as a 1% “canary” on Monday, Tuesday would see it at 2%, Wednesday at 4%, Thursday at 8%, Friday at 16%, Saturday at 33%, Sunday at 67%, and the following Monday would have it become officially “released” at 100%.