Editor (original) (raw)

This document is meant as both provisional documentation and design outline for the new integrated map editor under development for Freeciv 2.2.

The first part, the external design guidelines, are meant to document user interaction and as such describe such aspects as GUI layout, how to use the interface for specific tasks, and how the system should respond under certain actions and circumstances.

The second part, the internal design guidelines, are meant to describe the inner workings of the editor system. This section will deal with packet definitions, communication protocols, code module arrangement and related issues.

External Design[]

GUI Layout[]

[]

The Edit Mode Item[]

If the client has the ability to set the currently connected server to edit mode (i.e. that the client has hack access) then there should be an active (sensitive) check menu item_Edit Mode_ in the Edit menu. Otherwise if the client (from its own point of view) cannot set edit mode, (i.e. does not have hack access), then this menu item should be inactive (insensitive).

When the server notifies the client that it has entered or left edit mode, the client should change the checked status of the Edit Mode item accordingly. This update should occur even if the menu item is insensitive.

The shortcut for this check menu item is ctrl-e.

[]

These should remain inactive or hidden when not in edit mode.

• Undo. Sends an undo request to the server. Shortcut ctrl-z.
• Redo. Sends a redo request to the server. Shortcut ctrl-y.
• Properties. Pops-up a dialog where the client can set the name, comment, year (turn), global warming, etc., to be used for this map/scenario. Shortcut ctrl-p.
• Save Map. Possibly this could be subsumed by items already in the Game menu.
• Recalculate Borders. Automatically assigns borders/territory based on city size and distribution.
• Toggle Fog-of-war. To facilitate editing while controlling or observing a player, this option can be used to temporarily suspend fog-of-war for the current player. Fog-of-war is re-enabled automatically when edit mode is exited. This has no effect if fog-of-war is disabled globally. Shortcut ctrl-f.
• Bitmap To Map. A dialog to load an image file and use it to assign tile terrain automatically to the whole map.

The Editor Toolbar[]

Upon having entered edit mode, the client should show a previously hidden horizontally oriented toolbar below the map canvas notebook (or possibly in a vertical orientation to the left of it). This toolbar contains image-buttons used to perform editor operations. The buttons should be primarily arranged in order of frequency of use (e.g. most commonly used buttons are placed towards the left) and secondly by categorical relation (e.g. terrain related buttons go together).

If the image button is a "brush" type toggle, then it should remain depressed to indicate that that brush type is active.

If the tool represented by the button has individual values (such as terrain types or unit types), right-clicking on it brings up a selection list of available items. Alternatively, pressing shift and the appropriate shortcut key for that tool should also bring up the selection list. As a third alternative, tab brings up the value selection list for the current tool (if applicable).

Tool Mode Buttons[]

Each editor tool may support additional modes of operation besides the default paint mode. These modes may be set using a set of radio buttons on the toolbar if the mode makes sense for the current tool (otherwise the button will be insensitive).

• Erase mode button. Toggles erase mode. Shortcut shift-d.
• Copy mode button. Toggles copy mode. Shortcut shift-c.
• Paste mode button. Toggles paste mode. Shortcut shift-v.

Copy mode allows the the user to store some number of objects corresponding to the current tool type (e.g. terrains, cities, units) into a buffer. Objects can be copied from a square of tiles (using the size parameter) or from a group of selected tiles (copy using space once the tiles are selected).

Paste mode can then be used to place the contents of the buffer anywhere on the map.

Terrain Button[]

A single button to place a tile terrain type. Right-clicking the button should bring up a scrollable list of terrains generated from the currently loaded terrain ruleset. Shortcut t.

Terrain Resource Button[]

A single button that brings up a list of terrain "resources" generated from the currently loaded ruleset (e.g. wheat, gold, whales). Shortcut r.

Terrain Special Button[]

All terrain related entities not covered by the above two buttons are made available by this one. This includes terrain improvements (e.g. road, irrigation) and other terrain modifiers (e.g. fallout, pollution). Shortcut s.

Military Base Button[]

A button to place a military base (e.g. fortress or airbase). Shortcut m.

Unit Button[]

A single button to place a unit. It should bring up a list of all possible units in the current ruleset. Shortcut u.

City Button[]

A single button to place a city. Shortcut c.

Vision Button[]

A single button to toggle the visual state (known or unknown) of a tile for the current player point-of-view. Shortcut v.

Start Position Button[]

A single button to place a start position (for a player or nation). This would only be useful for certain kinds of map/scenario creation. Shortcut p.

Player POV Indicator[]

A combo box (if there are 8 players or less), or popup scrollable list to switch the point-of-view of the editing client. Thus the player set in the combo-box will be the player under which units or cities will be created by the editing client (by default, but see the applied player under Edit Info Box), and whose vision information will be changed by the vision buttons, etc. There should also be a global observer option so that objects not visible to any player can be edited.

Beside the combobox is a properties button to bring up the property editor for players.

The Main Map View[]

The mouse click handling should be completely controlled by the editor, so that

• Left-click applies the current brush operation.
• Left-click drag applies the brush operation over all objects that the cursor passes over (i.e. in the manner of a painter's brush stroke). Additionally, if the cursor begins to leave the visible map area, the client should scroll the map so that the painted tiles are always visible.
• Right-click recenters the mapview and cancels the current selection.
• Right-click drag selects tiles covered by the selection rectangle.
• Shift-right-click and shift-right-click drag add tiles to the current selection.
• Alt-right-click and alt-right-click drag remove tiles from the current selection.
• Middle-click brings up a properties dialog for objects with complex states (tiles, units and cities). Alternatively this could use a modifier (e.g. alt) and right-click for users without 3 button mice.
• Shift-left-click applies the grab feature, that is the object thus clicked is made to be the current brush operation (a.k.a. copy). Since multiple objects may be on a single tile, the client uses a set scheme to select which object should be grabbed:

1. Air units over land units over sea units over transported units.
2. Cities.
3. Terrain specials (i.e. roads, irrigation, etc.).
4. Terrain resources (i.e. gold, whales, etc.).
5. Terrain.

Grabbing unseen tiles (i.e. the blacked-out area) sets the vision tool.

• Ctrl-left-click grabs the "owner" of the clicked object and sets it to be the applied player for the current tool (if applicable).

Selected tiles should give some visual indication that they are selected.

The Property Editor[]

Property editor in developement.

In order to allow users to modify the complex state of game entities (or objects), a special dialog is provided that allows the viewing and editing of one or more objects' properties at the same time.

This window can be brought up by middle-clicking in the main map view on an object or on a selection of objects, or by clicking the Properties button on the editor toolbar.

The property editor is split into a number of pages corresponding to the available objects for editing (e.g. Tile, Unit, City, etc.). Different object pages can be accessed via notebook tabs.

Each property page is generally sub-divided into three regions: the object list, properties panel, and extended property viewer.

Below this area there are some operation buttons:

• An Apply button. Pressing this button will send all modified property values (i.e. those whose names are displayed in red in the properties panel) of the objects currently selected in the object list to the server. The server should then modify the objects and send back information to the client regarding the new state, or a message describing why the modification was not possible.
• A Refresh button. Pressing this button will reset all modified property values to the object's current state for all currently selected objects in the object list.
• A Create button. Pressing this button will create objects corresponding to the current property page type and automatically add them to the object list. The parameters for object creation are taken from the editor tool states, so for example the unit tool type and count influence what kind of unit and how many are created by one press of the Create button. The location of the new objects is determined by their kind and the objects already present in the object list.
• A Destroy button. Pressing this button will completely erase the selected objects in the object list from the game.

Not all object types can be created or destroyed. Those for which such operations do not make sense will have the relevant buttons hidden.

The Object List[]

The leftmost region of a property page contains a list used to select one or more objects for editing. It also displays a number of object properties and their current values.

It is possible to sort the list by clicking on column names, resize column widths by clicking and dragging the boundary between column names, or re-order the columns themselves by dragging the column name to the desired location.

The Property Panel[]

The middle region contains a scrollable panel listing all of the available properties. The property name is displayed in the left column, while the value of the property is displayed in the right. If the property is editable, then the right column may also contain a widget for editing the property's value.

For complex properties that would be difficult to edit in the small space provided by the property panel, an Edit button is shown instead of an edit widget. Clicking this button will cause the extended property viewer to focus on the given property, facilitating its modification.

The panel also contains a Filter text entry below the list of properties. Typing letters into the entry filters which properties are displayed based on a case-insensitive match of their names. The filter pattern supports three kinds of operators, & (and), | (or) and ! (not). Not has higher precendence than and, and and has higher precedence than or. So for example the pattern im|ter|reso makes the Image, Terrain and Resource properties the only shown properties on the tile property page.

Modifying the value of an editable property while one or more objects are selected in the object list, will cause the name of the property to be displayed in red. This signifies that the property's value has changed, but that the change has not yet been applied to the object.

The Extended Property Viewer[]

Property values which would be difficult to edit in the small space provided by the property panel can be viewed or modified in the third, rightmost region of the property page. Generally, this will be required for array, bitvector or very long text values.

Player Properties[]

A dialog to edit the player's global state, e.g. discovered technologies, gold, government, diplomatic relations, etc.

The Edit Info Box[]

In edit mode the client's "unit info box", the area below the minimap and turn done button that displays currently selected units, is instead used to display information about the current editor tool.

It displays:

• The name of the current tool.
• The mode of the current tool (e.g. erase, copy).
• An image representing the mode. Clicking on this image will cycle through the available modes for the tool.
• The name of the tool's value if applicable (e.g. the unit type for the unit tool, the number of objects in the buffer for copy mode).
• An image of the tool's value if applicable. Clicking on this image brings up the tool value selection list.
• A size spin button that controls the size parameter for the current tool. In general this will be the half-width of the square of tiles that is affected by applications of this tool. The exception is the city tool for which it means the size of the created city.
• A count spin button that controls the count parameter for the current tool. For example, this can be used to place more than one unit at a time with the unit tool.
• An applied player combobox that controls under which player units and cities are created by the current tool.

Editor Operations[]

Editor Behaviour[]

Internal Design[]

Code Modules[]

Server Side[]

Editor code located in the server directory of the source tree.

• edithand.c: Handlers for the editor packets are defined here.

Client Side[]

Editor code in the client directory.

• editor.h: Declares the client programming interface for the editor state manipulating functions.
• editor.c: Definitions of the core editor state and functions operating on it.
• include/editgui_g.h: Declarations of the interface that the core editor functions expect the gui implementation to provide.
• gui-gtk-2.0/editgui.h: Declarations of the editor gui functions and types.
• gui-gtk-2.0/editgui.c: Definitions of the editor gui components, e.g. the editor toolbar and infobox. Also contains any needed helper functions.
• gui-gtk-2.0/editprop.h: Declarations of the properties editor gui component.
• gui-gtk-2.0/editprop.c: Definitions of the functions and variables needed by the property editor.

Shared Code (Common)[]

This code is depended on by both the client and server modules. It resides in the common directory.

• packets.def: Besides all of the other freeciv packets, the editor packets are defined here.

Packet Definitions[]

Editor Protocol[]