RL tutorial Advanced Searching
ROMLister is a search tool. The fun part is that you can search for an unlimited number of items, and group those items any way you'd like to.
You may have noticed when playing around with the checkboxes on the main page that the text on the bottom of the screen changed as you clicked various options.
That text in the -find window is what gets sent into the search engine. Any ROM that meets all of the criteria supplied, gets put into the output list.
Let's examine a simple search query of
Any game that is 3 buttons or less, and uses an 8-way joystick
The following text is what gets built by the application when you select 8way stick and change the buttons dropdown to 3: (yeah, there's a little more text, but this is the core of this part of the search.
(buttons=3 | buttons=2 | buttons=1 | buttons=0) & joy8way
Here's the same query in slightly more human-readable format:
( buttons=3 OR buttons=2 OR buttons=1 OR buttons=0 ) AND joy8way
Remember back in math class with order of operations? (sorry to bring up that subject!) You do stuff in the parenthesis first, then take the results of that "group" and continue working through the problem. Same deal here.
In this example, ROMLister will check each game and see if it is a 3,2,1 or 0 button game. If it is, then it checks to see if the game uses an 8-way joystick. If the results from the button group AND the joystick type are both yes, then the game is added to the output list. If either the game is more than 3 buttons, or the game is not 8-way, then it doesn't get added. This search criteria is checked against every game, and only the ones that match are outputted to your working list.
So, with ROMLister, you can put as many of these search parameters as you want in, and you can build up some pretty unique searches. The checkboxes on the main window will do most of the work for you, but you can always go in and tweak things til your heart's content. Because the possible search items is nearly limitless, and the combinations of search items can be grouped in any way, there is no way all the possibilities can be represented with drop-down lists or checkboxes-if you want something complex, you need to do it by hand by editing the -find options yourself. Don't worry, it's not that hard to do.
- Note: Once you start changing the -find text by hand, if you click on any of the checkboxes on the main interface, it will overwrite (trash) anything you've typed in, so be careful!
Keep the following key in mind: & means AND. | means OR. ! means NOT
For a grouping of text, you can use ' (single quotes) around the text, for example 'Flying Vertical' could limit down the shooters category.
Let's go back to our search from above for 3 buttons or less and an 8way joystick.
Now let's put a filter on the results to remove all the vector based games.
To remove vector graphics monitors from showing up, all we need to do is add "& !vector" to the -find list.
Close the working list and start over again, this time add:
(buttons=3 | buttons=2 | buttons=1 | buttons=0) & joy8way & !vector
That should reduce the number of games by a few.
Let's also take out the games that don't support save states. The tag for that is 'savestate="unsupported"'
ROMLister ignores quote marks, so just add it like this:
(buttons=3 | buttons=2 | buttons=1 | buttons=0) & joy8way & !vector & !savestate=unsupported
Let's do another one. How about only the classics? Close your working list and add:
& <year>198
to the end of your query. If you notice in the example XML above, the year of release is surrounded by the <year> </year> tags.
This query brings up any game created in 1980-1989.
So how do I know what things can be searched on?
The stuff that you can search on is specified by the input XML file. double clicking any ROM name in your working list will display that game's XML data. Here's the data for puckman:
<game name="puckmana" sourcefile="pacman.c" cloneof="puckman" romof="puckman"> <description>PuckMan (Japan set 2)</description> <year>1980</year> <manufacturer>Namco</manufacturer> <category>Maze</category> <controls info>numPlayers="2" alternating="1" mirrored="1" usesService="0" tilt="0" cocktail="1"</controls info> <player number="1" numButtons="0"> <controls> <control name="4-way Joystick"> <constant name="joy4way"/> </control> </controls> <labels> <label name="P1_JOYSTICK_RIGHT" value="Right"/> <label name="P1_JOYSTICK_LEFT" value="Left"/> <label name="P1_JOYSTICK_DOWN" value="Down"/> <label name="P1_JOYSTICK_UP" value="Up"/> </labels> </player> <chip type="cpu" name="Z80" clock="3072000"/> <chip type="audio" name="Namco" clock="96000"/> <display type="raster" rotate="90" width="288" height="224" refresh="60.606061" /> <sound channels="1"/> <input players="2" buttons="1" coins="2"> <control type="joy4way"/> </input> <dipswitch name="Rack Test (Cheat)"> <dipvalue name="Off" default="yes"/> <dipvalue name="On"/> </dipswitch> <dipswitch name="Service Mode"> <dipvalue name="Off" default="yes"/> <dipvalue name="On"/> </dipswitch> <dipswitch name="Cabinet"> <dipvalue name="Upright" default="yes"/> <dipvalue name="Cocktail"/> </dipswitch> <dipswitch name="Coinage"> <dipvalue name="2 Coins/1 Credit"/> <dipvalue name="1 Coin/1 Credit" default="yes"/> <dipvalue name="1 Coin/2 Credits"/> <dipvalue name="Free Play"/> </dipswitch> <dipswitch name="Lives"> <dipvalue name="1"/> <dipvalue name="2"/> <dipvalue name="3" default="yes"/> <dipvalue name="5"/> </dipswitch> <dipswitch name="Bonus Life"> <dipvalue name="10000" default="yes"/> <dipvalue name="15000"/> <dipvalue name="20000"/> <dipvalue name="None"/> </dipswitch> <dipswitch name="Difficulty"> <dipvalue name="Normal" default="yes"/> <dipvalue name="Hard"/> </dipswitch> <dipswitch name="Ghost Names"> <dipvalue name="Normal" default="yes"/> <dipvalue name="Alternate"/> </dipswitch> <driver status="good" emulation="good" color="good" sound="good" graphic="good" savestate="supported" palettesize="512"/> </game>
Anything in the above text can be a search parameter. You've got screen orientation, screen refresh rate, resolution, joystick/control types, emulation status, cocktail support, manufacturer, year of release, category, clone or parent, even actual ROM names. You can pick anything in there to search on, and combine multiple searches into a single query.
How about adding individual games?
Perhaps there's a game you're thinking of that didn't show up in your query. You could adapt your -find query to include it, or a simpler method is to click on the "list all ROMs" from the main romlister window and it will generate a complete list of all the known games. From that list, just right-click on any game(s) you want in your list and select "add to your list" and it will throw that ROM over to your working list.
Macros
If you've played with the region selection, you may have noticed that ROMLister adds only a bit of text in the -find window, something that looks like this: @USA @ASIA or @JAPAN
Those are macros. Included in the ROMLister distribution package is a file called rlmacros.txt. It needs to be in the same folder as ROMLister itself to work properly. All ROMLister does is expand out the @USA with the corresponding data from rlmacros.txt. The region macros are pretty crazy and long, so they are hidden behind a macro to make things a little easier to read in that -find text.
Here's the macros for @USA:
@USA = ( ' USA ' | '(USA ' | '(USA, ' | 'USA (Japan)' | 'USA (Japan, ' | '(JPN, USA, EXP, KOR, AUS)' | '(USA)' | '(International/Japan)' | '(US)' | '(US?)' | '(US,' | '(US ' | '(Europe / USA / Japan / Asia) ' | ', US' | '(World)' )
Crazy eh? It doesn't even fit on the screen!
You can most certainly add your own macros or edit the ones that are supplied for regions. The formatting is really quite simple; it's just:
@macro name = search text
Notice how there are search parameters with only a single parenthesis in them. Any search item like that has to be inside single quote marks, so RL treats that string as a single element. Without the quote marks, RL would think those parenthesis are part of a grouping. Notice also that the entire macro itself is grouped inside a pair of parenthesis, so that it is treated as a single yes/no as each game is processed through it.
