Creating a Custom Merchant for The Player’s Camp – Part 3

In part 1 of this tutorial series, we looked at how we can use a “PRCSCR” file to get the game engine to run a custom script upon entering an area.  This allowed us to then spawn an NPC character that we created inside the Single Player game’s Player Camp.  In part 2 we looked at the conversation editor, and how to create conversations.  We then gave a basic conversation to our NPC in preparation for turning them into a merchant.

In this part we’re going to actually turn our NPC into a merchant that the player can interact with.  Now unfortunately Bioware made what I feel is a bad decision, and made it so that you can not dynamically create a merchant resource.  If you attempt to use CreateObject() with OBJECT_TYPE_STORE you will find that the call fails every time.   This means we need to think outside the box and figure out how to get our merchant resource into the player’s camp.  So let’s see how we can do that.

What We Have right Now

Let’s take a quick stock of what we have.  We have our PRCSCR file that calls our “spawn” script.  We have our Creature resource, and a Conversation resource that is tied to the Creature.  some of you also have a placeable that you are spawning with the merchant, like a chest or crate.  We also have our ShowLocation debug script.

Just to organize things a bit, what i’ve done is gone and created a few folders in the toolset to contain the resources from each part of the tutorial.  You can easily do this by first opening up the properties of one resource, and in the Folder property just type in a new folder structure and it will create that structure, then move the resource there.  Once the folder(s) have been created, you can simply drag and drop other resources into it.

Folders are per resource however so you need to create them for each, but once you have done that you can click on the ALL resource and you will see everything in a nice neat package.

This isn’t a requirement, I just wanted to get us organized.  You can see what I did below.

So in part 1 we have our Creature resource, the spawn Script, and the ShowLocation debug Script.  In part 2 we have our Conversation resource, and you can see there a sneak peek of what we will be doing in this part, another Script which we will use to open our store from the conversation, our merchant, and a new area? Yep.  Just stay with me 🙂

Why We Can’t Just Spawn a Merchant with CreateObject()

When you first think about this, knowing what you now know from past tutorials, you would think this would be as simple as creating a merchant resource, and then spawning it in our spawn script using CreateObject().  It makes sense, but unfortunately you would be wrong.  That would be great if we could, but Bioware made a strange (in my opinion) decision to limit the use of the CreateObject function.  This is what the Wiki says:

Note that dynamic creation of objects in the engine is subject to a host of limitations, reason being attempts to cut down ‘unaccounted’ memory usage.
Avoid using CreateObject whenever possible.

These objects can be created with CreateObject:
– Creature
– Placeable
These objects can not be created with CreateObject:
– Merchant

Note the section I put in bold. Simply put, the engine will not allow you to spawn a merchant dynamically.  That means we need to find some other way to get our merchant into the camp.  It is time to think outside the box.  There are actually three solutions to this that I thought of.  I’ll briefly detail each, but we will only cover one in detail — for now.

Option 1 – Create a new player camp area, and override the original
Easiest, but least compatible

The first, and easiest way would have been to create a completely new area that duplicates the player camp from Single Player.  In this new area we could then have simply used the area editor to drag and drop in our NPC, crates, and the merchant with ease.  We would never have had to bother with the PRCSCR file, or the spawn script.  nice and easy.  We then could use this new area to override the original.

So if this is so easy why didn’t I go this way at the start?  As most of you know, compatibility is very important to me.  I feel it is vital that mod authors make the effort to make their mod work as well as possible with the base game and other mods, as well as any future mods and DLC’s that might appear.  While this solution is the easiest to do, it is also the least compatible of the choices.  It completely replaces the base camp, and while we might make it look the same, there is always the possibility of it not playing well with other mods and future DLC.

Option 2 – Create a small dummy area that holds our merchant, but also loads up with the original player camp
A bit more work, and fairly compatible

For this option, what we would do is still create a new area for our merchant, but it would be a small dummy area that is actually in the same area list as the player camp.  An area list is a list of areas that the game should consider related, and as such it will load all those areas into memory at once.  You can have one outside area, and an unlimited number of inside areas in an area list.  Since all the areas in the list are loaded into memory, we are able to access objects between areas.

So what we can do is create this dummy area, place our merchant in there, then make sure this dummy area is in the same area list as the player camp.  Then we can simply use the merchant from that area while we are in the single player camp.

This is sort of the “middle of the road” solution.  It isn’t the easiest of the three, but it isn’t the hardest either.  It is more compatible than the first option, but not as compatible as we could make it.  It is however pretty darn compatible.  In this case the only incompatible issue is that we are modifying an area list from the base game.  So in theory this could cause a problem if that area list ever needed to change, but the chances of this for this specific area are pretty slim.

This is the option we will be doing in this tutorial.

Option 3 – Re-use the existing merchant in the player camp
This is the most complicated, but also the most compatible

This option is a bit tricky, but doable.  What you would do is essentially re-use the existing merchant that is in the player camp by saving that merchants complete state when your store is opened, then setting the merchant to your store’s state.  Then when the store is closed, saving your stores state and restoring the original merchant.

This is essentially 100% compatible in that it never overrides anything from the base game.  The only thing that could cause a problem was if some other mod actually removed that merchant, but I can’t see that happening.

The downside to this option is that it is the absolute most complicated and requires extremely advanced scripting.  As such we will not be doing that for this tutorial.

Create a Merchant

The first thing we need to do is actually create our merchant resource.  So go ahead and do that.  It can just be in your module, no need for Core here.

There isn’t much to a merchant really.  Give it a name that the player will see at the top of the store window.  I’m going to name mine “Talia’s Store”.  You can leave the script as it is.  It is just a blank script anyway.  If you prefer then you can change that to (none) to be safe.  After that skip down to Pricing and set your markup and markdown as desired.  This is a percent.  For now I set both of mine to 20%.

Lastly you have an inventory property just like our creature did.  You can go ahead and throw items in there depending on what you want your merchant to sell.  You can also play with the restricted items if you want to get advanced.  This property basically allows you to set items that the merchant buys.  You can either set it so the merchant will only buy the items you specify, or so that the merchant will buy anything except what you specify.  Essentially its either a whitelist or a blacklist.

Save it and your done.  Nice and simple!  Now on to the workaround to actually get this in game.

Creating a New Area to Hold our Merchant

I’m not going to go very in-depth into area creation and editing in this tutorial, as it deserves it own writeup, but we will go through the basics of what we need to do.  Since we can’t spawn a merchant through script, we have be able to just drop it into an area through the area editor.  To do this we will create a small indoor dummy area to hold our merchant.

Go ahead and create a new area resource, and set the module to Core Game Resources.  I’m not 100% positive this is required, as I didn’t test it the other way, but let’s just go the safe route.  Once the new area is created and loaded up, you will see pretty much a black screen with some controls on the left.  The reason the screen is black is because our new area has no area layout.  The area layout defines the static geometry of the area.  Over on the bottom right you will see your area’s properties. Open up the area layout and choose “lak105d”.  This is a nice small indoor area.  We want to keep it small so it loads fast and doesn’t use a lot of memory.  Since we won’t actually be sending the player here, it doesn’t matter what it looks like.  They will never see it.

Once you have set the area layout you should actually see it in the main window.  Quick controls:

• CTRL-LEFT MOUSE DRAG will pan the view
• MOUSEWHEEL will zoom the view
• CTRL-RIGHT MOUSE DRAG will rotate the view

If you are like me and used to most 3D applications that use ALT plus mouse buttons, this will drive you absolutely insane 🙂

Putting our merchant in here is simple.  Just left click once on the merchant resource on the right, then click to place it in your area.  Put it inside the room, wherever.  It doesn’t matter.

Once you have placed your merchant, go ahead and save the area, check it in, and export it.  Do the same with the merchant.  We’re done with them.

Hook the Merchant to our NPC

Now that we have our merchant resource, we need a way for the player to actually open it up.  What we need to do is hook it into the NPC that we already made.  We will tie it into the conversation that we made last time.  This is extremely simple to do.

Create a new script resource, and call it something like “blah_openstore” or whatever you want.  Below is the script we will use.  Remember to change your tags to match what you have, and if you copy and paste the script, make sure you retype any quotes or it wont’ compile.

void main()
{
object oPlayer = GetMainControlled();
// This gets our custom area that we made. Use your area’s tag here
object oArea = GetObjectByTag(“tut_merchant_area”);
if (IsObjectValid(oArea))
{
DisplayFloatyMessage(oPlayer, “Custom area found.”, FLOATY_MESSAGE, 16777215, 20.0);
}
else
{
DisplayFloatyMessage(oPlayer, “Custom area NOT found.”, FLOATY_MESSAGE, 16777215, 20.0);
}
// This gets our merchant resource. Again use your tag here
object oStore = GetObjectByTag(“tut_merchant_001”);
if(IsObjectValid(oStore))
{
DisplayFloatyMessage(oPlayer, “Valid store found. Opening store.”, FLOATY_MESSAGE, 16777215, 20.0);
OpenStore(oStore);
}
else
{
DisplayFloatyMessage(oPlayer, “Could not find valid store!”, FLOATY_MESSAGE, 16777215, 20.0);
}
}

What this script will do when run is first look to make sure the dummy area we made is loaded. This isn’t necessary but it is there for debugging. If the area isn’t loaded we won’t be able to use the store, so this check helps us find whats going wrong in that case. Then it looks for the merchant resource, and calls OpenStore() to actually open the store for the player to use.

You may note that i’m starting to put more debugging into our scripts. This is for two reasons. The first is that our scripts are just naturally getting more involved, so its good to be able to know what is working and what isn’t. The second is to make it easier to help you all when problems do occur. Once you have everything working, you can always go back and just remove the debug code.

Go ahead and get that saved and exported, and then we need to hook it to our conversation, so open up the conversation we made last time.

In the conversation, select the nodes that we want to open the store and down at the bottom select the Plots and Scripting tab.  This is broken into two main sections.  Condition and Action.  Each of those sections is then broken up into Plot and Script.  The condition section allows you to define either a plot requirement or a scripted requirement for that dialog option to be displayed.  The action section allows you to assign a plot or a script that is executed when the player chooses that line of dialog.  This is what we want.  We want to assign our openstore script as the script action for the dialog.

Once you have done that, export your changes to the conversation.  Your merchant is now hooked to the NPC.  When the appropriate dialog options are chosen, the openstore script will be run, opening the store up for the player to interact with.

Now comes the slightly hacky part.

Putting our Dummy Area into the Camp’s Area List

This is the part where we have to override one of the core game files.  What we need to do is get our new dummy area inserted into the player camp’s area list, so that it will get loaded with it. This involves editing the core area list, so please follow along closely.

In the toolset go to FILE->OPEN and browse to wherever you installed Dragon Age.  Go to Modules\Single Player\Data and open the file designerareas.erf.

ERF files are essentially archives.  They pack all the game files into these ERF files.  When you load this into the editor you will see all the files that are in it.  What we want to do is find cam100ar_camp_plains.lst in the list.  This is the area list file for the single player camp.  We know this because the filename matches the camp’s tag and it has the .lst extension. Once you find the file, RIGHT CLICK->EXTRACT RESOURCE and specify where to save it. For now I just save it to my desktop as it makes it easy to access. We’ll put everything where it needs to go when we’re done.

Once you have extracted it, then open that extracted file into the toolset. What we’re now looking at is a compiled file. You’ll note that we don’t actually have the normal editor view of the resource. Instead we are literally seeing the raw data that is in the file. However, the toolset does let us edit this in a way, so we can do what we need to do. You should be seeing something like this:

Go ahead and click the plus button next to Area_List and you will see a new entry “0”. Click its plus button as well and it opens up to show “Area_Name” and you can see the tag for the camp in there.

This is essentially an area list with only one area in it. What we are going to do is insert another area, our area, into the list. Left click to select “Area_List” then right click it and choose INSERT->STRUCTURE. When you do this you will see a new entry has appeared, and it should be “1”. Now Right Click on the “1” and choose choose INSERT->RESREF. Again a new entry will be created. At this point yours should look EXACTLY like this:

Now what we have done is add a new entry to the Area List, but we need to clean this up a bit. Double click on FIELD1 to edit it and change it to “Area_Name”. Exactly that (without the quotes). You essentially want it to match the one that appears under “0”. Once you have done that move over to the right side, the Vlue column and double click that to enter a new value. In here enter the tag of the area you created. This is what mine looks like now:

Yours should look exactly the same except for the area’s tag.  Go ahead and save that file.  Since this isn’t a normal resource, there is no checking in or exporting.  Its like a normal file on your computer.  Just save it.

Ok that’s it.  That is all the “hacking” we need to do.

Exporting and Moving Files

Ok we should be all set at this point, so go ahead and make sure everything is saved, checked-in and exported.  Export your module and manifest XMLs, etc.  You know the drill by now.  The last thing we’re going to need to do is physically move one file to the right location.  The area lis file that we modified, cam100ar_camp_plains.lst needs to be placed into <youraddin>\core\override

With that you should be good!  Go ahead and fire up the game and test it out.  Remember that all of this will only work if the NPC hasn’t already spawned.  So its best to keep a save game right before you enter the camp for testing.