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 You're done!  To use the level editor without installing the plugin, just
  37 |source| the plugin in vim:
  38
  39     :source path/to/leveleditor.vim
  40
  41 ===========================================================================
  42 3. Features                                          *leveleditor-features*
  43
  44 Here is a brief summary of some of the more useful features provided by
  45 this plugin.
  46
  47                                                           *leveleditor-new*
  48 To start editing a new level, type <Leader>ei or select `Initialize Buffer'
  49 from the menu.  This will clear the current buffer of any contents and
  50 insert a partially filled-out template.  That much is undoable.  It will
  51 also set the filetype of the current buffer to `dosini' which will give you
  52 at least partial syntax coloring (if you have that syntax file installed).
  53
  54                                              *leveleditor-editing-maptable*
  55 When your cursor is in the |leveleditor-maptable| section, a few things
  56 will change to help speed up the process of making changes and adding or
  57 removing game entities.  One of those things is the |cursorcolumn| option
  58 is set (if it isn't already), which makes lining stuff up and measuring
  59 easier.  Also, the |expandtab| option is set since you should not insert
  60 literal tabs in this section, and that could end up being a hard bug to
  61 find.  Finally, the current position of the cursor, in map coordinates, is
  62 appended to the |statusline| so you can quickly tell where you are.  Before
  63 these features will work, you must define the `dimensions' key in the
  64 |leveleditor-metadata| section to be the size of the map.
  65
  66 ===========================================================================
  67 A. Map File Format                                 *leveleditor-fileformat*
  68
  69 The format of the CarFire map file follows the de facto standard INI file
  70 format, with at least one notable exception which we'll get to shortly.
  71
  72                                                      *leveleditor-metadata*
  73 The metadata section of the file contains just that: metadata.  Some of the
  74 key-value pairs may not actually be used for anything, but others may be
  75 quite important.  You can use the |leveleditor-new| command see some of the
  76 pairs that could be defined.  In particular, the `dimensions' key must be
  77 set to a coordinate with the width and height of the map, in grid units.
  78 Parsing the |leveleditor-maptable| depends on the value of this key, which
  79 is why the metadata section must go first in the file.
  80
  81                                                      *leveleditor-maptable*
  82 The maptable section of the file is what makes this file format differ from
  83 the common INI file format.  This section includes no key-value pairs;
  84 rather, immediately following the section header is a block of text with
  85 the same dimensions specified earlier.  This block of text represents the
  86 placement of static objects and game |leveleditor-entities| that make up
  87 the level, each ASCII character representing exactly one object or entity.
  88 Some ASCII characters represent static objects like walls and other fixed
  89 scenery, but the alphabetic characters can be defined to represent certain
  90 special or mobile game entities, including keys, monsters, triggers, spawn
  91 locations, and more.  This description is not meant to be comprehensive;
  92 you should look at an actual level file to figure out what all this means.
  93
  94                                                      *leveleditor-entities*
  95 Game entities can be defined in their own section of the file.  Entity
  96 sections are directly named after the ASCII character that will place them
  97 on the map.  Only alphabetic characters (lowercase or uppercase) may be
  98 defined in this manner; all other characters are reserved for static
  99 objects and whatnot.  For example, if I wanted to place a monster on the
 100 map using the `A' character, I would create a section of the file named `A'
 101 and then place one or more `A' characters in the |leveleditor-maptable|
 102 section at the coordinates where I want the monsters to be created when the
 103 map file is loaded.
 104
 105 You can also use the same definitions to place identical copies of the same
 106 entity at different locations on the map.  This is what allows you to
 107 create more entities on the map than there are characters in the alphabet,
 108 although you are limited to only 52 different types of entities per level.
 109 By the way, these sections can appear anywhere in the file, either before
 110 or after the |leveleditor-maptable| section.
 111
 112 ===========================================================================
 113 B. Basic Syntax                                        *leveleditor-syntax*
 114
 115 To make parsing simple, the format of the values that make up a key-value
 116 pair follows a consistent pattern based on the type of thing being
 117 described.  Here are the things that can appear on the right side of a
 118 key-value pair assignment:
 119
 120                                                       *leveleditor-strings*
 121 Strings are simply a sequence of characters.  If the key expects to be set
 122 to a string, then the right side of the assignment up to the line-end will
 123 be parsed as a string, including any white space.  If a string value is not
 124 necessarily expected, you can explicitly surround the string with quotes;
 125 otherwise, the value could be interpreted as a list if it contains any
 126 white space.
 127
 128 The characters that make up the string are included in the string according
 129 to their literal characters; no escape characters are ever parsed (i.e. \t
 130 or \n).  Any value which does not follow any of the following formats will
 131 be read as a string.
 132
 133                                                       *leveleditor-numbers*
 134 Base-ten numbers are parsed as they appear.  The parser is allowed to read
 135 numbers with special characters such as -10e5.  Numbers cannot be specified
 136 in any other base than ten.
 137
 138                                                   *leveleditor-coordinates*
 139 To specify a coordinate or location on the map, surround two
 140 comma-separated integers with square brackets.  For example,
 141
 142     [0,0]       The origin, or top-left unit-square on the grid.
 143     [3,9]       The tenth unit-square from the top, fourth from the left.
 144
 145 The coordinate system of the grid in the |leveleditor-maptable| section is
 146 Cartesian with reflection over the horizontal axis, so that y increases as
 147 you go down.
 148
 149                                                        *leveleditor-ranges*
 150 A range of integer values is parsed as two comma-separated integers with
 151 angular brackets.  For example,
 152
 153     <1-4>       Matches any integer between 1 and 4, inclusive.
 154
 155 In this way, you could set a range as the value for the key `numplayers' in
 156 the |leveleditor-metadata| section, representing the minimum and maximum
 157 number of players the map supports.
 158
 159                                                     *leveleditor-functions*
 160 The syntax of a function call is familiar.  First comes the name of the
 161 function to be called, then an open parenthesis, followed by a
 162 comma-separated list of arguments before a closing parenthesis.  For
 163 example,
 164
 165     wait(3)             Delay for 3 seconds.
 166     has(F)              Check if a player has an entity F in inventory.
 167     create(B,[2,3])     Create an entity B on the map at [2,3].
 168
 169 Note, the file loader parses each group of characters between white space
 170 separately; therefore, do not include spaces between the arguments of the
 171 function call, only a single comma.
 172
 173                                                         *leveleditor-lists*
 174 Some keys can be assigned a list of things, such as functions to be called
 175 sequentially to accomplish some thing.  The syntax of this is to simply
 176 separate each thing with any amount of white space, except for a
 177 line-ending which serves to terminate the list and value being assigned.
 178
 179 vim:et:ft=help:tw=75