Editor
From Freeciv
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.
The RT meta-ticket for the editor is PR#17880. Related tickets are marked with "Editor:" in the subject line.
Contents |
[edit] External Design
[edit] GUI Layout
[edit] The Edit Menu
[edit] 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.
[edit] Other Menu Items
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.
[edit] 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 and selection mode are active.
Right-clicking on a button brings up a selection list of available items (e.g. right-clicking on the Terrain button brings up a list of terrains from the current ruleset).
[edit] General Buttons
- Delete tool. If nothing is selected, puts cursor into delete mode. Otherwise deletes the currently selected objects. Shortcut shift-d.
- A brush size/shape modifier. This could be a numeric input box with spinner or some kind of similar GUI component that controls the number and distribution of tiles affected by a click on the main map view. Possible shortcut keys for increase/decrease in size +/-.
- A button to place a start position (for a player). This would only be useful for maps/scenarios intended to be played from the very start of the game.
[edit] 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.
Activating the terrain button changes the selection mode to terrain. Shortcut t.
[edit] 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).
Activating this button changes the selection mode to terrain resource. Shortcut r.
[edit] 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, fortification) and other terrain modifiers (e.g. fallout, pollution).
Activates selection mode terrain special. Shortcut s.
[edit] Unit Button
A single button to place a unit. It should bring up a list of all possible units in the current ruleset.
Activating a unit button changes the selection mode to unit. Shortcut u.
[edit] City Button
A single button to place a city. Activating this button change the selection mode to city. Shortcut c.
[edit] Vision Buttons
A single button to toggle the visual state (known or unknown) of a tile for the current player point-of-view.
Shortcut v.
[edit] Border/Territory Button
A single button that toggles the ownership of the clicked/selected tile(s) for the client's current player.
Shortcut b.
[edit] 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, 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 button to bring up the properties for the current player.
[edit] 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 (i.e. units or 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:
- Air units over land units over sea units over transported units.
- Cities.
- Terrain specials (i.e. roads, irrigation, etc.).
- Terrain resources (i.e. gold, whales, etc.).
- Terrain.
Selected tiles should give some visual indication that they are selected.
[edit] Unit Properties
A dialog used to edit a unit or a group of selected units all at once. Every aspect of the unit's state should be available for editing (movement points, hit points, veteran status, home city, activity [e.g. fortified], etc.).
[edit] City Properties
A dialog to edit one or more cities' states. Such things as the city name, improvements in the city, city size, food level, tile workers, specialists, etc., should be available for editing.
[edit] Player Properties
A dialog to edit the player's global state, e.g. discovered technologies, gold, government, diplomatic relations, etc.
