ParaJVE User Guide

Parabellum's Java Vectrex Emulator, version 0.7.0

- Launching ParaJVE
  - Command line parameters
  - Alternate Launching methods
    - Direct execution of an external ROM
    - Executing an external ROM binary
    - Executing an external ROM source
    - Reloading or ReAssembling a loaded ROM
  - Skipping the game selection dialog
- Emulated Peripherals
  - Vectrex Joystick Emulation
  - Lightpen Emulation
  - PS/2 Keyboard adapter Emulation
  - VecVoice Emulation
- Miscellaneous
  - Optimizing the emulator's window size
  - Saving and Loading the emulator state
  - Selecting a different Glow Shader profile
  - Taking a snapshot
  - Checking for new releases
  - Browsing the ParaJVE blog
- Troubleshooting & Known Bugs
  - The emulator display is not bright enough
  - The colors on the transparent areas of the overlays are barely visible
  - The emulator doesn't seem to react to the keyboard hits
  - The emulator runs too slowly on my computer
  - The emulator's window is all black or empty on Windows Vista

Launching

ParaJVE comes with a Graphical User Interface that makes it easy to select the game to be ran ; this is usually the preferred way to start a gaming session. Some users, however, may have more specific needs (homebrew developers, or third party front-end users, for instance), that's why ParaJVE provides several different ways to tweak its launching. This section describes the different options available.

Command line parameters and switches

The emulator now supports a larger set of command line parameters. They can be added at the end of the script line invoking the java runtime (by editing `ParaJVE.bat` on windows, or `ParaJVE` on other platforms). Here is the list of supported parameters and switches :

Parameter | Value | Description
--- | --- | ---
    -Game=...
    SELECTED
    <Game-ID>
    <Path>
| This optional parameter is used to bypass the game selector dialog. When it is present, ParaJVE will automatically load the specified game without opening the game selector dialog. The value can take one of the three following forms : -game=SELECTED to load the game that was last executed by ParaJVE. -game=< Game ID > to load a specific game. Here, < Game ID > is the ID of the game ROM to be executed. (The available game IDs can be found in the configuration file). -game=< Path > to load a specific ROM that's not included in ParaJVE. < Path > is the path to the ROM file to be used (either an absolute path, or relative to ParaJVE main folder). This path handling as been added in version `0.6.0`.
    -Config=...
    <Path>
| An optional parameter that instructs ParaJVE to work with a specific configuration file, instead of the defaut one. If this parameter is used, the configuration will be loaded from the specified file, and any change will be saved into the same file. The default configuration file is "`data/configuration.xml`"
    -Fullscreen=...
    TRUE
    FALSE
| When this parameter is specified, it forces the emulation renderer to use the fullscreen mode (TRUE) or the windowed mode (FALSE), no matter what was the fullscreen state when the emulator was last terminated. If both "-fullscreen=TRUE" and "-menu=OFF" are set on the command line then the mouse cursor is automatically hidden at startup.
    -Rotation=...
    0
    90
    180
    270
| When this parameter is specified, it specifies the rotation applied to the screen (in degrees), no matter what was the rotation value when the emulator was last terminated. There are four valid values for this parameter (0 meaning "no rotation").
    -Shader=...
    ON
    OFF
| When this parameter is specified, it forces the glow shader to be enabled (ON) or disabled (OFF), no matter what was the shader activation state when the emulator was last terminated.
    -Sound=...
    ON
    OFF
| When this parameter is specified, it forces the sound emulation to be enabled (ON) or disabled (OFF), no matter what was the sound emulation state when the emulator was last terminated.
    -Menu=...
    ON
    OFF
| When this parameter is specified, it forces the emulator's menu to be shown (ON) or hidden (OFF), no matter what was the menu state when the emulator was last terminated.
    -Wobbling=...
    ON
    OFF
| When this parameter is specified, it forces the vectors wobbling to be enabled (ON) or disabled (OFF), no matter what was the wobbling activation state when the emulator was last terminated.
    -ResetBounds
    ---
| This flag will reset the size, position and state of the emulator's window to the defaults. If this parameter is not included in the command line, the window will open with the same settings that were last used (including the maximized state).
    -NoDeployment
    ---
| If this flag is present, ParaJVE will not check its libraries upon startup (and thus, will not try to re-deploy the right ones, if needed). The deployment is usually only performed during the very first execution of ParaJVE (to select the 32 or 64 bits libraries depending on the execution environment), but you can disable it if for some reasons the emulator keeps on deploying the libraries after the first run...
    -NoRedirect
    ---
| When this parameter is present ParaJVE prints its log on the standard output/error streams (if -noredirect is not used, the output is logged into the file named at "data/temp/ParaJVE.log" instead).
    -NoSplash
    ---
| If this flag is present, ParaJVE starts without opening any splash-screen. Note that this option is only useful when the emulator is launched via the "ParaJVE.exe" Windows executable file (as there is not any splash screen in the other launchers anyway). Watch out, this parameter is case-sensitive.
    -Debug
    ---
| Adding this flag will activate verbose logs.
    -PreloadLibs
    ---
| You can try to use this switch if ParaJVE doesn't starts correctly (especially if you experience some kind of Unsatisfacted Link Error). This flag should not be used otherwise...

Launching a game that is not included within the ParaJVE distribution

ParaJVE comes with a rather complete games bundle, but there will be occurrences when you want to run an extra game that is not included within the original ROMs package, or when an homebrew developer would like to assemble and/or test his latest code in the emulator. There are several ways to proceed (some are making use of the Graphical User Interface, others are Command-Line based).

- Direct execution of an external ROM binary (command-line) :

This method can be used to instruct ParaJVE to directly load an external ROM binary without poping up the game selection dialog. This is especially geared towards homebrew developers as it will allow them to integrate the emulator more tightly in their development cycle. With this feature, they can invoke ParaJVE directly from within their preferred IDE and make it execute their current work (provided that their IDE can invoke external tools, for assembling the source then call ParaJVE).

All you have to do is setup your IDE so that it calls ParaJVE with the extra `-GAME` parameter whose value is the path of the binary ROM (that should have been assembled prior by your IDE). For a complete description of the `GAME` parameter, you can further read this section.

- Executing an external ROM binary (GUI) :

This method can be used to run an external game ROM (downloaded from the internet, for instance).

In the game selection dialog, click the `"Select another ROM"` button, and browse to the file containing the binary ROM to be ran. Once done, click the `"Run Game"` button, and ParaJVE will be launched with the specified binary.

- Executing an external ROM source (GUI) :

This method is likely to be used by homebrew developers that use the AS09 assembler only : it instructs ParaJVE to assemble some 6809 source code, and load the resulting binary (rather than directly loading an already assembled ROM).

In the game selection dialog, click the `"Assemble Source"` button, and browse to the main source file to be be assembled. Once done, click the `"Build ROM & Run Game"` button. The AS09 assembler is then invoked to build the ROM, and if successful, the generated binary is loaded by ParaJVE. If an error occurs during the assembly phase, an error dialog will notify you about the problem.

- Reloading or ReAssembling a loaded ROM (GUI) :

This is not a Launching method per se, it is rather a trick to avoid the need for a relaunch ; its purpose is to force ParaJVE to reload a ROM binary (or reassemble a source) if for some reasons its content changed since it was first loaded.

In the emulator menu, select the `[Debug-> Reload Cartridge ROM]` menu item (or `[Debug-> Rebuild Cartridge ROM]` if you started the emulator with some source code as described here). The ROM is then reloaded (or rebuilt, displaying a message in case of assembly error), and a dialog asks whether the emulator should be reset or not. Clicking the `YES` button will reboot ParaJVE (ie. perform a clean restart), whereas clicking `NO` will let the emulation resume its execution without any reset.

Unless you know exactly what you do, the `NO` option is usually discouraged, as it resumes execution in the same exact state as when it was suspended (excepting for the cartridge memory area that has just been reloaded or rebuilt), the other memory areas and sub-systems (CPU and chips) are left untouched... For instance, you could very well end up with the PC register pointing to a cartridge address that is not intended to be executed anymore - and this is only one funny scenario amongst many others!

Skipping the game selection dialog

For the users that launch the emulator through a third party front-end, ParaJVE can easily be started directly (ie. without poping up the game selection dialog). In order to do so, all you have to do is make use of the `-GAME=<identifier>` command-line parameter (as described in here).

Also, for the developers that seek a way to invoke ParaJVE with their assembled ROM directly from within their IDE, have a look at this section.

Emulated Peripherals

ParaJVE emulates an ever-growing set of vectrex peripherals and devices, that can be plugged in the first and/or the second gameport (depending on the peripheral type). To change the peripheral attached to one of the two gameport, select the new device menu item in the gameport menu : either `[Controls-> Game Port #1->...]` or `[Controls-> Game Port #2->...]`.

The devices currently attached to the two gameports will have a check mark before their associated menu item. At any time, there can be only one device plugged into a gameport (attaching another device will unplug the old peripheral first) when a gameport has no device plugged-in, the `Empty` device (fake device place holder) is used.

Vectrex Joystick Emulation

The basic peripheral for the vectrex is its joystick (made of two analog axis, along with four fire buttons). This device is of course emulated, and unless you change it, a joystick is plugged by default in each gameport. To support the joystick(s), ParaJVE maps some of your keyboard's keys (hitting these keys will make the emulator act as if the corresponding joystick button/axis was operated).

To change the current key-mapping and tweak it to your needs, select the `[Controls-> Key Mapping]` menu item. Then, in the `Joystick#1` or `Joystick#2` tabs, click on the buttons you want to configure, and simply hit the key you want to be bound to that button.

The default key-mapping (local sensitive)
Target Component | Mapping for GamePort #1 | Mapping for GamePort #2
--- | --- | ---
Belgium, France | Other locales
Action : Button 1 | A | Q | 7
Action : Button 2 | Z | W | 8
Action : Button 3 | E | 9
Action : Button 4 | R | 0
X Axis : LEFT | LEFT | KEYPAD-4
X Axis : RIGHT | RIGHT | KEYPAD-6
Y Axis : UP | UP | KEYPAD-8
Y Axis : DOWN | DOWN | KEYPAD-5

ParaJVE can also handle any gamepad physically connected to your computer and map it to a virtual vectrex joystick (instead of using the keyboard). To use a physical controller within ParaJVE, it must have been connected before the emulator started (otherwise ParaJVE will not see this controller as available). Every detected controller will be listed under the `[Controls-> Game Port-> Controller]` sub-menus.
To assign a physical controller to one of the two vectrex gameports, select the associated sub-menu entry. A dialog will then appear, letting you configure the mapping between the controller buttons/axis and the virtual joystick. Once validated, you can use your controller to play in the emulator.

The vectrex games can poll the joystick using two different modes : either Digital, or Analog. These modes do not change the way the buttons work (they are always polled as being either pressed or released) ; the difference lies in the way the axis coordinates are handled.

- Digital Mode :

The Digital mode is the default one in ParaJVE, because it is the standard used by most games. This mode does not take advantage of the (accurate) analog values of the joystick, it only cares for the general direction in which the axis are oriented. For instance, it doesn't matter if you have the stick fully moved to the right or just half-way, as in both case the system will only note that the X axis is right-oriented.

While operating in Digital mode, ParaJVE will use the four directions keys to control the joystick axis (as defined in the key mapping configuration).

- Analog Mode :

A few games make use of the vectrex joysticks analog capabilities (Hyperchase, Star Sling 4K and Patriots III to mention a few). This means that these games will not only care about the direction of the joystick axis; they will also look at how far the joystick moves along the axis, and will use this value to adjust the actions taken. ParaJVE cannot handle this mode with just four directions button (as it does in digital mode) ; that's why it will use the Mouse moves to emulate this mode.

To enter Analog mode, you must first have a (virtual) joystick plugged in the target gameport, and operating in digital mode (this is the case by default). Then, double-click anywhere in the emulator window. As a result, the Analog mode will be activated (the mouse cursor vanishing is an indication), and from now on, every mouse move will be converted as an analog move in the corresponding virtual joystick. This will last until you switch back to digital mode, by clicking any mouse button.
Note that double-clicking the left mouse button will enter analog mode for the joystick plugged in the first gameport (if any), while double-clicking with the right mouse button will operate on the joystick plugged in the second gameport, if any.

Lightpen Emulation

The lightpen is a legacy peripheral that was supported by a very small set of original games. It is a kind of pen, dragged around the screen by the user, that detects the light emitted by the display beam. This device is emulated within ParaJVE (since version 0.6.0) by using the Mouse moves.

When starting one of the four embedded games that requires the lightpen, this device is automatically assigned to the appropriate gameport, so it is immediately available. If you launch an external ROM that makes use of the Lightpen - MailPlane, anyone? ;) -, you will have to plug it manually (using the `[Controls-> Game Port #2-> LightPen]` menu item) to activate its emulation.

When the lightpen is plugged in, the Mouse Pointer is replaced with a Cross that figures the position of the lightpen on the screen. By default, the lightpen is considered inactive (it cannot detect the light beam) as long as no mouse button is pressed. It becomes active when either (or both) the Left or Right mouse button(s) is(are) pressed. If the Right mouse button is pressed, the lightpen operates in accurate mode (that means that its precision is greater than normal, but also that it is likely to loose track of the light more easily if you move the mouse too fast).

PS/2 Keyboard adapter Emulation

The PS/2 adapter is a connector (created in 2007) that provides a way to connect a PS/2 keyboard into the vectrex second gameport (and let the vectrex program access the keyboard hits).

When the Keyboard Adapter is plugged into the game port, it remains inactive until you press the engagement key (`PAGE_UP` by default). Once the keyboard has been activated, it will intercept any keypress (including the keys already mapped to joysticks or the general keys) and forward them to the gameport. This will last until the keyboard is disengaged (by pressing `PAGE_DOWN` by default).

ParaJVE does not embed any game making use of this adapter so far, so its emulation for the time being is aimed at homebrew developers that wish to write some code that uses this adapter.

VecVoice Emulation

The VecVoice is a passive peripheral, as it does not require any user action to carry out its task (it is a sound synthesizer that is entirely driven by the vectrex program, through the gameport signals). Therefore, 'using' the VecVoice emulation is as simple as pluging it into the second gameport, and let the VecVoice-enabled games operate it!

So far, the only embedded game that makes use of the VecVoice is `Verzerk`, and launching this game automatically instructs ParaJVE to plug the VecVoice in the gameport, so you don't even have to do anything to have it working. However, if you happen to launch an external ROM that makes use of the VecVoice, you will have to plug it manually (using the `[Controls-> Game Port #2-> VecVoice]` menu item) to enjoy its emulation.

Miscellaneous

Optimizing the emulator's window size

TO DO ...

Saving and Loading the emulator state

TO DO ...

Selecting a different Glow Shader profile

TO DO ...

Taking a snapshot of the current screen

If you want to save a picture of the current screen display, you can do so, at any time, by hitting the ScreenShot shortcut key (which is `PRINTSCREEN`, by default). You can also get the job done via the `[File-> Take ScreenShot]` menu item (but first pausing the emulation by hitting the `PAUSE` key might prove helpful in this scenario).

The emulation will then enter paused mode (if not already done), and a file requester will popup, waiting for you to enter the name of the file where to save the picture. You can cancel the saving by hitting the `ESCAPE` key. The format used to encode the picture depends on the file extension you provided (the only supported file formats are `BMP`, `JPG` and `PNG`, this later being the default if no extension was specified).

Checking for new releases of ParaJVE

ParaJVE comes with an integrated way to check if a newer version is available for download. Whenever you want to check if a newer version is released, select the `[Help-> Check for new versions]` menu item. The emulator will then gather information about the latest version over the internet , and open a dialog telling whether a new version is available (providing a link to the download site, in that event).

If you are concerned about privacy, rest assured that ParaJVE will not send any personal information of any sort on the internet (in fact, the emulator just downloads a version manifest) ; also, rest assured that this check is never performed without you asking for it to occur.

Browsing the ParaJVE development blog

The emulator will open your preferred browser and automatically load the ParaJVE development blog for you if you select the `[Help-> Open ParaJVE Blog]` menu item. In some (undefined) occurrences, the browser's page might only open after the emulator has been closed.

Troubleshooting and Known Bugs

To Do ...

TO DO ...

Franck Chevassu, ©2008