doc/script_course/lecture1.html

   1 <html>
   2 <head>
   3 <title>IVAN script lecture 1</title>
   4 </head>
   5 <body>
   6
   7 <h2>holybanana's IVAN script course, lecture I</h2>
   8 <h4>Database types and configs</h4>
   9
  10 <p>First, get <a href="http://ivan.sourceforge.net">IVAN</a>. In this lecture we don't need the source code yet, so a binary release is enough. You'll also need a simple text editor and an image editor which can show pcx files.</p>
  11 <p>Install IVAN and look at your IVAN installation folder. You should find a folder named Script. I'm not absolutely sure where this folder is located under different OSs, ask Hex (our porter) or the community for help if you can't find it.</p>
  12 <p>Open glterra.dat. IVAN's squares have two terrains, ground terrain and over terrain. This is the file where the data of the ground terrains is stored.</p>
  13 <p>You'll see several structures like this:</p>
  14
  15 <pre>solidterrain /* glterrain-> */
  16 {
  17   Walkability = WALK|FLY|ETHEREAL;
  18   IsAbstract = true;
  19   ...
  20   Config SNOW_TERRAIN;
  21   {
  22     OKVisualEffects = MIRROR|FLIP|ROTATE;
  23     MainMaterialConfig == SNOW;
  24     NameSingular = "ground";
  25     BitmapPos = 16, 16;
  26   }
  27   ...
  28 }</pre>
  29
  30 <p>Here solidterrain is called a <i>type</i>. SNOW_TERRAIN is called a <i>config</i>. Types can have very special unique attributes, for instance a octopus character type may have dozens of bodyparts. Configs only differ from an object of their base type by more subtle details that can be defined in the script.</p>
  31 <p>For instance, SNOW_TERRAIN here acts just like any other solidterrain except for its outlook.<p>
  32 <p>The values that are inside the type definition but outside any config determine the <i>main config</i>, config number 0. The values of the main config are <i>inherited</i> to all other configs.</p>
  33 <p>Types must be added both in the code and in the script. Configs may be added to script only, although if you want to use the config in the code, you need to add a short definition to Main/Include/confdef.h, too.</p>
  34 <p>Now you may try adding a new config, for instance CUSTOM_TERRAIN. But wait! Other files need to know this config, too. Open define.dat. Search for SNOW_TERRAIN. You'll find the lines:</p>
  35
  36 <pre>#define PARQUET 1
  37 #define FLOOR 2
  38 #define GROUND 3
  39 #define GRASS_TERRAIN 4
  40 #define LANDING_SITE 5
  41 #define SNOW_TERRAIN 6
  42 #define DARK_GRASS_TERRAIN 7
  43 #define SAND_TERRAIN 8</pre>
  44
  45 <p>These are the configs of solidterrain. You must add CUSTOM_TERRAIN here.</p>
  46
  47 <pre>#define CUSTOM_TERRAIN 9</pre>
  48
  49 <p>Now every script file knows what you mean when you talk about CUSTOM_TERRAIN. Coders should do exactly the same steps in confdef.h, ie. add</p>
  50
  51 <pre>#define CUSTOM_TERRAIN 9</pre>
  52
  53 <p>after the definition of SAND_TERRAIN. This way, the code would also know CUSTOM_TERRAIN.</p>
  54 <p>Note that the number 9 here is an arbitrary value which the game uses to distinguish this config. It is a good custom to number the configs 1,2,3,... Note that number 0 cannot be used, since it is the number of the main config.</p>
  55 <p>Now you can add something like this in glterra.dat:
  56
  57 <pre>  Config CUSTOM_TERRAIN;
  58   {
  59     MainMaterialConfig == ???;
  60     NameSingular = ???;
  61     BitmapPos = ???, ???;
  62   }</pre>
  63
  64 <p>These three <i>database values</i> are obligatory here. How do we know what we can put in place of the ???-strings?</p>
  65 <p>For materials, this is easy. Open material.dat. Check out all the materials. Let's say you like the config EBONY_WOOD. Then</p>
  66
  67 <pre>MainMaterialConfig == EBONY_WOOD;</pre>
  68
  69 <p>does the trick. You don't have to care about the type of the material, only the config name is needed. Note that this is an exception. Normally both the type and the config are needed to specify a database unambiguously. For instance, to instantiate a kobold lord you use kobold(LORD), not just LORD. This is because a config LORD may be a config of some other character too. For materials, we have guaranteed that different types have different configs, so they can be referred to more simply.</p>
  70 <p>It will be explained in later lectures why we use a double equality symbol == here instead of =.</p>
  71 <p>Fill anything you like for NameSingular. The name should be surrounded by quotation marks, for instance "dance floor".</p>
  72 <p>Now open the Graphics folder, which is in the same place as the Script folder. Open GLTerra.pcx with a picture editor. Choose a 16x16 tile from the pcx and note the position of its upper left corner. Say it is 32,0. Then add</p>
  73
  74 <pre>BitmapPos = 32,0;</pre>
  75
  76 <p>to the config.</p>
  77 <p>In the next lecture I'll tell you how to <i>instantiate</i> your new terrain. After instantiation you are able to see your terrain in the game.</p>
  78 <p>Easy exercise: Add a new ground terrain and start the game. If you get an error message, check the contents of this lecture again. Otherwise you pass.</p>
  79
  80 <hr>
  81
  82 <p>
  83 <a href="lecture2.html">Next lecture</a>
  84 <a href="index.html">Back to main</a>
  85 </p>
  86
  87 <hr>
  88
  89 <p>Last modified August 29 2006.</p>
  90
  91 </body>
  92 </html>