This doc describes a potential menu interface for TW.
Revision history:
2003.10.14 youbastrd started
2003.10.29 youbastrd continuing after a hiatus
2003.11.03 youbastrd testing wacky new commit mailing list... should work now

*************************************************************************
Goals - What do users want to do inside this game? **********************
*************************************************************************

exit the game
see the name of the game
see the version number of the game

set the video mode
  * set resolution, color depth, full-screen
  * set refresh rate (?)
  * set gamma correction
toggle full screen/windowed mode (?)
  * quick toggle in-game, alt-enter (?)

replay demo
start recording demo
  * select file to output to? (just pick an unused one)
  * set maximum size of demo file? (pick a reasonable default size)
  * report to user that a demo has started to record
stop recording demo
  * select file to output to if not done so already
  * report to user that demo has stopped recording, report the filename, report resulting filesize or length?


set the rendering options
  * set star depth
  * set shot relativity (?)
  * toggle interpolation
  * toggle Anti-aliasing
  * toggle AA:non-integer (?)
  * toggle AA:Blend (?)
  * toggle AA:Alpha (?)
set the sound volume
set the music volume

select the number of players on this local machine
set each player's name for use in internet multiplayer
Keyjam
Set Controls for each local player (make keyjam related here)

start a new melee game
join a multiplayer game
  * type in IP address of server to join
set internet connection type
start hosting a multiplayer game
set multiplayer hosting max # of players (currently 2)
see their own IP address (figure it out accurately, even through a firewall?)
set the gametype you're like to play
before a game has started, configure the gametype you'd like to play
  * select the mission (?)
  * set the frag limit, time limit (?)
  * set the min/max fleet size or point value (?)
  * select the playing field/map rotation (?)
  * set the difficulty(?)
  * set the # of bots
  * set the starting points for games like Gob (?)

set the fleet of ships you'd like to use
  * show the list of available ships
  * show the current fleet
  * make the current fleet obvious
  * add a ship from the list of available ships to the fleet
inside the game, as a live player, fire the main gun, special gun, turn left, turn right, accelerate and escape if possible
inside the game, as a live player, select a device to interact with; activate selected device
inside the game, select a team (?)
inside the game, exit to a main menu-lookin thing: close up this game
inside the game, when playing, pause the game; unpause a paused game (single player only?)
Inside a match/round, pick your ship out of your fleet when spawning
inside a match/round, send a chat message
inside a match/round, initiate a vote
inside a match/round, vote for something (change map, reset map, etc) (?)
inside a match/round, kick a player cleanly
inside the game, set the video mode, sound options, toggle full-screen


get help on keys
inside the game, set the view mode on a per-player basis
inside the game, set the view zoom on a per-player basis

set in-game rendering options

*************************************************************************
Style Goals - Stuff that I want to say about this interface  ************
*************************************************************************

This interface should be have an arcade feel to it.  Each options should be accesible by both mouse and keyboard via the cursor keys.  In fact, it should be possible to use the entire interface via joystick.

The interface should be very fast and responsive at all times.  Anything which requires any substantial amount of load time should be done concurrently (ie in another thread) and not slow down the interface.

The idea is to make it like an arcade-style interface, or like a console-type game.  Local players can simply hit their "Start" button on their controller to join in a game.  In some gametypes, that means the rules of the game should reflect this possibility, ie if we know that a player may join the game late, make the victory limit a fraglimit or timelimit, rather than to eliminate every player's fleet; a late joiner will have a larger fleet when joining, and hence a competetive advantage.  Or simply make the late player wait until the next round to join with his complete fleet.

Also, as much as possible, the screens should make use of OO-inheritance to re-use code.  Some screens may be reused in unexpected ways.  For example, when joining the game, a user may have to select a fleet, or even edit their fleet just before joining the game.  So the fleet editor should be able to be shown as the only "panel" on the screen, or as one of a few panels on the screen at once.  Say there's a player playing solo, and a local player presses "Start" to join the game.  The screen changes to 2-person split view, and the new player has his fleet editor show up in his view, which the first player keeps playing in her view.  When the new player is all set up, the view may change to both on the screen at once, depending on how they want things set up.


*************************************************************************
Screens - Stuff the user sees inside the game ***************************
*************************************************************************

Legend:

........           Empty space

...........        Some kind of non-interactive image or text
.. image ..
...........

...............    A list of objects.  Normally, this allows for single
.. Object1   ..   or multiple selection, and double-clicking or pressing 
.. Object2   ..   enter with the focus does something interesting with 
.. Object3   ..   the current selection.  
..     (list)..
...............

[button]         Can either be moved to by the cursor keys, or clicked on with mouse.  Activating this button makes the "activate" sound from sc2, selecting it with the cursor keys makes the "select" sound from sc2.  (quieter but similar sound for mouseover event?)  Keyboard shortcuts are drawn in different a colour, example if the button text was "Button", "B" would be coloured differently to indicate that it is a keyboard shortcut.  When a button has the focus, it it drawn differently, with a coloured or "throbbing" border.

[submenu button>   A control similar in functionality to button that, when it has the focus, triggers a popup menu.  Its selected value is shown to the right of the button when it does not have the focus.  This menu appears when the button has the focus or has the mouse over it.  Pressing the button changes the focus to an previous selected entry in the menu.  Similar to the windows start menu, except that the selected value appears next to the control when the menu is not expanded.  The current expanded menu is drawn overtop of the other displayed values, and everything else for that matter.  The button which has the focus on starting a page normally does not expand (so a user can see the selected values).  These menus should appear very very quickly.

Example:
..............................................................................
...[  Choose your favorite pet:   >.. Fish         ...........................
..............................................................................
Focus is elsewhere, no highlighting

..............................................................................
...[**Choose your favorite pet:***>..[None        ]...........................
.....................................[Cats        ]...........................
.....................................[Dogs        ]...........................
.....................................[Fish--------]...........................
..............................................................................
"Choose your favorite pet:" gets focus or mouseover.  Button gets highlighted, menu expands, current selected value is highlighted within the menu.  The button is shown as colour throbbing or some other effect to show that it has the focus.

..............................................................................
...[--Choose your favorite pet:--->..[None        ]...........................
.....................................[Cats        ]...........................
.....................................[Dogs        ]...........................
.....................................[Fish********]...........................
..............................................................................
User "Fish" presses right cursor button, or enter; or moves mouse to the menu.  Button loses focus, and focus stays with the user's keyboard or mouse input within the menu.  Pressing enter selects the value and returns focus to the button.  Pressing left returns the focus to the button, but undoes the choice made by the user.  

This is so the user can easily and quickly explore menus without potentially screwing things up.  The problem comes from the fact the UP/DOWN means two things: move through a bunch of buttons which are likely laid out vertically, and selecting between each of the values in a vertical menu.  By pressing enter, the user ensures the value is selected.

An optional selection can take place by focussing on the button, and pressing the "cycle forward/backward through the list of devices" keys.  















Section: Title Page **********************************************************
Goals: Show title of game, exit game, link to all functions within the game, show version number
Links to:
Melee
Host Multiplayer
Replay Demo
Options
Exit Game

Layout:
..............................................................................
......................................................                  ......
......................................................     LOGO /       ......
......................................................       title of   ......
............................... Main Menu      .......         game     ......
..............................................................................
..............................[Start Melee     ]..............................
..............................[Join Multiplayer]..............................
..............................[Host Multiplayer]..............................
..............................[Replay Demo     ]..............................
..............................[Options         ]..............................
..............................[Exit Game       ]..............................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)          .. Version# ..

Background has a cool looking spacey scene, perhaps a planet, a nebula or something else that looks colourful and pretty which is animated, and maybe a spaceship occasionally zooms by.  Maybe a distant battle has some flashes of light with quiet booms and distant ships flying around.  

Keyboard shortcuts:
ESC==Exit Game



Section:  Melee **********************************************************
Goals: Configure and start a melee game, link to everything needed to configure a melee game.
* configure maps 
* select gametype

Links to:
Start Melee Game
Configure Gametype
Configure Maps

Layout:
..............................................................................
............................. Start Melee ....................................
..............................................................................
.....[Start Playing!           ]..............................................
.....[Pick Gametype            >.. Classic Melee                    ..........
.....[Configure Gametype...    ]..............................................
.....[Pick maps...             ]..............................................
.....[Confgure local players...]..............................................
.....[Host multiplayer         >.. No (local players only)          ..........
.....[Configure Multiplayer... ]..............................................
..............................................................................
..............................................................................
.....[Back                   ]................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

"Start Playing!" is selected when starting this screen.

"Start Playing!" starts the game with the current settings.

"Pick Gametype" Menu:
   * one entry for each registered gametype.  
Selecting one of these gametypes does the following:
   *  Set the selection of maps to the most recent list of maps for that gametype (there exists a reasonable default selection for each gametype).   

"Configure Gametype..." opens up the configure gametype screen which is relevant to the gametype selected.  There should be such screen for each gametype, quite probably making use of inheritance to make coding easier.

"Pick Maps..." opens up a screen which has a listing of the available maps for a given gametype.

"Confgure local players..." opens up a screen that shows the local (human) players and their involvement in the game.  The screen may be different depending on the gametype.  For example, a game without teams may just have the players show up, or a game with teams may ask the players to pick their teams here.  

"Host multiplayer" menu:
   * No (local players only)
   * Yes (LAN and Internet players)

"Configure Multiplayer.." opens up Configure Multiplayer section

ESC goes back to previous menu screen

Notes:

/*
.....[Set number of bots       >.. 1                       ...................
.....[Set fleet limit          >.. 100 Small               ...................
*/



Section:  Configure Gametype  **********************************************
Goals: Configures the gametype.  This is a superclass to be subclassed by something to configure a specific gametype.  For example, if this is called ConfigureGameTypePanel, a sub-class to configure GOB might be  ConfigureGOBPanel.

Links to:

Layout:
..............................................................................
............................ Configure Gametype ..............................
..............................................................................
.....[Accept         ]........................................................
.....[Cancel         ]........................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

ESC goes back to previous


Section: Pick Maps **********************************************************
Goals: Manipulate a list of maps which should be relevant for the selected gametype.  Note the following:
   * each map for the current gametype should make sense
   * the order of maps is to be preserved and presented as meaningful
Links to:

Layout:
..............................................................................
.............................. Pick Maps .....................................
..............................................................................
.....[Add map               >................. Single planet                ..
.....[Add All Available Maps]................. Asteroid field               ..
.....[Remove Map            ]................. Star System                  ..
.....[Remove All Maps       ].................                              ..
.....[Reorder Maps          ].................                              ..
..............................................                              ..
.....[Accept                ].................                              ..
.....[Cancel                ].................                              ..
..............................................                              ..
..............................................                              ..
..............................................                              ..
..............................................                  (map list)  ..
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

When starting this screen, the map list is populated with the most recent selection of maps for the given gametype.  A reasonable default selection is available for each gametype.  

"Add map" menu:
   * one entry for each map which is relevant to the gametype.  Picking one of these will add it to the end of the map list
"Add All Available Maps"
   * adds one of each available map to the map list
"Remove Map" changes focus to the map list, in "remove maps mode."
"Remove All Maps" removes all the maps from the map list.
"Reorder Maps" changes focus to the map list in "reorder maps mode."
(map list) is a list of the chosen maps.  Multiple selections are allowed.  The behaviour of this thing is like so:
   * by default, the list is in "remove maps mode"
   * in "remove maps mode", double clicking or pressing enter with the focus will remove the selected maps.
   * in "reorder maps mode," pressing enter while selecting item(s) will place an asterisk or other mark next to the item(s).  Any other movements within the list will show an arrow next to the current cursor position to indicate an insertion point.  Pressing enter again will move the marked maps to the current cursor position.  
   * mouse dragging moves maps from one position to another.

ESC goes back to previous

Notes:
   * Can't set things like the number of asteroids anywhere...?

Section: Join Mulitplayer (current) *****************************************
Goals: Joins a multiplayer game at a specific IP address
Links to: 

Layout:
..............................................................................
.......................... Join Multiplayer ..................................
..............................................................................
......[Join                ]..................................................
......[Specify Address     ].. 127.0.0.1 (text field)     ....................
......[Recent Addresses    >.. 127.0.0.1                  ....................
......[Port                ].. 15515 (text field)         ....................
......[Accept              ]..................................................
......[Cancel              ]..................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

Activating "Join" attempts to join the game at the specified address.

Activating "Specify IP Address" changes focus to a text field to the right.  As the user types, a list of previously entered addresses is shown in a list below the text field.  Only those that match what the user has typed should appear.  The user can use the up/down keys to move down and within this list to select an address.  Any new address the user types in here will be added to the list of recent addresses.  (for use in this popup list and the one for "recent addresses").  Specifying a text address will perform a DNS lookup when it's time to connect.  As much as possible, show the server address in a human-readable format.

Pressing enter while the address text field has focus changes the focus to the "Specify Address" button.

Activating "Recent addresses" pops up a menu with the recent addresses in it.  Picking one sets the "Specify address" and "Port" text field.
  * one entry for each of the last 20 (or whatever) entries.  Displays as a human-readable format, but with the port at the end seperated by a colon (ie myserver.com:15515 rather than 12.34.56.78:15515)

Activating "Port" changes focus to the port text field.  pressing enter on that field changes focus to the port button.

ESC goes back to previous



Section: Join Mulitplayer (future) *****************************************
Goals: shows a list of available multiplayer games from the internet or LAN, configures filters which show a subset of all available games.
Links to:
Layout:
TODO
ESC goes back to previous


Section: Confgure Local Players ********************************************
Goals: Declares which players are available for a given instance of a game; player availability and options may vary by the selected gametype. Some options the should appear for some gametypes:
   * declare the player as playing
   * for each player, set the starting team
   * for each player, set his controls
   * for each player, set his starting fleet
Links to:

Layout:
..............................................................................
.......................... Configure Local Players ...........................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

ESC goes back to previous


Section:   **********************************************************
Goals: 
Links to:

Layout:
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

ESC goes back to previous


Section:   **********************************************************
Goals: 
Links to:

Layout:
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

ESC goes back to previous


Section:   **********************************************************
Goals: 
Links to:

Layout:
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

ESC goes back to previous


Section:   **********************************************************
Goals: 
Links to:

Layout:
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
. Help Text (changes to reflect the current selection)                      ..

ESC goes back to previous


