BuildingFactions

From The Battle for Wesnoth Wiki


Creating Custom Factions

This page describes how to create and modify eras. You spent all that time making a new unit, but now you can't use it in game! Unfortunately new units just don't show up. Because configuration files are used to tell the game which units to use where, new units need to be added to the list. The first section describes how to make a new faction. The second section tells you how to add units to existing multiplayer factions. Discussion on how to set up a faction is found in EraWML.

Adding a whole new era with its own factions - modular

The best way of adding an era does not involve modifying game files. It will allow you to create an era that you can package and distribute to other players. It uses the same methods user campaigns are packaged and distributed. There are several examples of new multiplayer eras already on the campaign server. When we're done your era will look exactly like the ones on the server. That means you can skip all of these instructions, download one of the eras off the server, and modify it to your taste. For those of you who are still with us, instructions follow

  • Navigate to the /data/add-ons directory. (Note: In Windows, this directory will by under My Documents/My Games/Wesnoth) Everything from now on will occur relative to here. The era we'll use as an example will be called MyEra.
  • Create a text file called MyEra_MP_era.cfg. Add the following lines:
#ifdef MULTIPLAYER
{~add-ons/MyEra_MP_era/}
#endif
If you will include custom units, images, sounds, or music, add the following lines instead:
#ifdef MULTIPLAYER
[binary_path]
    path=data/add-ons/MyEra_MP_era
[/binary_path]
{~add-ons/MyEra_MP_era/}
[+units]
    {~add-ons/MyEra_MP_era/units}
[/units]
#endif
  • The binary path statement points the game to the media
  • The [+units] tag points the game to the units subdirectory.
  • NOTE: You cannot create new units with the same unit id's as in-game units. Unit id keys must be unique.
  • Create another text file called server.pbl. Add the following lines to it:
author="your name"
icon="any image file in the game's ./images directory"
version="1.0"
title="MyEra MP Era"
type="era"
description="a brief description of your era"
passphrase="the password you want to use to upload your era to the add-ons server"
email="your e-mail address"
  • The passphrase ensures that no one but you can modify your era. Once it is set (by uploading it the first time) it will take an admin to change it.
  • Including your e-mail address will allow moderators to contact you if there are any severe problems with your add-on.
  • Create a folder called MyEra_MP_era. Navigate to it.
  • If you will have custom maps, units, images, sounds, or music, create those subdirectories and fill them with your custom maps, units, images, sounds, and/or music.
  • Create a text file called MyEra.cfg. Add the following:
[era]
    id=my_era
    name= _ "My Awesome Era"
    [multiplayer_side]
        id=Random
        name={MENU_IMG_TXT "random-enemy.png" _"Random"}
        random_faction=yes
    [/multiplayer_side]
    [multiplayer_side]
        id=
        name={MENU_IMG_TXT "any image file in the game's ./images directory" (_"faction name")}
        type=
        leader=
        recruit=
        music=
        terrain_liked=
        [ai]
            recruitment_pattern=
        [/ai]
    [/multiplayer_side]
[/era]
  • Fill in the appropriate key values for each multiplayer side. Copy and paste the mutiplayer side tag structure for as many sides as you wish to have in this era
  • You should be ready to publish the MP era. Test it out first and make sure everything works. Then, access the campaign server and publish your MP era

Modifying an Existing Faction

  1. Take note of your new unit's id key.
    • The id is found in the unit's .cfg file and must be unique.
    • There are over 200 units, so it pays to double check the exact spelling and capitalization of the unit id, especially if english is not your primary language
  2. Locate multiplayer.cfg in the game's data directory. This file sets up the basic multiplayer rules for the entire game.
    • Warning: if you modify this file, it may cause problems when you play 'live' on the server. If you are using a unit no one else has, it will cause the game to go out of sync.
    • If this is a problem for you, you can copy the contents of your favorite era into a new era (instructions at bottom) and use the new unit there
  3. Inside multiplayer.cfg, locate the era and faction you want to modify.
    • The eras are Default, Classic, Age of Heroes, and Great War -- they start with [era] tags.
    • The factions (for example) are Loyalists, Rebels, Undeads, etc. and start with [multiplayer_side] tags. each facion is in it's own file in the wesnoth/data/factions/ directory
  4. To make it recruitable, locate the recruit= key and add your unit id to the end of the list
    • For example, let's say your new unit was the Elvish King and the id was Elvish_King. We want to add him to the Rebels of Default
      • Change this: recruit=Elvish Fighter,Elvish Archer,Mage,Elvish Shaman,Elvish Scout,Wose,Merman Hunter
      • To be this: recruit=Elvish Fighter,Elvish Archer,Mage,Elvish Shaman,Elvish Scout,Wose,Merman Hunter,Elvish_King
  5. To make it a leader option, locate the leader= key and add your unit id to the end of the list
    • For example, using the Elvish King example, suppose we want to make him a leader for the Rebels of Default
      • Change this: leader=Elvish Captain,Elvish Hero,Elvish Ranger,Elvish Marksman,Elvish Druid,Elvish Sorceress,White Mage,Red Mage
      • To be this: leader=Elvish Captain,Elvish Hero,Elvish Ranger,Elvish Marksman,Elvish Druid,Elvish Sorceress,White Mage,Red Mage,Elvish_King
  6. Multiplayer factions also have a random_leader= key. This tells the game that it can be chosen as a random leader (some units such as healers are excluded because they are considered weaker than the most of the other units so the player cant randomly get them, but he can still choose them as leaders if he wants to)
    • Follow the same procedure as in the previous step

New Eras and Factions

Adding a faction to multiplayer.cfg

In this example, you made some new Centaur units and artwork for them, and you want to make a Centaur faction for the Default era.

  1. Save the unit .cfg files in the game's data/units directory
  2. Save the artwork files in the games's /images directory
  3. Locate multiplayer.cfg in the game's data directory. This file sets up the basic multiplayer rules for the entire game.
    • Warning: if you modify this file, it may cause problems when you play 'live' on the server. If you are using a unit or faction no one else has, it will cause the game to go out of sync.
    • If this is a problem for you, you can copy the contents of your favorite era into a new era (instructions below) and use the new unit there
  4. Inside multiplayer.cfg, locate the era you want to modify
  5. Copy one of the existing factions. Each faction is in it's own file in the factions/ directory, copy the file instead, and add a call to your new file : {factions/myfaction.cfg}
    • Select everything between the [multiplayer_side] and [/multiplayer_side] tags and paste it somewhere inside the [era] tag
  6. Modify the copied faction to be how you want it. See EraWML for more information
    1. Change the id to something unique (it only has to be unique within the era)
    2. Change the name. This is not straightforward since it uses the macro {MENU_IMG_TXT "image" _"name"}
      • The image is an image file in the game's /images directory. Replace image with the filename relative to the /images directory
      • In this example, the new name key could be {MENU_IMG_TXT "centaur-warrior.png" _"Centaurs"}
    3. The type= key specifies which leader on the leader list will be the default leader type. If there is no leader list, then this will always be the faction's leader type. Use the id values of one of your new units
    4. The leader= key is a list of type ids for the units you can pick to be the leader
      • For example, you could have leader=Centaur Warrior,Centaur Bowmaster,Centaur Mystic
      • you can also have a random_leader= key (in addition to the leader key) to set which units can be randomly selected if you want to exclude a unit from random selection
    5. The recruit= key is a list of type ids for the units you can recruit in this faction
      • For example, you could have recruit=Centaur Fighter,Centaur Archer,Centaur Shaman
    6. The music= key is the music that will play during this faction's turn. Choose from the files located in /music
    7. The terrain_liked= key is for use by map generators. The right-hand side is a comma-separated list of terrain codes near which the game will attempt to put your keep.
    8. The [ai] tag is used to tell the AI how to recruit. You should make sure you ONLY put values on the list if you have corresponding units in the faction.
      • For example, let's say the Centaur faction is made up of units where the usage= keys are either fighter or archer. The [ai] recruitment pattern should only consist of these values. If you accidentally include mixed fighter (for example), the AI will refuse to recruit properly
      • If all of this confuses you, either try it out and see what happens or visit the Wesnoth forum for live help

Adding a whole new era with its own factions - modifying multiplayer.cfg

Creating a new era is similar to adding a faction as described above. If you copy and paste one of the existing eras inside multiplayer.cfg then modify the values, you will have a brand new era. If you plan on using new units and/or artwork, make sure you added them to /images and /data/units.

See Also

This page was last modified on 23 October 2014, at 05:07.