Handling mods

From Running With Rifles Wiki
Jump to: navigation, search

How to obtain a mod from Workshop?[edit | edit source]

  • Go to [1] or access RWR's Workshop in Steam client
  • Browse the shop for mods you wish to try
  • Access a mod page and click on Subscribe - Steam will begin downloading the mod content
  • Once downloaded, the mod shows up in the game in either Start new Campaign menu or Start Quickmatch menu in Setup mods -- depends on the mod
    • Generally mods are encouraged to be made as campaigns, look there first unless described otherwise
  • Alternatively, if you attempt to join an online game using Workshop content, the game offers you to subscribe to the mod
    • Accepting subscription, Steam begins the download and once done, the game will let you attempt joining the server again

How to upload a mod to Workshop?[edit | edit source]

  • See the Workshop upload tool post on the forum [2]

How to create a mod?[edit | edit source]

Simple mod[edit | edit source]

Just want to make a simple mod for testing weapons, models, sounds etc. without dealing with all that other stuff? Here's a quick guide:

  • Find your RWR install folder
  • Go to the media/packages folder.
  • Create a new folder with your mods name.
  • Inside that create a file called package_config.xml and paste this into it, edit as needed and save.
<?xml version="1.0" encoding="utf-8"?>
    name="Your mods name here"
    description="Your mods description here"
    show_in_quick_match_mods = "1">

  • Now you are ready to add your modded files. Make sure you mirror the folder structure and naming of vanilla files and your modded files will be loaded instead.
  • General mod types
    • Campaign mod - appears in Start new Campaign menu (preferred)
    • Quickmatch - appears in Quickmatch mod list
      • usually used for testing content in various maps, or testing custom maps
    • simply content for other mods
      • models, sounds, weapons, vehicles, items, factions, maps, etc
      • in most cases can't be played directly, needs a Campaign or Quickmatch mod to utilize the content
        • only exception is maps; if the map allows it, the map will show up among the maps in Start Quickmatch menu
  • Create a local folder for your mod
    • Locate where RWR is stored on your system
      • On Windows, most of the time it's at C:\Program Files\Steam\SteamApps\common\RunningWithRifles
      • Linux: TODO
      • Mac OSX: TODO
    • Create a new folder in the RWR folder, in subfolder media/packages, e.g. media/packages/my_mod
    • It's a good idea to avoid spaces and try to keep at lower case letters in folder names, but not required
  • Create a new text file package_config.xml in the folder with such content as

<package name="my mod" description="my very own mod" />

    • If it's a Campaign mod, you'll be using a script to define what happens when the Campaign is started - usually starting from a map change, starting the match, handling what happens when the match ends
      • You'd add show_in_campaigns="1" and campaign_entry_script="start_campaign.as" in <package> in package_config.xml, so that it says

<package name="my mod" description="my very own mod" show_in_campaigns="1" campaign_entry_script="start_my_mod.as"/>

      • You can control which UI controls are shown in Start Campaign menu for your Campaign with by adding attributes like faction, presets, friendly_capacity, enemy_capacity, friendly_accuracy, enemy_accuracy, xp_multiplier, rp_multiplier, with value of 0 (disable) or 1 (enable) in the package element; by default all are enabled
    • If it's a Quickmatch mod, the mod is loaded as additional content after the map resources chosen in the Quickmatch menu
      • You'd add show_in_quick_match_mods="1" in the package element to make the mod available there
    • If it's just a content package meant to be used by other packages, you're done - in fact you wouldn't need the package_config.xml file at all
  • Some templates exist targeted for Campaign mods, find them in media/packages
    • simple_template: simple 1-map Campaign with looping and script side save/load enablers, see media/packages/simple_template/readme.txt for details
    • full_campaign_template: Vanilla Campaign with enablers for replacing factions, item deliveries and unlock items
  • Let's extend it into a simple Campaign mod!
    • Copy all files from media/packages/simple_template/scripts to your own mod e.g. media/packages/my_mod/scripts
    • Edit the files, start_campaign.as and my_gamemode.as and work out the marked TODO points
    • Start RWR, choose Start new Campaign, your mod should show up in the list of available campaigns, select it and continue
    • Start the Campaign - the sliders won't have an effect yet as your script is not prepared to handle the settings
    • If the map loads, congrats, you've just made a new Campaign mod
    • If nothing happens, there's a problem in the script
      • Navigate to %appdata%\Running with rifles (~/.running_with_rifles/ on Linux), and open rwr_game.log
        • On Windows, you might eventually want to use something like Notepad++ to work with the files, but the good old Notepad will work too
      • Scroll to the end of the log to see what's the problem
      • Most of the time it's about syntax errors in the script, read the error descriptions, fix them and retry
        • It's a good idea to run RWR in a window (Configure in Steam to change fullscreen to No) when working with mods
        • With Notepad++ you can keep rwr_game.log open and reload it when it changes (use the File menu)
        • You can then switch between windows quickly and try starting your Campaign in RWR, look at errors in rwr_game.log in Notepad++ and fix the scripts
    • What's next?
      • a) Create new content into the mod; TODO: Content mod link
      • b) Use scripts to create new logic into your mod; TODO: Script work link
      • c) Extend the Campaign into a multimap scenario - look into full_campaign_template to use Vanilla Campaign as a basis or come up with a custom solution of your own
      • d) look at other mods to learn how they did it
      • e) look at what Vanilla did (media/packages/vanilla/scripts)
    • Eventually you'll want to publish the mod, see SteamWUT; TODO link
    • Watch out for weird stuff if you subscribe to your own mod and have it located under RWR's media/packages with the same name.

Full Campaign Mod[edit | edit source]

  1. Create a folder named <mod_name> in resources/media/packages and copy the files in the packages/full_campaign_template folder into your mod folder
  2. Follow the TODOs in these .as files (open with a text editor or your preferred IDE)
  3. Copy files you want to mod from the packages/vanilla folder structure into your mod's folder and start modding them!

File and folder structure and interconnectivity[edit | edit source]


  • The mod's root folder contains package_config.xml, which references the mod's startup script file as well as UI components such as the mod's description, which can be passed as a text string here or as a string that matches a key name found in /languages/<language>/package_ui.xml. When the latter is used, the value of the key (another text string) is displayed.

Finally, the file specifies a number of campaign options as boolean settings, which dictate whether the player may customise the mod's default settings at launch.


  • all_factions.xml lists the factions in the mod. Make sure the order you list the factions here matches that in scripts/my_stage_configurator.as
  • <faction>.xml high-level information about each faction in the game/mod, from rank structure to unit / soldier type declarations. This file links to a bunch of resource files that are specific to the faction, and also common to all units in the game.
  • <faction>_default.resources contains links to vehicles, weapons, radio calls, and carry items specific to the faction. Items are named and enabled here, but also have to be listed in all_(vehicles|weapons|calls|carry_items).xml files in their relevant folders!
  • <faction>_primaries.resources contains the primary weapons used by members of the faction (in addition to those listed in common.resources)
  • <faction>_secondaries.resources lists the secondary weapons available to the faction (again, in addition to common weapons)
  • <faction>_supply.resources contains the items that are available to the faction from supply drops
  • common*.resources lists the resources available to all factions. Put an item in here instead of a faction's resources if all factions are able to use it
- Important note: All carry items available in the game must be listed in common.resources. This includes faction-specific carry items, which also require enabled="0" to be set, making them present in the game but not available to anyone by default. These carry items must then be listed in <faction>_default.resources with enabled="1" to enable that carry item only for that faction
  • *.character files each references another level of .character file, starting with (e.g.) default_male.character voice files, to default.character text / chat comments, to default_base.character, which has the real AI meat (also see default.ai)
  • <type>.squad_config files list unit types that will be present in a squad of that type. Referenced (as usual) by all_squad_configs.xml. The user can pre-configure these squad configs and then cycle through them in-game with home and end keys


All 3D models are found here either in .xml (voxel) or .mesh (OGRE 3D) format. Note that while most vehicles are ogre meshes, the general consensus is that only voxel models can be animated via a skeleton (e.g. the soldier models). See soldier_animations.xml to understand how the animations are managed.


Almost entirely .png files of artwork for hud items and texture wraps for ogre static models


Radio calls *.call and the all_calls.xml are found here. The invasion_all_calls.xml file is also present, but simply includes the all_calls file. All calls lists the file names of the call files that are included in the game. These files contain the actual call key value, which is referenced in /factions/common.resources to make the call available to use. To make a call faction-specific, include it in /factions/<faction>_default.resources, not the common resources file.


Items (excluding weapons) that can be worn such as vests and items that can be dropped from and picked up into a character's inventory. all_carry_items.xml and all_visual_items.xml are found in here and reference the physical file names for these items. Each of these files then notes the key value for these items. Finally, /factions/common.resources is used to include the carry items (by key reference) in the game. See the note above in factions regarding listing — but disabling — all faction-specific carry items in this file.


This folder contains the usual all_weapons.xml file along with all_throwables.xml. These two files list the file names of every *.weapon available in the game. Depending on each weapon's class, it will fire a *.projectile or apply an effect directly (melee/medikit/bandage). Weapon models are usually voxel-based if held by soldiers. To save doubling up on code — and unless you specifically want different weapons to be available in different game modes — you can reference the all_weapons.xml file from invasion_all_weapons.xml as follows:
<?xml version="1.0" encoding="utf-8"?>
    <weapon file="all_weapons.xml" />


all_vehicles.xml contains a list of the file names for vehicles in the game. As with other resources, these resources' keys need to be included by the common or faction-specific .resources files.


The contents of the package_ui.xml file in each sub-folder (by language code) is referenced by the /package_config.xml file. Primarily used to store key/value pairs for campaign descriptions, setup/config options, and to call the script /scripts/start_campaign.as that forms the entry point of the mod. Also see intro.xml for text info that displays on the loading screen.


first and last name files, per faction. Referenced by <faction>.xml.


Angel Script files that allow you to modify and extend the game's behaviour. Do note scripts/internal/log.as allows you to control logging level to the rwr_game.log file. Handy for testing and debugging while building the mod.


Sound Effects in 44K mono wavs please. Soundtrack / music in 44K stereo wavs.

How to create mod content?[edit | edit source]

  • General things about packages and overlay resource system
    • Files are added in an in-game resource system
    • Most resources are referred to by filename only, no path, also in all XML and Angelscript files
    • In case there are several similarly named files in the system, only the one loaded last is used
    • This makes it possible for a content mod to replace how an AK47 looks in otherwise a vanilla game
    • e.g. resource meshes, textures, sounds, specifications can be changed this way without having to locally change vanilla files
  • How to create voxel items? TODO: link
  • How to create weapons?
  • How to get various faction resources (like weapons) into the game?
    • Faction files, e.g. media/packages/vanilla/factions/green.xml control which items are available for the faction
    • In Vanilla, such faction resources are listed for each soldier group in *.resources files
    • To add your new weapon mod for a faction, for example
      • 1) Ensure the weapon is loaded by the game in the first place, you generally need to have it in all_weapons.xml (or invasion_all_weapons.xml if you're overlaying Vanilla Campaign)
      • 2) Duplicate green_default.resources file into your mod to overlay the Vanilla version of the file
      • 3) Edit the file and add your weapon key (usually you'd define the key in the weapon file to be same as the filename, but it's up to you) in the list similar to others
      • 4) Ensure your weapon specification doesn't have in_stock="0" which makes the weapon unavailable in an armory
      • 5) Done! Playing as Greenbelts with the mod enabled, the basic type soldiers would now have a chance to spawn carrying your weapon, and players can find it in the armory
  • How to create factions?
    • See media/packages/vanilla/factions, green.xml, grey.xml or brown.xml
    • These files refer to the additional faction specific files *.models, *.resources, *.character, *.ai for convenience
    • Adding another faction can be basically done by duplicating one of these in your mod with another name
    • To get that faction playable in a Campaign, you'd likely want to pick full_campaign_template as a basis for your mod's scripts
      • In my_stage_configurator.as you'd refer to your custom faction as one of the three available factions
      • You could also extend the Vanilla Campaign to deal with 4+ factions scenario, by e.g. introducing your own version of media/packages/vanilla/scripts/gamemodes/invasion/stage_configurator_invasion.as, with 1-4 factions defined for each stage
    • Note that all_factions.xml is used by the Start new Campaign menu for the list of available factions; only the name field is used

How to run a mod on a dedicated server?[edit | edit source]

  • Use SteamCMD to download RWR on the server, see [3]
  • Use SteamCMD to download the mod
    • TODO: instructions
    • Figure out the Workshop item ID from the URL: TODO instructions
  • Copy the mod SteamCMD downloaded to a location where the RWR server knows to look for it, media/packages/
  • Create steam_workshop_items.txt in RWR server root folder and list the required Workshop item ID(s) there, one per line; clients use this info to ensure they have the correct resources
  • Duplicate the mod's gamemode script and edit server settings in it
    • It's possible the mod's author has created a server specific starter script, located in media/packages/the_mod_folder/scripts/start_mod_server.as, filename may vary
    • If there's no such example script, you may have to create it yourself from mod's campaign start script
      • It totally depends on the mod, but if it's based on Vanilla campaign or templates, chances are you'll need to add something like this in the script
        settings.m_startServerCommand = """
<command class='start_server'
        comment='Yes yes very nice mod server come see'
        <client_faction id='0' />
  • Launch the server
  • Start your gamemode script in the console with start_script start_my_mod.as media/packages/the_mod_folder
  • For additional stuff about server setup, see [4]

What to do with scripts?[edit | edit source]

  • [5]
  • XML commands described behind above link can be executed
    • From a script by sending a command to the game
    • With init_match.xml, usually in a map folder, to run a bunch of commands at the start of a match
    • When a radio call is made, if the call supplies <command>s inside its <round>s
    • As a <result class="xml_command"><command ... /></result> in events in grenade or vehicle specifications
    • As a local player by typing /_execute file.xml with file.xml in RWR root folder, the file consisting of a <command /> or <commands><command>...</commands>
    • From server console by typing execute file.xml, like above
  • Angelscript reference docs ... cript.html
  • Look at what vanilla does media/packages/vanilla/scripts/
  • If there's a problem with a script, %appdata%\Running with rifles\rwr_game.log will tell you about it

Troubleshooting errors with your mod[edit | edit source]

Always 'tail' the rwr_game.log file in a terminal/powershell window when running your launching and playing your mod and have verbose debug log output enabled. The log provides invaluable insights to your mod's behaviour and performance.

  • Linux: tail -f ~/.running_with_rifles/rwr_game.log
  • Windows: get-content "$env:APPDATA\running with rifles\rwr_game.log" -wait
  • Mac: tail -f '/Users/<username>/Library/Application Support/RunningWithRifles/rwr_game.log'

rwr_game.log error messages[edit | edit source]

loading faction resources in <mod_folder_path>/factions/<file_name>
CHECK: characters or character element not found 
execution halted

This error indicates you have made reference to a non-existent character file in factions/<faction>.xml.

Ensure the file exists in the factions folder, is spelled correctly, matches the case and launch the game again.

loading faction resources <mod_folder_path>/factions/common.resources
loading faction resources in <mod_folder_path>/factions/<another_file>.resources
loading faction resources in 
CHECK: resources element not found
execution halted

This error indicates you have made reference to a non-existent resources file. The actual file causing the error (typo, doesn't exist, or trying to load a non-existent resource) will be the file loaded after <another_file>.resources is listed in factions/<faction>.xml.

loading calls in <mod_folder_path>/calls/<call_name>
loading calls in 
CHECK: calls or call element not found
execution halted

Similar to the error above, this error indicates you have made reference to a non-existent call file in calls/all_calls.xml. Calls are generally processed in the order they are listed in all_calls.xml, so check which call was the last to load before the error occurred and the error will most likely be to do with the next referenced file.

<filename.as> (line_num, col) : ERR  : No matching signatures to '<text>'

Does <filename>.as include the file that contains the class, constructor, method, etc. referenced in text?

Issues that don't show up in rwr_game.log[edit | edit source]

  • Commander briefing at start of mission fails to appear
- This generally indicates you have made a syntax error early on in /languages/en/default_shared.character, such as a missing forward slash '/' at the end of a <comment key="blah" text="blah blah" /> tag. Every line after the one(s) with a syntax issue will fail to be read at start time, resulting in the comment keys used in the commander briefing failing to appear.
- You may also notice unprivileged calls (xp < 1000) don't result in a text bubble advising "I don't have a radio yet" or other text string appropriate to the <comment key="no radio equipment"... />. These comment tags start from line 110, so your syntax error is going to be before this line.