Grid Motorsports Client Software

IMPORTANT!

Please note that the installation path MUST NOT be the root directory of rFactor, or really any directory that already has content in it -- the installation must be pointed to a new directory (i.e. one that the installer itself creates).  The installer will default to use 'GameData\Vehicles\GridMotorports' inside rFactor.  There are almost no circumstances in which you'll want or need to change this.

Inquiries/Support

Please direct all inquiries regarding this program to help@gridmotorsports.com.  If you're experiencing problems with the installation or operation of the software, please review the support information.

Note that our issue tracker is also available for browsing.

Description

Grid Motorsports is a program that facilitates customization of rFactor for the purpose of participating in a sim-racing league environment.  In particular, it is configured by default to support the GMWC league (though it can be reconfigured to support other leagues).  The program masquerades as a normal vehicle mod for rFactor.

Disclaimers

• Use at your own risk.  You know the drill.
  
• The content included in this mod is intended for the win32 version of the game rFactor.
• There are likely some issues associated with use of the software on Windows Vista.  We don't currently have a Vista system available for QA purposes.
  

Download

There are two installers: a full install and a minimal (bootstrap) install.  You don't need both, just one or the other.  The full installer is probably the fastest way to get going, particularly if you use one of the better mirrors we have available.  The bootstrap install is a very small download initially, but it has to then fetch the majority of the GM content on its own, over our dedicated rsync connection, so it doesn't really save you anything in terms of downloading, plus it has to build the mod before you can use it in rFactor, whereas the full installer is ready to go right out of the box (though it won't be consistent with the latest league updates).
 

Download the full installer (~120MB) from one of the following mirrors:

codeen.org

Main download link.

S3 Amazon.com Bittorrent

A bittorrent directed through Amazon's S3 service.  You can save us money by using bittorrent.  And stick it to the man as well!

S3 Amazon.com Standard

Standard download directed through Amazon's S3 service.  This one costs us lots of money, based on bandwidth.

OR... download the bootstrap installer (~10MB)

Installation

1. Run the installer and follow the instructions.  Be sure to direct its installation into the GameData\Vehicles\GridMotorsports subdirectory of your rFactor installation (which it should find automatically - something like 'C:\Program Files\rFactor', or C:\games\rFactor).  Note that it will automatically apply 'GameData\Vehicles\GridMotorsports' to the installation destination, unless you change it (which you generally shouldn't).
   
2. Run the Grid Motorsports Mod Manager (you'll have a shortcut for it after installation, or select it from within the programs list in the windows start menu).
3. If you used the bootstrap installer, the client will detect the situation, and will prompt you to conduct the update process.  Note that the bootstrap installer only provides just enough of the program to allow it to update itself -- in order to build/configure/use the mod, you have let the program conduct an initial update which will fetch and install the remaining parts of the program (more detail on this procedure is provided below).  If you used the full installer, then you're ready to use Grid Motorsports, though you are still encouraged to go ahead and conduct an initial update, since even the full installer won't include the latest league updates (which change every week).
   
4. The program will restart itself twice during the update procedure - this is normal.  It should progress normally, and will show you its log window during the procedure so you can observe.
5. Once it finishes (presumably successfully), you should see the green status light on the left side of the client illuminated.  This indicates that your installation of Grid Motorsports is complete and furthermore that it is fully updated to be consistent with the latest version and configuration available.
   
6. Start rFactor (you can launch it directly from the GM client).
7. From within rFactor, select 'Grid Motorsports' as the race series, purchase one or more cars (there's no price limit preventing you from trying any of them).
   
8. Enjoy!

Synchronization Process

1. Whenever you start the GM client, the program will check the official server to determine if (a) any new updates are available and (b) whether your current configuration/version of the mod is consistent with the official configuration/version that is being used for league events.  After it finishes this check, one of the 3 colored status indicators on the left of the program will be illuminated (see the image above).  Each one indicates a different situation.  Green means that you're ready to connect to official GMWC servers.  Yellow means that you're able to use the mod as it is currently built/configured on your system, but it is inconsistent with the current official league configuration.  Red means that the mod is not currently in a usable state on your system.
2. If the status is either yellow or red, you should probably initiate an update.  Switch to the 'Update' tab, review the available options (the defaults are fine) and when you're ready,  click on the 'Update' button.
   
• This will initiate the update and build process, which can be lengthy for an initial bootstrap install, as it will have to first download much of the content that is not included in the bootstrap installation, and from that will need to generate all of the additional client-side mod content (the most time-consuming of which is creating some procedurally generated skin textures).  For a normal update (i.e. generally any update after the initial one) the entire process shouldn't take more than a few minutes.  The changes from update to update tend to be small, and so they download quickly and the mod is able to be rebuilt/reconfigured quickly.
  
• Just be patient and allow it to do its thing.  You'll be able to monitor the progress via the log window in the GUI.
• Note that the program will restart twice during this process and resume automatically.  That is normal and necessary.
  
• If there are any issues or errors, or you think something has gone awry, please make note of the particular message and circumstances and use any of the methods described above (in the Inquiries/Support section) to communicate the issue to us.
  
3. Eventually, the process will complete and the mod will be fully installed and usable.  You'll see something like 'Successfully generated GridMotorsports mod.  Enjoy!' in the log window, along with a summary of the version/configuration information for both your install and the official server.

Anatomy of the update and build process (for the curious)

The GM client application is used for the bootstrap installation and for updating the mod on a regular basis.  It utilizes several tools to accomplish incremental, anonymous, one-way directory hierarchy synchronization and client-side mod customizations. That's just a fancy way of saying that instead of downloading a giant zip file, the mod content is actually exposed as a repository on a server, which is then accessed by a tool that knows how to talk to the server to retrieve each individual piece of the repository. The cool thing is that once you've done this once, any subsequent updates to the mod can be obtained trivially via the same method, and the only parts that you'll actually download will be the new parts.  Furthermore, the manager enables you to customize the mod in a number of ways, allowing you to apply your own personal preferences without having to download multiple versions of the mod (which typically isn't even an option in the first place with most mods).

The following is a list of the major tools we've assimilated to provide this functionality:

• rsync: rsync provides the means of efficiently synchronizing the contents of a local directory to that of an rsync repository available over TCP/IP. Note that we're actually 'synchronizing', in the customary rsync manner, which means we do delete local files that reside within the target directory hierarchy, if those files aren't consistent with the contents of the server.  Normally, this won't affect you unless you manually put other files inside the 'GridMotorsports' directory.  Such files would get deleted when you update the mod.
• cwrsync: rsync is a unix tool, so we needed a win32 version of it, which is provided by cwrsync. This is basically just a a win32 build for rsync, along with some ssh related tools.
• cygwin: cwrsync utilizes the cygwin DLL to replicate the necessary unix libraries in win32.
• UTF8-cygwin: unfortunately, cygwin has yet to join the 21st century and provide unicode support, which is crucial to this effort. So, we've supplanted the cygwin.dll that is provided with cwrsync with a version from okisoft, which is UTF8-enabled. Hopefully, cygwin will get its act together in the near future and this customization will no longer be required.
• python: a terrific cross-platform scripting language.  The GridMotorsports mod is, well, 'modular'.  There's a post-installation step that (re)generates a set of (customized) vehicles.  We've done this for the following reasons:
  

• rFactor's mechanism for associating skins with vehicle models with teams is horribly busted and short-sighted.  Yes, it is.
  
• By separating the heavyweight pieces of the mod content (skins & vehicles) and the actual configuration of the mod's vehicles, we regain the flexibility that is lost with rFactor's design.
• We enable dynamic reconfiguration of the vehicles/teams without requiring you to re-download all of the big pieces (skins, etc..).
• This dynamic configuration is accomplished via a python-based GUI application.
• wxwidgets: *the* preferred library to use for cross-platform GUI application development.
• wxpython: *the* preferred manner of using wxwidgets.
  
• py2exe: however, since we don't want to force people to install python just to use the mod, we've leveraged this excellent little utility that converts a python script into an executable file that can be run on MSWindows.  Good job, you crazy internet guys!