Log In to Evolve

Time to get back to the important things in life. Like killing zombies. Capturing flags. And complaining about balance issues.

Guides

  • Learn How to Use Evolve!

Gamesdb Rules

Created: Oct 6 '12 at 1:45am • Author: mamu
The Evolve gamesdb is a set of heuristic definitions used by the client to determine if a game is running. These rules are required to support features like the overlay and playtime tracking. Unlike many other tools out there, Evolve automatically detects you are playing a game as soon as you launch the game. You don't need to launch the game through Evolve to have Evolve detect it. To make this magic happen, we have an XML database of rules that ships with the client and gets synced from the Evolve servers every so often. If you happen to have a game installed that Evolve doesn't currently support, you can help us by writing a rule for the game, adding it to your local copy of the gamesdb, verifying that the game is detected and that the overlay works, and then submitting the rule to us for inclusion in the master copy of the gamesdb. Read on for a full explanation of how rules work, and what options are available when writing rules. Be warned that, although it is straightforward, it's not trivial—please do read the entire guide.
• • • • •

Limitations

Currently, the Evolve overlay works with games using Direct3D 7, 8, 9, 10, 10.1, 11, and OpenGL. Direct3D 7 and 8 games do sometimes have issues, so please get in touch if you discover the overlay isn't working in a particular game. Evolve tracking should work with all games, including Direct3D, OpenGL, DirectDraw, SDL, and so on. If you find a game you cannot seem to track, please let us know.
• • • • •

Finding the Database

The first step in learning how to write a rule is to find the local copy of the rule database. Open up Windows Explorer and navigate to the following location:
  • Windows Vista/7/8 C:\Users\<Your Windows Username>\AppData\Local\Echobit\Evolve
  • Windows XP C:\Documents and Settings\<Your Windows Username>\Local Settings\Application Data\Echobit\Evolve
Note that the AppData directory is hidden by default in Windows. In order to get to it, you'll either need to modify your Explorer settings or directly navigate to it by pasting the whole path in to an Explorer window. Once in the %LocalAppData%\Echobit\Evolve directory, you should see a file called gamesdb.xml--the rules database. It should look something like this: Note: The gamesdb.xml file is volatile! While the client is running, every 4 hours, it will attempt to sync gamesdb.xml against the master copy on the Evolve servers. Any changes you have made to the file in the %LocalAppData%\Echobit\Evolve directory will be overwritten if the master copy is detected as having been updated.
• • • • •

Anatomy of A Rule

Now that you have gamesdb.xml open, you're probably freaking out at the complexity of the rules in front of you. Don't panic. Let's examine an individual rule—in this case, the rule for detecting Heroes of Newerth:
<game>
	<id>37</id>
	<name>Heroes of Newerth</name>
	<conditions>
		<cond name="is-hon-exe-present" type="exe-present" exe="hon.exe"/>
		<cond name="has-textures-s2z" type="file-present" file="{exedir}game\textures.s2z"/>
	</conditions>
	<detection>
		<variant order="1" name="default">
			<if cond="is-hon-exe-present"/>
			<if cond="has-textures-s2z"/>
		</variant>
	</detection>
</game>
Rules are wrapped inside an outer <game> node, which is in turn wrapped in the root node for the file, <games>.

<id>

The first node inside a rule is <id>. The ID represents a 32-bit integer used by our servers to identify the game. If you're adding a rule for a new game, you should use an ID greater than 9999. Our submissions system will automatically tag it with the proper ID when we accept your proposal. If you're adding a rule for a game that already exists on the Evolve website, you may find the ID for the game by visiting the games library and looking at the URL for the edit tab. The URL for Heroes of Newerth edit tab is as follows: /games/-/id/37/submissions. As you might have guessed, the 37 in the URL represents the ID of the game.

<name>

The next node inside a rule is <name>. The name should match the name used in the games library on the website. It's included primarily as a way to make it easier to know which game a given rule is for—but please do make sure to include it. Note that name values with ampersands in them must contain the entity escaped version of the ampersand: &amp;In our example rule above, the game name is (surprise, surprise) Heroes of Newerth.

<conditions>

The <conditions> node contains a set of <cond> nodes that define various conditions used to determine if a supported game has been launched. A <cond> of the type exe-present is required in all rules. At least one additional condition is needed to weed out false positives or games that have identical executable names. All games must include at least two conditions, the second preferably being a file-present condition for a likely unique file in the game directory. Note that rules can have as many conditions as are necessary. Each <cond> node inside the <conditions> node has a name. The name is used to reference the condition later, in the <detection> node. Pick a name that's all lowercase and uses hyphens to separate words. The name must be unique within the scope of the particular <game> node. Each <cond> also has a type. The type indicates what kind of a condition the <cond> is. The most commonly used types are:
  • exe-present — Required. Detects the presence of a game executable. The exe attribute should be set to simply the name of the game executable. In cases where a game has multiple executables, multiple exe-present conditions should be added—one for each game executable. The best way to determine the executable name is to open the Windows task manager after getting into the game proper and looking for something that's using a lot of RAM and CPU. That's almost always the game executable.
  • file-present — Detects the presence of a file. {exedir} must be used at the start of the file attribute to act as a placeholder for the directory in which the game executable lives. The rest of the file attribute should then be relative to that directory. Note: Please do NOT create file-present entries referencing readme files, DLLs, icons, or exe files EXCEPT in the rare cases where there are no other options.
  • file-absent — The inverse of file-present. Causes detection to fail if the specified file path is found. Needed only in the rare cases where file-present isn't enough.
  • arg-present — Detects the presence of a command line argument. The following arg attribute defines the name of the argument that should be detected in the game executable's command line, and should include any hyphens or slashes. Wildcard placeholders can be specified using asterisks, *.
  • arg-absent — The inverse of arg-present. Causes detection to fail if the specified arg attribute is detected in the game executable's command line. Needed only in the rare cases where arg-present isn't enough.
In the case of Heroes of Newerth, the only two conditions defined are a file-present condition that checks for the presence of a file named textures.s2z in the game subdirectory and an exe-present condition that checks for hon.exe. It's highly unlikely any other game would utilize such a file and exe combination, and thus these two conditions makes it extremely likely that the game is indeed Heroes of Newerth.

<detection>

The <detection> node contains a set of <variant> nodes that act as boolean OR operators toward one another. As long as one <variant> evaluates to true, the whole detection rule will also evaluate to true. Every <variant> node must include an order attribute. The order must be a positive integer. Variant orders define precedence for the variant--if one variant is the most common, it should be given an order of 1. Every <variant> node must include a name attribute. Variant names are used as internal references to support various client features and generally make rules easier to read. In almost all straightforward rules, only one variant is necessary—and should be named simply "default." For rules covering games with separate executables for DirectX 9 and 10/11, or rules covering games with separate executables for 32-bit and 64-bit systems, we suggest naming the respective variants things like "dx9," "x64," and so on. Each <variant> node contains child <if> nodes. The <if> nodes reference a <cond> name from the <conditions> node. Each <if> node is evaluated as a boolean AND with the other <if> nodes present in a given <variant>. In the case of Heroes of Newerth, as there were only two <cond> nodes defined, there is only one <variant> with two <if> nodes defined. One <if> checks if the textures.s2z file is indeed present, while the other <if> checks if the running game exe is called hon.exe. Examples:
<detection>
	<variant order="1" name="default">
		<if cond="is-hon-exe-present"/>
		<if cond="has-textures-s2z"/>
	</variant>
</detection>

<features>

The <features> node, unlike all the other main nodes listed in bold above, lives under the <runtime> node, which in turn lives under the <game> node. It contains a set of individual feature nodes that override default feature settings for the client. The current features are:
  • <overlay> — By default, the overlay is enabled for all games. Setting the enabled property to false prevents the overlay hotkey from inadvertently capturing input for games in which the overlay doesn't work.
  • <forcebind> — By default, forcebind is disabled for all games. Setting the enabled property to true forces the game to bind to all available network adapters when launched. If a game only binds to a single adapter, there's a good chance it won't bind to the Evolve party adapter, thus preventing the game from working over Evolve's party system—forcebind fixes this issue.
  • <forcetopmost> — By default, forcetopmost is disabled for all games. Setting the enabled property to true forces the game window to remain topmost at all times, preventing odd cases where the desktop client windows actually appear on top of the game window. These cases typically happen with games that use a faux-fullscreen mechanism for rendering. Note that this should not be enabled for games like World of Warcraft, which have optional faux-fullscreen settings available in the game's config.
  • <forcerenderer> — By default, Evolve automatically detects the renderer in use by a game when it launches. In certain rare cases, a game loads two renderers simultaneously, making our automatic detection fail. In cases such as these, the forcerenderer feature should be added with its type set to either Direct3D or OpenGL.
  • <forcecursor> — By default, Evolve uses a hardware cursor in all games. Unfortunately, for certain games with overzealous anti-cheat, this fails to work properly. In such cases, the forcecursor feature should be added with its type set to software.
Examples:
<runtime>
	<features>
		<overlay enabled="false" />
	</features>
</runtime>
<runtime>
	<features>
		<forcecursor type="software" />
		<forcetopmost enabled="true" />
	</features>
</runtime>
• • • • •

Writing Your Own Rule

Now that you know a bit about how detection rules are written, it's time you tried writing your own. Use the previous section as a reference while you write your first rule. When in doubt, try modeling it off of an existing rule such as the rule used as an example above. If you're having trouble, get in touch with a member of the Evolve staff and ask for help. We can take a look at your rule and offer suggestions as to why it might not be working and what you can do to fix it.
• • • • •

Testing Your Rule

Once you write the rule, you should add it to the bottom of the <games> node in the gamesdb.xml file. To get the client to load your rule, open the client console via the help menu in the main window and enter the gamesdb reload command. You should see output indicating the number of games loaded. If this number is 0, it's likely you have introduced a typo in the gamesdb file. Now that the rule has been loaded by the client, it's time to test the game and make sure that the client properly detects the game and that the overlay works correctly in the game. Launch the game for which you wrote the rule, hit the overlay hotkey, and once the overlay appears, try dragging windows around, clicking on buttons, opening a chat window, and so on. If the overlay fails to appear when you hit the overlay hotkey, it's likely that the game is DirectX 7, 8, or is OpenGL. It is also possible that you wrote your rule incorrectly, so take another look at it and see if anything seems out of place. Even if the overlay isn't available and must be disabled, you will be able to observe if your rule is working by looking at the bottom of your friends window for the following message: "Unverified: Playing [game name]" -- if present, the rule can be considered working. Note: If you corrupt the format of your local gamesdb.xml file, you can resync it. To resync a corrupted gamesdb.xml file, use the gamesdb resync command in the console. Keep in mind that this will wipe out any changes you've made to the file, so please back up any local rules you may be working on before you run the command.
• • • • •

Submitting Rules

If the rule works well, your game is properly detected, and the overlay is set to enabled or disabled depending on your testing observations, it's time to submit your rule to the Evolve staff. Currently, there is no official rule submission process. Simply post the individual rule (not the whole gamesdb.xml file) to the game proposals system on the site -- https://www.evolvehq.com/games/-/submissions -- and we'll examine the rule and get back to you. Please post rules for games that don't exist yet at all on the service as proposals, and rules for existing games as edits on that game's profile on the site (there's an edit tab on the right side of game profiles). Our submission system keeps track of who submitted rules. If your submission is accepted, you'll see your name up in lights in the contributors box at the bottom of the game profile's sidebar on the website. Good luck, and thanks for helping us improve Evolve!

39 Comments

DaWulf   Member

  • Joined Aug 15 '12
  • 9 Posts
Maybe can make a Wizzard to make it easy?
...

mamu   Admin   Helix

  • Joined Oct 11 '10
  • 2,192 Posts
DaWulf posted:
Maybe can make a Wizzard to make it easy?
Writing rules isn't terribly difficult. The guide is lengthy to try cover every single edge case, but most rules are very straightforward. We're unlikely to create a wizard as we receive rule submissions regularly enough that it wouldn't provide much value relative to the difficulty it making it work for every strange title out there.
One of the three crazy co-founders

StealthyHidraga   Member

  • Joined Sep 13 '12
  • 8 Posts
Quote: "Each <if> node is evaluated as a boolean AND with the other <if> nodes present in a given <variant>." So this means even if there is more then one <if>, then it counts as one boolean?
Thanks to mamu now I can use this account: https://www.evolvehq.com/players/hidraga That means I will not use this one anymore.

mamu   Admin   Helix

  • Joined Oct 11 '10
  • 2,192 Posts
Think of the logic this way: <if> AND <if> AND <if> <variant> OR <variant>
One of the three crazy co-founders

Bloodrassil   Member

  • Joined Jan 18 '13
  • 1 Posts
If a rule is accepted, but not applied for days (whereas in the edit it is said "4-6 hours"), should I be worried or is it normal and you need some time to apply it?

ThE_MarD   Member   Helix

  • Joined Jul 27 '11
  • 785 Posts
Bloodrassil posted:
If a rule is accepted, but not applied for days (whereas in the edit it is said "4-6 hours"), should I be worried or is it normal and you need some time to apply it?
Heyyo, Usually once a rule is accepted give it a week or two if the code doesn't show up in the gamesdb.xml. It's two separate approval paths. One for the code submission and another for the code to be added to the gamesdb.xml. One thing this tutorial doesn't really cover is recommended programs used for editing. I myself use NotePad++ cause it's free and does XML parsing perfectly. http://notepad-plus-plus.org/ [EDIT1] Also? If you can't find out what argument is used when launching a game? Process Hacker 2 is fantastic for that. http://processhacker.sourceforge.net/
Edited by ThE_MarD Apr 16 '13 at 1:47am
Later-a-Much and LONG LIVE THE D! ThE_MarD

Marcelloz   Member   Helix

  • Joined Oct 11 '12
  • 60 Posts
Somehow I got a few games from Mambo Jambo (e.g. Samantha Swift and the Golden Touch \ Midnight Mysteries) that are started using an exe file, but then switch over to a game.dmg file that keeps it running (according to the task manager). Never seen it before, but it keeps Evolve from detecting the game as you need an .exe file in the detection rules. Any suggestions?
PC setup: Windows8-x64 | GTX770 | 16Gb RAM

ThE_MarD   Member   Helix

  • Joined Jul 27 '11
  • 785 Posts
Heyyo, Actually, you can use any file since it's an executable file just smartly hidden via extension. Some games like Lineage use .bin files. ;)
Later-a-Much and LONG LIVE THE D! ThE_MarD

ThE_MarD   Member   Helix

  • Joined Jul 27 '11
  • 785 Posts
Heyyo, Another thing this tutorial needs is how to determine if you Evolve's party mode will work. Dreijer actually gave me this tip on how to check and if forcebind is needed. Start a Party > Start the game > go into the LAN portion and create a multiplayer game Once that's done? go into command prompt on your PC (Start > All Programs > Accessories > Command Prompt) and enter..
netstat -a -b
Once that's done? look for the game's .exe file and see if the IP shows as either 0.0.0.0 or 10.x.x.x which would mean it works. If it does not show up as either? gamesdb.xml file and try to add the forcebind feature as described above and reload_gamesdb > restart the game and try the netstat -a -b in command prompt again.
Later-a-Much and LONG LIVE THE D! ThE_MarD

LilTufty   Member

  • Joined Feb 19 '14
  • 1 Posts
The Evolve Client doesn't seem to be detecting the game State of Decay. It says in the Games section that the overlay and track are supported. :/

PowerfulKyurem   Member

  • Joined Mar 9 '14
  • 97 Posts
Hi. I am trying to make a rule, but I am unsure of where to put the code in the file. I noticed a tag that says checkpoint and a number right before the closing games tag. Should that come before or after my rule? Also, how do I determine if a game is opengl or Direct3D? Is there some kind of test? I know the game was made in Game Maker. The only thing I know about it's 3d is that its functions all have "d3d" at the beginning. I'll take a wild guess, and say those are direct3d, but not everyone knows that. Also, the testing portion of the guide is a little vague. Not everyone knows how to bring up the overlay. I had to go through my settings to find the hotkey. It's a little obscure. I wasn't even aware of its existence until this pointed it out.

mamu   Admin   Helix

  • Joined Oct 11 '10
  • 2,192 Posts
PowerfulKyurem posted:
Hi. I am trying to make a rule, but I am unsure of where to put the code in the file. I noticed a tag that says checkpoint and a number right before the closing games tag. Should that come before or after my rule?
You should put it just before the closing games tag. It's the easiest place for you to find it again if you need to make changes before submitting it.
PowerfulKyurem posted:
Also, how do I determine if a game is opengl or Direct3D? Is there some kind of test? I know the game was made in Game Maker. The only thing I know about it's 3d is that its functions all have "d3d" at the beginning. I'll take a wild guess, and say those are direct3d, but not everyone knows that.
You shouldn't need to worry about this--as the guide points out, we automatically detect which rendering pipeline is in use. You only need to manually override it in your rule if the automatic detection doesn't work. Seeing as there are only a handful of games in the 3000+ we support that we don't detect the rendering pipeline correctly, the game in question is probably just fine.
PowerfulKyurem posted:
Also, the testing portion of the guide is a little vague. Not everyone knows how to bring up the overlay. I had to go through my settings to find the hotkey. It's a little obscure. I wasn't even aware of its existence until this pointed it out.
We hadn't thought of that before! Evolve does show a toaster by default on game launch indicating there's overlay support and telling you which hotkey you've bound. I'll add a note to the guide about that. Make sure you indicating in your submission author notes field that you've verified the rule works, by the way (you could simply say you've tested it in game, and it worked fine).
One of the three crazy co-founders

PowerfulKyurem   Member

  • Joined Mar 9 '14
  • 97 Posts
I still have a bit of a problem. I'm not entirely sure how the overlay works. :p I pressed the button, but nothing appears. What does the overlay look like? Could you add some screenshots, so people know what to look for? EDIT: You should change the tutorial to let people know that it only appears in full screen.
Edited by PowerfulKyurem Mar 27 '14 at 8:28pm

AwesomeDan   Member

  • Joined Jul 8 '14
  • 9 Posts
Hello, I'm confused. I'm trying to rewrite the rule for the game Super Smash Bros. Crusade so that it works again, since it's broken because of the v0.9 update of the game. I wrote (at least attempted to write) the rule, but it doesn't work. What did I do wrong? The rule:
<game>
    <id>3173</id>
    <name>Super Smash Bros. Crusade</name>
    <conditions>
	<cond name="is-crusadepatch2-exe-present" type="exe-present" exe="{exedir}New folder\SSB_Crusade_v09Patch2\SSB Crusade v0.9 Patch\CrusadePatch2.exe"/>
	<cond name="has controls-ini" type="file-present" file="{exedir}New folder\SSB_Crusade_v09Patch2\SSB Crusade v0.9 Patch\controls.ini"/>
    </conditions>
    <detection>
	<variant order="1" name="default">
	    <if cond="is-crusadepatch2-exe-present"/>
	    <if cond="has-controls-ini"/>
    </detection>
    <features>
	<overlay enabled="false"/>
    </features>
</game>
What I did so far: - Put it within the <games> tag. - Follow all the directions (unconfirmed).
Edited by AwesomeDan Oct 15 '14 at 7:56pm

CoolMan1342   Member   Helix

  • Joined May 25 '12
  • 107 Posts
I mean if you can see the error from looking at the two arguments in the rule you'll be fine. Well you'd better get back to updating the rule sooner or later hopefully, since I don't think anyone has "fixed" it yet.
..<cond name="has controls-ini" type="file-present" file="{exedir}New folder\SSB_Crusade_v09Patch2\SSB Crusade v0.9 Patch\controls.ini"/>
...<if cond="has-controls-ini"/>