
Johnny 5 Readme(turn on wordwrap)
===============

Beta 3.2
========
Added DDE Support! Now launching a second instance of j5 with a different command line will pass those commands to the existing instance!
Developers can also interact with the DDE interface directly.

Added a -show flag, which simply hides the layoutview so you can keep J5 running indefinately even if you don't want it visible all the time.
Added a -nolight flag, which halts lighting.
Added a secondary exit key, set to "p" by default... useful for viewing j5 within mame.

Beta 3.1
========
LedWiz Ocx updated to 3.0

Beta 3.0
========
Added Light support Including LedWiz Support
Added support for colors.ini, a sister ini to controls.ini that documents colors instead of captions.
Added Generic Read support for j5... now the viewer generates an entry based on the mame controls info if no entry is found.
Added some various command line tags to implement all of this.
Fixed bugs related to dual display use.



Beta 2.6
==========
What's New

Primarily a bug-fix release.
Added the directional arrow gifs (oops).
Fixed the viewer's backwards compatability with older versions of mame.  
A few other misc things.



Beta 2.5
==========
What's New

Fixed bugs, too numerous to mention.
Improved layout editor by adding various hotkeys.


Added a few, self-explanitory, new options for layouts and things in general.

Note:  Due to this change, some of your old layouts may be invalid.  
The layout itself is fine, but the layout's cfg is invalid.
Simply open it up in the layout editor, go to layout settings and set them and save.  
All will be well then.  


Now you can delete or add any label, not just the last one.  
Now you can swap the zorder (layering) of two labels.

Direcitonal Arrow Support Added.
"_device" settings are now used to fudge rather than the fudging hacks.  
Added a slew of new joystick constants.  

Added the "-emu" tag allowing you to specify the emulator.  
When the emu tag is used, j5 searches in "emunameStd.ini" for defaults and "emunameControls.ini" for entries.
Also added an advanced plugin that allows you to add full support for other emulators (actually read the emu's control cfg and send it to j5).

Added support for cpanel and instruction card images in the layouts.  
Added support for cpanel images via the toggle button.


Improved functionaly for the "-justprint" tag:  

Now you can specify an output filename and path and are not limited to bitmap output.
Irfanview is no longer needed, all conversions are done internally.  
Specifying a "-position" along with -justprint allows you to generate the image at any size.
Sprites and the newly added cpanel/icard  images WILL print along with the output.
Better bounding checks from printing output, so labels remaind in their bounds.

New "Purdier" layout, which takes advantage of sprites, the cpanel addition and directional arrows.  

The merged label system now checks to see if a label has been processed, preventing confilcts from overlapping merges.
All labels, and I mean ALL labels now support image sprite replacement.






Beta 2.0
What's New
========

Fixed Various bugs.  

Added Command.dat support.

Added fixes that are required by the new mame core, Johnny will still work with older versions of mame. 

The auto hot key script has now progressed enough to be considered a true feature.  By using this seperate download package,
along with some help from your favorite fe, you can now view j5 and all it's supported dats while in mame!
(2000/Xp users only)

Added -ahk tag, which helps with the script.

Added -driver allowing the user to manually set the driver.

The viewer can now automatically retrieve the driver and clone, all that is required is the rom name, making it easier to use
j5 with your favorite fe.


Beta 1.5
What's New
========

Fixed Various bugs.  

Johnny5 is now works in 98 without a hitch.

Added Instruction Card Support.

Made the exit key remappable along with a new toggle key to switch to cards.




Beta 1.0
What's New
========
Johnny5 Now only Supports xml-style ctrlr files. For those of you using older versions of mame, a converter will be made available soon.

Mame's Cfg files are now read.

Mame's Default.cfg is now read.

Hard-coded input changes at the driver level are now detected.

Added "Merged Caption" Support

Added "Warning" Speciality Tag, which alerts you if you haven't mapped all the needed inputs for a game.

Added true support for analog inputs.

INI files (not the old ctrlr files, ini files) are now read and parsed for important data.  So if you have a vector ini that changes inputs (why?) or a neogeo.ini that changes the current ctrlr file it will be reflected in the viewer.

Added support for the new device-based control schemes in mame.  (Paddle_Device, adstick_device, ect.)  Btw if you are still using the old "joystick" and "mouse" switches then STOP!!!  These are much more user-friendly and save you from having a million game-specific ini files. 

Changed Font-Scaling code for a more visually pleasing display.

Removed the mouse and joystick fudge options as they are no longer needed.  


Fixed Various bugs.  

I am including a file which should fix the problems users are having with the viewer in 98.  If it still isn't working, contact me.  







Beta 0.7
What's New
===========

Several bug fixes.  
Better error handling.
"Icon" support for image-based cpo labels.  
-justprint tag, for the project that will integrate the viewer into mame itself.  


What is Johnny 5 ?
------------------

Johnny 5 utilizes the controls.dat to display the labels to your favorite games overlayed on a picture of your own control panel layout.  The result is never having to ask "What does this button do?" ever again.
Johnny 5 also also reads data from mame itself, generating an entry if controls.dat doesn't have one.  
Johnny 5 can control lights as well supporting the yet unreleased colors.ini.

Setup
-----

When you first run the viewer, it will send you to the options menu to setup your paths.  The viewer isn't going to work properly until you do, so go ahead and do so.  Note that for the ctrlr entry, it wants the name of the cfg file, NOT the name and extension.  So it's "HotRod" NOT  "HotRod.cfg"

After you save it'll warn you that the layouts included with J5 are nothign mroe than examples.  There is a simple reason for  this.  Unlike other viewers out there, this one is designed to show your actual layout on your actual control panel.  Since I don't know how you've mapped your keys or what controls are on your panel, you'll have to do that bit.  See the layout section below for instructions.  After that basic setup is complete and you can start using the viewer.  It's ran by the command line (for front-end use) so you won't find any way to lookup a game via the menu (Yet).  


Command Line Options
-------------------

Usage:  Johnny5.exe romname -clone clonename -position x,y,width,height -lof layoutfile.lof

-clone clonename= optional parent rom to the rom you specify (like cloneof in mame)

-cloneof clonename= optional parent rom to the rom you specify (like cloneof in mame)

-driver drivername= optional parent rom to the rom you specify (like sourcefile in mame)

-position x,y,width,height  = optional position and dimensions of the view.  

-lof lofFile.lof = override the default.lof with the lof you specify. 

-clf clffile.clf = override the default.clf with the clf you specify.

-ahk ####  Used in the ahk script to fix resizing problems. You can optionally set the delay time in milliseconds.

-quit = send the call to quit (for developers only)

-listen 1000 = listen for new commands (for developers only)

-next = when used with the viwer in "listen" mode, this simulates the pressing of the ui toggle key, just changing to the next screen.

-debug = Prompts You with some debug info (for developers only)

-justprint filename =  loads the game you call with the given options you called, blanks the screen, saves to the filename you specify and exits.

-justlight =  silenty read all ini's to get data light the lights and exit.

-nolight = bypasses lighting.

-emu emuname= optional Emulator Name you specify.  This is used to add support for other emulators.  If a emuname is not given J5 assumes it is mame.

-show # Used to hide/show the layout.  A value of 0 hides while a value of 1 shows


example:  johnny5.exe sf2t -clone sf2

*Note* 
======

The viewer stretches the layout, it doesn't scale it, so keep that in mind. 

If you omit all command line options you will get the layout editor.

If you omit the position tag, the view will default to fullscreen.  

The ONLY way to view controls.dat entries is to pass command line options. 

Label icons are now supported.  They should be saved in gif format and named after the label and romname. For example to 
replace the "Fire" label in the game 005 with an image, simply drop a gif named "005Fire.gif" in the layouts/images/ folder.
Please note that the labels behavior type has to be adjusted so allow images (the default layout does not). 


Irfan view is used to convert the printed controls.bmp into controls.png for your benefit.  In vb6, converting a bmp file into a png file requires a very expensive plugin.  I used irfanview because it's free and tiny.  If I hadn't I would have to charge for the viewer to pay for the plugin. To use the just print feature, get a copy of irfanview and drop the whole thing in the viewer folder. 

http://www.irfanview.com/

======

Using the Editor
----------------

The layout editor is built into the viewer.  Don't pass any command line options and the layout editor will come up.

When making a layout First go to File/New.  You will be prompted for a filename.  This is simply to create a working directory.  Make sure not to overwrite any existing files.  Once that is done you need to go to Options/Layout.  the most important thing to set right now is the background image.  (Jpegs only please.)  Once that is setup click ok to return to the main layout.  You can now start adding labels by Label/Add.  Please note that You can only delete the last label back, so be careful when doing a layout and save often.  

The rest of the editor is pretty self explanitory.  One thing of note is to get to the options for individual labels you simply right click on them.  Basically, you tell the editor what key that label should be mapped to and it does the rest.  The layouts are fully scaleable as is the font size, but keep in mind that you'll want to use a true type font.  Your background image file needs to be at a 3:4 aspect ratio.  If it's not it'll be squished to fit.    

Once you are done save your layout.  If it's the main layout you will be using, you want to save it as "default.lof"  Just backup the original first!  It's a very useful example!

Advanced Usage:
---------------

Instruction Cards:

The "toggle" button recently added toggles the view of the instruction card for that game.  You define the card path in the viewer cfg.  Cards can also be
displayed in a layout via special tags.

Control Panel Images:

Work just like the cards.  





Sprites:

Some games didn't have labels for controls, rather a graphic or icon. J5 allows you to substitute a label for a graphic or "sprite".  All sprites need to be
in gif format, with NO matting and a transparent background.  Name the gif after the parent rom name plus the caption displayed for the control in j5.  For
example... to use a sprite in place of the "push" label for the game's button, make a sprite called "pengopush.gif"  All sprites go in the layouts/images folder.  Note that labels marked as "text" in their options will not display images, even if they are found.  In the default layout, all labels are intelligent.


Other Emulator Support:



First off there is a plugin system, where emu automatically becoome supported, for those the instructions depend upon the plugin.
A daphne plugin is nearly complete, and a zinc one is planned.

As for the rest....

Other emulators are supported, they have thier own std.ini named, EmuNameStd.ini (replace emuname with the name of the emu of course), will search for 
std-based files for each game in their own "ctrlr folder" and search for game entries in a "EmuNameControls.ini" You have to make these files yourself though.  To configure a emu that doesn't have a plugin, run the NoPlugin.exe in the plugins folder, there you can set key paths and modify existing emus.





Command.dat:

For those of you living in a cave, the command.dat is a project that documents special moves, tips and tricks, for various games (mostly fighters).  Up until .99u3 special builds of mame allowed you to view this document inside mame itself. Sadly now that support is gone due to core changes.  Luckily J5 now has support for it. Download the optional command.dat pack and extract it to your johnny 5 folder. Next, simply put the latest version of the command.dat in the "data files" folder.  Now when in the viewer pressing the toggle key brings it up.  It's that simple.  Please note that I've also added support to change the command.dat graphics as well as protrait support. Simply name the graphic properly (see the default graphics I've included) and put it in place.  You can also have specific graphics for specific roms/clones/ect. Just name a folder in the "commanddat/images" folder after the rom in quesiton and place your images there.  Anything that's normally in brackets in the command.dat entry can have an image (thus portrait support).  Simply name them like the entry (sans brackets all lowercase) and it will show up above the entry.  Again, like the regular graphics, you can use generic ones or make speficic ones for each rom.  



Filtered Layout Files:

You can make multiple layout files and they will automatically load based upon the situation.  First off, default.lof is always loaded first. The system then checks for "1PlayerDefault" through "8PlayerDefault" respectively, based upon how many simultanious players there are for the game.  The the viewer checks the controls for the game and compares them to the "loffilters.txt" found in your data files folder.  It's a simple text file that lists keywords.  When a keyword is found in a game entry, the layout file named after said keyword is loaded.  The file is read from top to bottom, so obviously more vague keywords (joy8way, joy, ect) need to be at the top, while more specific ones (Lightgun, 360 Steering Wheel, ect) need to be at the bottom). 

And to confuse you even more, every single entry is searched three times for even more specific matches.  First by player ("#PlayerKeyword" where "#" is the number of players and "Keyword" is the search keyword.).  Then by the number of buttons ("#ButtonkKeyword") And finally by both  (#Player#ButtonKeyword)  

So long story short, you can get VERY specific on what you filter out to the point that you have a layout for every situation.


Merged Captions:

Street Fighter 2 has loooong captions for it's buttons.  Part of this is due to the fact that "Punch" or "Kick" has to be tacked on to each caption.  The same thing goes with dual joystick games and other such oddities.  Wouldn't it be nice if you could setup a special caption to Hold these common words thus, making the whole thing more readable?  Well this is exactly what merged captions do.  You may have noticed by now that when you right click a label you have a strange option called "Merged Label"  If you check this box, then the ordinary caption becomes a merged caption.  You'll have to set a range of labels to compare.  When the mouse is over a label it's number is displayed in the title bar.  Simply figure out which labels to wish to compare.  From now on when ALL the labels you ar comparing share common text, it'll be moved to the assigned merged label.  You can do these in a hierarhy too.  Setup a merged caption for your first three buttons, then add a label and set one up for your first two.  If you set them up in this order (most buttons to least buttons) when all three captions share common text it'll show up in the 3 button merged label a when it's just the first two, they'll show up in the 2 button merged label.  Confused yet?  Don't worry, play around with it a bit and you'll get the hang of it.  there are plenty of examples in the included default.lof

Special Tags:

When you are setting up a key to bind you may notice some odd constants at the bottom of the drop-down list that start with a "*".  These are special tags.  Binding a label to one of these displays the information described.  You can also make your own.   You can manually add messages you want to display on your labels by adding custom entries in the keycode_constants.txt in the data files folder.  Simply add them at the misc section and put an "*" at the beginning.  The exact phrase you entered will be available in the drop down box for the label's function in the layout editor.  So if you want to label your admin buttons (which aren't supported in the controls format) you can "hard-code" a label to always display that info.

Also ff a keycode constant that you use in mame isn't there, you can also manually add it.  You just have to figure out what mame calls it internally.  (Good luck with that. ;-)  )


Light and Color Managment:

J5 now supports outputs to two parallel ports, 16 ledwiz's and all three keyboard leds.  It also boasts support for the (non-existant) colors.ini, A ini file based on controls.ini that has color vlaues rather than captions.  You'll notice a new folder called lights.  Inside you'll find a lights.ini and a default.clf.  You want to make your own lights.ini based on the one included.  It basically tells the program what kind of devices you have hooked up and how you are using them.  It is heavily commented so I won't go into detail on how to use it here.  You MUST fill out this ini file before you make your clf (color layout file).

After the lights.ini is squared away, you can now make a layout file for lights just as you would for captions.  In the menu in the tools section you'll find a light editor option.  Open it up and you'll see a list of all the lights you made in your lights.ini follwoed by a key to bind them to.  
It works on the same principle as the regular layout files.  To change a value, simply double click on the value part and a drop-down list will appear.  If you wish to use a regular layout file as a guide, you can.  Load em both up and you can quickly use the same key as the key on a layout by first clicking on the caption on the layout and then clicking on the light on the light layout. 

Note, the lights.ini and default.clf included are just examples.  They WILL NOT WORK out of the box. Also the colors.ini only has one fake entry (sf2) to test the parsing.  A colors.ini willhave ot be established.  


DDE:

End users will never see DDE but what it means is if you launch j5 again while it is already running, the command lines you send will be passed on to the first instance!
You can also send command lines directly to j5 with dde.  The appname is "Johnny5" and the keyname is "J5DDE".  For further info on how to take advantage of this, please contact me personally.



Fudging:

See the Fudging.txt in the docs folder.














