A Start: Creating a Module to Give Your Player an Item

In this tutorial we’re going to look at something pretty basic, but that will give you a good overview of the toolset.  It is also something a lot of people are wanting to do.  You cheaters you!

We are going to create a new module that extends Single Player.  Bioware would call this an add-in.  What this basically means is we are not going to modify the single player campaign at all.  Our add-in will instead extend the original campaign by adding new content to it.  This is vital, because if we tried to change the original campaign by editing it we could, and probably would, break it in some way.  The toolset is like that.  Think of this like a mini Shale Tower in a way.  We’re simply adding new content.

For the purposes of this tutorial i’m going to assume you already have the toolset installed.  Unfortunately there have been lots of issues with the installation, but I can’t really help you with that.  Check out the wiki and the forums for answers to the more common problems.

Now another thing i’m going to assume is that you’ve been messing around in the toolset, and quite possibly with the Single Player module, which is the game’s original campaign.  This quite honestly is a bad thing and can break the campaign.  The first thing you should do, is in the toolset go to TOOLS -> EXPORT -> EMPTY EXPORT DIRECTORIES.  This will wipe out any modifications you’ve made.  It will reset all overrides on Single Player but its important to keep the campaign running properly.  After you’ve done that, never ever open the Single Player module again 🙂.

  

Create a New Module

Ok to get started we need to create our own module.  FILE -> MANAGE MODULES will open up the window we need.  Click on NEW to create a new module. 

The window that pops up is the “Module Properties” window.  In here we need to set a few things.  First, give your module a name.  For this tutorial i’m calling mine “Bow of Athena”.  Call yours whatever you want.  The next thing to set is UID.  This is a Unique Identifier, so it has to be unique amongst every module you create and unique amongst every module anyone else makes or their may be conflicts.  This must be in lower case, and you can use letters and underscores.  Possibly numbers and other symbols, but i’ve not tried.  A great way to help ensure your UIDs will be unique is to come pu with some 3 or 4 letter prefix sort of unique to you and always use that plus some identifier for the module.  In may case, I do a lot of things under the online name “Agathorn” so I tend to prefix my stuff with “aga_”. 

The last thing you need to do is set this module to extend the original campaign, which is the “Single Player” module.  to do this, scroll down the properties window to the next section “Info” and change the “Extended Module” property to “Single Player.  Once you’ve done this, click OK. 

You will find yourself back in the Manage Modules window, and your new module will be in the list, and should be selected.  If it isn’t selected, select it.  Now click OPEN to open your new module.  There is one last thing we need to do with the Manage Modules window, so go back to FILE -> MANAGE MODULES one last time.  Select your module and click on HIERARCHY…  In here place a checkmark next to Single Player.  NOTE: If all the modules in this window are greyed out, and you can’t select them then it means you didn’t open the module first, as mentioned above. 

Click OK to close the Hierarchy window, then close the Manage Modules window as well.  We’re done here for now.

Create Your Item

The next thing we need to do is actually create the item we want to give the player.  If you want to give your player some item that already exists in the game you can skip this section.

For this tutorial we’re going to create a nice bow, useable at low level but one with a bit of power to it so that it shows you some of the options.  In the pallete window on the right side, click the sword icon to switch to Items.  When you do this, you will see under that a bunch of folders open up.  These folders mean nothing to the game, but are there simply for organization.  However, i’ve not yet figured out how to actually add your own folders, so for now i’ve been putting everything in the root.

Right click anywhere in the empty space below the folders, and choose NEW -> ITEM.  In the window that pops up we have a few things to do.  First we need a Resource Name.  Like your UID this needs to be unique, so bear that in mind.  Folder is just where in the folder tree above it will sit.  Again this is meaningless to anything but your orginization.  I put mine in root “\”.  You decide.  Next is Module and this is very important.  Right now Module will be set to your module that you are creating, but we want this to instead be added to the games “Core Resources”.  The reason for this is that way we are properly extending Single Player and our module canb co-exist with others that do the same thing.  By putting this item into Core Resources, any other module that extends Single Player can also use it.  so in the Module property choose “Core Game Resources”.  Everything else can remain at the defaults, with Owner Module being your module.  Click OK and the item will be created and checked out so you can edit it.

Let’s talk a minute about this checking out thing.  This toolset is essentially what Bioware used to create the Single Player module, and of course the module wasn’t writtem by just one person.  There were many people who worked on it.  In any group project there is a concept of “Version Control”.  In a nutshell its a way for multiple people to work on the same files without getting in each other’s way.  The process is simple.  If you want to work on a file you first check it out of the control library so to speak.  This tells the system that you are working on this file, and it gives you a local copy for you to modify.  Then when you are done editing it, you check it back in to the library, at which time it compares your new copy to its own copy, and sees what you changed, and builds a new version by combining them.  This way if you and someone else were editing the same file at the same time, your changes get merged together to create a final file. 

Now most of that you don’t really need to worry about or even remember, but what you do need to take form that is that anytime you want to edit a resource you must check it out, and then when you are done you save, and then check it back in.  In this case the system automaticly checks out the new resource for us.  If this was an existing resource, we could right click on it and choose CHECK OUT.  In either case you will now see the new item open in the main window of the toolset.  On the left hand side are its properties and on the right is a 3d model of the item.  In the 3d view, mousewheel will zoom in or out, and CTRL+RIGHT MOUSE will rotate the model.

What we want though are the properties on the left side.  Base Item Type indicates what type of item it is.  Is it a longsword (default) or perhaps some Light Armor?  The base type is where a lot of its properties come from.  For example a longsword has certain base damage values, speed values, crit chance values, etc.  In our case we’re making a bow, so I chose “Weapon – Longbow”.  You’ll notice this also affects the 3d model.  Next you can give it a Description. You can just type directly into thebox, or if you click the 3 dots on the right of the field it will open a larger edit box for multi-line editing.  It also has a built in spell check 🙂

Once you’ve described your object, it needs an icon, so click on the icon property then click the 3 dots to open a file browser.  Unfortunately this file browser doesn’t let you see thumbails of the images and theres a lot of them.  We want an icon file though, and they all start with “ico_”.  I chose “ico_longbow”.

The next field is Inventory Subgroup.  I’m not 100% sure what this affects, but the best thing to do is just make it the same as another item of this basic type.  So on the right, open the _Global folder, then the Weapons, Ranged folder, and finally the Longbows folder.  Left click on any of the bows in there.  I clicke don the bottom one which is the generic Longbow.  When you do this its properties will be displayed in the window below it.  You can see it has a subgroup value of 21200 so we just put that same number in on ours.

Item Variation lets you choose from a few different 3d models for your item.  Choose whatever you want. 

Next up is Material Progression and Material Type.  These determine the tier of the weapon, and the texture of the 3d model.  I set both to “Bow, Horn” which is tier 1.

An Aside on Material Progression and Item Scaling: You may have noticed in the items list that there is only one base Longbow.  You don’t see a Horn Longbow, Ash Longbow, etc.  Just the one “Longbow” along with a few special types like Darkspawn or Dalish Longbows.  The reason for this is that Dragon Age works on a different basis than what you may be used to if you ever created modules in say Neverwinter Nights like I did.  In NWN you created every single item.  If you wanted lower and higher versions of an item, then you created multiple versinos and tweaked the stats on each.  Dragon age though works by automaticly scaling items to be appropriate for the player.  You will also notice that nowhwere in these properites for our bow can you set things like Damage, Critical Chancem, etc.  This is all built into the base item and the material tiers. A base longbow has a damage value of 6, and then each material tier applies a multiplier to that.  For example an Elm bow has a 1.0 multiplier, but a Dragonthorn bow has a 1.6 multiplier.  So how does all this tie in?  The way I believe it works is that the Material Progression property tells the game scripts what possible material tiers the item can be when it does its autoleveling.  You’ll note that one of the options is “All Woods”.  I think this means the script can set it to any level as appropriate.  On the other hand if you set Material Progression to “Bow, Ironbark” I think that would tell the script that Ironbark is the minimum tier it can be.  Where does all this come from? It is in the 2da’s, which are really beyond the scope of this tutorial but i’ll talk about them in a future tutorial.  I just wanted to introduce the bsic concepts a bit here.

Ok now that we have our material tier set up, we need to give our item its Name and Tag.  The name is pretty obvious.  The tag is an identifier you can use in scripts to reference this item.  By default it sets the tag to be equal to the Resource Name and I just leave it that way.

The next section, Attributes, allows us to apply some fun things like modifiers and on-hit effects to our item, as well as set its cost.  Cost is first and is simply what the item should cost, in copper.  100 copper = 1 silver.  100 siver = 1 gold.  Let’s give our bow a couple of cool modifiers.  Click on the Item Properties field, then click the 3 dots.  This will open up the Item Properties window where you can assign up to 5 “abilities” to the item.  I remember in NWN the more abilities you added to an item, and th emore powerful they were, the higher level the item became.  I don’t know if it works the same in Dragon Age or not.  In our case we’re going to give it two abilities.  On the left is all the abilities you can assign.  First select the one that says “Faster Aim (0.1s per power)”, then click on the ADD-> button to add it to the item.  When you do this you will see it appear over on the right side of the window.  On the right side you will see three columns, and the far right one is cut off and just says “Po…”.  This is actually “Power” and indicates how powerful this ability is.  By default its 0.  Notice how the name of our ability indicates “0.1s per power” ?  This means that each power level will make the aim time 0.1 seconds faster.  To set the power level simply click the 0 and change it to 1 and press enter.  Next add one more ability, “Increase Electricity Resistance (5 per power)” and set it to a power of 1 as well.  Once you are done click OK to close that window.  Now the next property right below that is OnHit Effect and we’ll use this to give our bow the ability to do electrical damage.  Click the dropdown arrow and select the one that says +electricty damage.

Now, we’re done with editing our item.  So what do we do? Save, and check in.  SAVE is just like most any Windows application, and has a hotkey of CTRL-S or you can go to the FILE menu, or click the little floppy disk icon on the toolbar.  Whatever works for you.  Go ahead and save the item.  Now we need to check it in.  You can do this either by right clicking the item in the tree view on the right, or you can actually also do it by right clicking the item’s filename in the tab list up top.  Again whichever works for you.  Right click and choose CHECK IN.  The checkin window will come up.  Entering a comment is pretty pointless for the average user, but its up to you.  If you dont’ want to enter anything, just click the box that says “I do not wish to enter a comment” then click OK.  This will check in the item.  Notice two things.  First that the top now has a red border and indicates a READ ONLY COPY.  You can no longer edit this item right now.  Also note that on the right, in the tree view, when the item is checkd OUT it has a green checkmark on it, and now that it is checked IN the checkmark is gone.

If for any reason you want to edit this again, simply right click on it and choose CHECK OUT.  Again that whole check out, check in, process is important to be aware of.

Creating an Event Script to Give the Item

We’re almost there.  One last resource to create, and then we can start exporting everything to play with it!  Now that we have the item, we need a way to actually give it to our player.  We’re going to do this through the use of an event script, or module core script.  You see, for certain things that happen in game that affect your module, the game engine calls this module core script and passes it an event to handle.  What we will do is use this to tap into an event that is called when the module loads, and at that point stick the item into our player’s inventory.

Scripts in Dragon Age are in standard C++ and teaching that language is really beyond the scope of this tutorial, so what i’m going to do is simply provide you with a script that you can use that is heavily commented.  First we need to create a new script.  On the pallete window click the icon in the second row, just to the left of the paper icon with a C in it.  It is the paper icon with all the lines on it.  Just like before, right click an empty space and choose NEW -> SCRIPT.  This will pop up the same new resource window we saw before.  Give your script a name, i’m calling mine “module_core_bowathena”.  Set a folder like before as well.  The one thing we need to do differently this time is the Module script shoudl be set to your module, not Core.  Both Module and Owner Module shoudl be your module.  Click OK to create and checkout the new script.

// All module events
#include "utility_h"
#include "wrappers_h"
#include "events_h"
void main()
{
    event ev   = GetCurrentEvent();
    int nEvent = GetEventType(ev);
    Log_Events("", ev);
    switch (nEvent)
    {
        ////////////////////////////////////////////////////////////////////////
        // Sent by: The engine
        // When: The module loads from a save game, or for the first time. This event can fire more than
        //       once for a single module or game instance.
        ////////////////////////////////////////////////////////////////////////
        case EVENT_TYPE_MODULE_LOAD:
        {                           
            // this event can fire multiple times, and we only want to do this once
            // So we save a flag inside a number variable.  We check it here and if its
            // set already then we know we've already done this before.  The name of the
            // variable in quotes can be whatever you want.
            int iModuleLoaded = GetLocalInt(OBJECT_SELF, "aga_bowathena");
            if (iModuleLoaded == 1)
                break;

            // get the object which contains the player
            object oPlayer = GetHero();

            // The flag we save won't persist beyond the game session, so its a good idea to actually
            // look to see if the player already has the item, unless you WANT them to get another one
            // The name in quotes is the TAG of the item.  So what we do is see how many of the item
            // the player already has, and if its 0, we know we haven't given it to them yet (or they sold it :p)
            int iItemCount = CountItemsByTag(oPlayer, "aga_bowofathena");                                       
            // if its 0, then let's give them the item.  Now this first parameter is a RESOURCE identifier.  Note
            // how its formatted.  R"resource_file_name"
            // The "R" part is important and identifies it as a resource.  The filename is just the filename of the
            // resource.  You can see this in the toolset on the tabs up top.
            // The number 1 means give 1 item.
            if (iItemCount  == 0)
                UT_AddItemToInventory(R"aga_bowofathena.uti",1);

            // lastly we set that number variable we talked about earlier, to save the fact that we've
            // done this already.
            SetLocalInt(OBJECT_SELF, "aga_bowathena", 1);
            break;
        }
        default:
        {
            break;
        }
    }
}

Editors Note: In the time since I wrote this original tutorial, better ways of doing things have emerged. While the above is a great simple introduction, its not the best way to do it in a released mod. Please follow up with this article.

Once you have entered the script, save it.  In the case of a script it will take a bit longer to save.  It has to compile the script for you.  Once it is done, check this in as well.  Now we need to set the module to use this script as its core script.  To do this we need to edit our module properties again, so go back to FILE -> MANAGE MODULES and select our module, then click on PROPERTIES.  Click the Script property, click the 3 dots, and select the script you just made.

If you skipped creating a new item, and want to just give yourself an existing item then you will still need to know the “tag” and “resource filename” of the item.  You can find that by simply selecting the item in the tree view on the right.

Exporting Your Module

We’ve now come to the final step.  All the hard work is done, now all you need to do is export your resources and your module so that it shows up in game.  To do this, we first need to export each resource we made.  If you made an item, you need to export that.  Click the sword icon again to go back to items, then right click your new item and choose EXPORT -> EXPORT WITHOUT DEPENDENT RESOURCES.  Then go to the scripts and do the same thing for your script.  Lastly, to export your module go to the menu, TOOLS -> EXPORT -> GENERATE MODULE XML and then TOOLS -> EXPORT -> GENERATE MANIFEST XML. 

Now go ahead and run the game, and you should see your module in your downloaded content.  Start a new game or load an existing save and you should find your new item in your inventory.  Enjoy!

FOLLOW-UP: A followup to this article covers some of the more common problems and mistakes people ran into.