CtrlrMaker by Michael Miller Version 0.1 January 30, 2003 Welcome! CtrlrMaker helps you create a full set of INI files for use with the MAME ctrlr directory feature. This first version is a simple engine. With it, you write the INI files once and the engine compiles a complete controller config directory. You'll have to do a bit of work to set up the files for CtrlrMaker to fill out. System Requirements =================== This version of CtrlrMaker was written with a relatively new version of VBScript. That means it will only run on Windows and you'll need to have Internet Explorer 5.5 (or later) or install the latest Windows Scripting Host to use it. Also, the Windows Scripting Host must be enabled. (Some people turn it off to protect themselves from VBScript viruses.) You can download Internet Explorer from Windows Update, or from here: http://www.microsoft.com/ie/ You can download just the Windows Scripting Host from here: http://msdn.microsoft.com/scripting/ CtrlrMaker may trigger warnings from overzealous AntiVirus applications. CtrlrMaker does no damage to files other than ones it creates. (It creates temporary files and deletes them after it's done, if it is told to do so.) Files ===== The sources directory contains: Copy Definition (.def) files for various emulator versions. Folders containing templates for various controller types. Each controller template folder contains: A Name Definition (.def) file for the controller type. INI Source (.insrc) files for various game types. This first version of CtrlrMaker does not include full data files. It has one incomplete controller definition ("psstick"), which is designed for a PlayStation controller with a PC Magic Box adapter. It may work with other PS->PC controller adapters; give it a try. The mame64.def file is similarly incomplete. Copy Definition Files ===================== Copy definition files contain lists of files to create from a template .INI file. It's structured like an .INI file, with sections and lists of destinations. For example: [default] default [mk] mk mk2 mk3 Tells CtrlrMaker to copy the generated default.ini to default.ini in the destination folder, and copy mk.ini to mk.ini, mk2.ini, and mk3.ini. As with all other types of files used by CtrlrMaker, you can put comments into the file by using the # symbol. Everything that follows a comment mark is ignored. # This is a comment [default] # Here we go! Name Definition Files ===================== The way the buttons are layed out in many controllers have no relation whatsoever to their representations in the emulator. A Name Definition File lets you link the controller's name (or any other name) to the emulator's name for the button. Then it's easier to fill out the templates. Names must start with a ~, and the text to replace the name with must be enclosed in quotes. You may also put comments in with #. Here's some sample lines from psstick: ~Triangle "J1_Button_0" ~Circle "J1_Button_1" ~X "J1_Button_2" # This is a test comment INI Source Files ================ These are the definitions for what keys and buttons activate which emulator button. They use the same formatting as the normal .INI files you'd put in a ctrlr subdirectory in MAME. Step by Step ============ Here's how to customize the existing directory for your controller to create a set of files for MAME: * Make a copy of the psstick directory in the sources directory off of this one. * Rename the psstick directory to the name you want for your controller. * In the new directory, rename psstick.def the same as the directory name. * Open the new .def in your favorite text editor. Here you need to define the names and button links for your controller. You can use the emulator's native control reassignment methods or the Game Controllers Control Panel for a reference. * Open each .insrc in your favorite text editor. Start searching for ~, replacing each one with the appropriate button for your controller or deleting it (and one of the leading or trailing | characters). * In the root CtrlrMaker folder, make a copy of psstick.bat. * Rename it to your directory. * Edit your new batch file. Change the "psstick" after -ctrlr to your controller directory name, and the path after -dest to where you want CtrlrMaker to put the files. (Typically the ctrlr directory in your MAME directory.) * Run the batch file from the command line and see if it works! Known Bugs ========== It can't create more than one level of folder, so make sure you pass an existing directory for -dest. Planned Changes =============== More helpful error reporting. Make a fully generic folder to use as the template, with the existing psstick as a completed example. Fill in the long list of controller types for various games, or find out how to ask for it from an external file. Is there a controls.dat or something similar being worked on? Add a script that clones an existing source folder. Turn the "engine" into a generic C++ lib that works cross-platform, and wrap it into a command line util and the appropriate scripting systems on the various platforms. (COM server on Windows and an OSAX or Application-as-OSAX for the MacOS. I don't think you'd need more than a command line util for the *nix variants.) - or (much less likely) - Rewrite the VBScript to use a lower version of VBScript. Write an AppleScript and Perl version of it for other OSes. Use the native game controller access functionality to help fill in the button name file. (Put up a list of controllers, pick one, start going through all of its controls. This would require a local util anyway.) Make the whole process GUI driven, with an example picture of what the arcade controls looked like. Wrap all of the files to make a specific ctrlr directory into a .zip. Once the app can generate everything itself (no manual editing of text files required), consider giving these zips a different extension. Version History =============== 0.1.0 - First Release. Feedback ======== Please send all comments to parody@esglabs.com. You can find the latest news and updates at http://www.esglabs.com/ctrlrmaker/ License ======= CtrlrMaker is an engine that helps generate MAME ctrlr directories. Copyright (C) 2003 Michael Miller Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.