Creating & Using Game Modules

Author:Jeremy Stieglitz

What are Game Modules?

Game Modules are sets of scripts and media, located in a subdirectory of the application, which can be launched as a unique game. In other words, these file sets are easy to distribute & install, allowing end-users to easily mod your game (should you wish them to), or for you to easily maintain your application's media separate from the core Reality Engine files. There is considerable organizational benefit to constructing your game as a Module, and product benefit to allowing end-users to modify your game via Modules. So then, let's look at how a Game Module is created and run!

Adding Your Own Game Modules

To add your own Game Module, simply create a subdirectory within the main application directory. Give the subdirectory the desired name of your Module. So if your application directory is "C:\Reality\bin\", then your module subdirectory could be "C:\Reality\bin\MyModule\". Also, add a "Scripts" subdirectory within your module subdirectory -- "C:\Reality\bin\MyModule\Scripts\". Every Module must contain its own Scripts directory, since without any Scripts a Module would have no functionality. It's also recommended (though not required) that you add a "C:\Reality\bin\MyModule\MyModule.ini" -- name it whatever your Module subdirectory's name is -- containing some key information. Use this as a template for your ini:

// 
// Game Module Configuration: EvalKit
//

ModuleFullName = "Eval Kit"
ModuleDescription = "The Evaluation Kit's game module."
ModuleAuthor = "Artificial Studios"
ModuleWebsite = "www.artificialstudios.com"
ModuleCopyrightDate = "2005"
ModuleMediaDirectories = "EvalKit"
ModuleAssemblyReferences = ""

//-------------------------------------------------------
[InputControls]
// NOTE: Never add config settings in this block, only input mappings
//-------------------------------------------------------

TestHandle1 = l
TestHandle2 = o

Following this standard INI format will allow other Modules to easily list your Module in a GUI box. Note, as depicted here, you can add custom INI keys (and any other custom Keys) within your Module's INI, which you can then load as described in the next section. Now your Module is nearly ready to go, you just need to populate it with Scripts and Media. First, on the subject of Scripts, your Module won't have much functionality without a main menu of some sort, so we recommended, to get yourself started, that you either copy over the contents within "EvalKit\Scripts" or "EvalKit\SimpleModule" from the EvalKit fileset. Now you can create all the various media folders within your Module's subdirectory, and they will automatically be searched during corresponding Media loads. The currently supported media subdirectories are (and any number of subdirectories within them):

• Maps
• Models
• Textures
• Recordings
• Scripts
• Sounds

With this, your module is ready to go! You can run it by setting the "GameModule = MyModule" key in the RealityEngine.ini, or by using the following command line: "Reality.exe" -module:MyModule.

Advanced Game Module Features

Game Modules can rely on any number of Module main media paths, defined in the Module's INI like so:

• ModuleMediaDirectories = "EvalKit" // (this will look for media inside the EvalKit subdirectories)
  
• ModuleMediaDirectories = "EvalKit,SimpleModule" // (this will look for media inside both the EvalKit and SimpleModule subdirectories)

All modules also automatically incorporate the Scripts located in the ..\Scripts\Base directory, which includes several core scripts which are necessary for Reality to function properly.

Additionally, you can specify extra .NET assemblies to use with your Module, by delimiting them with a "," in the <nopModuleAssemblyReferences key defined in your Module INI. For instance:

• ModuleAssemblyReferences = "System.Data.dll,System.Web.dll" // (this will include extra .NET assemblies whose namespaces you can then use in your scripts)
  

Maps created in Reality Builder are tagged with the Module used at the time of their creation, and attempting to load a map created by a different Module than the one you are running will result in an incompatibility notification message. You can pre-check maps for module compatibility by running the MHelpers.IsCompatibleWithGameModule script function with the full-path filename.

You can conveniently store additional information about your module, such as custom INI keys and control handles, in your module's INI. You can access your Game Module's INI easily by using MConfigFile.ModuleConfig, and then add the Control Handles via MInput.LoadInputConfig The following code shows you how to do this:

// a couple of game input handle objects

public static GameInputHandle testHandle1;
public static GameInputHandle testHandle2;

...

// get our Module's INI and load the input handles!
MInput.LoadInputConfig(MConfigFile.ModuleConfig);
testHandle1 = new GameInputHandle("TestHandle1");
testHandle2 = new GameInputHandle("TestHandle2");

You may also find it useful to display a list of all installed Game Modules. To get a list of such Game Modules, you can simply enumerate all directories in the root that have a "Scripts" subdirectory (and presumably contain a configuration INI of the same name as the directory). Let's look at how this is done:

// handy structure to contain information about the Game Modules we find
   struct ModuleInfo
   {
      public String ModuleFullName;
      public String ModuleDirectoryName;
      public String ModuleDescription;
      public String ModuleAuthor;
   };
...

// Enumerate all installed game modules
ArrayList ModuleDirList = MHelpers.EnumerateDirectories(MConfigFile.MainConfig.GetString("SearchPath"), 2);
foreach (String dir in ModuleDirList)
{
   // Modules are never in the main Scripts directory
   String lowerDir = dir.ToLower();
   if (lowerDir.Contains("\\scripts\\"))
      continue;

   // Modules should always have Scripts subdirectories
   String scriptsDir = lowerDir + "scripts";
   if (!System.IO.Directory.Exists(scriptsDir))
      continue;

   ArrayList iniFiles = MHelpers.EnumerateFiles(lowerDir, ".ini", 1);

   // let's only add modules that have properly named INI files
   foreach (String iniFile in iniFiles)
   {
      // load the Module's INI file and store some information about it
      MConfigFile config = new MConfigFile();
      config.Load(lowerDir + iniFile);
      ModuleInfo modInfo;
      modInfo.ModuleDirectoryName = iniFile.Substring(0, iniFile.IndexOf(".ini"));
      modInfo.ModuleFullName = config.GetString("ModuleFullName");
      modInfo.ModuleDescription = config.GetString("ModuleDescription");
      modInfo.ModuleAuthor = config.GetString("ModuleAuthor");
      ModuleInfos.Add(modInfo);
   }
}

Finally, you may wish to take that array of the Modules' information and put it into an MGUIComboBox, or display it however you see fit. You can also switch modules at runtime by running the MHelpers.ChangeModule function, however keep in mind this will totally reset your application state.