module_system_doc2-3

M&B Module System Documentation Table of Contents 1 Getting Started 2 Editing the Module System 3 Module Troops 4 Module Party Templates 5 Module Items 6 Module Constants, Factions, Strings and Quests 7 Game Menus 8 Scene Editing 9 Module Dialogs 10 Triggers 11 Mission Templates BETA but working 12 Tableau_matrials & Heraldic Armor Apendix (i) - Generic for now PART 1 1.1 What is the Module System? The Mount&Blade Module System is a set of python scripts that lets you create and/or modify content for Mount&Blade. This is actually the system we are using for working on the content of the official version. Using the module system, you can do things like adding new troop types, new characters, new quests, new dialogs, etc., or you can edit the existing content. It is important to note that Mount&Blade does not use Python and does not read the Module System python scripts directly. Rather, the python scripts are executed to create the text files that Mount&Blade reads. Mount&Blade actually reads its content from text files under the Mount&Blade/Modules folder. Thus, *in theory* you can do all the modifications you'd like to do by editing these text files. (Indeed, some modders had worked out how to use these files and were able to create amazing mods by themselves.) However the text files are not really human-readable and are very impractical to work with. There are currently two options for writing new modules. The first is the official module system described in this document. The other is Effidian's unofficial editor which is currently discontinued and unusable for the current version - v.1.011, but works for older versions of M&B, such as v.7.51 . 1.2 Requirements for using the Module System The module system consists of Python scripts, and as such, you need to have Python installed on your system to be able to work with them. You can download Python from Python.org's download page: http://www.python.org/download/ There are more than a few downloads on that page. However you'll only need the Windows version 2.6.1. NOTE: ANY OTHER VERSION OF PYTHON WILL NOT WORK. ONLY USE 2.6 After you download and install Python, you'll also need to add Python to your path enviroment variable. This is important, so try to be exact when you make these changes. For Windows 9x systems, you can edit autoexec.bat file and add your python folder to the Path. For example if Python is installed under C:\Python24, add the following line: set PATH=C:\Python24;%PATH% If you have a Windows XP or a Windows Vista system, this operation is slightly different: Right-click on My Computer (Computer in the start menu for Vista users) select 'Properties', click on the 'Advanced' tab and then click on 'Enviroment Variables': 1. Scroll down on the 'System variables' until you find the 'Path' variable. 2. Click on the 'Edit...' button, a new window should pop up: Scroll to the end of the 'Variable value' and add ";C:\Python26", where “C:\Python26” is the name of the folder python is installed to. Click ok on this box, then ok again on the next box. 1.3 Obtaining the Module System The latest version of the Module System can be downloaded from Module System's official webpage at: http://www.taleworlds.com/download/mb_module_system_1010_0.zip You'll need to download the zip file for the module system and extract it (requring a program such as WinRAR, or 7-zip). Extract the Module System wherever it is easy to locate, e.g, the Desktop or My Documents. 1.4 Module Sytem Files Now, let's have a look at the files in the module system. When we look at the actual Python files (files that end with .py) we see that there are actually four kinds of files: * files that start with header_ * files that start with process_ * files that start with ID_ * files that start with module_ The first two kinds of files are necessary for running the module system. You shouldn't modify these at all. The third kind of files (ID_) are temporary files created while building the module. You can delete them if you like and the module system will generate them again. The final kind of files (module_) are actually the files that contain the content data. These are the files you will be modifying. 1.5 Creating a new module Before going any further, let's first create a folder for your new module. For this, we need to go to the Mount&Blade/Modules folder (by default this is at "c:/Program Files/Mount&Blade/Modules") Now, under the Modules folder there should be a folder named Native. This is, so to speak, the official module. For your own module, you must create a new folder here, and copy the files from Native to the new folder. This new folder will be your own module folder so name it as you like. For the sake of simplicity, I am assuming it is named MyNewModule You can test if you have done this right by launching Mount&Blade. Now, Mount&Blade's launch window should show a combo box, which lets you select the module you'd like to play. Now, try selecting your new module and starting a new game. Since we copied the contents of the native folder for our new module, the game we play now will be identical to the native game. Next, we must make the Module System use the new folder as its target. To do that, open the file module_info.py for editing (Right click on the file and select "Edit with IDLE"; or open the file with Notepad or your preferred text editor) and change export_dir to point to your new folder. For example, if the folder for your module is: c:\Program Files\Mount&Blade\Modules\MyNewModule You should change this line as follows: export_dir = "C:/Program Files/Mount&Blade/Modules/MyNewModule/" NOTE: Within the Module System, directories are separated by forward slashes(/) not backslashes(\) that windows uses. Also note that you need the forward slash at the end of the declaration. Now our module system setup should be ready. To try it out, remove the file conversation.txt inside our new module folder, and then double click on build_module.bat. You should see a command prompt with some output like this: Code: [Select] Initializing... Compiling all global variables... Exporting strings... Exporting skills... Exporting tracks... Exporting animations... Exporting meshes... Exporting sounds... Exporting skins... Exporting map icons... Creating new tag_uses.txt file... Creating new quick_strings.txt file... Exporting faction data... Exporting item data... Exporting scene data... Exporting troops data Exporting particle data... Exporting scene props... Exporting tableau materials data... Exporting presentations... Exporting party_template data... Exporting parties Exporting quest data... Exporting scripts... Exporting mission_template data... Exporting game menus data... exporting simple triggers... exporting triggers... exporting dialogs... Checking global variable usages... ______________________________ Script processing has ended. Press any key to exit. . . If you ran into an error, make sure you've followed all the steps of this tutorial exactly, and if you think you have, please use the Search function on the forums; chances are someone has already run into the same problem and an easy solution has already been posted. If not, you should see the conversation.txt file re-created. Congratulations! You're all set up to create your own mod with the M&B module system. PART 2 As mentioned in the previous chapter, you work with the Module system as follows: 1 ) Edit one or more of the module files (those starting with module_ and ending with .py) and make any changes you like. (Usually you need to right click and select 'Edit with Idle' to do that using the phython editor) 2 ) After that, double click on the file build_module.bat . This action will attempt to build your module (and report errors if there are any) 3 ) If there are no errors, you may launch Mount&Blade and test the changes you have made. Sometimes you may need to start a new game for the changes to take effect. NOTE: Though PYTHON has its own editor, I have found that using NOTEPAD++ is of great help. You can have multiple files open (in tabs), as well as easily customize the look a feel of the interface. I have found this very helpful since I am used to working with other code editors (such as BYOND) with a specific layout. 2.1 – Personalizing Your Mount&Blade Mod Before we begin, we will take the first step in personalizing your mod. Let’s change the mod selection picture. This can be done with MS Paint, or anything that will edit BMP files. The file (main.bmp) is located in your Mount&Blade modules folder (ex. C:\Program Files\Mount&Blade\Modules\MyMod). Editing this will change the picture shown when you select your mod. This is often a good idea if you jump between working on a mod and playing others. If you have the ability to edit DDS image files, you can make copies of the various DDS background pictures to your mod’s texture folder (ex. from C:\Program Files\Mount&Blade\Textures to C:\Program Files\Mount&Blade\Modules\MyMod\Textures). If you change them in your mod’s texture folder, they will be changed in the game when you play your mod. The file bg2.dds is the standard background for most menu pictures, and pic_mercenary.dds is the picture for the main menu. Don’t spend too much time with this now, but know that you can make your mod look a lot slicker when it’s done. 2.2 -- Editing the Module Files The module system uses Python lists to represent collections of game objects. ( A python lists starts with a square bracket '[', includes a list of objects seperated by commas, and ends with a closing square bracket ']' ) If you open and view any of the module files you'll see that it contains such a list. If you open up module_map_icons.py, for example, it contains: map_icons = [ ("player",0,"player", avatar_scale, snd_footstep_grass, 0.15, 0.173, 0), ("player_horseman",0,"player_horseman", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("gray_knight",0,"knight_a", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("vaegir_knight",0,"knight_b", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("flagbearer_a",0,"flagbearer_a", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("flagbearer_b",0,"flagbearer_b", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("peasant",0,"peasant_a", avatar_scale,snd_footstep_grass, 0.15, 0.173, 0), ("khergit",0,"khergit_horseman", avatar_scale,snd_gallop, 0.15, 0.173, 0), ("khergit_horseman_b",0,"khergit_horseman_b", avatar_scale,snd_gallop, 0.15, 0.173, 0), ("axeman",0,"bandit_a", avatar_scale,snd_footstep_grass, 0.15, 0.173, 0), ("woman",0,"woman_a", avatar_scale,snd_footstep_grass, 0.15, 0.173, 0), ("woman_b",0,"woman_b", avatar_scale,snd_footstep_grass, 0.15, 0.173, 0), ("town",mcn_no_shadow,"map_town_a", 0.35,0), ("town_steppe",mcn_no_shadow,"map_town_steppe_a", 0.35,0), ("village_a",mcn_no_shadow,"map_village_a", 0.45, 0), ("village_burnt_a",mcn_no_shadow,"map_village_burnt_a", 0.45, 0), ("village_deserted_a",mcn_no_shadow,"map_village_deserted_a", 0.45, 0), ###more in the actual code, but we’ll stop here### Here map_icons is declared as a Python list and every element in the list is the declaration for a specific map icon object. In this example, ("player",0,"player", avatar_scale, snd_footstep_grass, 0.15, 0.173, 0), is such an object. We call such objects tuples. Tuples, like lists, contain elements seperated by commas (but they start and end with parentheses). The structure of each tuple object is documented at the beginning of the module file. For map icons, each tuple object contains: 1 ) name of the icon, The prefix icon_ is automatically added before each map icon id. 2 ) icon flags, See header_map icons.py for a list of available flags 3 ) Mesh name, can be found in the BRF files map_icon_meshes, map_icons_b, and map_icons_c 4 ) Mesh scale, 5 ) sound id. 6 ) Offset x position for the flag icon. 7 ) Offset y position for the flag icon. 8 ) Offset z position for the flag icon. So, for the first tuple: ("player",0,"player", avatar_scale, snd_footstep_grass, 0.15, 0.173, 0), 1 ) name of the icon = "player" 2 ) icon flags = 0 3 ) Mesh name = "player" 4 ) Mesh scale = 0.2 5 ) sound id = snd_footstep_grass 6 ) Flag offset x = 0.15 7 ) Flag offset y = 0.173 6 ) Flag offset z = 0 You can work out the structure of game objects for each module system file in this way, by reading the documentation at the beginning and matching that with the contents of the list. 2.3 -- Adding New Game Objects Knowing the structure of the map icon tuples, we can now begin to add our own map icons. Let us take another look at the list. map_icons = [ ("player",0,"player", avatar_scale, snd_footstep_grass, 0.15, 0.173, 0), ("player_horseman",0,"player_horseman", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("gray_knight",0,"knight_a", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("vaegir_knight",0,"knight_b", avatar_scale, snd_gallop, 0.15, 0.173, 0), ("flagbearer_a",0,"flagbearer_a", avatar_scale, snd_gallop, 0.15, 0.173, 0), . . . ("banner_125",0,"map_flag_f20", banner_scale,0), ("banner_126",0,"map_flag_15", banner_scale,0), ] ###more in the actual code, but we’ll stop here### New game objects in any module file must be added inside the list. You can see, the list for module_map_icons ends just below ("banner_126",0,"map_flag_15", banner_scale,0)). In order to make room for our new game object, we have to move the bracket down by one line. Having done that, we can now begin to add a new object. The easiest way to do this is to copy and paste a pre-existing object and then editing its contents. For example, copy the “town” tuple just below “banner_126”: . . . ("banner_126",0,"map_flag_15", banner_scale,0), ("town",mcn_no_shadow,"map_town_a", 0.35,0), ] In this example, we have copied ("town",mcn_no_shadow,"map_town_a", 0.35,0). Now give it a new icon name; "new_icon". This new icon has a flag on it. Flags are settings that can be turned on and off by including or removing them in the appropriate field. For example, the flag mcn_no_shadow on our new icon will set this icon to cast no shadow on the ground. We will now remove mcn_no_shadow from our new icon. To do this, we replace mcn_no_shadow with 0, telling the module system there are no flags for this icon. . . . ("banner_126",0,"map_flag_15", banner_scale,0), ("new_icon",0,"map_town_a", 0.35, 0), ] Both "town" and "new_icon" use the Mesh "map_town_a", which means they will both use the 3d model named map_town_a in the game's brf resource files. By changing this field, the icon can be set to use any 3d model from the resource files. Because both icons use the same Mesh, if we were to put "new_icon" into the game at this point, it would look exactly the same as "town". Now let us give "new_icon" a bit of a different look. Let’s change it to “city”. This mesh is currently not used and it will stand out better in our mod. . . . ("banner_126",0,"map_flag_15", banner_scale,0), ("new_icon",0,"city", 2,0), ] In this example, we have also changed the icon's scale from 0.35 to 2. This means the icon will be displayed two times as large as normal. That should help us tell it apart from "town" when we put it into the game. Next we will create a new party in module_parties.py that uses our new icon. To do this, we will need to reference the icon from module_parties.py. Before continuing, we will run build_module.bat. This will let us know that we got the syntax right. It is a good idea to run the build to ensure that you aren’t making errors that may be hard to track down later. 2.4 -- Referencing Game Objects Open module_parties.py in your module system folder. You will see another Python list, parties = [, just below some constants declarations (pf_town = pf_is_static|pf_always_visible|pf_show_faction|pf_label_large). They can make repeated flags a lot easier to enter. More on constants later. As you can see, the structure of tuples in module_parties.py is slightly different from module_icons. This holds true for many -- if not all -- of the module files. We'll take this opportunity to closely examine the parties structure. First, Understand that parties can be anything that you come in contact with on the map. These can be traveling groups or stationary villiages, towns or other locations of your own design. One key to parties is that an encounter is triggered when 2 or more parties meet. Let’s look at an example of a party. If you scroll down a bit you will come to: ("town_1","Sargoth", icon_town|pf_town, no_menu, pt_none, fac_neutral,0,ai_bhvr_hold,0,(-1.55, 66.45),[], 170), This tuple places the town of Sargoth on the map. Sargoth's various qualities are set in the appropriate fields -- quite similar to the fields we've seen in module_map_icons.py. Breakdown of the tuple fields: 1 ) Party-id. This is used for referencing the party in other files. 2 ) Party name. This is the party's name as it will appear in-game. Can be as different from the party-id as you like. 3 ) Party flags. The first flag of every party object must be the icon that this party will use. 4 ) Menu. This field is deprecated, which means that it's outdated and no longer used. As of M&B version 0.730, this field has no effect whatsoever in the game. 5 ) Party-template. ID of the party template this party belongs to. Use pt_none as the default value. 6 ) Party faction. This can be any entry from module_factions.py. 7 ) Party personality. See header_parties.py for an explanation of personality flags. 8 ) AI-behaviour. How the AI party will act on the overland map. 9 ) AI-target party. The AI-behaviour's target. 10 ) Initial coordinates. The party's starting coordinates on the overland map; X, Y. 11 ) List of troop stacks. Each stack record is a triple that contains the following fields: 11.1 ) Troop-id. This can be any regular or hero troop from module_troops.py. 11.2 ) Number of troops in this stack; does not vary. The number you input here is the number of troops the town will have. 11.3 ) Member flags. Optional. Use pmf_is_prisoner to note that a party member is a prisoner. 12 ) Party direction in degrees [optional] Sargoth’s tuple examination: ("town_1","Sargoth", icon_town|pf_town, no_menu, pt_none, fac_neutral,0,ai_bhvr_hold,0,(-1.55, 66.45),[], 170), 1 ) Party-id = "town_1" 2 ) Party name = "Sargoth" 3 ) Party flags = icon_town|pf_town 4 ) Menu = no_menu 5 ) Party-template = pt_none 6 ) Party faction = fac_neutral 7 ) Party personality = 0 8 ) AI-behaviour = ai_bhvr_hold 9 ) AI-target party = 0 10 ) Initial coordinates = (-1.55, 66.45) 11 ) List of troop stacks = [] (None) 12 ) Party direction = 170 By looking at field 3, we can see that Sargoth references the icon "town" from module_icons.py, by adding the prefix icon_ to it. This prefix is what points the system to the right module file. In order to reference module_icons, we use icon_; in order to reference module_factions, we use fac_; in order to reference module_parties, we use p_; and so on. There is an appropriate prefix for every module file -- you will find them all listed at the bottom of this segment. Now that we know how parties are structured, we can begin adding our own. But before you do so, take note: In the case of module_parties.py and certain other module files, you should not add your new towns at the bottom of the list. There will be comments in these