X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fcarfire;a=blobdiff_plain;f=CarFire%2Fleveleditor%2Fdoc%2Fleveleditor.txt;fp=CarFire%2Fleveleditor%2Fdoc%2Fleveleditor.txt;h=46cfb6392ab89f364ace8046390aedb5fffd590e;hp=eaa9e3c45bc1dc0dd424469b0387e99a77027d51;hb=c255cb9589044501e3b16774eb96c9c803f523cc;hpb=e15d06e5a374072d02f3df46c1e15b88255ae6a1 diff --git a/CarFire/leveleditor/doc/leveleditor.txt b/CarFire/leveleditor/doc/leveleditor.txt index eaa9e3c..46cfb63 100644 --- a/CarFire/leveleditor/doc/leveleditor.txt +++ b/CarFire/leveleditor/doc/leveleditor.txt @@ -1,179 +1,179 @@ -*leveleditor.txt* Car Fire Level Editor for Vim - - By Charles McGarvey - 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 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 +*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 + +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 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. + + *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