Dogcows Code - chaz/carfire/blob - CarFire/leveleditor/doc/leveleditor.txt

   1 *leveleditor.txt*  CarFire Level Editor for Vim
   2
   3     By Charles McGarvey <mcgarvey@eng.utah.edu>
   4     For Team CarFire, University of Utah CS3505, Spring 2010
   5
   6
   7 This plugin provides some nice features to help you edit CarFire map files.
   8 Here's some quick documentation.
   9
  10 ===========================================================================
  11 1. Contents                            *leveleditor* *leveleditor-contents*
  12
  13     1. Contents             |leveleditor-contents|
  14     2. Installation         |leveleditor-installation|
  15     3. Features             |leveleditor-features|
  16
  17     Appendix
  18     A. Map File Format      |leveleditor-fileformat|
  19     B. Basic Syntax         |leveleditor-syntax|
  20
  21 ===========================================================================
  22 2. Installation                                  *leveleditor-installation*
  23
  24 To install this plugin, move the `leveleditor.vim' file to the `plugin'
  25 directory inside your user vim directory; usually:
  26
  27     $HOME/.vim/plugin or
  28     $HOME/vimfiles/plugin
  29
  30 Then, move this documentation file to the `doc' directory inside your user
  31 vim directory; usually:
  32
  33     $HOME/.vim/doc or
  34     $HOME/vimfiles/doc
  35
  36 Alternatively, you can use the level editor without installing the plugin,
  37 just |source| the plugin in vim:
  38
  39     :so /path/to/leveleditor.vim
  40
  41 Or setup Vim to do it automagically with |:autocmd|; put this in your user
  42 Vim config file:
  43
  44     au BufNewFile,BufRead *.cfmap so /path/to/leveleditor.vim
  45
  46 ===========================================================================
  47 3. Features                                          *leveleditor-features*
  48
  49 Here is a brief summary of some of the more useful features provided by
  50 this plugin.
  51
  52                                                           *leveleditor-new*
  53 To start editing a new level, type <Leader>ei or select `Initialize Buffer'
  54 from the menu.  This will clear the current buffer of any contents and
  55 insert a partially filled-out template.  That much is undoable.  It will
  56 also set the filetype of the current buffer to `dosini' which will give you
  57 at least partial syntax coloring (if you have that syntax file installed).
  58
  59                                              *leveleditor-editing-maptable*
  60 When your cursor is in the |leveleditor-maptable| section, a few things
  61 will change to help speed up the process of making changes and adding or
  62 removing game entities.  One of those things is the |cursorcolumn| option
  63 is set (if it isn't already), which makes lining stuff up and measuring
  64 easier.  Also, the |expandtab| option is set since you should not insert
  65 literal tabs in this section, and that could end up being a hard bug to
  66 find.  Finally, the current position of the cursor, in map coordinates, is
  67 appended to the |statusline| so you can quickly tell where you are.  Before
  68 these features will work, you must define the `dimensions' key in the
  69 |leveleditor-metadata| section to be the size of the map.
  70
  71 ===========================================================================
  72 A. Map File Format                                 *leveleditor-fileformat*
  73
  74 The format of the CarFire map file follows the de facto standard INI file
  75 format, with at least one notable exception which we'll get to shortly.
  76 Because of that exception, a specialized loader is necessary, so map files
  77 should carry the extension `cfmap' so as not to have them be mistook as
  78 your everyday household variety INI file.
  79
  80                                                      *leveleditor-metadata*
  81 The metadata section of the file contains just that: metadata.  Some of the
  82 key-value pairs may not actually be used for anything, but others may be
  83 quite important.  You can use the |leveleditor-new| command see some of the
  84 pairs that could be defined.  In particular, the `dimensions' key must be
  85 set to a coordinate with the width and height of the map, in grid units.
  86 Parsing the |leveleditor-maptable| depends on the value of this key, which
  87 is why the metadata section must go first in the file.
  88
  89                                                      *leveleditor-maptable*
  90 The maptable section of the file is what makes this file format differ from
  91 the common INI file format.  This section includes no key-value pairs;
  92 rather, immediately following the section header is a block of text with
  93 the same dimensions specified earlier.  This block of text represents the
  94 placement of static objects and game |leveleditor-entities| that make up
  95 the level, each ASCII character representing exactly one object or entity.
  96 Some ASCII characters represent static objects like walls and other fixed
  97 scenery, but the alphabetic characters can be defined to represent certain
  98 special or mobile game entities, including keys, monsters, triggers, spawn
  99 locations, and more.  This description is not meant to be comprehensive;
 100 you should look at an actual level file to figure out what all this means.
 101
 102                                                      *leveleditor-entities*
 103 Game entities can be defined in their own section of the file.  Entity
 104 sections are directly named after the ASCII character that will place them
 105 on the map.  Only alphabetic characters (lowercase or uppercase) may be
 106 defined in this manner; all other characters are reserved for static
 107 objects and whatnot.  For example, if I wanted to place a monster on the
 108 map using the `A' character, I would create a section of the file named `A'
 109 and then place one or more `A' characters in the |leveleditor-maptable|
 110 section at the coordinates where I want the monsters to be created when the
 111 map file is loaded.  The static scenery at the places where entities are
 112 placed is determined by the `defaulttile' key in the |leveleditor-metadata|
 113 section.
 114
 115 You can also use the same definitions to place identical copies of the same
 116 entity at different locations on the map.  This is what allows you to
 117 create more entities on the map than there are characters in the alphabet,
 118 although you are limited to only 52 different types of entities per level.
 119 By the way, these sections can appear anywhere in the file, either before
 120 or after the |leveleditor-maptable| section.
 121
 122 There is also a way to place entities on the map without putting its
 123 identifying character in the |leveleditor-maptable| section.  You might
 124 want to do this if you want to place an entity at some cell on the map that
 125 you don't want to be the default tile.  This is accomplished by listing
 126 the coordinates where entities should be place after the `create' key.
 127 Sometime during the map loading process, entities defined with this key and
 128 one or more valid sets of coordinates will be made available to the game in
 129 the usual manner, just as if its identifier was put on the map.  The
 130 difference is, you can put any (open) static scenery you want at those
 131 locations.
 132
 133 ===========================================================================
 134 B. Basic Syntax                                        *leveleditor-syntax*
 135
 136 To make parsing simple, the format of the values that make up a key-value
 137 pair follows a consistent pattern based on the type of thing being
 138 described.  Except in the case of strings, white space is ignored.  Here
 139 are the things that can appear in a map file.
 140
 141                                                          *leveleditor-keys*
 142 Keys are special strings that appear on the left side of a key-value pair,
 143 which combined is a key and value separated by an equals sign.  Keys are
 144 simply a sequence of alphabet characters.  No white space, digits, or
 145 punctuation is allowed in a key.
 146
 147                                                       *leveleditor-strings*
 148 Strings are simply a sequence of characters.  If the key expects to be set
 149 to a string, then the right side of the assignment up to the line-end will
 150 be parsed as a string, including any white space.  If a string value is not
 151 necessarily expected, you can explicitly surround the string with double
 152 quotes; otherwise, the value could be interpreted as a list if it contains
 153 any white space.  The characters given as a string are interpreted as-is.
 154 No escape characters are ever parsed (i.e. \t or \n).
 155
 156                                                      *leveleditor-integers*
 157 Base-ten numbers are parsed as they appear.  The parser is allowed to read
 158 numbers with special characters such as -10e5.  Numbers cannot be specified
 159 in any other base than ten.
 160
 161                                                      *leveleditor-booleans*
 162 Boolean values are one of two keywords: `true' and `false.'  Case is
 163 ignored when parsing booleans, but abbreviations are not allowed.  For
 164 example, `TrUe' is okay, but `T' is not.
 165
 166                                                   *leveleditor-coordinates*
 167 To specify a coordinate or location on the map, surround two
 168 comma-separated integers with square brackets.  For example,
 169
 170     [0,0]       The origin, or top-left unit-square on the grid.
 171     [3,9]       The tenth unit-square from the top, fourth from the left.
 172
 173 The coordinate system of the grid in the |leveleditor-maptable| section is
 174 Cartesian with reflection over the horizontal axis, so that y increases as
 175 you go down.
 176
 177                                                        *leveleditor-ranges*
 178 A range of integer values is parsed as two comma-separated integers with
 179 angular brackets.  For example,
 180
 181     <1,4>       Matches any integer between 1 and 4, inclusive.
 182
 183 In this way, you could set a range as the value for the key `numplayers' in
 184 the |leveleditor-metadata| section, representing the minimum and maximum
 185 number of players the map supports.
 186
 187                                                     *leveleditor-functions*
 188 The syntax of a function call is familiar.  First comes the name of the
 189 function to be called, then an open parenthesis, followed by a
 190 whitespace-separated (no commas!) list of arguments before a closing
 191 parenthesis.  For example,
 192
 193     wait(3)             Delay for 3 seconds.
 194     has(F)              Check if a player has an entity F in inventory.
 195     create(B [2,3])     Create an entity B on the map at [2,3].
 196
 197                                                         *leveleditor-lists*
 198 Some keys can be assigned a list of things, such as functions to be called
 199 sequentially to accomplish some thing.  The syntax of this is to simply
 200 separate each thing with any amount of white space, except for a
 201 line-ending which serves to terminate the list and value being assigned.
 202
 203 vim:et:ft=help:tw=75