====================================================
Vector Mame Menu - a Menu for Vector Mame/ZVG owners
====================================================

Contents:
=========

1.  Introduction

2.  Installation
       2.1 The quick way for the impatient
       2.2 Customised Install
       2.3 Upgrading
       
3.  Using VMMenu

4.  Games list configuration
       4.1 Overview
       4.2 Generating VMMenu.ini - the games list
       4.3 Games list customisation

5.  VMMenu configuration
       5.1 Interface settings
       5.2 Controller options
       5.3 keys section
       5.4 Colour settings

6.  VMM.bat advanced usage

7.  Files in archive

8.  Version history

9.  Thanks

10. To do...



 ===================
== 1. Introduction ==
 ===================
 
 
This program provides a launch platform for the vector games supported by mame, running on a real vector monitor driven by a Zektor "ZVG" Vector Generator.

The menu has been written from scratch, and builds on the features provided by Ian Boffin's original vector menu.

Features include:

* Customisable manufacturer lists
* Customisable games lists
* Colour and B&W monitor support
* Full screen rotation
* Re-definable control keys
* User defined colour scheme

VMMenu requires a pure DOS environment. Setting this up is beyond the scope of this document, so it is assumed you already have a working configuration with the appropriate drivers for your system (sound card etc).

You should also have a copy of DOS Mame supporting the ZVG. A customised build of version 0.96 supporting only the vector games can be downloaded from the Zektor website.

The last version of DosMame was 0.106, after which support was dropped.



 ===================
== 2. Installation ==
 ===================


2.1 The quick way for the impatient
===================================

Copy the following to your vectormame directory:

vmmenu.exe        The menu program
vmmenu.ini        The games list
vmm.bat           Batch file mame launcher
makeini.exe       Creates a default vmmenu.ini from your mame version
keycode.exe       Determines scan code of key pressed
vmm-read.txt      This file

Edit vmm.bat to reflect the name of your mame exe (eg dvmame.exe, vmame.exe, dmame.exe), sound card settings and so on.

Note the following useful mame.cfg options which should be set if your version supports them:

zvg_artwork = yes
zvg_overlay = yes
zvg_menu = yes[1]

and also:

skip_disclaimer = yes
skip_gameinfo = yes
skip_warnings = yes

Launch vmmenu.exe (tip: add it to the end of your autoexec.bat file) and you should be good to go.

[1] Early versions of mame with ZVG support did not support the zvg_menu option. This resulted in Mame shutting down the ZVG on exit before returning control to the menu, which was then unable to display any vectors as the ZVG was effectively no longer present.

The zvg_menu=yes option was added to prevent Mame from closing the ZVG, hence the menu still functions when control is returned.

From VMMenu 1.2, there is a configuration option included called  "reopenzvg" which will automatically re-open the ZVG on return from MAME enabling the use of Mame versions not supporting the zvg_menu option. Please see later in the document for more details.


2.2 Customised Install
======================

Copy the files as above to your vector mame directory.

Grab the latest version of DOS mame you can find. I believe this is a dmame.exe v0.106 but I could not find it anywhere. Google for mame0100b_dos.zip and you'll find version 0.100. Whilst this is not compiled for vector games only, it will still run them all but is slower to start up than an optimised vector-only version.

Edit vmm.bat to reflect the name of your mame exe (eg dvmame.exe, vmame.exe, dmame.exe), and soundcard etc.

Read the makeini section of this document, and generate a vmmenu.ini file, or use the included one as a template. Tweak this as required to suit your needs and setup.

Note the following useful mame.cfg options which should be set if your version supports them:

zvg_artwork = yes
zvg_overlay = yes
zvg_menu = yes [see note 1 above]

and also:

skip_disclaimer = yes
skip_gameinfo = yes
skip_warnings = yes

Launch vmmenu.exe to begin. Add it to the end of your autoexec file for automatic execution.


2.3 Upgrading
=============

Upgrading from a previous version is usually as simple as replacing the VMMenu.exe with the new copy.
Sometimes the options in the config file are changed. It is advisable to make a copy of your existing VMMenu.cfg file and let the new version of VMMenu.exe create a new one in the current format. You can then paste in any customised settings into the new file.


 ===================
== 3. Using VMMenu ==
 ===================

Note: the control keys are fully customisable - the description below relates to the default settings which have been defined with an Asteroids type control panel in mind and are mapped to the default "Mame" keys, i.e.

Control Panel        Key
---------------------------------
Rotate Left          Cursor Left
Rotate Right         Cursor Right
Hyperspace           Space Bar
Thrust               Left Alt
Fire                 Left Control
1P Start             1
2P Start             2

By default, the manufacturer menu will have focus. This is the section at the top of the screen listing the manufacturer names, with the currently active manufacturer in the centre. Pressing Left or Right will change to the previous or next manufacturer. These will cycle in a circular loop.

Note: Manufacturers called Atari, Cinematronics and Sega will get a nice logo displayed on screen, courtesy of much hard work by Ian Boffin. Bear this in mind if you rename manufacturers in the ini file (see the configuration options later in this document). Other manufacturer names are just displayed as text, though other logos may well be added later.

Press Space to change to the games menu, or back to the manufacturer menu again. This key works in a toggle fashion, always changing you from one menu to the other.

New for v1.2: If you have a joystick or buttons forming a cursor layout, you may wish to enable a feature called "SmartMenu" which will let you simply navigate from the manufacturer menu to the games menu by moving the stick/pressing the button in the appropriate direction.

When in the games list, the Left and Right keys will now cycle through the list of games. The selected game will appear in Bright White (customisable) to make it stand out on B&W monitors.

If clones of the highlighted game are available, an arrow will be printed on either side of the game name. Press Ctrl and Alt (Thrust/Fire) to cycle forward and backward through the available clones.

Once the desired game/clone is selected, press 1 player start to run the game in Mame. This launches vmm.bat with the game name as a command line argument. You can set other mame options in vmm.bat if required, or just set them in mame.cfg. See later for advanced tweaking of the vmm.bat file to enable unique settings to be passed to specific games.

To prevent screen burn, a screensaver is included which will kick in after 30 seconds of inactivity.

To exit the menu, press the Escape key (IPAC owners: hold 1P start and press 2P start). You will be asked if you really want to exit, just in case the escape sequence from Mame made it through to the menu.

Pressing escape again will exit to DOS, whilst pressing any other control will cancel the quit sequence and bring you back to the menu. The escape screen will also time out after 30 seconds and take you back to the menu automatically.



 ===============================
== 4. Games list configuration ==
 ===============================


4.1 Overview
============

One of the key features of VMMenu is that you are able to customise the manufacturer and games lists. This is controlled by the content of the file named vmmenu.ini.

A utility called makeini.exe is provided which will assist in the creation of this file, based on the games supported by your version of Mame.


4.2 Generating VMMenu.ini - the games list
==========================================

First, we need to get mame to tell us what games it supports. This can be done by telling it to list the supported games in xml format, which we will capture to a file called mame.xml:

mame.exe -listxml > mame.xml

substitute mame.exe with the name of your variant, if necessary (dvmame.exe, dmame.exe etc)

** Warning - the resulting xml file may be very large if you are using a generic version of mame rather than one which has only the vector games (25Mb or so). Ensure you have enough space on your drive if you are running your setup from a flash card or similar **

We can now run makeini.exe, which will look for the file mame.xml in the current directory and pull out all the vector titles. By default it will output to the screen, so we will direct this output into the file vmmenu.ini:

makeini.exe > vmmenu.ini

We will now have a file, vmmenu.ini, containing only the vector game details.
The ini file consists of records of 4 fields in the following format:

manufacturer|description|parent|clone

Where:

manufacturer = name of manufacturer
description  = description of game
parent       = name of the parent game in mame
clone        = name of the mame variant (or parent name again for non clones)

When launched, VMMenu will parse this file and create a manufacturer item of each unique manufacturer found, and a corresponding games list for each one. If a clone of an already added game by the same manufacturer is found, it is added as a clone of that game rather than as a separate item.


4.3 Games list customisation
============================

When run against the raw mame.xml file, the resultant ini file consists of many manufacturers with just a single game, and there are some anomalies.

e.g. in mame .100, The Empire Strikes Back entry appears as:
Atari Games|The Empire Strikes Back|esb|esb

This would cause the creation of a separate manufacturer "Atari Games" containing the single game "The Empire Strikes Back", as all the other Atari games just have the manufacturer name "Atari".

We can tweak the ini file to tidy this up. Changing the ESB entry to:

Atari|The Empire Strikes Back|esb|esb
will bring ESB into the correct menu along with the rest of the Atari games.

Note: Manufacturers and games are added in the order they appear in the ini file, no sorting takes place. If you wish to rearrange the order of things, move the entries in the ini file around accordingly.

Other edits you may wish to make:

If you don't want a "hack" manufacturer, you could change any entries to the manufacturer of the original game. e.g. 

changing:
hack|Major Havoc (Return to Vax)|mhavoc|mhavocrv

to:

Atari|Major Havoc (Return to Vax)|mhavoc|mhavocrv

Will move Major Havoc (Return to Vax) to the "Atari" menu, as a clone of Major Havoc.

Similarly, changing:
Sidam|Asterock|asteroid|asterock
VGG|Meteorites|asteroid|meteorts

To:
Atari|Asterock|asteroid|asterock
Atari|Meteorites|asteroid|meteorts

Would cause Asterock and Meteorites to appear as clones of Asteroids under the "Atari" menu, and prevent the creation of 2 different manufacturers containing only one game.

Alternatively, you may wish to group all the hacks and one-offs under an "other" manufacturer menu or similar, in which case just change the manufacturer name appropriately for all these games.

You can also list a game more than once - how about a manufacturer called Favourites? 

If you don't want a game to appear in the list, simply delete it from the ini file, or comment it out by placing a # in column 1. You may wish to do this for games which are not suitable for your control set up, games which do not work correctly, games for which you do not have roms, or for games that you simply don't like!

Customise the ini file suit to your needs, but ensure you retain the correct format, or vmmenu.exe may bomb out. You can also change the description (field 2) but do not make this longer than 50 characters. Manufacturer names have a 20 character limit.

** Do not change the 3rd of 4th fields as these are used to determine the parent/clone relationship, and the name of the game to launch from mame.

A sample vmmenu.ini file generated from Mame .100 is included which has the following customisations:

* All Atari games collected together (as Atari)
* All Sega/Gremlin games collected together (as Sega)
* All Cinematronics/Vectorbeam games collected together (as Cinematronics)
* All remaining games collected together (as Other)

You can use this file to get things up and running quickly if you wish, or as a template for your own edits.



 ===========================
== 5. VMMenu configuration ==
 ===========================

From VMMenu 1.1, various settings are read from a configuration file - vmmenu.cfg - which you can modify to customise how the menu looks and operates. These settings fall under 4 groups:

* Interface configuration options
* Controller options
* Key bindings
* Colour settings

The vmmenu.cfg file will be created by the menu if it does not already exist, and populated with enough default values to get you going.

The cfg file is re-written on exit and any comments are removed. 

Here is more detail on each of the groups of settings:


5.1 Interface settings
======================

These are listed in the vmmenu.cfg file under the [interface] section

The available options are:


rotation=n  (n is an integer from 0 to 3)

rotation=0  : no rotation
rotation=1  : screen rotated 90 clockwise
rotation=2  : screen rotated through 180
rotation=3  : screen rotated 270 clockwise

This option is for use in cabinets with a vertically mounted monitor. Setting a rotation option other than 0 will rotate the entire display through the selected angle.


stars=n     (n is 0 or 1, or no/yes)

stars=0     : starfield does not appear on the main interface screen
stars=1     : starfield appears on all screens


caps=n      (n is 0 or 1, or no/yes)

caps=0      : Games list text appears in upper and lower case
caps=1      : Games list appears in upper case only


showpnm=n   (n is 0 or 1, or no/yes)

showpnm=0   : Do not show previous and next manufacturer names
showpnm=1   : Do show them

Once I had rotation working, I didn't like the appearance of the previous and next manufacturers on screen when vertical so much as in horizontal mode. It kinda loses symmetry more and didn't look right... so I put in an option to turn off that part of the display.


smartmenu=n  (n is 0 or 1, or no/yes)

smartmenu=1  : enable smartmenu navigation
smartmenu=0  : disable smartmenu navigation

If you have a joystick or suitable control panel, you can define the navigation controls such that left/right move through the manufacturers and clones, and up/down navigate the games list. With smartmenu enabled, you can move down to the games list directly from the manufacturer list without having to press the menu toggle button. You will lose the functionality of going directly from the top of the games list to the bottom, and vice versa, as the manufacturer menu will be selected when you navigate off the end of the games list.


reopenzvg=n   (n is 0 or 1, or no/yes)

reopenzvg=0   : Don't reopen the ZVG on return from Mame - Mame won't close it
reopenzvg=1   : Do reopen the ZVG on return from Mame in case it was closed.

This option works around older versions of Mame which do not have the zvg_menu option. By default, Mame will close the ZVG when it exits and this prevents the menu from being able to display any more vectors!

Later version of Mame supported the "zvg_menu" option which prevented Mame from closing the ZVG, but older versions had no support for this feature.

reopenzvg will tell the menu that it needs to reopen the zvg interface when Mame returns control. Setting this means that you don't need to set zvg_menu=1 in your Mame.cfg file, and older Mame version will work with the menu as expected.


5.2 Controller options
======================

Controller options hold the settings for an optical device on your control panel if you have one (Spinners or Trackballs). The settings come under the heading [controls].

spinnertype=n	(n is 0-2)

spinnertype=0	: Don't use an optical controller (default)
spinnertype=1	: Use 1-axis controller (spinner)
spinnertype=2	: Use 2-axis controller (Trackball/Mouse)

For the Tempest, Tac/Scan and Quantum cabs - if you've installed a DOS mouse driver (I used the free "CuteMouse" driver), you can use the spinner/trackball to navigate the menus. Enabling this option will cause the following options to be written to the config file on exit, which can be used to fine-tune the controller:


swapaxes=n	(n is 0 or 1, or no/yes)

swapaxes=0	: X axis is left/right, Y axis is up/down
swapaxes=1	: X axis is up/down, Y axis is left/right

Depending on how your controller is wired up, you can reverse the axes with this setting. This can be useful for spinners which could be wired to use either the X- or Y-axis.


spinsens=n	(n is 1 to 100, default = 30)

Sensitivity - the value specified here determines how far the control needs to be moved in order to register a move


spinsamp=n	(n is 1 to 20, default = 6)

This is the sample rate - the controller will be read every "n" frames. Lower values increase sensitivity.


reversexaxis=n	(n is 0 or 1, default = 0) and
reverseyaxis=n	(n is 0 or 1, default = 0)

These two options can be used to reverse the direction of movement of either axis of the controller to reflect how it is wired up.

Note that the Menu will apply the axis swap before an axis reverse. Bear this in mind if you have both options set!


5.3 keys section
================

The key bindings are listed in the [keys] section of the vmmenu.cfg file. The name of the control is listed along with the keycode of the key which you wish to assign to that function. Keycodes can be obtained by use of the keycode.exe program provided.

The windows keys, R-Ctrl and R-Alt aren't recognised as independent keypresses - sorry. I don't think this is really a problem, but if anybody wants to point me to a nice, small keyboard handler for DJGPP that also supports modifiers, please do so! (without installing the overheads of Allegro...)

You can only define one key for a particular setting, but you can use the same key for more than one function - just make sure they don't conflict.

Valid keynames are:

k_rotate    : the key to rotate the screen cw by 90 from the current orientation
k_stars     : the key to toggle starfield on or off
k_showpnm   : the key to toggle display of previous and next manufacturers
k_caps      : the key to toggle between all caps or mixed upper and lower case

Tip: If you don't have entries for any of these four settings, you won't be able to change that setting via the keyboard - only via the value in the config file. This could be useful if you want to prevent users from being able to change things.

k_togglemenu: the key to toggle between the manufacturer menu and the games list
k_quit      : the keypress to quit the menu

* Remember, if you don't set a valid quit key, you won't be able to nicely quit to DOS.

When in the manufacturer menu:

k_prevman   : the key to go to the previous manufacturer
k_nextman   : the key to go to the next manufacturer

When in the games list:

k_prevgame  : previous game in list
k_nextgame  : next game in list
k_prevclone : previous clone of selected game
k_nextclone : next clone of selected game
k_start     : play the selected game/clone

You could define the same key for, say, previous manufacturer and previous clone. Just be careful not to have conflicting settings, such as using the same key for more than one function in the same menu. The program won't check the sanity of your configuration!

If different keys are defined for k_prevman and k_prevgame, and for k_nextman and k_nextgame, then you can enable "smartmenu". This is useful (and gives more intuitive navigation) for panels with a joystick or keys arranged in a cursor pattern.


5.4 Colour settings
===================

Now, the thing to bear in mind is that the VMMenu was developed solely on a B&W monitor. Originally I used a Vectrex, and later an Asteroids Deluxe Cabaret.

Colour was added as a bit of an afterthought and has not been revisited - after all, I'd no idea how it looked. The result of this is that the colour code is pretty simplistic, and perhaps the default scheme is not to your (or perhaps even my!) taste. The code could do with an overhaul to make it more flexible, but in the meantime it's quite easy to let you tweak the current values which should suffice..

The menu support 7 colours - each 1-bit combination of the red, green and blue components:

Value    Colour      RGB
------------------------
0        red         100
1        magenta     101
2        cyan        011
3        blue        001
4        yellow      110
5        green       010
6        white       111

The R, G and B components are determined, and each is multiplied by the intensity value. Yes, all by the same value - as I said, it's pretty simplistic. Maybe I'll revisit this another day, but whilst using a B&W monitor it's not a priority for me.

Intensity values are in the range 0-31 (I only used 0-25, but I think it's 5-bit)

Colour configuration is listed under the [colours] section of the vmmenu.cfg file. Note the British English spelling.

Tip: if you want to reset the colours to the defaults, delete the entire [colours] section (leaving the heading [colours] in place) and the original values will be re-written when you next exit the menu.

Each item on screen has an associated colour and intensity. These are denoted in the vmmenu.cfg file by a prefix, either
c_(item)    for the colour of (item), or
i_(item)    for the intensity of (item)

The available (items) which you can tweak are:

gamelist  : the colour of the games list
selgame   : the colour of the selected game
selman    : the selected manufacturer, when in the manufacturer menu
man       : the manufacturer name when in the games list.
pnman     : the colour of prev and next manufacturers text
arrow     : the colour of the arrows to either side of the selected manufacturer name

The colour values range from 0-6, as per the table above. You can also specify the colours by the names listed in the table.
The intensities range from 1-31 (I only used a few values: 5=dim, 15=normal, 25=bright).

So, for example, you'll see some default values are initially written to the file, such as:
c_gamelist	=	green
i_gamelist	=	15

Which indicates the gameslist should be green (colour 5) and intensity 15 (normal brightness)

Just edit the values to suit and create your own look and feel.
Use values 0-6 for colours, or the name of the colour as listed above.
Use 0-31 for the intensity values.



 =============================
== 6. VMM.BAT - advanced use ==
 =============================
 
Got a game needing a specific Mame command line argument?
Or a game which works best under a different version of vector Mame?

You can relatively easily accommodate such tweaks in the VMM.BAT file.

The name of the game is passed to the batch file, so we can do stuff like the following example, which runs space fury with a different version of Mame, and Sundance and Barrier with screen rotation options:


:: new VMM.bat file

:: the name of the game is passed as %1

if %1 == spacfury GOTO spacfury
if %1 == sundance GOTO flipxy
if %1 == barrier GOTO flipxy

:: General settings for most games
dmame %1 -zvg 2 -r 640x480 -vesa vesa1 -frameskip 0 -nostretch -soundcard 1
GOTO end

:: Run Space Fury with a different version of mame
:spacfury

:: switch to older mame folder se we can preserve a different mame.cfg
cd \oldmame
oldmame.exe %1 -zvg 2 -r 640x480 -vesa vesa1 -frameskip 0 -nostretch -soundcard 1
:: go back to standard vmame folder
cd \vmame

GOTO end

:: Run sundance and barrier with x- and y-axes flipped
:flipxy
dmame %1 -zvg 2 -r 640x480 -vesa vesa1 -frameskip 0 -nostretch -soundcard 1 -flipx -flipy

:end

Tip: If using different versions of Mame, it is recommended to run them from different directories, as in the example above. The Mame.cfg file changes from release to release, and you may find some versions write incompatible settings which break other versions if you try to share a single mame.cfg file.



 =======================
== 7. Files in archive ==
 =======================
 
The downloaded archive should contain the following files:

vmmenu.exe        The menu program
vmmenu.ini        Sample games list
vmm.bat           Batch file mame launcher
makeini.exe       Creates a default vmmenu.ini from your mame version
keycode.exe       Display scan codes for pressed keys
vmm-read.txt      This file



 =============
== 8. Thanks ==
 =============

Ian Boffin for the original VM_MENU, and for use of his vector co-ordinate logos.
The Zektor team for making the ZVG and letting us play emulated vector games on a proper monitor
The Mame team and all contributors, for emulating all these games for us.
All the original Vector game manufacturers for producing the games in the first place.



 ==============
== 9. History ==
 ==============
 
Dec 2009
========

Original version released to a few testers. This was pretty much the same functionally as v1.0 but some core routines were re-written prior to release. I was pretty happy with how it worked so shelved development.

Feb 24th 2011
=============

Poked by Dan Pearson, I picked up the code again to determine why it crashed on his system (this turned out to be unrelated to the menu ;)
This led to the release of...

v1.0:

* Customisable lists
* Screen saver
* B&W highlighting


March 1st 2011
==============

v1.1:

* Full screen rotation!
* Options are now read from a configuration file
* Re-definable control keys
* Various tweakable interface options (upper-case menus, stars etc.)


Mar 14th 2011
=============

Happy 30th birthday, Sinclair ZX81. My first introduction to computing and the platform I learnt to program on. I have no doubt that I would not be coding this today had I not got one of these for xmas all those years ago.

v1.2:

* Re-definable colours (hoping this will help with Cinematronics monitors)
* More interface options - reopenzvg, smartmenu navigation
* Documentation consolidated into this single file
* Spinner and trackball/mouse support
* Start button LEDs used, if connected (suggested by Barry Shilmover)
* Return to menu message on screensaver (suggested by Barry Shilmover)



 ==========================
== 10. To do...  possibly ==
 ==========================
 
Cinematronics monitor support (2 level brightness)
More manufacturer logos
... anything else that comes to mind.




VMMenu
(c) Chad Gray, Dec '09-Mar '11

Thanks for playing :)

