Creation/Dev/GMap

From Graal Bible

GMaps are files that contain information about how to links many single Level files (.nw) to a big Map that seems like one level in game. This makes it possible to have a map that displays all players who are in the same area, and removes restrictions on what NPCs can do caused by the separation of levels. Earlier this was done through .txt files merely containing a list of Levels, and the Old GScript:setmap command, but this lacks many of the features the gmap way provides, and therefore is considered deprecated. Many Playerworlds still use the old way, but this is merely because of the difficulties that make it hard and error prone to convert a whole server to a new format.

Creation

GMaps, if not handmade, are created by the Level generator that is installed through Graal's setup.exe along with the Windows version of the game. There is also a dungeon generator which can generate dungeons or caves and is available on Windows and Linux.
GMaps can also hold height information that are used by the Graal engine to display Levels in a three dimensional looking way. This is called Terrain. The height information is mainly created by the level editor and the Terrain Generator programs that allows creation of whole islands.

File Format

GMaps are plain text files, and all GMaps as of now start with the string GRMAP001, followed by a newline. Then, in each line, a 'command' is given, usually in capital letters. Parameters to those commands are put into the same line after a whitespace. Some commands are in fact lists, which have nothing in their line, but which treat all following lines as their parameters until they see themselves followed by 'END' without any whitespace again.

To learn about all that, in addition to reading this article, it is recommended to check your 'maps' subfolder, and have a look at some Playerworlds' GMaps.

WIDTH, and HEIGHT

   followed by an integral number

Dimensions of the whole map, given in single levels. If given incorrectly, these can break the whole map, thus be careful.

GENERATED

   followed by a level name

Gives the last, or bottom right, level that was generated if the gmap was created along with a whole set of levels using a device such as the terrain generator.

LEVELNAMES

   followed by a list of levels, and terminated by LEVELNAMESEND

The list of levels that are part of this map. Each 'row' of levels goes into one line, seperated by commas. There is no comma at the end of a line. If there are "holes" in your map (areas where there is no level, meaning the GMap is not a perfect square), you must make sure the levels surrounding each hole don't contain links to nonexistant levels.

MAPIMG

   followed by a PNG file name

The image file that is to be used as the map that players see if they press their Map key.
Note: This feature is not supported in Graal4

MINIMAPIMG

   followed by a PNG file name

The image file that is to be used as the mini map in the bottom left corner of one's screen.

NOAUTOMAPPING

   uses no param

Disables the assembly of automagical screenshots into a map that is drawn over the MAPIMG image.

LOADFULLMAP

A serverside option: The gmap loading is optimized so that parts are only loaded when they are needed, and afterwards they are removed from memory again. If you put this line, that will be disabled and the full map with all levels will be loaded at once.

LOADATSTART

   followed by a list of level names, terminated by LOADATSTARTEND

A serverside option: The level names given here are not subject to the optimizations described above.

Terrain settings

GENEVENBORDERS, followed by true/false

GENSEED, followed by a big number used to seed randomness

GENBASE, followed by a height value

GENHEIGHT and LEVHEIGHT, followed by a height value

GENCHAOS and LEVCHAOS, followed by a number between 0 and 1, I think, exact to 1/20

HEIGHMAP, followed by a list of height values for each level ordered similar to the LEVELNAMES list, terminated by HEIGHTMAPEND

RANDOMSEEDS, followed by lots of big numbers, probably ordered similar to the LEVELNAMES list, terminated by RANDOMSEEDSEND

The random numbers generator is seeded with these to render the terrain in a three dimensional looking way. The borders of gmaps are defined by the global map attributes, but for map part heights a row of random numbers is used. The seeds are constant so the terrain looks the same all the time, and there are many of them so it is possible to take a small rectangle out of the map and still display it correctly, which would not be possible with one global seed.


Not all of these lines are needed.

Deployment

Now, imagine you have a gmap and a set of levels and want to actually use it on your Playerworld.

For offline editing add the gmap name as a new line to a file loadgmaps.txt which must be put in your Graal Editor base folder. The editor will automatically load the gmap once it is started and will correctly link levels. This will only enable the engine to assign and connect levels the player enters or sees. Levels must still have Link areas to each other in order for the player to move on the map.

As you are going to use the GMap on your Playerworld, you need to make it available for Players to download, by putting it inside the levels/ folder hierarchy using the RC file manager, and adding it to the Folder configuration as mere Level; level *.gmap, for example. It is neccessary to additionally register it as file in the folder configuration, but there is no gmap category to put it under.

To make the NPC Server aware of your gmaps, you need to list them in the Server options too. Add a new option gmaps= followed by a comma seperated list of names without the .gmap extension. If your line gets too stuffed, you can as well use multiple lines, as long as you prefix each one with gmaps=. The entries in each lines will be added, and not replace each other.

If you are converting levels that are already uploaded to use a GMap, you will need to restart the GServer, or you can keep all players out of the levels for about 5 to 10 minutes. The latter may be difficult, however, because players could log on to one of the levels nobody should be in, which would disrupt the 5/10 minute wait time, so restarting the GServer may be a better choice.

For speeding up the entering of maps you can preload gmaps on clientside using the script command "loadmap <mapname>;". This is actually not required, but will reduce the loading time when the player is warped onto the map.