Rapture Manual
Iron Realms Entertainment
Rapture Overview
Index
Function Reference
Language Reference
Language Docs

Maps

Maps are large, two dimensional grids of data.  Much like a bitmap or an image, it stores data at a two dimensional point (or at least that’s the interface provided).  Rapture is responsible for manipulating and accessing these much like it does for databases.  Maps can be anonymous or persistent (just like <databases>), however there is one distinction: anonymous maps are not cleared when an executable is reloaded, they stay resident (unlike anonymous databases which are cleared upon a reload).  Perhaps you’re wondering just what use maps provide.  Well, let’s see a couple examples:

  • An overhead ASCII wilderness.  In a text based game, large over-land maps can be setup using a tile based system.  As an adventurer walks along the land, his X and Y location is used to determine where he is currently standing, and since the overland wilderness is stored in a map, it can easily be accessed and his surroundings shown to him.
  • A maze definition.  A classic example of maze construction is to take a uniform grid of binary values, and simply being able to walk around in only the ‘on’ locations.  This provides a compact storage solution for the maze data, allowing the descriptions (or even the maze itself) to be generated programmatically when needed.
  • Two-way di-graph relations.  If you must track certain values in a directed relation graph, a 2D matrix is one primary storage method.  For instance, say you wanted to relate the distances between 4 different cities.  You could define a 4X4 map, and store the ‘distance’ between each city at a location in that map.  The distance between the first city and the third would be at the (0-based) coordinate (0,2).  Note that this also allows asymmetric relations.  (The distance from city 1 to city 3 doesn’t have to be the same as the distance from city 3 to city 1.)

Here to use maps

Summary
Maps
Maps are large, two dimensional grids of data.
map. new(<name$>)
Creates a new map with the given “name”.
map[].delete()
This deletes the map and frees all the memory associated with it.
map[].valid
This indicates that the map has been created with map.new() and has not been deleted.
map[].name$
This returns the name used when the map was created (read-only).
map[].filename$
Set the file to save the map into to keep it permanent.
map[].load(<filename$>)
Load a map from a given file (relative to the DataDir config option) replacing the information already in memory.
map[].saveas(<filename$>)
Write the map into the given file.
map[].x[<x>].y[<y>]
Access one element of the map using two dimentional coordinates.
map[].element[<offset>]
Access one element of the map using a single offset value.
map[].resize(<width>, <height>, <bpp>)
Reallocate the map with the given dimensions and initialize every element to 0.
map[].width
Return the width of the map (read-only).
map[].height
Return the height of the map (read-only).
map[].bpp
Return the bits-per-pixel of the map (read-only).

map. new(<name$>)

Creates a new map with the given “name”.  Returns an integer ID used to reference it.  If a map already exists with that name, that ID is returned and no new map is created.  Note that every map is anonymous by default, you must set its filename to make it permanent.

map[].delete()

This deletes the map and frees all the memory associated with it.  (If this is a permanent map, the file stored on disk is not deleted.)

map[].valid

This indicates that the map has been created with map.new() and has not been deleted.

map[].name$

This returns the name used when the map was created (read-only).

map[].filename$

Set the file to save the map into to keep it permanent.  Set this to the empty string (“”) to make the map anonymous.

map[].load(<filename$>)

Load a map from a given file (relative to the DataDir config option) replacing the information already in memory.  This resizes and overwrites the map.

map[].saveas(<filename$>)

Write the map into the given file.  No information is changed on the map, not even the filename.  This is unnecessary if you have set the filename$ field, because Rapture will write it to disk automatically.

map[].x[<x>].y[<y>]

Access one element of the map using two dimentional coordinates.  It is treated as a two dimensional array with the x value varying between 0 and width-1, and the y value varying between 0 and height-1.  This may be used to read the value (in an expression) or to set it (in an assignment statement).

map[].element[<offset>]

Access one element of the map using a single offset value.  It is treated as a linear array of elements.  That is, the offset can be anywhere between 0 and (width×height)-1.  The addressing is row-major meaning that elements 0 through width-1 refer to the first row, width through (2×width)-1 is the second row, etc.  This may be used to read the value (in an expression) or to set it (in an assignment statement).

map[].resize(<width>, <height>, <bpp>)

Reallocate the map with the given dimensions and initialize every element to 0.  Width and height must be greater than 0, and currently only 8 bpp is supported.

map[].width

Return the width of the map (read-only).

map[].height

Return the height of the map (read-only).

map[].bpp

Return the bits-per-pixel of the map (read-only).
Copyright © 2016 Iron Realms Entertainment.  Generated by Natural Docs.