Difference between revisions of "GSoC-WesnothWhiteboard Gabba"

From The Battle for Wesnoth Wiki
(Removing Delay Shroud Updates)
m (fix layouting)
 
(106 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{SoC2010Student}}
+
{{SoC2010Student_2|gabba|SoC Ideas Your Own Ideas}}
 
[[Category:SoC Ideas Your Own Ideas]]
 
[[Category:SoC Ideas Your Own Ideas]]
  
=Description=
+
'''''Important note for GSoC students: this document is only here for archival purposes! It is definitely not the best way to understand the whiteboard project in its current state. You should rather play around with it in the game, and study the source code, as well as ask gabba questions.'''''
<h4>Gabba - Wesnoth Whiteboard</h4>
 
  
My original goal for this project was to reduce waiting tedium in coop multiplayer games, by allowing you to see your ally's moves exactly as if you were staring at the same screen while he plays his turn.
+
==Description==
 +
<h4>Gabba - Interface Streamlining and Planning System</h4>
  
This has evolved in a wider Whiteboard project, which will allow you and your allies to visually plan moves on the map together. It will replace the current undo system, which has some kludgy problems and conflicts.
+
I intend to rework the current Wesnoth interface by introducing a planning system that will allow you to give orders and modify them before executing them as a "real action".
  
''Updated 04/05/2010''
+
Side benefits include:
 +
*allowing you and your allies to visually plan moves on the map together
 +
*replacing "delay shroud updates" by a more elegant system
 +
*finally making wml "sighted" events work properly
  
=IRC=
+
''Updated 04/12/2010''
 +
 
 +
==IRC==
 
gabba
 
gabba
  
=About Me=
+
==SoC Application==
 +
[http://socghop.appspot.com/gsoc/student_proposal/review/google/gsoc2010/gabba/t127042278960 Wesnoth Whiteboard]
 +
 
 +
==About Me==
 
See [[User:Gabba]]
 
See [[User:Gabba]]
  
=History=
+
==History==
  
 
To put things in context, this idea was already discussed in embryonic form
 
To put things in context, this idea was already discussed in embryonic form
Line 26: Line 34:
 
before it ended up as this formal GSoC proposal.
 
before it ended up as this formal GSoC proposal.
  
=Credits=
+
==Credits==
 
*''Boucman'' for introducing the idea of setting gotos when it's not your turn, and his thorough review of the proposal.
 
*''Boucman'' for introducing the idea of setting gotos when it's not your turn, and his thorough review of the proposal.
 
*''Crab_'' for the overall concept and the backend mechanisms, as well as many details I would not have thought of.
 
*''Crab_'' for the overall concept and the backend mechanisms, as well as many details I would not have thought of.
 
*''Mordante'' for his review and comments.
 
*''Mordante'' for his review and comments.
 
*''Noy'' for analysing in depth the gameplay implications.
 
*''Noy'' for analysing in depth the gameplay implications.
 +
*''Happygrue'' for his review and comments, and for being a patient multiplayer teacher.
 +
*''Zookeeper'' for providing valuable input on some key points.
  
=The Problem=
+
==The Problem==
 
===Waiting tedium and difficult allied planning===
 
===Waiting tedium and difficult allied planning===
 
Currently when playing a coop game (either RPG or more standard multiplayer campaign), there are several things that really irk me when it's not my turn:
 
Currently when playing a coop game (either RPG or more standard multiplayer campaign), there are several things that really irk me when it's not my turn:
Line 50: Line 60:
  
 
===Annoying gotos===
 
===Annoying gotos===
Gotos (i.e. multi-turn moves) can be useful, but are also annoying since they are executed automatically at the beginning of your turn, and there's no visual display to show you at a glance which units have gotos set.
+
Gotos (i.e. multi-turn moves) can be useful, but are also annoying since they are executed automatically at the beginning of your turn, and there's no visual display to show you at a glance which units have gotos set. You have no way to modify them outside of your turn either, to react to an unexpected turn of events.
  
=The Project=
+
==The Project==
 
==Overview==
 
==Overview==
 
My project directly addresses the problems described above:
 
My project directly addresses the problems described above:
Line 63: Line 73:
 
===Conflicts between undo and various events (solution)===
 
===Conflicts between undo and various events (solution)===
 
You'll be able to plan as many moves as you want, but unlike the current "undoable moves", they won't become "real" until ''you'' decide to:
 
You'll be able to plan as many moves as you want, but unlike the current "undoable moves", they won't become "real" until ''you'' decide to:
*Simply planning a moves triggers nothing. Shroud updates, WML events, ambushes and the like won't have the possibility of happening until you decide to commit a move.
+
*Simply planning a moves triggers nothing. Shroud updates, WML events, ambushes and the like won't have the possibility of happening until you decide to execute a move.
 
*When you commit a move and it does trigger an ambush, shroud update or WML event, your other planned moves will stay modifiable. The game will simply show you which of your remaining planned moves have become invalid because of the changing situation, so you can modify or replace them at your leisure.
 
*When you commit a move and it does trigger an ambush, shroud update or WML event, your other planned moves will stay modifiable. The game will simply show you which of your remaining planned moves have become invalid because of the changing situation, so you can modify or replace them at your leisure.
 
*Unlike undoable moves which must be undone in order, planned moves can be undone in any order, and commited individually in any order.
 
*Unlike undoable moves which must be undone in order, planned moves can be undone in any order, and commited individually in any order.
  
 
===Annoying gotos (solution)===
 
===Annoying gotos (solution)===
(Controversial)
+
 
No more self-executing gotos. You'll be able to plan multi-turn moves, they'll always be visible on the map (and to your allies), and the part that corresponds to the current turn will execute only when you decide to.
+
If you don't want to rely on self-executing gotos, you won't have to. You'll be able to plan multi-turn moves, they'll always be visible on the map (and to your allies), and the part that corresponds to the current turn will execute only when you decide to.
  
 
==Interface==
 
==Interface==
 
===A little use case===
 
===A little use case===
Let's say it's the beginning of your turn. You select one of your elven archers, move your mouse around, and click a destination to move it to. Instead of your unit moving immediately, you'll see an arrow-terminated line showing the path your unit will take to get there, and a "ghost" (i.e. semi-transparent) form of the archer at the destination position. You repeat this with an elven fighter and a scout, and all three paths now show on the map.
+
Let's say it's the beginning of your turn, and you have planning mode turned on. You select one of your elven archers, move your mouse around, and click a destination to move it to. Instead of your unit moving immediately, you'll see an arrow-terminated line showing the path your unit will take to get there, and a "ghost" (i.e. semi-transparent) form of the archer at the destination position. You repeat this with an elven fighter and a scout, and all three paths now show on the map.
  
Now, since you're playing as a team of two, you're not sure that the moves you picked will really benefit the team. You chat with your ally, and ask him "should I send my scout this way?". Fortunately, he sees on his screen the same arrows as you, and therefore the move you plan for the scout. "Sure", he answers. With renewed confidence, you hover the mouse over your elven scout and press 'c' to commit the move. The unit now really moves, and the arrow disappears.
+
Now, since you're playing as a team of two, you're not sure that the moves you picked will really benefit the team. You chat with your ally, and ask him "should I send my scout this way?". Fortunately, he sees on his screen the same arrows as you, and therefore the move you plan for the scout. "Sure", he answers. With renewed confidence, you hover the mouse over your elven scout and press 'E' to execute the move. The unit now really moves, and the arrow disappears.
  
Before committing the two other moves, you want some assurance that you'll have backup, since the orcs are charging at you across the plain. You ask your ally: "Can you move your white mage behind my archer and fighter?", and he agrees to do it. Even though it's not his turn, he selects his white mage and picks a destination for him, right next to your two units. You both see on your screens the path and the destination of the mage (on your screen his arrow shows in his team color); you now feel safer and decide to commit all moves. You select "commit all actions" from the context menu, and the game starts executing your remaining planned actions in the order you defined them.
+
Before committing the two other moves, you want some assurance that you'll have backup, since the orcs are charging at you across the plain. You ask your ally: "Can you move your white mage behind my archer and fighter?", and he agrees to do it. Even though it's not his turn, he selects his white mage and picks a destination for him, right next to your two units. You both see on your screens the path and the destination of the mage (on your screen his arrow shows in his team color); you now feel safer and decide to commit all moves. You select "Execute All" from the context menu, and the game starts executing your remaining planned actions in the order you defined them.
  
The archer starts its move, but unfortunately it gets ambushed mid-way by a sneaky orcish assassin (you are playing the "Ambushing Assassin Era" :P). Since a special event happened, the game stops executing your moves. You decide to change the planned move of the fighter and attack the orcish assassin; since it's your last unit and you don't really need to plan the move before executing it, you shift-click to attack the orc, and the attack happens immediately. When his turn comes, your ally will probably also change the destination of his white mage.
+
The archer starts its move, but unfortunately it gets ambushed mid-way by a sneaky orcish assassin (you are playing the "Ambushing Assassin Era" :P). Since a special event happened, the game stops executing your moves. You decide to change the planned move of the fighter and attack the orcish assassin; since it's your last unit and you don't really need to plan the move before executing it, you shift-click to attack the orc, and the attack happens immediately. When his turn comes (or even before), your ally will probably also change the destination of his white mage.
  
 
Without depicting the scene frame by frame, the mockup below shows a tentative look for the interface elements necessary to realize this use case:
 
Without depicting the scene frame by frame, the mockup below shows a tentative look for the interface elements necessary to realize this use case:
Line 89: Line 99:
  
 
===Features===
 
===Features===
These are the features planned for the Wesnoth Whiteboard interface.
+
These are the features planned for the Wesnoth Planning System interface.
  
 
Disclaimer: all artistic details in this proposal, such as the display of arrows, numbers and the like, are subject to change.
 
Disclaimer: all artistic details in this proposal, such as the display of arrows, numbers and the like, are subject to change.
Line 105: Line 115:
  
 
This image also shows a solution to display multiple moves/attacks planned for the same hex. Here: the two scouts that want to attack the orcish grunt from the same spot. We can't prevent the player from doing that, since he might have perfectly valid reasons to do so, such as repeatedly attacking a paladin with a horde of walking corpses from the only available hex.
 
This image also shows a solution to display multiple moves/attacks planned for the same hex. Here: the two scouts that want to attack the orcish grunt from the same spot. We can't prevent the player from doing that, since he might have perfectly valid reasons to do so, such as repeatedly attacking a paladin with a horde of walking corpses from the only available hex.
 +
 +
*A situation that requires special attention is when you'd like to plan a move that ends on a hex that currently contains a friendly or enemy unit. This should be supported, since the friendly unit can move out of the way and the enemy can die by the time you execute the planned move. However with the current interface, clicking on an occupied hex will select the unit in that hex, not give an order to move there.
 +
**The most reasonable solution seems to be that if you're in planning mode and you have a unit selected, clicking on an occupied hex will set a planned move there, ''not'' select the unit there.
 +
**Barring that, we'd need a shortcut key (such as Ctrl or Alt) to make sure a move gets planned instead of selecting a unit. I'll try to avoid this as it complicates the interface further.
 +
 
=====Recruit/Recall=====
 
=====Recruit/Recall=====
 
A "ghost" of the soon-to-be-recruited/recalled unit will appear in the hex; various visual clues are being considered to indicate the planned move status and avoid confusion with an ambushing unit.
 
A "ghost" of the soon-to-be-recruited/recalled unit will appear in the hex; various visual clues are being considered to indicate the planned move status and avoid confusion with an ambushing unit.
Line 114: Line 129:
 
*''Action Conflict'' ("soft conflict"): Conflict between two planned actions: any planned action which targets the same location as another. All actions displayed on screen will be checked for this, including those coming from other players. The game will let you plan voluntarily this kind of conflicting action, but will add a visual warning.
 
*''Action Conflict'' ("soft conflict"): Conflict between two planned actions: any planned action which targets the same location as another. All actions displayed on screen will be checked for this, including those coming from other players. The game will let you plan voluntarily this kind of conflicting action, but will add a visual warning.
 
**example: the two Elvish Scouts planning to attack the Grunt from the same hex, in the image from the "little use case" section above, should both receive a conflict marker.
 
**example: the two Elvish Scouts planning to attack the Grunt from the same hex, in the image from the "little use case" section above, should both receive a conflict marker.
 +
**if a move's destination is on top of a friendly unit's current position, we should probably not mark it as a conflict if we know from the move ordering that said unit is gonna evacuate the hex before the move that interests us is executed, thus freeing the way.
 
*''Gamestate conflict'' ("hard conflict"): Conflict between a planned action and the game state: this would be a planned action that tries to do an impossible move, such as moving into a cave wall. You won't be able to define those voluntarily, but some actions might end up in that state because of a WML event. These conflicts will have a stronger visual warning.
 
*''Gamestate conflict'' ("hard conflict"): Conflict between a planned action and the game state: this would be a planned action that tries to do an impossible move, such as moving into a cave wall. You won't be able to define those voluntarily, but some actions might end up in that state because of a WML event. These conflicts will have a stronger visual warning.
  
Line 125: Line 141:
  
 
=====Commiting moves=====
 
=====Commiting moves=====
Whenever the player is satisfied with one of his planned action, and this action does not have a gamestate conflict, he can individually '''commit''' it by either accessing the unit's context menu and selecting "commit", or simply hovering his mouse over it/selecting it and pressing 'e' (for "Execute", which will probably be how the user knows the command, rather than "Commit" that sounds good for svn/git users).
+
Whenever the player is satisfied with one of his planned action, and this action does not have a gamestate conflict, he can individually '''commit''' it by either accessing the unit's context menu and selecting "commit", or simply hovering his mouse over it/selecting it and pressing 'e' (for "Execute", which will probably be how the user knows the command, rather than "Commit" that sounds good for s&shy;&shy;v&shy;&shy;n/git users).
  
 
If no unit is selected or hovered over, then the first action in the planned move queue (the one numbered '1' on screen) will be commited.
 
If no unit is selected or hovered over, then the first action in the planned move queue (the one numbered '1' on screen) will be commited.
Line 132: Line 148:
 
*The moves and recruits won't be animated, only combat will be.
 
*The moves and recruits won't be animated, only combat will be.
 
*If there is shroud and you have the "stop when enemy sighted" option activated, any enemy sightings will be ignored nevertheless: this behavior is similar to what happens when you disable "delay shroud updates" after having done a bunch of undoable moves.
 
*If there is shroud and you have the "stop when enemy sighted" option activated, any enemy sightings will be ignored nevertheless: this behavior is similar to what happens when you disable "delay shroud updates" after having done a bunch of undoable moves.
 +
*The following behavior is also being considered (but won't easily be intuitive for the player, and might need to be moved to a separate command): if a unit is selected when Execute All is called, only moves numbered equal or higher as the number of the current unit will be executed. This allows you to quickly execute your last few planned moves while keeping the rest for later.
  
 
Committing a move means the "real" action is executed as usual in Wesnoth, and remaining planned actions get validated. Note that you do not lose your other planned actions.
 
Committing a move means the "real" action is executed as usual in Wesnoth, and remaining planned actions get validated. Note that you do not lose your other planned actions.
Line 142: Line 159:
  
 
====Canceling planned actions====
 
====Canceling planned actions====
Canceling planned actions will be per-unit (unlike the old undo stack that force you to undo things in order). By selecting "cancel" from the context menu of a unit or hitting 'C' while it's selected, you'll clear the planned action from that unit.
+
Canceling planned actions will be per-unit (unlike the old undo stack that forces you to undo things in order). By selecting "cancel" from the context menu of a unit or hitting 'C' while it's selected, you'll clear the planned action from that unit.
 
* move/attack: the ghost form, arrow and attack indicator just disappear
 
* move/attack: the ghost form, arrow and attack indicator just disappear
 
* recruit: the "planned recruit" ghost unit will disappear.
 
* recruit: the "planned recruit" ghost unit will disappear.
However, once a move is commited, there will be no way of undoing it.
 
  
You will also be able to cancel the planned action that was last defined if you issue the "cancel" command, without any unit selected. (This will somewhat mimic the current undo behavior, for players who prefer working that way.)
+
You will also be able to cancel the planned action that was last defined if you issue the "cancel" command, without any unit selected.
  
 
====ZOC display====
 
====ZOC display====
"Show enemy moves" will now be calculated taking into account planned unit positions, instead of real unit positions. However you'll be able to hold the tab key to see the "old" display, which takes into account only commited actions.
+
"Show enemy moves" will now be calculated taking into account planned unit positions, instead of real unit positions.
 +
 
 +
====Toggle "now" and "after execute" positions====
 +
To help visualizing the situation in tights spots where planned moves are likely to point to unit current positions, I'm considering implementing a view that removes all arrows (or at least those of valid moves) and shows only the positions of units after all moves are executed. It would be linked to a shortcut key so you can quickly switch back and forth between current <-> future situation.
  
 
====Planning actions when it's not your turn====
 
====Planning actions when it's not your turn====
The whiteboard system will be available to plan moves, recruits and attacks when it's not your turn. If you have allies, they will see your plans if you have shared them.
+
The planning system will be available to plan moves, recruits and attacks when it's not your turn. If you have allies, they will see your plans if you have shared them.
 
Design choices will need to be made in the following areas:
 
Design choices will need to be made in the following areas:
 
*Do we enable planning mode by default when it's not your turn, and then non-planning mode when your turn starts? If so, a proeminent visual reminder of which mode we're in will be needed to avoid confusing players.
 
*Do we enable planning mode by default when it's not your turn, and then non-planning mode when your turn starts? If so, a proeminent visual reminder of which mode we're in will be needed to avoid confusing players.
Line 160: Line 179:
 
*If move tracking is disabled, adding some visual warning that something is going on outside of your sight while you're planning moves would be useful.
 
*If move tracking is disabled, adding some visual warning that something is going on outside of your sight while you're planning moves would be useful.
  
====Summary of commands====
+
===Options===
 +
*I will provide a dialog or menu to control who you share your planned moves to, and whose planned moves you display on your map.
 +
 
 +
*A "Toggle Planning Mode" option will be provided to invert the behavior of shift-clicking; in planning mode shift-clicking does the real action directly; in normal mode shift-clicking will rather do the planning.
 +
 
 +
===Summary of commands===
 
(Subject to change)
 
(Subject to change)
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
Line 175: Line 199:
 
|  Cancel
 
|  Cancel
 
|  C
 
|  C
 +
|-
 +
|  Cancel All
 +
|  Shift+C
 
|-
 
|-
 
|  Direct action (planning mode) / Planned action (normal mode)
 
|  Direct action (planning mode) / Planned action (normal mode)
Line 180: Line 207:
 
|-
 
|-
 
|  Toggle planning mode (invert shift-click behavior)
 
|  Toggle planning mode (invert shift-click behavior)
Caps Lock
+
P
 
|-
 
|-
 
|  Bump action up and down in queue
 
|  Bump action up and down in queue
 
|  X, Z
 
|  X, Z
 
|-
 
|-
|  Toggle ZOC display
+
|  Toggle Now/After Execute display
 
|  Tab
 
|  Tab
 
|}
 
|}
 
===Options===
 
*I will provide a dialog or menu to control who you share your planned moves to, and whose planned moves you display on your map. If [[SoC_Ideas_New_Alliance_System|the new alliance system GSoC project]] is implemented, these options can be integrated to the fine-grained ally controls.
 
 
*A "Toggle Planning Mode" option will be provided to invert the behavior of shift-clicking; in planning mode shift-clicking does the real action directly; in normal mode shift-clicking will rather do the planning.
 
  
 
===Mockups for various interface elements===
 
===Mockups for various interface elements===
Line 200: Line 222:
  
 
====Variants and experiments on the numbering system====
 
====Variants and experiments on the numbering system====
The "status-ball" display (cute but would pose problems for double and triple digits):
+
The "status-ball" display (cute but would pose problems for double and triple digits, and may conflict with the crown symbol):
 +
 
 
http://forums.wesnoth.org/download/file.php?mode=view&id=39500#.png
 
http://forums.wesnoth.org/download/file.php?mode=view&id=39500#.png
  
Line 214: Line 237:
 
Alternative "side" display: simply show the number next to units. Less disruptive visually maybe?
 
Alternative "side" display: simply show the number next to units. Less disruptive visually maybe?
 
http://forums.wesnoth.org/download/file.php?mode=view&id=39524&sid=bb7ee496abdc777856a391f020f2d084#.png
 
http://forums.wesnoth.org/download/file.php?mode=view&id=39524&sid=bb7ee496abdc777856a391f020f2d084#.png
 +
 +
====Manoeuvering in cramped areas====
 +
Let's take the following "real-world" starting situation, from a campaign some of you will recognize:
 +
http://www.wesnoth.org/forum/download/file.php?id=39774&mode=view#.png
 +
 +
With a lot of units close together, the arrow display will get rather cramped. I tried to depict a lot of overlapping moves, to try and figure out how to best help the player in these circumstances. Of course this is an ugly hack job and could look better; also, not all of the elements depicted have to get in.
 +
 +
http://www.wesnoth.org/forum/download/file.php?id=39793&mode=view#.png
 +
 +
Legend:
 +
* The hovered over unit and it's highlighted arrow: this is a static picture, but in reality hovering the mouse over the various units would quickly clear up which arrows belongs to which units.
 +
* Tentative display for a "destination" number (yellow ball with blue number). It may help matching starting and ending positions of units, especially when the ending is where another unit is standing.
 +
* Tentative display for an invalid move (#4, the archer trying to move on the location of the druid, who is not programmed to move out of the way beforehand): the striped arrow, and triangle instead of a circle behind the blue '4'.
 +
 +
With such a busy screen, even with paths that highlight on unit hover and such niceties, the player might get a bit confused: what's it gonna look like after all moves are executed? One solution would be to let the player hold a key such as Space or Tab, to end up with the following view:
 +
 +
http://www.wesnoth.org/forum/download/file.php?id=39773&mode=view#.png
 +
 +
This one doesn't convey as much info, but it's much clearer and offends the eye less. There's nothing that prevents the player from planning actions in this mode, either, switching to the "full info" view only occasionally.
 +
*This is also a good view to see the result of Execute All:
 +
**The moves are trivial and will probably not trigger an ambush or wml event
 +
**Therefore after an Execute All from either view, the result will look like this view, except that all the numbers will be gone. (Well technically, the invalid move will still be visible in the "busy" view, since it was impossible to execute.)
 +
*Practically, Execute All wouldn't be such a good idea; the player would probably commit one or two moves and then attack, or plan two moves and an attack and ''then'' Ex. All, which would commit the two moves, do the attack, and then stop.
  
 
==Engine==
 
==Engine==
Line 224: Line 270:
  
 
===Changes to the game engine===
 
===Changes to the game engine===
For this project, I want to completely get rid of the concept of an "undoable action".
+
For this project, a vector of a new kind of object called ''planned_action'' will be maintained on each client. Vectors will all get exchanged between allied clients, so that each ally will end up with a vector of planned_actions per ally in play. A planned_action will either be a WML config, or have methods to serialize/deserialize easily to it, to allow sending over the network.
 
 
Instead, a vector of a new kind of object called ''planned_action'' will be maintained on each client. Vectors will all get exchanged between allied clients, so that each ally will end up with a vector of planned_actions per ally in play. A planned_action will either be a WML config, or have methods to serialize/deserialize easily to it, to allow sending over the network.
 
  
 
* Here I'm using the term ''vector'', but I'll try to stay data-structure-agnostic as much as possible by hiding it under my own interface, so I can for example easily change it to a linked list or a dequeue if it seems desirable.
 
* Here I'm using the term ''vector'', but I'll try to stay data-structure-agnostic as much as possible by hiding it under my own interface, so I can for example easily change it to a linked list or a dequeue if it seems desirable.
Line 256: Line 300:
 
The "show enemy moves" feature will now be calculated from planned unit positions by default, instead of current unit positions. For this I'll need to build my own unit map and calculate ZOCs from there.
 
The "show enemy moves" feature will now be calculated from planned unit positions by default, instead of current unit positions. For this I'll need to build my own unit map and calculate ZOCs from there.
 
When several moves are planned for the same spot, only the last one to be programmed will be taken into account; this will have an influence when ZOC-less and normal units are heading for the same hex.
 
When several moves are planned for the same spot, only the last one to be programmed will be taken into account; this will have an influence when ZOC-less and normal units are heading for the same hex.
 +
*Alternatively, we can take into account only the unit with the most powerful ZOC headed for this hex, it might be more intuitive for the player.
  
 
==Clean up==
 
==Clean up==
This is a list of issues resolved, options removed (more KISS) and of areas of the code that will get cleaned up or completely removed as a result of this project.
+
This is a tentative list of issues resolved, options removed (more KISS) and of areas of the code that will get cleaned up or completely removed as a result of this project.
 
* "Delay shroud updates" won't be necessary anymore; this will get rid of the "delay shroud update on start" preference, and of the in-game "delay shroud updates" menu element.
 
* "Delay shroud updates" won't be necessary anymore; this will get rid of the "delay shroud update on start" preference, and of the in-game "delay shroud updates" menu element.
* (Controversial) The undo stack and related code will be removed.
 
 
* The "sighted" WML event will work properly, now that the conflict with delay shroud updates will be gone.
 
* The "sighted" WML event will work properly, now that the conflict with delay shroud updates will be gone.
 +
* The undo stack and related code will be removed, if after gathering feedback on the new interface it is deemed obsolete.
  
 
==Gameplay considerations==
 
==Gameplay considerations==
[http://wesnoth.pastebin.com/aBpS1Zyy| Recent IRC discussions] brought up several possible effects on gameplay that need to be discussed, and I thought of several more:
+
Moved these somewhat lenghty considerations to [[GSoC-WW_Gameplay_Considerations_Gabba]].
 
 
===Removing Gotos===
 
It was argued that removing the current goto system and replacing it with planned actions would be annoying, if players have to confirm the remaining part of planned moves manually on every turn start.
 
*If you have several planned moves available at the beginning of your turn and they're all trivial moves (i.e. equivalent to gotos), you can just have a quick glance to see if those moves still make sense and then hit "Execute All". The extra keystroke is I think acceptable.
 
**The only problem I can see with this is if you define some planned moves as reminders of what you'd like to do, and others as gotos. Or, if you have a mix of actions of which some are goto equivalents, and the others really need to be executed one by one. Then executing them all would be annoying.
 
*A good compromise (suggested by Upthorn if I remember well) would be to execute any remaining planned moves when you end your turn. Is gotos executing at the beginning of the turn an essential feature of Wesnoth? Many strategy games actually execute gotos as you end it, to give you a chance to modify the goto before it's executed.
 
**Once again with this, keeping some planned moves as reminders from turn to turn to eventually modify them later would not be feasible. However you could plan "draft" moves while it's not your turn, so this option sounds rather reasonable.
 
*If the above doesn't seem convicing, ''gotos as they are now can coexist with the whiteboard''. I haven't found any technical issue preventing it. I kind of see it as anti-KISS, but that's a concession I'm ready to make.
 
 
 
===Removing Undo===
 
Do we remove the current undo system, or build this new system on top of it?
 
*Keeping both violates the KISS principle by having two systems side by side that provide rather similar functionality.
 
*The UI for undo is not user-friendly, since there's no visual cue telling you that you just lost your undo stack, and the reasons why you may lose it only become apparent from experience (for instance recruiting a unit with random traits makes you lose undo, but recruiting undead or recalling units doesn't, as far as I remember).
 
**The planning system seems better in that aspect, since you get to decide when moves become permanent; the player is more in control and we have a better learning curve.
 
*The main purpose of undo as I understand it is to allow you to test visually several attack patterns, verifying your ZOC along the way. The planning system provides exactly that, plus:
 
*#The extra benefit of visually planning/canceling recruits: you can visually fill up your castle with future recruits, see how it affects your budget, then change one or two recruits to fine-tune your plan and finally "execute all" to get your recruits.
 
*#Visually planning your attacks and surrounding the enemy, without having to undo a lot of moves to make a small adjustment.
 
*#No danger of losing your planning for reasons such as attacking, ambush, a WML event, or forgetting to set Delay shroud updates.
 
*The only situation in which the current undo system is more user-friendly than planning is when you do a bunch of undoable moves in a shroud-less game, and you're happy about them and would like to do your attack. The old system just lets you attack, the new one requires you to commit them first. To alleviate this and not force you to commit a bunch of trivial moves one by one, an "Execute All" command that executes all commands without animating them would be ideal. It would stop if one of the moves triggers something that prevents other moves to execute, but for most ordinary it would execute all orders instantly.
 
 
 
===Removing Delay Shroud Updates===
 
If we keep undo, do we need to keep Delay Shroud Updates as well, or is the planning system considered a better or at least equal alternative?
 
*Delay shroud updates [https://gna.org/search/?Search=Rechercher&words=sighted&type_of_search=bugs&only_group_id=1242&exact=1&max_rows=25#options| is in great part responsible for breaking WML "sighted" events], and is the feature Crab_ and I are the most keen to replace.
 
*It is also the system for which the whiteboard is the most direct plug-and-play replacement, as can be read in [[GSoC-WesnothWhiteboard_Gabba#Removing_Undo| Removing Undo]] and [[GSoC-WesnothWhiteboard_Gabba#Workflow_of_long-time_players| Workflow of long-time players]].
 
 
 
===Default action vs Shift-click action===
 
What should be the default action: setting a planned move, or directly moving the unit (the other being available on shift-click)? And how should the option to toggle the default to the opposite be introduced: preferences option, or menu+hotkey in-game?
 
*''toggle'': the best approach seems to be the menu+hotkey (Caps Lock would make a nice hotkey since it's related to shift in the minds of players; not sure if using that key presents technical issues)
 
*if undos get removed, having permanent moves as the default might be offputting for players used to undoable moves.
 
 
 
===Workflow of long-time players===
 
According to noy, the workflow (so to speak) of good players involves making some moves, then an attack, then some more moves depending of the result of that attack. How does this workflow translate into the new system? The following questions/assumptions need answers:
 
*Do good players use Delay shroud updates? If '''not''', they're not taking advantage of undo capabilities anyways (or very little), and can probably turn off planning mode for the whole game, and happily keep playing as usual.
 
**When they actually want to visualize several unit placements or recruitments in a zone where they've pushed out the shroud far enough and therefore would currently benefit from undo capabilities, it seems that using shift-click to plan and then instant executing the actions with "Execute all" would not be an additional chore; it would rather be more flexible.
 
*If they '''are''' using delay shroud updates, it seems the planning system would work just as well as the status quo, except with a bit more visual clutter due to arrows:
 
*# Move units around with undo capability = Plan moves
 
*#*additional bonus: they get to reorder moves and cancel them without having to backtrack
 
*# Toggle delay shroud updates if you want to take a look at the situation before proceeding = "execute all" or "execute moves one by one"
 
*#*additional bonus: the game will warn you if a special event was just triggered and you'll be able to ajust your plan in consequence
 
*Do good players use the "Interrupt moves when an ally is sighted" option? This option does absolutely nothing if you leave "delay shroud updates" activated the whole game; however we have to think how to integrate this option in the whole planning framework, since if you're using "execute all" to quickly commit a series of moves without care for enemy sightings, being interrupted constantly by those would be the pinnacle of annoyance.
 
 
 
==="Execute All" vs "enable scroll tracking of unit actions"===
 
There's a potential interface conflict between planning actions while it's not your turn, and the "enable scroll tracking of unit actions" preference.
 
* The most obvious answer to this is to disable scroll tracking when planning mode is activated, otherwise the screen will scroll under your mouse just as you try to set a move.
 
**As a side note, scroll tracking also makes the view follow your own units that are executing automated gotos.
 
* But do we need a visual notification for when you're happily planning moves and something is happening outside of your screen? For combat at least, the combat sounds are probably sufficient notifications.
 
  
 
==Optional/Future developments==
 
==Optional/Future developments==
 +
Many interesting further developments will be made possible by this project, such as showing the chance-to-kill for a combined attack.
 +
See [[GSoC-WW_Optional_Future_Gabba]].
  
* Allow allies of player A to suggest moves to him while he's playing his turn. Overall idea is: player B moves one of A's units that he sees on screen, creating a planned moves. A then either immediately sees the suggested move (could be a pale line of the suggesting player's color, or something of the sort), or gets a prompt "suggested moves from player B are available", and he can then see a list of suggested moves, see what would their result on-screen be, and choose for each one to apply it (add them to his set of planned actions) or delete it.
+
==Calendar==
 +
*''Note: tasks colored <span style="color:green">green</span> are done''
  
* Allow suggesting moves to an allied AI.
 
  
* Add a way to show the attack choice and stats for already planned attacks, and to change the weapon used for that attack. Possibly show at the same time all attacks that are going to be executed on a single unit.
 
 
* Might be useful (if not too hard to use), to allow to make assumptions about enemy units. e.g., "what will zoc look like if those three enemy units are dead ?"
 
** visual is easy to find: mark them with a a large skull-and-bones similar to pirate flags :)
 
** auto-assume that units, say, with >80% ctk will be dead ???
 
 
* (Very Difficult) Find some way of displaying the dialogues the current player sees to his allies (for instance the item choice screens from Bob's RPG era), but in a non-interactive way, so they can counsel him and be a bit more active when it's not their turn.
 
 
=Calendar=
 
 
'''Start of GSoC: May 24'''
 
'''Start of GSoC: May 24'''
 
===Before mid-term eval===
 
===Before mid-term eval===
 
''(8 weeks of work)''
 
''(8 weeks of work)''
 
'''Implement planned moves as a local (non-networked) feature.'''
 
'''Implement planned moves as a local (non-networked) feature.'''
#Initial backend work (2 weeks)
+
#<span style="color:green">Initial backend work (~1 week)</span>
#* Design and implement planned_move class and the management of its container, vector or otherwise
+
#* <span style="color:green">Backend: Design and implement framework for managing planned moves (planned_move class, stl container)</span>
#* Implement operations in planned_move to add, remove planned moves; add stubs for more advanced features such as switching places between moves
+
#* <span style="color:green">Backend: Implement operations in planned_move to add, remove, switch place of planned moves</span>
#*Implement the merge algorithm for planned_action vectors
+
#<span style="color:green">Interface for adding and removing planned moves (~1.5 week)</span>
#Interface for adding and removing planned moves (2 weeks)
+
#* <span style="color:green">Backend: Arrow and unit ghosts display framework</span>
#* Preliminary display and highlighting of arrows; includes setting up the new graphics layer that will serve for all interface elements [Leaving aside attacks and recruits unless the project is doing really well is being considered]
+
#* <span style="color:green">Backend: Checking of moves for gamestate conflicts</span>
#* Preliminary interface to define and delete move arrows
+
#* <span style="color:green">Interface: defining planned moves (volutarily creating gamestate conflicts is forbidden)</span>
#* Add preliminary numbering display and reordering moves
+
#* <span style="color:green">Interface: reordering moves</span>
#* Implement display of planned attacks, with unit ghosts
+
#* <span style="color:green">Interface: Add preliminary numbering display</span>
#* Add "ghosted unit + visual cue" display of planned recruits
+
#* <span style="color:green">Interface: Highlight arrows on hover/selection of their unit</span>
#Introduce committing of actions and basic action validation (1 week)
+
#Introduce committing of moves and basic move validation (~1.5 week)
#* Implement "commit-on-hover/select" and "commit next", and deleting the planned action
+
#* <span style="color:green">Interface: "commit on select" + ''[optional] commit on hover''</span>
#* Implement committing of planned moves
+
#* <span style="color:green">Interface: "cancel on select" + ''[optional] cancel on hover''</span>
#* Implement committing of planned attacks
+
#* <span style="color:green">Backend: check moves for gamestate conflicts after every commit</span>
#* Implement committing of recruits
+
#* Interface: Visual warning for gamestate conflicts
#* Implement basic conflict checking (i.e. impossible moves) and preliminary visual warning.
+
#'''Intermediate milestone: (4 weeks in) June 21: all the above tasks must be finished.'''
#Now that interface elements won't change much, start recruiting artist contributors in the wesnoth forums so they can help make this thing look better
+
#<span style="color:green">Implement "soft conflicts" detection and ZOC display (~1 week)</span>
#Implement "soft conflicts" detection and ZOC display (1 week)
+
#* <span style="color:green">Backend: Add ZOC (ctrl+v) calculations according to planned moves</span>
#*Add detection and display of multiple moves (includes attack+move) of the current player headed for the same hex
+
#* <span style="color:green">Backend: Detect "soft blocks" i.e. blocking of planned moves by own units/own planned moves</span>
#*Implement detection and display of conflicts for all actions planned for the same hex
+
#* <span style="color:green">Interface: for now, forbid defining moves with "soft blocks"</span>
#*Add ZOC (ctrl+v) calculations and display according to planned moves (1 week)
+
<span style="color:green">#Add attack and recruit to the planned actions (~1 week)</span>
#Remove remaining obsolete code and refactor a bit (1 week)
+
#* <span style="color:green">Interface: display of planned attacks</span>
#*Remove undo code
+
#* <span style="color:green">Backend: committing of planned attacks</span>
#*Remove delay shroud updates code
+
#* <span style="color:green">Backend: planning/committing of recruits ''[optional]''</span>
#*Test if "sighted" wml events now work properly
+
#* <span style="color:green">Interface: display of planned recruits ''[optional]'' </span>
#Polish interface as much as possible for mid-term eval (remaining time, if any)
+
#* <span style="color:green">Backend: work out interactions with WML events; validate actions after they happen.</span>
 +
#Add other useful interface features (~1 week)
 +
#* <span style="color:green">Backend: toggling of state between planning mode and normal mode</span>
 +
#* <span style="color:green">Interface: menu/shortcut for "toggle planning mode"</span>
 +
#* <span style="color:green">Interface: tab-click inversion of behaviour ''[optional]''</span>
 +
#* <span style="color:green">Interface: "commit next" ''[optional]''</span>
 +
#* Interface: <span style="color:green">"cancel last"</span>/"cancel all" ''[optional]''
 +
#Bugfixing in preparation for mid-term (~1 week)
 +
#* <span style="color:green">General bugfixing</span>
 +
#* Backend: If appropriate, <span style="color:green">temporarily disable delay shroud updates code</span>, and test if "sighted" wml events now work properly ''[optional]''
  
'''Milestone: July 16, Mid-term eval''': we have a functional local whiteboard.
+
'''Milestone: (8 weeks in) July 16, Mid-term eval''': All the above tasks must be finished. We have a functional reworked interface and planning system for single-player.
  
 
===After mid-term eval===
 
===After mid-term eval===
 
''(3 weeks of work)''
 
''(3 weeks of work)''
'''Add the networked part of the whole deal'''
+
#Additional interface work (~1 week)
#Set up and test transmission and merging of planned_action vector diffs between clients (2 weeks)
+
#* <span style="color:green">Interface: Resolve issues with planning actions when it's not your turn</span> (some issues remain)
#*Implement structure allowing each client to keep a copy of the planned action vector of every other ally in play
+
#* <span style="color:green">Interface: allow defining moves on hexes occupied by current units or planned moves ''[optional]''</span>
#*Implement and test continuous syncing mechanism of planned_moves between X number of allies
+
#** Interface: alternate display to ghosts for multiple moves planned for the same hex ''[optional]''
#Implement interface elements for networked whiteboard (1 week)
+
#** <span style="color:green">Interface: visual hints for a move heading for an existing unit's location. ''[optional]''</span> (more needs to be done)
#*Implement team-colored display according to planned move origin
+
#* Interface: Implement alternate arrow-less view on [some key] ''[optional]''
#*Expand soft conflict detection to include planned_actions received from allies
+
#<span style="color:green">Bugfix and improve the interface (~2 weeks)</span>
#*Add filter backend and dialogs to choose who you share your planned_moves to and who you receive them form
+
#*<span style="color:green">Make sure all commands are accessible through both menus and shortcut keys</span>
#*Make sure all commands are accessible through both menus and shortcut keys.
+
 
 +
 
 +
'''Milestone (no set date), Complete Interface:''' The planning interface must undergo review by the dev team and be considered solid and complete before any work on the networked part starts.
 +
 
 +
====Add the networked part====
 +
''This whole section is [optional]''.
 +
#Backend: Implement the merge algorithm for planned_action vectors from other clients
 +
#Set up and test transmission and merging of planned_action vector diffs between clients
 +
#*Backend: each client keeps a copy of the planned action vector of every other ally in play
 +
#*Backend: Implement and test continuous syncing mechanism of planned_moves between X number of allies
 +
#Interface: Implement team-colored display according to planned move origin
 +
#Interactions with undo (if we don't decide to get rid of it)
 +
#*Backend: Keep planned actions around as "undoable" until their corresponding real action is permanent
 +
#*Backend: On undo, revert the appropriate planned action to normal status
 +
#*Interface: make undoable planned actions invisible to their owner but visible to his allies.
 +
#Backend: Expand soft conflict detection to include planned_actions received from allies
 +
#Add filter to choose who you share your planned_moves to and who you receive them form
 +
#*Backend: filter reception/sending of planned moves
 +
#*Interface: dialogue for filtering planned moves
 +
#If the networked part gets done in time, organise a dev tournament with team games to see the system in action on a larger scale.
  
'''Milestone: August 9, suggested pencils down date:''' we have a functional networked whiteboard
+
'''Milestone: (11 weeks in) August 9, suggested pencils down date:''' All the above tasks must be finished. We have a polished reworked interface and planning system.
 +
If things went exceptionally well, we also have a multiplayer allied planning system.
  
 
===Final touches===
 
===Final touches===
 
''(1 week of work)''
 
''(1 week of work)''
'''Document more, write small after-action report'''
+
#Add a section to the Wesnoth manual introducing and explaining the planning system.
 +
#Write a short after-action report
 +
#<span style="color:green">Discuss future plans for improving/expanding on the planning system</span>
  
'''Milestone: End of GSoC 2010'''
+
'''Milestone: (12 weeks in) August 16, End of GSoC 2010:''' Documentation tasks must be completed.

Latest revision as of 07:32, 10 November 2020


This page is related to Summer of Code 2010
See the list of Summer of Code 2010 Ideas



This is a Summer of Code 2010 student page
Project: SoC Ideas Your Own Ideas


Important note for GSoC students: this document is only here for archival purposes! It is definitely not the best way to understand the whiteboard project in its current state. You should rather play around with it in the game, and study the source code, as well as ask gabba questions.

Contents

Description

Gabba - Interface Streamlining and Planning System

I intend to rework the current Wesnoth interface by introducing a planning system that will allow you to give orders and modify them before executing them as a "real action".

Side benefits include:

  • allowing you and your allies to visually plan moves on the map together
  • replacing "delay shroud updates" by a more elegant system
  • finally making wml "sighted" events work properly

Updated 04/12/2010

IRC

gabba

SoC Application

Wesnoth Whiteboard

About Me

See User:Gabba

History

To put things in context, this idea was already discussed in embryonic form

before it ended up as this formal GSoC proposal.

Credits

  • Boucman for introducing the idea of setting gotos when it's not your turn, and his thorough review of the proposal.
  • Crab_ for the overall concept and the backend mechanisms, as well as many details I would not have thought of.
  • Mordante for his review and comments.
  • Noy for analysing in depth the gameplay implications.
  • Happygrue for his review and comments, and for being a patient multiplayer teacher.
  • Zookeeper for providing valuable input on some key points.

The Problem

Waiting tedium and difficult allied planning

Currently when playing a coop game (either RPG or more standard multiplayer campaign), there are several things that really irk me when it's not my turn:

  • You wait a long time before seeing anything happening (unless your opponents are playing without delay shroud updates).
  • When your ally who's taking his turn finally attacks an enemy or makes another non-undoable move, you have to sit through a delayed replay of his moves. If he already finished his turn, your ally has to wait while you watch this.
  • After a few undoable moves by either allied player, communication is completely out of sync. If you tell your ally, "look, I'm encircling his leader", he has no clue what you're talking about: he doesn't see what you're doing. If your ally asks you "should I move my white mage here to heal you units next turn", you 1) have no clue about which hex "here" is supposed to mean 2) even if you did, you can't adequately counsel him, since you don't see how he positioned his other units.

For this last point, you can of course place labels all over the place, but this project intends to provide a much more natural way to communicate.

Conflicts between undo and various events

Undo and delay shroud updates are very useful, but several game features conflict with them. You could have 10 temporary moves planned, just to see what your ZOC would look like, but the first of any of these events will makes you lose any undo possibility:

  • Triggering an ambush
  • Triggering an WML event ("sighted" in particular poses problems)
  • Attacking a unit

One of the goals of this project is to remove conflicts between planning moves, and this kind of event.

Annoying gotos

Gotos (i.e. multi-turn moves) can be useful, but are also annoying since they are executed automatically at the beginning of your turn, and there's no visual display to show you at a glance which units have gotos set. You have no way to modify them outside of your turn either, to react to an unexpected turn of events.

The Project

Overview

My project directly addresses the problems described above:

Waiting tedium and difficult allied planning (solution)

  • Instead of waiting, you'll be able to plan moves (and recruits, attacks, etc) while the others are playing.
  • If you have allies, a whole new dimension opens:
    • You'll see the moves of your currently playing ally as he plans them, and therefore will be able to comment on them before he commits them
    • Even better, he'll be able to see any moves you have planned for your turn, so you can finally coordinate that white mage placement or that attack correctly.

Conflicts between undo and various events (solution)

You'll be able to plan as many moves as you want, but unlike the current "undoable moves", they won't become "real" until you decide to:

  • Simply planning a moves triggers nothing. Shroud updates, WML events, ambushes and the like won't have the possibility of happening until you decide to execute a move.
  • When you commit a move and it does trigger an ambush, shroud update or WML event, your other planned moves will stay modifiable. The game will simply show you which of your remaining planned moves have become invalid because of the changing situation, so you can modify or replace them at your leisure.
  • Unlike undoable moves which must be undone in order, planned moves can be undone in any order, and commited individually in any order.

Annoying gotos (solution)

If you don't want to rely on self-executing gotos, you won't have to. You'll be able to plan multi-turn moves, they'll always be visible on the map (and to your allies), and the part that corresponds to the current turn will execute only when you decide to.

Interface

A little use case

Let's say it's the beginning of your turn, and you have planning mode turned on. You select one of your elven archers, move your mouse around, and click a destination to move it to. Instead of your unit moving immediately, you'll see an arrow-terminated line showing the path your unit will take to get there, and a "ghost" (i.e. semi-transparent) form of the archer at the destination position. You repeat this with an elven fighter and a scout, and all three paths now show on the map.

Now, since you're playing as a team of two, you're not sure that the moves you picked will really benefit the team. You chat with your ally, and ask him "should I send my scout this way?". Fortunately, he sees on his screen the same arrows as you, and therefore the move you plan for the scout. "Sure", he answers. With renewed confidence, you hover the mouse over your elven scout and press 'E' to execute the move. The unit now really moves, and the arrow disappears.

Before committing the two other moves, you want some assurance that you'll have backup, since the orcs are charging at you across the plain. You ask your ally: "Can you move your white mage behind my archer and fighter?", and he agrees to do it. Even though it's not his turn, he selects his white mage and picks a destination for him, right next to your two units. You both see on your screens the path and the destination of the mage (on your screen his arrow shows in his team color); you now feel safer and decide to commit all moves. You select "Execute All" from the context menu, and the game starts executing your remaining planned actions in the order you defined them.

The archer starts its move, but unfortunately it gets ambushed mid-way by a sneaky orcish assassin (you are playing the "Ambushing Assassin Era" :P). Since a special event happened, the game stops executing your moves. You decide to change the planned move of the fighter and attack the orcish assassin; since it's your last unit and you don't really need to plan the move before executing it, you shift-click to attack the orc, and the attack happens immediately. When his turn comes (or even before), your ally will probably also change the destination of his white mage.

Without depicting the scene frame by frame, the mockup below shows a tentative look for the interface elements necessary to realize this use case: file.php?mode=view&id=39500#.png

(Yes, I know that orcish assassins usually don't have ambush, but this one took courses from a renegade Elvish Ranger. Understood?)

  • Red arrows are planned moves for the current player, the blue arrow is a move planned by his ally.
  • Also notice the numbering, that corresponds to the order of programmed moves. The white mage should actually bear the number 1, if moving it is the first planned move that his owner set up. (See Variants and experiments on the numbering system: various ways of displaying those numbers are being considered.)

Features

These are the features planned for the Wesnoth Planning System interface.

Disclaimer: all artistic details in this proposal, such as the display of arrows, numbers and the like, are subject to change.

Planning various actions

The player will be able to plan visually on the map all his actions (moves, attacks, recruits/recalls) before "making them real", i.e. commiting them. He will also see on his map all planned actions from his allies who have shared them. Filtering those actions per-ally will be possible, to minimize map clutter. The display for those actions will be identical to his own, except they'll be clearly identified by the originating player's team color.

Moves and attacks

When the player selects a unit with movement points remaining, he'll see the usual thing as he moves his mouse, i.e. footsteps and the attack indicator to show attack possibilities. When he clicks to order an attack or a move, it won't be executed right away, but rather an arrow will be draw from the units current to its future position, and a "ghost" form of the unit will be drawn at the destination. If the action is an attack, the action indicator will remain to show the future attack. With several attacks planned, the display would look like this: file.php?mode=view&id=39499#.png

If a move will take several turns to execute, this will be displayed on the arrow in a similar manner than the current footsteps.

This image also shows a solution to display multiple moves/attacks planned for the same hex. Here: the two scouts that want to attack the orcish grunt from the same spot. We can't prevent the player from doing that, since he might have perfectly valid reasons to do so, such as repeatedly attacking a paladin with a horde of walking corpses from the only available hex.

  • A situation that requires special attention is when you'd like to plan a move that ends on a hex that currently contains a friendly or enemy unit. This should be supported, since the friendly unit can move out of the way and the enemy can die by the time you execute the planned move. However with the current interface, clicking on an occupied hex will select the unit in that hex, not give an order to move there.
    • The most reasonable solution seems to be that if you're in planning mode and you have a unit selected, clicking on an occupied hex will set a planned move there, not select the unit there.
    • Barring that, we'd need a shortcut key (such as Ctrl or Alt) to make sure a move gets planned instead of selecting a unit. I'll try to avoid this as it complicates the interface further.
Recruit/Recall

A "ghost" of the soon-to-be-recruited/recalled unit will appear in the hex; various visual clues are being considered to indicate the planned move status and avoid confusion with an ambushing unit.

  • Do we visually decrement the player's gold (without touching the backend value) when a planned recruit is added? It looks like a good idea, so he can count up how many units he can afford before confirming the recruits/recalls.

Validation and Conflicts

The game will check all actions for validity whenever they are planned. They will also be re-checked for this after any modification to the planned moves, or after committing a move (which might trigger an ambush or a game-altering WML event). Two kind of conflicts can be detected by this validity check:

  • Action Conflict ("soft conflict"): Conflict between two planned actions: any planned action which targets the same location as another. All actions displayed on screen will be checked for this, including those coming from other players. The game will let you plan voluntarily this kind of conflicting action, but will add a visual warning.
    • example: the two Elvish Scouts planning to attack the Grunt from the same hex, in the image from the "little use case" section above, should both receive a conflict marker.
    • if a move's destination is on top of a friendly unit's current position, we should probably not mark it as a conflict if we know from the move ordering that said unit is gonna evacuate the hex before the move that interests us is executed, thus freeing the way.
  • Gamestate conflict ("hard conflict"): Conflict between a planned action and the game state: this would be a planned action that tries to do an impossible move, such as moving into a cave wall. You won't be able to define those voluntarily, but some actions might end up in that state because of a WML event. These conflicts will have a stronger visual warning.

With both kinds of conflicts, the player will keep the ability to delete the planned action or define another in its place.

Order of actions and Committing

Ordering of actions

Planned actions will receive a sequence number as they are added. First action get number 1, second action gets number 2, and so on. You can see some mockups of various ways of displaying those numbers in the mockups section. Each player's units will be numbered separately.

The sequence number is important for when the player would like to commit his planned actions without having to hover over individual units.

Commiting moves

Whenever the player is satisfied with one of his planned action, and this action does not have a gamestate conflict, he can individually commit it by either accessing the unit's context menu and selecting "commit", or simply hovering his mouse over it/selecting it and pressing 'e' (for "Execute", which will probably be how the user knows the command, rather than "Commit" that sounds good for s­­v­­n/git users).

If no unit is selected or hovered over, then the first action in the planned move queue (the one numbered '1' on screen) will be commited.

A "fast-commit", "fast-forward" or Execute All command will be added, so that a bunch of trivial actions can be commited quickly. This command has only one goal: transform your planned moves into real moves nearly instantly. Therefore, with this command:

  • The moves and recruits won't be animated, only combat will be.
  • If there is shroud and you have the "stop when enemy sighted" option activated, any enemy sightings will be ignored nevertheless: this behavior is similar to what happens when you disable "delay shroud updates" after having done a bunch of undoable moves.
  • The following behavior is also being considered (but won't easily be intuitive for the player, and might need to be moved to a separate command): if a unit is selected when Execute All is called, only moves numbered equal or higher as the number of the current unit will be executed. This allows you to quickly execute your last few planned moves while keeping the rest for later.

Committing a move means the "real" action is executed as usual in Wesnoth, and remaining planned actions get validated. Note that you do not lose your other planned actions.

  • The planned action is usually deleted at this point, except if it was a multi-turn move/move-attack; in this case only the part of the path that was executed on this turn gets removed.
Re-ordering

The player will be able to change the ordering of his planned actions.

  • The simplest way will be to cancel the action and to issue a new one, in which case the new order will be added at the end of the queue.
  • I will also provide two commands, "bump up" and "bump down", that move the selected or hovered unit one step up or down in the action queue. Those will need shortcut keys (tentatively 'z' and 'x'), as well as menu elements.

Canceling planned actions

Canceling planned actions will be per-unit (unlike the old undo stack that forces you to undo things in order). By selecting "cancel" from the context menu of a unit or hitting 'C' while it's selected, you'll clear the planned action from that unit.

  • move/attack: the ghost form, arrow and attack indicator just disappear
  • recruit: the "planned recruit" ghost unit will disappear.

You will also be able to cancel the planned action that was last defined if you issue the "cancel" command, without any unit selected.

ZOC display

"Show enemy moves" will now be calculated taking into account planned unit positions, instead of real unit positions.

Toggle "now" and "after execute" positions

To help visualizing the situation in tights spots where planned moves are likely to point to unit current positions, I'm considering implementing a view that removes all arrows (or at least those of valid moves) and shows only the positions of units after all moves are executed. It would be linked to a shortcut key so you can quickly switch back and forth between current <-> future situation.

Planning actions when it's not your turn

The planning system will be available to plan moves, recruits and attacks when it's not your turn. If you have allies, they will see your plans if you have shared them. Design choices will need to be made in the following areas:

  • Do we enable planning mode by default when it's not your turn, and then non-planning mode when your turn starts? If so, a proeminent visual reminder of which mode we're in will be needed to avoid confusing players.
  • How do we deal with the "track moves" option? It should at least be impossible to set or modify a planned move when the camera has been stolen by the "track moves" feature, otherwise you'll end up very frustrated.
  • A solution to both points above could be to always disable planning mode by default (but unfortunately it might prevent people from even knowing the system exists), and disable move tracking whenever planning mode is on, even temporarily such as when you're holding shift to define planned actions.
  • If move tracking is disabled, adding some visual warning that something is going on outside of your sight while you're planning moves would be useful.

Options

  • I will provide a dialog or menu to control who you share your planned moves to, and whose planned moves you display on your map.
  • A "Toggle Planning Mode" option will be provided to invert the behavior of shift-clicking; in planning mode shift-clicking does the real action directly; in normal mode shift-clicking will rather do the planning.

Summary of commands

(Subject to change)

Command Shortcut key
Commit/Execute E
Fast Commit/Execute All Shift+E
Cancel C
Cancel All Shift+C
Direct action (planning mode) / Planned action (normal mode) Shift+Click
Toggle planning mode (invert shift-click behavior) P
Bump action up and down in queue X, Z
Toggle Now/After Execute display Tab

Mockups for various interface elements

Highlight planned path on select or mouseover

A lot of planned paths overlaying each other would quickly get confusing, if you don't have a mean of telling which belongs to which unit. Paths will be highlighted whenever you hover over them or their unit; if a unit is selected its path will always be highlighted. file.php?mode=view&id=39504&sid=351c6863d85dce6d56e131736224b471#.png

Variants and experiments on the numbering system

The "status-ball" display (cute but would pose problems for double and triple digits, and may conflict with the crown symbol):

file.php?mode=view&id=39500#.png

The "overlay" display: file.php?mode=view&id=39503&sid=351c6863d85dce6d56e131736224b471#.png

The double/triple digits "overlay" display of number seems to work ok (three-digit might need to be placed in upper-half of hex to avoid completely hiding middle digit), file.php?id=39520&mode=view#.png

especially with brief flashing of the number on top of a unit when this unit is hovered over or selected. file.php?mode=view&id=39521&sid=bb7ee496abdc777856a391f020f2d084#.png

Alternative "side" display: simply show the number next to units. Less disruptive visually maybe? file.php?mode=view&id=39524&sid=bb7ee496abdc777856a391f020f2d084#.png

Manoeuvering in cramped areas

Let's take the following "real-world" starting situation, from a campaign some of you will recognize: file.php?id=39774&mode=view#.png

With a lot of units close together, the arrow display will get rather cramped. I tried to depict a lot of overlapping moves, to try and figure out how to best help the player in these circumstances. Of course this is an ugly hack job and could look better; also, not all of the elements depicted have to get in.

file.php?id=39793&mode=view#.png

Legend:

  • The hovered over unit and it's highlighted arrow: this is a static picture, but in reality hovering the mouse over the various units would quickly clear up which arrows belongs to which units.
  • Tentative display for a "destination" number (yellow ball with blue number). It may help matching starting and ending positions of units, especially when the ending is where another unit is standing.
  • Tentative display for an invalid move (#4, the archer trying to move on the location of the druid, who is not programmed to move out of the way beforehand): the striped arrow, and triangle instead of a circle behind the blue '4'.

With such a busy screen, even with paths that highlight on unit hover and such niceties, the player might get a bit confused: what's it gonna look like after all moves are executed? One solution would be to let the player hold a key such as Space or Tab, to end up with the following view:

file.php?id=39773&mode=view#.png

This one doesn't convey as much info, but it's much clearer and offends the eye less. There's nothing that prevents the player from planning actions in this mode, either, switching to the "full info" view only occasionally.

  • This is also a good view to see the result of Execute All:
    • The moves are trivial and will probably not trigger an ambush or wml event
    • Therefore after an Execute All from either view, the result will look like this view, except that all the numbers will be gone. (Well technically, the invalid move will still be visible in the "busy" view, since it was impossible to execute.)
  • Practically, Execute All wouldn't be such a good idea; the player would probably commit one or two moves and then attack, or plan two moves and an attack and then Ex. All, which would commit the two moves, do the attack, and then stop.

Engine

Current state of the game engine

The game state is currently synced between clients through the use of replays. As actions (recruits, moves, attacks, etc.) are executed on the current client (i.e., the client of the player who's playing his turn now), the local replay gets augmented with corresponding commands. Those commands are are stored as WML config objects, and have an undo attribute that indicates if they can still be undone, and a sent attribute that indicates if they have been synced over the network.

Periodically, the current client calls turn_info::send_data(). Through a chain of calls, this function locates non-undoable, non-sent commands (with replay::get_data_range()), and transmits them over the network (network::send_data()) after having placed them in a config object under a [turn] tag.

On the receiving end (i.e. all other clients), replay info is detected in turn_info::process_network_data(), and is eventually processed in do_replay_handle(), which actually replays the actions on the remote clients.

Changes to the game engine

For this project, a vector of a new kind of object called planned_action will be maintained on each client. Vectors will all get exchanged between allied clients, so that each ally will end up with a vector of planned_actions per ally in play. A planned_action will either be a WML config, or have methods to serialize/deserialize easily to it, to allow sending over the network.

  • Here I'm using the term vector, but I'll try to stay data-structure-agnostic as much as possible by hiding it under my own interface, so I can for example easily change it to a linked list or a dequeue if it seems desirable.

Current client to allies

On the current client, the player will have an appropriate interface to plan actions, and will be able to commit them as real actions, either one by one in the order of his choice, or all at once, in the order in which they exist in the planned_action vector. A commit means that the planned_action is deleted, and the corresponding real action performed, and then added to the replay as in the current system.

After each commit, whether it's a single one or part of a sequence, it's very possible that other planned moves will not be realizable. Anything could have happened, from the position of a move now being blocked because the last unit that tried to move got ambushed, to a WML event that could change anything it wants. Therefore, each commit is followed by a validity evaluation of all remaining planned_moves (in this vector and others). Detected conflicts will stop the execution of a commit sequence, and they will be displayed to the player in the interface.

The mechanism of calling send_data() periodically will not change, except that the current client will send together (in the same network::send_data()) any updates to the replay, and any updates to the planned_action vector. Here an important distinction will be made between allies and enemies:

  • enemies get sent only updates to the replay
  • allies get sent both updates to the replay and planned_moves

On the receiving end of these updates, clients will use turn_info::process_network_data() to process the incoming info as usual. Updates to the gamestate i.e. replay commands will be applied first, followed by updates (if any) to the vector of planned_actions that corresponds to the sender. Then clients will check all planned_moves in all vectors for conflicts with the updated game state.

The simplest approach for updating remotely the vector of planned_moves would be to re-send it completely whenever there's any change to it. However this wastes network bandwith and processing time, and since planned_moves are designed to be displayed on-screen, it might affect their display speed. The preferred approach will therefore be to implement a simple merge algorithm -- the merge will be very simple and without possibility of conflicts, since each vector will only have one update source. Only changes will be transmitted, such as additions and deletions at specific positions in the vector, as well as planned_actions switching places, and all operations that will become necessary.

Allies to current client

Even if it's not their turn, players will still have access to the interface to plan actions. In addition of being available at the beginning of the next turn, the planned_action vector hence created will periodically get transmitted (network::send_data()) to all allies, including the ally who's currently having his turn.

The processing of those planned_actions will happen in the same way that those originating from the current client: they get merged in the vector of planned_actions corresponding to the sender, checked for validity and displayed accordingly.

Sequence diagram showing the exchange of data

file.php?mode=view&id=39611&sid=1a3b8ffb7bbc1206d1257a5878a78584#.png

ZOC calculations for planned moves

The "show enemy moves" feature will now be calculated from planned unit positions by default, instead of current unit positions. For this I'll need to build my own unit map and calculate ZOCs from there. When several moves are planned for the same spot, only the last one to be programmed will be taken into account; this will have an influence when ZOC-less and normal units are heading for the same hex.

  • Alternatively, we can take into account only the unit with the most powerful ZOC headed for this hex, it might be more intuitive for the player.

Clean up

This is a tentative list of issues resolved, options removed (more KISS) and of areas of the code that will get cleaned up or completely removed as a result of this project.

  • "Delay shroud updates" won't be necessary anymore; this will get rid of the "delay shroud update on start" preference, and of the in-game "delay shroud updates" menu element.
  • The "sighted" WML event will work properly, now that the conflict with delay shroud updates will be gone.
  • The undo stack and related code will be removed, if after gathering feedback on the new interface it is deemed obsolete.

Gameplay considerations

Moved these somewhat lenghty considerations to GSoC-WW_Gameplay_Considerations_Gabba.

Optional/Future developments

Many interesting further developments will be made possible by this project, such as showing the chance-to-kill for a combined attack. See GSoC-WW_Optional_Future_Gabba.

Calendar

  • Note: tasks colored green are done


Start of GSoC: May 24

Before mid-term eval

(8 weeks of work) Implement planned moves as a local (non-networked) feature.

  1. Initial backend work (~1 week)
    • Backend: Design and implement framework for managing planned moves (planned_move class, stl container)
    • Backend: Implement operations in planned_move to add, remove, switch place of planned moves
  2. Interface for adding and removing planned moves (~1.5 week)
    • Backend: Arrow and unit ghosts display framework
    • Backend: Checking of moves for gamestate conflicts
    • Interface: defining planned moves (volutarily creating gamestate conflicts is forbidden)
    • Interface: reordering moves
    • Interface: Add preliminary numbering display
    • Interface: Highlight arrows on hover/selection of their unit
  3. Introduce committing of moves and basic move validation (~1.5 week)
    • Interface: "commit on select" + [optional] commit on hover
    • Interface: "cancel on select" + [optional] cancel on hover
    • Backend: check moves for gamestate conflicts after every commit
    • Interface: Visual warning for gamestate conflicts
  4. Intermediate milestone: (4 weeks in) June 21: all the above tasks must be finished.
  5. Implement "soft conflicts" detection and ZOC display (~1 week)
    • Backend: Add ZOC (ctrl+v) calculations according to planned moves
    • Backend: Detect "soft blocks" i.e. blocking of planned moves by own units/own planned moves
    • Interface: for now, forbid defining moves with "soft blocks"

#Add attack and recruit to the planned actions (~1 week)

    • Interface: display of planned attacks
    • Backend: committing of planned attacks
    • Backend: planning/committing of recruits [optional]
    • Interface: display of planned recruits [optional]
    • Backend: work out interactions with WML events; validate actions after they happen.
  1. Add other useful interface features (~1 week)
    • Backend: toggling of state between planning mode and normal mode
    • Interface: menu/shortcut for "toggle planning mode"
    • Interface: tab-click inversion of behaviour [optional]
    • Interface: "commit next" [optional]
    • Interface: "cancel last"/"cancel all" [optional]
  2. Bugfixing in preparation for mid-term (~1 week)
    • General bugfixing
    • Backend: If appropriate, temporarily disable delay shroud updates code, and test if "sighted" wml events now work properly [optional]

Milestone: (8 weeks in) July 16, Mid-term eval: All the above tasks must be finished. We have a functional reworked interface and planning system for single-player.

After mid-term eval

(3 weeks of work)

  1. Additional interface work (~1 week)
    • Interface: Resolve issues with planning actions when it's not your turn (some issues remain)
    • Interface: allow defining moves on hexes occupied by current units or planned moves [optional]
      • Interface: alternate display to ghosts for multiple moves planned for the same hex [optional]
      • Interface: visual hints for a move heading for an existing unit's location. [optional] (more needs to be done)
    • Interface: Implement alternate arrow-less view on [some key] [optional]
  2. Bugfix and improve the interface (~2 weeks)
    • Make sure all commands are accessible through both menus and shortcut keys


Milestone (no set date), Complete Interface: The planning interface must undergo review by the dev team and be considered solid and complete before any work on the networked part starts.

Add the networked part

This whole section is [optional].

  1. Backend: Implement the merge algorithm for planned_action vectors from other clients
  2. Set up and test transmission and merging of planned_action vector diffs between clients
    • Backend: each client keeps a copy of the planned action vector of every other ally in play
    • Backend: Implement and test continuous syncing mechanism of planned_moves between X number of allies
  3. Interface: Implement team-colored display according to planned move origin
  4. Interactions with undo (if we don't decide to get rid of it)
    • Backend: Keep planned actions around as "undoable" until their corresponding real action is permanent
    • Backend: On undo, revert the appropriate planned action to normal status
    • Interface: make undoable planned actions invisible to their owner but visible to his allies.
  5. Backend: Expand soft conflict detection to include planned_actions received from allies
  6. Add filter to choose who you share your planned_moves to and who you receive them form
    • Backend: filter reception/sending of planned moves
    • Interface: dialogue for filtering planned moves
  7. If the networked part gets done in time, organise a dev tournament with team games to see the system in action on a larger scale.

Milestone: (11 weeks in) August 9, suggested pencils down date: All the above tasks must be finished. We have a polished reworked interface and planning system. If things went exceptionally well, we also have a multiplayer allied planning system.

Final touches

(1 week of work)

  1. Add a section to the Wesnoth manual introducing and explaining the planning system.
  2. Write a short after-action report
  3. Discuss future plans for improving/expanding on the planning system

Milestone: (12 weeks in) August 16, End of GSoC 2010: Documentation tasks must be completed.

This page was last edited on 10 November 2020, at 07:32.