Modding:Key Mapping (Commands)

This page is about modding. See the modding overview for an abstract on modding.

For best results, it's recommended to have read the following topics before this one:

• Modding:C Sharp Scripting

Mods can add custom key mapping entries to the Key Mapping menu.

Players can then bind a key to the mod's custom command.

When the player presses that key, the mod's custom command is received as an event on the player character. This means that at least a small amount of C# scripting is required to take advantage of the key mapping infrastructure.

Define Key Mapping Options

A mod defines its custom key mapping options in a Commands.xml file. Here's an example file that defines two commands.

<?xml version="1.0" encoding="utf-8"?>
<commands>
  <command ID="ModName_Cmd_One" DisplayText="My Custom Debug Command" Category="Debug"></command>
  <command ID="ModName_Cmd_Two" DisplayText="My Custom Cool Command" Category="Cool"></command>
</commands>

In this case, we've added one command to the existing "Debug" category in the Key Mapping menu. We've added another command to a new category - the "Cool" category. Here's how it looks in game:

Creating a Part to Listen for the Command

Create a part to listen for your Key Mapping command on the player.

using System;

namespace XRL.World.Parts
{
    [Serializable]
    public class ModName_CommandListener : IPart
    {
        public static readonly string CmdOne = "ModName_Cmd_One";
        public static readonly string CmdTwo = "ModName_Cmd_Two";

        public override void Register(GameObject Object)
        {
            Object.RegisterPartEvent(this, CmdOne);
            Object.RegisterPartEvent(this, CmdTwo);
            base.Register(Object);
        }

        public override bool FireEvent(Event E)
        {
            if (E.ID == CmdOne)
            {
                //Do something when the keybind for ModName_Cmd_One is pressed!
            }
            if (E.ID == CmdTwo)
            {
                //Do something when the keybind for ModName_Cmd_Two is pressed!
            }
            return base.FireEvent(E);
        }
    }
}

Adding the Part to the Player

Add your part to the player when a New Game is started. This section uses the method described in the Modding:Adding_Code_to_the_Player article. Refer to that article for more information, including how you can also add your part to the player when an existing save game is loaded.

  using XRL;
  using XRL.World;
  
  [PlayerMutator]
  public class ModName_PlayerMutator : IPlayerMutator
  {
      public void mutate(GameObject player)
      {
          // add your command listener to the player when a New Game begins
          player.AddPart<ModName_CommandListener>();
      }
  }

Shipping Your Mod

Your completed mod should look like this. For more info about the proper Mods directory location, see File locations > Offline mods.

<Caves of Qud App Directory>
    Mods
        MyModFolder
            Commands.xml
            ModName_CommandListener.cs
            ModName_PlayerMutator.cs