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.
 112
 113 You can also use the same definitions to place identical copies of the same
 114 entity at different locations on the map.  This is what allows you to
 115 create more entities on the map than there are characters in the alphabet,
 116 although you are limited to only 52 different types of entities per level.
 117 By the way, these sections can appear anywhere in the file, either before
 118 or after the |leveleditor-maptable| section.
 119
 120 ===========================================================================
 121 B. Basic Syntax                                        *leveleditor-syntax*
 122
 123 To make parsing simple, the format of the values that make up a key-value
 124 pair follows a consistent pattern based on the type of thing being
 125 described.  Except in the case of strings, white space is ignored.  Here
 126 are the things that can appear in a map file.
 127
 128                                                          *leveleditor-keys*
 129 Keys are special strings that appear on the left side of a key-value pair,
 130 which combined is a key and value separated by an equals sign.  Keys are
 131 simply a sequence of alphabet characters.  No white space, digits, or
 132 punctuation is allowed in a key.
 133
 134                                                       *leveleditor-strings*
 135 Strings are simply a sequence of characters.  If the key expects to be set
 136 to a string, then the right side of the assignment up to the line-end will
 137 be parsed as a string, including any white space.  If a string value is not
 138 necessarily expected, you can explicitly surround the string with double
 139 quotes; otherwise, the value could be interpreted as a list if it contains
 140 any white space.  The characters given as a string are interpreted as-is.
 141 No escape characters are ever parsed (i.e. \t or \n).
 142
 143                                                      *leveleditor-integers*
 144 Base-ten numbers are parsed as they appear.  The parser is allowed to read
 145 numbers with special characters such as -10e5.  Numbers cannot be specified
 146 in any other base than ten.
 147
 148                                                      *leveleditor-booleans*
 149 Boolean values are one of two keywords: `true' and `false.'  Case is
 150 ignored when parsing booleans, but abbreviations are not allowed.  For
 151 example, `TrUe' is okay, but `T' is not.
 152
 153                                                   *leveleditor-coordinates*
 154 To specify a coordinate or location on the map, surround two
 155 comma-separated integers with square brackets.  For example,
 156
 157     [0,0]       The origin, or top-left unit-square on the grid.
 158     [3,9]       The tenth unit-square from the top, fourth from the left.
 159
 160 The coordinate system of the grid in the |leveleditor-maptable| section is
 161 Cartesian with reflection over the horizontal axis, so that y increases as
 162 you go down.
 163
 164                                                        *leveleditor-ranges*
 165 A range of integer values is parsed as two comma-separated integers with
 166 angular brackets.  For example,
 167
 168     <1,4>       Matches any integer between 1 and 4, inclusive.
 169
 170 In this way, you could set a range as the value for the key `numplayers' in
 171 the |leveleditor-metadata| section, representing the minimum and maximum
 172 number of players the map supports.
 173
 174                                                     *leveleditor-functions*
 175 The syntax of a function call is familiar.  First comes the name of the
 176 function to be called, then an open parenthesis, followed by a
 177 whitespace-separated (no commas!) list of arguments before a closing
 178 parenthesis.  For example,
 179
 180     wait(3)             Delay for 3 seconds.
 181     has(F)              Check if a player has an entity F in inventory.
 182     create(B [2,3])     Create an entity B on the map at [2,3].
 183
 184                                                         *leveleditor-lists*
 185 Some keys can be assigned a list of things, such as functions to be called
 186 sequentially to accomplish some thing.  The syntax of this is to simply
 187 separate each thing with any amount of white space, except for a
 188 line-ending which serves to terminate the list and value being assigned.
 189
 190 vim:et:ft=help:tw=75