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