Welcome to CPMaker!
CPMaker is a standalone executable which creates artwork images which can be displayed by MAME or another emulator.
I have also compiled the CPMaker functionality into my own MAME build, which
I call "BuddaMAME".
CPMaker now (as of February 2006) also includes an image viewer and a layout program, with a graphical
user interface!
There is also a standalone image viewer for looking at .png or .jpg images.
Ctrlr files tell MAME what functions correspond to what keycodes. For example, you can tell MAME that when the R key is pressed, invoke Player 1 Button 1. MAME will run without any ctrlr file mapping, but at this time CPMaker will not create correct artwork without a ctrlr file.
Several sample ctrlr files are provided with the binary distribution of
MAME. I also have created several other examples with the BuddaMAME
distribution.
Buddabing's note: CPMaker only works with the XML-style ctrlr files. MAME
started using this ctrlr format at version 0.85.
Also note: There must be no extraneous spaces between the keycode names
and the XML delimiters! Otherwise labels will be displayed incorrectly
in games such as Mortal Kombat which have remapped function keys.
Here's an example of what a control panel image for Mortal Kombat looks
like without any ctrlr file mapping.
I added these lines to the ctrlr file:
<system name="mk">
<input>
<port type="P1_BUTTON2">
<newseq type="standard">KEYCODE_LALT OR KEYCODE_Z</newseq>
</port>
<port type="P1_BUTTON5">
<newseq type="standard">KEYCODE_X</newseq>
</port>
</input>
</system>
With the ctrlr mapping for mk in place, the game is more playable since
the control mappings make a lot more sense than they previously did.
Layout files tell CPMaker how to arrange the labels on the control panel image. Mortal Kombat has High Punch, Block, and so on, Donkey Kong has the Jump button, and so on. The layout file tells CPMaker to draw the button text for each button in the appropriate place. It does not tell what the actual button text is. That is the job of the controls.xml file.
Layout files are used to tell CPMaker where to put labels, their color, size, and font. Besides CPMaker, there are two other programs supported which generate these layout files. One is Johnny 5, created by Howard Casto, and the other is CPViewer, created by John Crouse. CPMaker expects Johnny 5 layout files to end in ".lof" and CPViewer layout files to end in ".lay". You can change where the layouts are located, for example, if you use Johnny 5 you might change the path to whereever Johnny stores its layout files. To do this, change the layoutpath value in cpmaker.ppf.
Johnny 5 doesn't have it's own home page, but the author's home page is here.
Hint: CPMaker can use Johnny 5 layout files directly. Keep in mind, though, that your background image needs to be in a 4:3 aspect ratio in order for CPMaker to produce an output with the labels in the right spot. This is because Johnny pads the background image with black until the image is at a 4:3 aspect ratio.
The newest version of Johnny also has the capability of displaying artwork when pause is pressed in MAME, just like BuddaMAME! This is good for people who want to display artwork when pause is pressed but want to use a different MAME build, such as AdvanceMAME.
The two types of external layout files and the programs which create them are no longer needed, because CPMaker now comes with a panel and label design program. A future version of CPMaker will be able to import and export Johnny and CPViewer file layouts.
Controls.xml is the result of a large project headed by SirPoonga and Howard_Casto of the Build Your Own Arcade Controls community. The project, named the "controls.dat" project, is a database which aims to accurately document the correct controls that all the various arcade games used. It also contains miscellaneous details and a bit of history about the games. As of this writing, the controls.dat project contains information about more than 1000 unique games.
CPMaker uses the controls.xml file to get the actual text that is to be
displayed on the image. The aforementioned Mortal Kombat has nine labels
defined for it: High Punch, Block, High Kick, Low Punch, Low Kick, Jump,
Duck, Move Left, and Move Right. These labels need to be displayed for both
player 1 and player 2.
CPMaker cannot make any control panel images without artwork. CPMaker needs images of joysticks, buttons, and other items in order to function. Fortunately, a BYOAC member named Frostillicus has provided a wonderful library of control panel pieces. I've separated the images into pieces for several of the joysticks and buttons, but this is not complete.
You may need to resize your background image to match the size of the
Frostillicus library, or you can generate your own artwork pieces from
Frosty's library. In my image library, I resized the Frostillicus artwork
to match my background image.
The panel preference file contains many parameters pertaining to where to find panels, layouts, and artwork, as well as optional parameters.
Panel preference files are comma-delimited text.
Tags used in panel preference files:
imagepath
magickpath
ctrlrpath
xmlcachepath
layoutpath
panelpath
productpath
controlsxmlpath
verbose
textconstraint
color_definition
If a global parameter is used in more than one panel, then the global parameter specified in one panel will override the parameter specified in the other, but in no guaranteed order.
CPMaker is designed to support multiple panels. Most users have only one physical control panel. Even these users may have need to have more than one panel filem, however.
Users of swappable and rotatable control panels will want to have separate panel files for each of their panels.
Users who have purchased my LED controller may also want multiple copies of the same panel file, even if they have only one physical control panel. This is because users may want different color schemes for different games. The LED controller supports RGB LEDs, and users may want to light up their RGB LEDs differently for each game. For example, they might want the LEDs to be yellow for Pac-Man.
A Panel Selection File (.psf extension) tells CPMaker what control panels you have, what panel you want to use for the majority of your games, and any specific games you want to use a specific panel for.
Tags used in panel selection files:
prefpanel
panelfile
majority
These files describe what kind of controls and artwork are on your panels. CPMaker expects a .PAN extension on these files.
Tags used in panel files:
template
controller
label
startpanel
endpanel
control
led_definition
imagepath - Tells CPMaker where to find images.
Usage: (used in .PPF files)
imagepath,path_value,Default:
imagepath,cpmaker\images,(.PPF only)
The "imagepath" panel parameter tells CPMaker where to find the control panel image artwork. You need images of buttons and joysticks for CPMaker to assemble into the destination image. Also, the background (template) artwork images for each panel must be stored in this directory.
Paths can be absolute or relative. Relative paths are relative to the directory from which the executable is found.
Restrictions:
Examples:
imagepath,\images, imagepath,c:\cpmaker\imagelib, imagepath,images, (relative) imagepath,"x:\long file name\images", imagepath,..\images,
magickpath - Changes the path to search for ImageMagick config files.
Usage: (.PPF only)
magickpath,pathname,
Default:
magickpath,cpmaker\magick,
The magickpath parameter is used for the ImageMagick libraries which are compiled into CPMaker. They should not be changed under normal circumstances.
ctrlrpath - Changes the path to search for ctrlr files.
Usage: (.PPF only)
ctrlrpath,pathname,
Default:
ctrlrpath,cpmaker\ctrlr,
Users will probably want to change this directory to whereever the ctrlr files are normally stored (usually the ctrlr subdirectory of the mame directory)
Buddabing's note: CPMaker only works with the XML-style ctrlr files. MAME started using this ctrlr format at version 0.85.
xmlcachepath - Changes the path to place xml cache files.
Usage: (.PPF only)
xmlcachepath,pathname,
Default:
xmlcachepath,cpmaker\xmlcache,
The controls.xml path is quite large and takes a bit of time to parse. So, CPMaker takes the relevant piece of controls.xml for each game and caches it in this folder. Additionally, there are some games for which there is no entry in controls.xml that I created xmlcache entries for so that my installation of CPMaker would create a good image.
If the path doesn't exist, xml will not be cached and the entire controls.xml will have to be parsed every time the same game is run.
layoutpath - Changes the path to find layout path.
Usage: (.PPF only)
layoutpath,pathname,
Default:
layoutpath,cpmaker\layout,
External layout files are for label placement. External label layout files can be created by hand or by using the Johnny5 or CPViewer layout editors. Johnny5 layout files must end in ".lof" and CPViewer layout files must end in ".lay".
CPMaker understands external label layout files and can generate images using them. However, some features in external label layout programs may not yet be implemented in CPMaker. Also, the text renderer in CPMaker formats text differently from the text renderers in external label layout programs. Thus, images created with the same exact external layout may appear differently in CPMaker than with the program that created the layout.
Label layouts may also be specified internally in panel files. Therefore, external layout files and this parameter are optional.
panelpath - Tells CPMaker where to find panel files.
Usage: (.PPF only)
panelpath,pathname,
default:
panelpath,cpmaker\panels,.PSF and .PAN files must be placed in this directory.
template - Set background image
Usage: (.PAN only)
template,template_type,template_name,
| Template Type | Meaning |
| 1 | Use the template_name as a filename |
| 2 | Use the background image specified in an external layout program |
| 3 | Use template_name as a color definition |
Each panel can have its own template image.
Template images can be png or jpg.
Color definitions are speicified with "0xAARRGGBB", where A is the hexadecimal representation (00 through FF) of the alpha value, RR is the hex value of red, GG is the hex value of green, and BB is the hex value of blue. As of February 2006, alpha values are ignored.
productpath - Tells CPMaker what the final product name will be.
Usage: (.PPF only)
productpath,productname,
Default:
productpath,controls.png,
This is a full path name. Product files can be png or jpg.
controller - Specifies the MAME controller (ctrlr) file used by CPMaker.
Usage: (.PAN file only)
controller,filename,
If no controller file is present, no dim buttons will be shown.
Remember, only MAME .xml ctrlr files are supported.
The ctrlr files are read from the folder specified by the ctrlrpath parameter.
controlsxmlpath - Specifies the name and path of the controls.xml file.
Usage: (.PPF only)
controlsxmlpath,filename,
Default:
controlsxmlpath,controls.xml,
If no controls.xml is present, no dim buttons will be shown.
Typically this parameter is left as default. It only should be changed when an older version of controls.xml is used. A full pathname can be used.
startpanel - Specifies the name of the current panel.
Usage: (.PAN only)
startpanel,panelname,
Panelname can be any string that doesn't contain commas, except "default", which is reserved.
Startpanel is required even for single-panel configurations.
endpanel - Marks the end of switches unique to a single panel.
Usage: (.PAN only)
endpanel,panelname,This tag may have not been required in previous versions of CPMaker, but it is definitely required as of version v0.104.
prefpanel - Set panel to use for specified game
Usage: (.PSF only)
prefpanel,gamename,panelid,
This will override any decision the program makes on which panel to use for a specific game.
Example, you can play pacman on a flight stick, but you probably don't want to, so you could put a "prefpanel,puckman,panel2"
You can use the game name or the cloneof for the parameter.
CPMaker will attempt to intelligently decide which panel file to use. If, for example, you have one panel that includes a trackball, then CPMaker will use that panel for Centipede.
Examples:
prefpanel,puckman,panel2, prefpanel,tron,panel3,
panelfile - Include panel file
Usage: (.PSF file)
panelfile,filename,
This will cause the program to parse the specified panel data file. More than one of these files can be included within a .PSF file. They cannot, however, be nested.
CPMaker will search in the folder indicated by the panelpath parameter. Full path names are not allowed. (This changed in version v0.102 of CPMaker).
Panel files must have an extension of .PAN! (This has changed in version v0.103 of CPMaker)
Examples:
panelfile,panel1.pan, panelfile,franken.pan,
majority - Set default panel
Usage: (.PSF only)
majority,panelid,
This marks the panel id of the panel on which the majority of games will be played. For example, if you have one panel with a joystick and three buttons and one with a joystick and four buttons, you could play pacman with either one. This parameter is optional.
textconstraint
Usage: (.PPF only)
textconstraint,value,
This determines what restrictions will be placed on label text.
| 0 | The text will be drawn as large as possible to fit into the layout and as small as necessary to fit. This is the default. |
| 1 | The text will be drawn at the specified font size, but will be reduced if it doesn't fit. |
| 2 | The text will be drawn at the specified font size regardless of whether the text fits the layout or not. |
| 3 | The maximum font size is calculated so that all text will fit their respective slots, and all text is drawn at that size. |
Note: The CPMaker GUI, as of version v0.104, does not provide a method of changing this parameter. It has to be changed by hand-editing the CPMAKER.PPF file.
color_definition
Usage:
color_definition,definition_name,red,green,blue,
The definition name can be anything. If it is one of the preset colors, then the color in the definition will override the preset color.
The red, green, and blue values range from 0 to 255.
Bug: White and black do not work. Many colors which have more than one tint
may not work well.
label,label_name,keycode,label_type,x,y,width,height,rotation,special1,special2,bgcolor,textcolor,fontname,fontsize,alignment,[bold,][italic,]
Label names can be any text which does not include commas or white text.
| Label types | Meaning |
| rect | A simple rectangle, special1 and special 2 ignored |
| roundrect | Rounded rectangle, special 1 is the corner radius |
| ellipse | Ellipse with major and minor axes equal to x and y. |
| image | Image label |
x,y,width, and height can be absolute (number of pixels) or relative (fraction of template image width or height).
bgcolor and textcolor can be 32-bit signed integers with alpha in the high 8 bits, red in the next 8 bits, green in the next 8 bits, and blue in the lower 8 bits. Currently all non-zero alpha values are treated as opaque.
bgcolor and text color can also be specified with "0xAARRGGBB", with AA being the alpha value, RR being the red (hexadecimal value 00 through FF), GG being the green value, and BB being the blue value.
alignment values: 0=left, 1=right, 2=center
TODO: Explain further the font names and how to find out what fonts are available.
control
Usage:
control,control type,startx,starty,filename,numkeycodes,keycodes,numleds,leds,
Do not put spaces between fields.
Commas are mandatory between fields.
control types: p1button, p2button, p3button, p4button, admin, lightgun, trackball, dial, stick, joy2way, vjoy2way, joy8way, joy4way
If a control is switchable (ie. 4 way/8way joystick) put a control for both types.
The start x and start y can be relative [0-1] or absolute [>1].
Work in progress: The filename is normally a .jpg or .png picture of a control, such as a joystick or button. I am implementing a way to directly specify the color of the control.
If "0x" are the first two characters of the filename, the color of the object is taken from the hexadecimal digits in the next six digits. Red are the first two, green are the second two, and blue are the third two. Possible values range from 00 to ff.
Some example colors might be:
0x0000ff - blue 0x00ff00 - green 0xff0000 - red
Black or white do not work well with this scheme.
If the color is specified in this way, then the control artwork piece filename is built from the control type. For control types containing the word "button", the piece filename will be "graybutton.png". For control types containing "joy", the piece filename will be "grayjoystick.png". For trackballs, the piece filename will be "graytrackball.png", and for flight sticks the piece filename will be "grayflightstick.png".
Besides the 0x color convention, some preset colors are defined. The same gray control artwork piece will be colorized. The following colors are defined:
red green blue cyan magenta yellow
You can use these colors instead of the filename and CPMaker will colorize the gray control panel piece.
Finally, you can specify your own colors. This functionality was added in BuddaMAME v0.99. To do this, add a "color_definition" parameter.
For remappable controls buttons and switched joysticks, put in standard MAME keycodes.
For trackballs, put P1_TRACKBALL_X, P1_TRACKBALL_X_EXT, P1_TRACKBALL_Y, P1_TRACKBALL_Y_EXT for the player 1 trackball.
For a player 1 spinner, use P1_DIAL and P1_DIAL_EXT for keycodes.
For a player 1 analog joystick, use P1_AD_STICK_X, P1_AD_STICK_X_EXT, P1_AD_STICK_Y, P1_AD_STICK_Y for keycodes.
leds is a list of LED definition names, separated by commas, one for each LED definition for the control.
So leds could be:
led1,led2,or:
led_def_p1b1,
led_definition
Usage:
led_definition,definition_name,led_type,led_subtype,num_parts,part_list,
led_type: 1=single LED, 2=joystick direction group, 3=start button, 4 = always on
A type 1 led definition defines only one LED. It will be lit if that control is active during a game. A joystick can have a type 1 LED if the joystick has a way to be lit up. Trackballs can also have type 1 LEDs.
A type 2 led definition defines a directional indicator. A directional indicator can be zero, two, four, or eight LEDs arranged around the joystick. Depending on what directions are active, the appropriate LEDs will be lit.
For example, Defender will light up only the top and bottom LEDs of the directional indicator. Donkey Kong will light up four of the eight LEDs, and Mortal Kombat will light up all eight.
Subtype 1 of type 2 LEDs is defined as LEDs for the player one joystick, subtype 2 is player 2, etc.
Type 3 LEDs are flashed on and off by MAME and will be turned on solid, not flashed, in a standalone application. The subtype field of type 3 LEDs is the player number.
Type 4 LED definitions can be used instead of type 1 if you want trackball backlighting to always be on, for pause/admin buttons, etc.
Monochrome (one color) LEDs will have only one part. RGB LEDs will have three parts.
Each part has a controller number, port number, and a brightness percentage value, all separated by commas.
controller = 0 (unless you have more than one LED controller board)
port = 1-40 (as labeled on PCB)
Brightness percentage goes from zero to 100%. If LEDs are too bright, a smaller percentage value can be used. Also, for RGB LEDs, a specified color can be used. For example, sometimes the user might want a RGB LED to be red for one game and green for another. So, the user could specify two panel definitions, one of which would have 100, 0, and 0 for the brightness percentages, and the other would have 0, 100, and 0.
Keep in mind - BuddaMAME is just MAME with some extra eye candy built in. BuddaMAME does not add any games. BuddaMAME has a limited capability to launch external applications via the extmakectrl and extmakeleds flags. BuddaMAME can display any artwork you have created when paused is pressed, and it can also create artwork. All you have to do is set the extmakectrl flag, edit your makectrl.bat file to create a PNG-format artwork image, and name it controls.png.
If a problem crops up when using the CPMaker GUI, try running CPMaker with the -cplog option. This will usually help in diagnosing. If this doesn't help, try using the -cpverbose and/or the -cpdebug command line options, which will generate more detailed messages. If you can't tell what the problem is from the logs, please email me at buddabing at houston dot rr dot com and attach the log from cpmaker -cplog -cpverbose -cpdebug.
BuddaMAME and the CPMaker standalone executable should be able to use Johnny 5 and CPViewer label layout files unaltered. However, CPMaker overrides the backgroud image used in any layout program with the background image specified in the panel file, unless template type 2 is used. I have provided templates for using Johnny5 and CPViewer label layouts with CPMaker. If you have problems getting your layout files to work in CPMaker, please let me know. As of version v0.104, the Johnny5 "Scroll" and "Merge" features have not been implemented in CPMaker. CPMaker does support merged labels natively, however.
You can use Johnny5 to make your control panel images and BuddaMAME to display them. You have to set up Johnny to create PNG files, by default it creates BMP files. You can tell if you have Irfanview installed. In your Johnny 5 directory you should see an executable named i_view32.exe. If you don't, download Irfanview and extract it into your Johnny folder. Move i_view32.exe to the same folder as johnny5.exe if necessary.
Test CPMaker with "cpmaker gridlee". A viewer will pop up with an image with a hotrod panel with three buttons and a trackball.
You can view controls.png with the viewer.exe provided, or with Internet Explorer, GIMP, or my personal favorite which is IFunView. I like IFunView because it allows preview of many different images at a time, which was great for when I was creating movies.
When cpmaker.exe is run without any parameters, or if it is double-clicked, the CPMaker GUI will appear. You can also run CPMaker with certain command line parameters. Some of the following parameters pertain to the image viewer and some of them pertain to the image renderer.
Viewer options:
| -[no]ddraw / -[no]dd | use DirectDraw for rendering |
| -[no]direct3d / -[no]d3d | use Direct3D for rendering |
| -[no]switchres | switch resolutions to best fit |
| -[no]switchbpp | switch color depths to best fit |
| -[no]maximize / -[no]max | start out maximized |
| -[no]keepaspect / -[no]ka | enforce aspect ratio |
| -screen |
specify which screen to use |
| -[no]window / -[no]w | run in a window/run on full screen |
| -[no]cplog | generate viewer.log (same as -log) |
| -[no]cpverbose | Verbose CPMaker output |
| -[no]cpdebug | Debugging CPMaker output |
| -[no]verbose / -[no]v | verbose MAME output |
| -log_name |
filename for log file |
| -showusage / -su | show list of parameters and their meanings |
| -showversion / -sv | show version information |
| -animation_type |
show animation |
Image renderer options:
| -[no]imdebug | turn on ImageMagick debugging |
| -[no]silent | no log output |
| -drawslots |
draw text slots (0=none, 1=all, 2=application choice) |
| -[no]drawlabels | draw labels |
| -[no]drawcontrols | draw controls |
| -[no]dimcontrols | dim unused controls |
| -max_words_per_line |
maximum number of words per line on labels |
| -[no]justprint | Do not launch the image viewer |
| -mame_path |
path to find mame executable |
| -product |
name of product image |
Notes on command line options:
The mame_path option overrides the mamepath tag in the cpmaker.ppf.
The product option overrides the productpath tag in the cpmaker.ppf.
The image_file can currently be a png or jpg image.
Command line parameters:
| -[no]ddraw / -[no]dd | use DirectDraw for rendering |
| -[no]direct3d / -[no]d3d | use Direct3D for rendering |
| -[no]switchres | switch resolutions to best fit |
| -[no]switchbpp | switch color depths to best fit |
| -[no]maximize / -[no]max | start out maximized |
| -[no]keepaspect / -[no]ka | enforce aspect ratio |
| -screen |
specify which screen to use |
| -[no]window / -[no]w | run in a window/run on full screen |
| -[no]log | generate viewer.log |
| -[no]cplog | generate viewer.log (same as -log) |
| -[no]cpverbose | Verbose CPMaker output |
| -[no]cpdebug | Debugging CPMaker output |
| -[no]verbose / -[no]v | verbose MAME output |
| -log_name |
filename for log file |
| -showusage / -su | show list of parameters and their meanings |
| -showversion / -sv | show version information |