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.

ROMLister -find criteria

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 check AND the joystick type are both yes, then the game is added to your 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 games 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.

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'

would limit down the shooters category to only vertical shooters, instead of the broader category of simply "shooters".

You will always see & (ands) around the various items you are looking for, because all of the items are checked against every ROM, so every ROM has meet all the criteria you specify. For example, in human speak, we might say: "I want the games that have a certain monitor type AND has a certain joystick type AND has a certain category type AND is NOT adult.
That type of speak can take a bit of getting used to, but once you start thinking that way, it'll make logical sense.

• 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!

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 below, the year of release is surrounded by the <year> </year> tags.
This query brings up any game created in 1980-1989.
If you wanted some specific years instead of a group, you'd have to list them separately:

& ( <year>1985 | <year>1996 | <year>1993)

The above would group the years 1985, 1996 and 1993 together and then filter any ROM outside of those years out of your final list.

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. All the games that MAME supports has similar data for searching. 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.

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 long, so they are hidden behind a macro to make things a little easier to read in that -find text.

Here's the macro details 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.

Return to ROMLister tutorials