*leveleditor.txt* CarFire Level Editor for Vim By Charles McGarvey For Team CarFire, University of Utah CS3505, Spring 2010 This plugin provides some nice features to help you edit CarFire 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 Alternatively, you can use the level editor without installing the plugin, just |source| the plugin in vim: :so /path/to/leveleditor.vim Or setup Vim to do it automagically with |:autocmd|; put this in your user Vim config file: au BufNewFile,BufRead *.cfmap so /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 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 CarFire map file follows the de facto standard INI file format, with at least one notable exception which we'll get to shortly. Because of that exception, a specialized loader is necessary, so map files should carry the extension `cfmap' so as not to have them be mistook as your everyday household variety INI file. *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. The static scenery at the places where entities are placed is determined by the `defaulttile' key in the |leveleditor-metadata| section. 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. There is also a way to place entities on the map without putting its identifying character in the |leveleditor-maptable| section. You might want to do this if you want to place an entity at some cell on the map that you don't want to be the default tile. This is accomplished by listing the coordinates where entities should be place after the `create' key. Sometime during the map loading process, entities defined with this key and one or more valid sets of coordinates will be made available to the game in the usual manner, just as if its identifier was put on the map. The difference is, you can put any (open) static scenery you want at those locations. =========================================================================== 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. Except in the case of strings, white space is ignored. Here are the things that can appear in a map file. *leveleditor-keys* Keys are special strings that appear on the left side of a key-value pair, which combined is a key and value separated by an equals sign. Keys are simply a sequence of alphabet characters. No white space, digits, or punctuation is allowed in a key. *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 double quotes; otherwise, the value could be interpreted as a list if it contains any white space. The characters given as a string are interpreted as-is. No escape characters are ever parsed (i.e. \t or \n). *leveleditor-integers* 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-booleans* Boolean values are one of two keywords: `true' and `false.' Case is ignored when parsing booleans, but abbreviations are not allowed. For example, `TrUe' is okay, but `T' is not. *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 whitespace-separated (no commas!) 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]. *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