Latest Posts

Changes in BlueprintRegions

Old Title


Editor Comment

Initial version


Revision Differences of Revision 1

# Region support in Editor and Game ¶

### Related links: ¶

* Discussion: <http://wl.widelands.org/forum/topic/397> ¶
* Blueprint: <https://blueprints.launchpad.net/widelands/+spec/areas-in-editor> ¶

## Overview ¶

Regions are a collection of unique Fields (or Nodes as some people call it). A region does not necessarily have to consist of neighbours or be connected, just any set of fields that is logically connected is a region. ¶

Defining a region on the map is important in scenarios or win conditions for various reasons: ¶

* Triggering actions upon revealing, or conquering any field in a region ¶
* Giving control or unhiding a region for a player ¶
* Region names can be displayed on the map to give more flair to scenario. Example: Build a Farm on the Strawberry Fields. ¶

## Current State ¶

Widelands supports regions currently as a center point and one or two radii, that is regions in the form of a circle or a disk. These can't have names and can't be defined in the editor. Currently they are implemented as generators: iterators that generate the return values on the fly. Current Regions are not persistent and are only used in game logic. ¶

## Suggestions ¶

This suggest implementation of regions with a strong focus on Lua integration. A region has a name and a set of (ushort x, ushort y) values. This is affordable, even a huge region would only take a few kilobytes of memory. Regions are created by Lua calls from the maps scripts. When a savegame is created, the regions will be saved in a new binary map data packet. ¶

## Changes to the Game ¶

This will have no visible changes to the player. Especially this blueprint does not aim to implement the UI changes necessary to display the region name on the map. The difference of this implementation is just the ease of use for the scenario designers. If someone is interested in implementing this feature, please speak up! ¶

### Changes to the Editor ¶

The editor will gain a new mode: currently it only has one mode called map editing. It will gain a new mode called regions: there will be other tools in this mode, for example no more terrain placing. This mode could eventually be extended to add support for filling or moving of regions. A new menu lists the currently defined regions and the currently selected region can be "painted" onto the map. One should also be able to visually highlight more than one region at once. Note that special fields are degenerate regions of 1 Field, so fields of interest can also be handled with this approach. ¶

#### Saving ¶

Upon save, the editor will write out the map data as usual. A special hook will be installed that gives Lua the chance to write out Lua scripts, These will all be named editor_*.lua (e.g. for this blueprint editor_regions.lua) and reside in the scripting directory of the map. These scripts are human readable Lua scripts that can also be changed manually with a text editor, for example to change names of regions or to add and remove fields. ¶

Analogously upon loading, the editor will run all scripts starting with 'editor_*.lua' which redefine the map regions (and later on maybe initial player infrastructure). ¶

Similar approaches are planed for defining initial configuration of user buildings & roads inside the editor. ¶

The scenario author then still has to manually use() the created script in it's init.lua to define and use the regions in game. ¶

## Roadmap ¶

The following items will be handled by this blueprint: ¶

* Add new Regions into widelands + Wrapping for Lua so that new Regions can be created. The old map regions are not to be touched, since they are conceptually different. ¶
* Add the tools and ui to the editor (will need that Lua is enabled in the editor which it isn't currently). ¶
* Implement the saving and loading hooks ¶
* Enhance/modify the existing Lua API to work with regions were appropriate and accept regions and fields were possible. ¶