--- /dev/null
+*leveleditor.txt* Car Fire Level Editor for Vim
+
+ By Charles McGarvey <mcgarvey@eng.utah.edu>
+ For Team Car Fire, University of Utah CS3505, Spring 2010
+
+
+This plugin provides some nice features to help you edit Car Fire map
+files. Here's some quick documentation.
+
+===========================================================================
+1. Contents *leveleditor* *leveleditor-contents*
+
+ 1. Contents |leveleditor-contents|
+ 2. Installation |leveleditor-installation|
+ 3. Features |leveleditor-features|
+
+ Appendix
+ A. Map File Format |leveleditor-fileformat|
+ B. Basic Syntax |leveleditor-syntax|
+
+===========================================================================
+2. Installation *leveleditor-installation*
+
+To install this plugin, move the `leveleditor.vim' file to the `plugin'
+directory inside your user vim directory; usually:
+
+ $HOME/.vim/plugin or
+ $HOME/vimfiles/plugin
+
+Then, move this documentation file to the `doc' directory inside your user
+vim directory; usually:
+
+ $HOME/.vim/doc or
+ $HOME/vimfiles/doc
+
+You're done! To use the level editor without installing the plugin, just
+|source| the plugin in vim:
+
+ :source path/to/leveleditor.vim
+
+===========================================================================
+3. Features *leveleditor-features*
+
+Here is a brief summary of some of the more useful features provided by
+this plugin.
+
+ *leveleditor-new*
+To start editing a new level, type <Leader>ei or select `Initialize Buffer'
+from the menu. This will clear the current buffer of any contents and
+insert a partially filled-out template. That much is undoable. It will
+also set the filetype of the current buffer to `dosini' which will give you
+at least partial syntax coloring (if you have that syntax file installed).
+
+ *leveleditor-editing-maptable*
+When your cursor is in the |leveleditor-maptable| section, a few things
+will change to help speed up the process of making changes and adding or
+removing game entities. One of those things is the |cursorcolumn| option
+is set (if it isn't already), which makes lining stuff up and measuring
+easier. Also, the |expandtab| option is set since you should not insert
+literal tabs in this section, and that could end up being a hard bug to
+find. Finally, the current position of the cursor, in map coordinates, is
+appended to the |statusline| so you can quickly tell where you are. Before
+these features will work, you must define the `dimensions' key in the
+|leveleditor-metadata| section to be the size of the map.
+
+===========================================================================
+A. Map File Format *leveleditor-fileformat*
+
+The format of the Car Fire map file follows the de facto standard INI file
+format, with at least one notable exception which we'll get to shortly.
+
+ *leveleditor-metadata*
+The metadata section of the file contains just that: metadata. Some of the
+key-value pairs may not actually be used for anything, but others may be
+quite important. You can use the |leveleditor-new| command see some of the
+pairs that could be defined. In particular, the `dimensions' key must be
+set to a coordinate with the width and height of the map, in grid units.
+Parsing the |leveleditor-maptable| depends on the value of this key, which
+is why the metadata section must go first in the file.
+
+ *leveleditor-maptable*
+The maptable section of the file is what makes this file format differ from
+the common INI file format. This section includes no key-value pairs;
+rather, immediately following the section header is a block of text with
+the same dimensions specified earlier. This block of text represents the
+placement of static objects and game |leveleditor-entities| that make up
+the level, each ASCII character representing exactly one object or entity.
+Some ASCII characters represent static objects like walls and other fixed
+scenery, but the alphabetic characters can be defined to represent certain
+special or mobile game entities, including keys, monsters, triggers, spawn
+locations, and more. This description is not meant to be comprehensive;
+you should look at an actual level file to figure out what all this means.
+
+ *leveleditor-entities*
+Game entities can be defined in their own section of the file. Entity
+sections are directly named after the ASCII character that will place them
+on the map. Only alphabetic characters (lowercase or uppercase) may be
+defined in this manner; all other characters are reserved for static
+objects and whatnot. For example, if I wanted to place a monster on the
+map using the `A' character, I would create a section of the file named `A'
+and then place one or more `A' characters in the |leveleditor-maptable|
+section at the coordinates where I want the monsters to be created when the
+map file is loaded.
+
+You can also use the same definitions to place identical copies of the same
+entity at different locations on the map. This is what allows you to
+create more entities on the map than there are characters in the alphabet,
+although you are limited to only 52 different types of entities per level.
+By the way, these sections can appear anywhere in the file, either before
+or after the |leveleditor-maptable| section.
+
+===========================================================================
+B. Basic Syntax *leveleditor-syntax*
+
+To make parsing simple, the format of the values that make up a key-value
+pair follows a consistent pattern based on the type of thing being
+described. Here are the things that can appear on the right side of a
+key-value pair assignment:
+
+ *leveleditor-strings*
+Strings are simply a sequence of characters. If the key expects to be set
+to a string, then the right side of the assignment up to the line-end will
+be parsed as a string, including any white space. If a string value is not
+necessarily expected, you can explicitly surround the string with quotes;
+otherwise, the value could be interpreted as a list if it contains any
+white space.
+
+The characters that make up the string are included in the string according
+to their literal characters; no escape characters are ever parsed (i.e. \t
+or \n). Any value which does not follow any of the following formats will
+be read as a string.
+
+ *leveleditor-numbers*
+Base-ten numbers are parsed as they appear. The parser is allowed to read
+numbers with special characters such as -10e5. Numbers cannot be specified
+in any other base than ten.
+
+ *leveleditor-coordinates*
+To specify a coordinate or location on the map, surround two
+comma-separated integers with square brackets. For example,
+
+ [0,0] The origin, or top-left unit-square on the grid.
+ [3,9] The tenth unit-square from the top, fourth from the left.
+
+The coordinate system of the grid in the |leveleditor-maptable| section is
+Cartesian with reflection over the horizontal axis, so that y increases as
+you go down.
+
+ *leveleditor-ranges*
+A range of integer values is parsed as two comma-separated integers with
+angular brackets. For example,
+
+ <1-4> Matches any integer between 1 and 4, inclusive.
+
+In this way, you could set a range as the value for the key `numplayers' in
+the |leveleditor-metadata| section, representing the minimum and maximum
+number of players the map supports.
+
+ *leveleditor-functions*
+The syntax of a function call is familiar. First comes the name of the
+function to be called, then an open parenthesis, followed by a
+comma-separated list of arguments before a closing parenthesis. For
+example,
+
+ wait(3) Delay for 3 seconds.
+ has(F) Check if a player has an entity F in inventory.
+ create(B,[2,3]) Create an entity B on the map at [2,3].
+
+Note, the file loader parses each group of characters between white space
+separately; therefore, do not include spaces between the arguments of the
+function call, only a single comma.
+
+ *leveleditor-lists*
+Some keys can be assigned a list of things, such as functions to be called
+sequentially to accomplish some thing. The syntax of this is to simply
+separate each thing with any amount of white space, except for a
+line-ending which serves to terminate the list and value being assigned.
+
+vim:et:ft=help:tw=75
projects / chaz / carfire / blobdiff