Adding Cities and Dungeons to the IVAN World Map

From IvanWiki
Jump to navigation Jump to search


This is a brief guide explaining how to include your customized dungeons on the IVAN world map.

Three key steps

There are three key steps to getting your dungeon to appear on the world map.

Your dungeon data file

Your dungeon data file should reside in Script/dungeons where it will automatically be picked up by the game when it creates the world map. It should contain the kinds of things described in the article on Dungeon Building. Most importantly, the Dungeon control variable will need to be the DEFINED_VALUE you set in define.dat, which will help link the dungeon to its overworld terrain.


You will need to define the name that the IVAN script files will use to recognise your dungeon. Therefore you will need to include a #define with the other dungeon names in define.dat.

Anything you put in define.dat, you can refer to in your other script files. This is a general rule and is applicable to any of the data files. For example, if you want to create another config of a guard, then you just put a new #define in define.dat, and you can now refer to it in char.dat and your dungeon data file. So it follows that you can #define your own dungeon name, which will be essential when we come to link the dungeon data file to the terrain data file.

Stick to upper case lettering when adding a new #define, and be sure to put an underscore when separating words. Be sure items that are enumerated follow a nice numerical sequence e.g. 1, 2, 3, 4, 5; or 2, 4, 8, 16, 32;, rather than 1, 2, 5, 7, 8;.

For programmers: note that if we wish to refer to a particular dungeon in the code itself, for example to do something special in game.cpp, then the code will need to know about it, and so a #define will also need to appear in ivandef.h before compiling the game.


The data file owterra.dat contains the "over-world terrains" of the IVAN world map. These are so named, because they become the pictures that sit over the ground terrain on the world map. They denote the places - cities or dungeons - you can visit when adventuring in the world map, and so they need to be linked up to the dungeon data files.

Here are some pictures showing famous owterrains:

New Attnam Attnam Gloomy Caves

As of IVAN 0.50.6, there are exactly 32 slots (dungeonAA up to dungeonBF) available for use as the over-world linkages to your dungeon. Simply pick one out that is free and modify it to link together with your dungeon data file by specifying which DEFINED_VALUE you introduced in define.dat

This table shows the control variables for each over-world terrain. You can configure your over-world terrain with the ground terrain type of your choice, and a bunch of other things besides.

Keyword Values Description
BitmapPos x, y; This determines the bitmap position of the picture of the terrain in WTerra.pcx. You can create your own picture by modifying WTerra.pcx.
NameStem "string" This is a string, beginning with a lowercase word, usually a noun or an adjective, for example, "mighty cathedral" or "cave entrance".
UsesLongArticle true or false Specify whether to prefix the name stem with the english language short article, "a", or the long article, "an".
IsAbstract true or false Do not worry about this. An over-world terrain has no other config than the base config and only the protoype is abstract, if that means anything.
CanBeGenerated true or false Set this value to true if you want your user defined dungeon to appear in the world map. It is not applicable to core locations.
AttachedDungeon DEFINED_VALUE This is the #define set in define.dat that is used to link the user-specified dungeon in the data file to its over-world terrain.
AttachedArea 0, 1, 2, ... This sets the initial level that the player will appear in upon entering the dungeon. Normally set this to zero.
NativeGTerrainType DEFINED_VALUE MUST be non-zero. Can select from DESERT, JUNGLE, STEPPE, LEAFY_FOREST, EVERGREEN_FOREST, TUNDRA, GLACIER. Note that the tundra type produces the familiar snow terrain.
RevealEnvironmentInitially true or false This determines whether to reveal the dungeon on the world map initially by uncovering the darkness, a la Attnam, or whether the player will need to discover it by using the field of view, a la underwater tunnel exit. Note that this differs from the way gloomy caves is hidden, and then revealed once you talk to Petrus.
HideLocationInitially true or false This tells the game whether to show the location on the world map or not. If it is set to true, then the location will be undiscoverable unless some internal condition within the game is met, that triggers the location to be revealed. If it is set to false, then the location will be accessible from the beginning of the game.
CanBeOnAnyTerrain true or false If set to true, this forces the world map generator to ignore the requirement to place the location in its exact native terrain type. It places these locations in the first available spot from Attnam outwards. This is necessary sometimes, to more or less guarantee the location to be accessible to the player. If it is set to false, there is a high chance the location will spawn on another continent.

A worked example

By following these three easy steps you can create and add new dungeons to your local copy of IVAN, without needing to know how to code!

Step 1: A basic dungeon data file

Copypaste this into your favorite text editor and save under Script/dungeons as "House.dat":

  *  Iter Vehemens ad Necem (IVAN)
  *  Copyright (C) Timo Kiviluoto
  *  Released under the GNU General
  *  Public License
  *  See LICENSING which should be included
  *  along with this file for more details
  * NOTICE!!!
  * This file contains SPOILERS, which might ruin your IVAN experience
  * totally. Also, editing anything can DESTROY GAME BALANCE or CAUSE
  * OBSCURE BUGS if you don't know what you're doing. So from here on,
  * proceed at your own risk!
   Levels = 1;
   Description = "House";
   ShortDescription = "HS";
   Level 0;
     FillSquare = solidterrain(GRASS_TERRAIN), 0;
     Size = 42, 26;
     GenerateMonsters = false;
     Rooms = 1;
     Items = 0;
     IsOnGround = true;
     TeamDefault = MONSTER_TEAM;
     LOSModifier = 48;
     IgnoreDefaultSpecialSquares = false;
     AutoReveal = true;
     CanGenerateBone = false;
     DifficultyBase = 50;
     DifficultyDelta = 0;
     EnchantmentMinusChanceBase = -15;
     EnchantmentMinusChanceDelta = 0;
     EnchantmentPlusChanceBase = 0;
     EnchantmentPlusChanceDelta = 0;
     BackGroundType = GREEN_FRACTAL;
     EarthquakesAffectTunnels = true;
     AudioPlayList = 
       Pos = 2:40,2:24;
       Size = 4:6,4:6;
       AltarPossible = false;
       WallSquare = solidterrain(GRASS_TERRAIN), wall(BRICK_PRIMITIVE);
       FloorSquare = solidterrain(GRASS_TERRAIN), 0;
       DoorSquare = solidterrain(GRASS_TERRAIN), BALSA_WOOD door;
       GenerateDoor = true;
       DivineMaster = 0;
       GenerateTunnel = false;
       GenerateLanterns = false;
       Type = ROOM_NORMAL;
       GenerateFountains = false;
       AllowLockedDoors = false;
       AllowBoobyTrappedDoors = false;
       Shape = ROUND_CORNERS;
       IsInside = true;
       GenerateWindows = true;
       UseFillSquareWalls = false;
       Flags = 0;

Step 2: Add the new dungeon definition to define.dat

Before After
 #define RANDOM 0
 #define ELPURI_CAVE 1
 #define ATTNAM 2
 #define NEW_ATTNAM 3
 #define EMPTY_AREA 5
 #define XINROCH_TOMB 6

 #define RANDOM 0
 #define ELPURI_CAVE 1
 #define ATTNAM 2
 #define NEW_ATTNAM 3
 #define EMPTY_AREA 5
 #define XINROCH_TOMB 6

Step 3: Add the new location to the worldmap with owterra.dat

Before After Result
   BitmapPos = 0, 64;
   NameStem = "empty area";
   UsesLongArticle = true;
   AttachedDungeon = EMPTY_AREA;
   AttachedArea = 0;
   CanBeGenerated = false;
   NativeGTerrainType = JUNGLE;
   BitmapPos = 64, 64;
   NameStem = "house on the steppe";
   UsesLongArticle = false;
   AttachedDungeon = HOUSE_ON_THE_STEPPE;
   AttachedArea = 0;
   CanBeGenerated = true;
   NativeGTerrainType = STEPPE;

What's this about "core locations"

Core locations are the original ones from IVAN 0.50. These are New Attnam, Under water tunnel, Attnam and Gloomy Caves. Their generation on the world map is not handled in the generic way covered by the means of adding places to the world map described here.

Known limitations

Distribution of ground terrain types

Terrain type Picture Percentage of global tiles (averaged over 8 PDS sampling trials)
Desert   7.1 %
Jungle   14.0 %
Steppe   13.7 %
Leafy forest   15.9 %
Evergreen forest   6.0 %
Tundra   33.4 %
Glacier   9.9 %

As of 0.50.6, the number of slots is 32.

Overflow of number of dungeons. Ways in which this can happen.

Population distribution of terrain types collected by the sampling algorithm.