Actually adding a new NPC

Krunch recently asked me something about "how to add/attach a npc to a map screen". Of course, this is what ToEEWB is for, and there are instructions for it in the tutorials, but it is one HUMUNGOUS tool capable of handling almost every aspect of the game, and finding something specific in it can be a li'l daunting. In fact, I can honestly say I expected someone to ask this, because while those of us who muddled along before ToEEWB came along were able to recognise its power and start familiarising ourselves with it, (because we knew what we needed to do and saw how it helped), someone just starting could get spooked. So, today we are going to add a new character to KotB (the Provisioner, whose dlg I did while over in Malaysia) using ToEEWB. And by 'add a new NPC' I don't mean hack it into the protos.tab - you should be able to do that! - but I mean put it in the game so it spawns and can be interacted with.

But first things first. Yes, you should be able to make NPC protos, but if you can't, a quick guide:

1) Pick either ToEEWB or ProtoEd to make it in. I recommend ProtoEd, but ToEEWB is far more powerful, more accurate (some of ProtoEd's columns are wrong) and lets you do things like copy existing ones better.

2) Get your tool of choice (if u have been following my tutorials you should have both, but otherwise, ProtoEd is HERE and the latest ToEEWB is HERE).

3) Back up your protos.tab before fiddling with it!

Now, do u wanna make a new one or mod an existing one?

To make a new one, you have to open Description.mes in the data/mes folder and put it in. Stick it in the 14000's, where the NPCs go. Then, power up your tool (oo-er). To add a new line to ProtoEd, go to the appropriate number - say, 14888 (or where the appropriate number SHOULD be, in this case, between 14705 (a trader from Allyx's shopmap) and 14996 (a mystery critter for my next little "get-more-of-Cujo's-stuff-into-the-game-without-consoling" effort)). Right-Click on one of the boxes in 14996 and hit "insert row above" from the menu. Shazzam! A new row appears. Double-click the leftmost box, put in 14888, and go for it: the entries are straightforward for a basic proto, more advanced entries can be considered by looking at stuff in the General Modding thread or asking questions there. But to add a new NPC with stats, classes, spells even, feats etc, u just gotta look at what is above, its not that hard. Don't forget to save, and to copy your new protos.tab and description.mes into the root folder of ToEEWB so when u run it in a minute, it can access your new proto.

To do it all in ToEEWB, well, really, read the tutorial Building a New Module, section 27 onwards, where u learn the mysteries of the 'add new proto' button ;-)

Easy. Now, suppose we have our NPC all done (and u have spawned him from the console in-game a few times to test him out). How do we get him to turn up in a game automatically?

There's a few ways. Firstly, you can have him spawn from a critter's dialogue thingy, thats the easiest. We saw that at THIS tutorial, where we spawned spiders from Lareth's dialogue. Simple, but obviously limited in its applications:

Orc Leader: Now you have upset me!

1. [continue dialogue to spawn rest of tribe]

Not that appropriate... but still has its moments (eg its how I bring in the Corporal and Scribe at the Gate in KotB. Must add a little postern door to the Tower for them to have come from).

The next way to do it is spawn from heartbeat. This is how we used to add things in the pre-ToEEWB days. A simple example of this is how I added the sheep and rooster for the original "Something about Mary" mod. Did I ever blog about that? Can't remember... nah I don't think I did, but I shoulda. Here's the script I used:

def san_heartbeat( attachee, triggerer ):
________if (game.global_vars[697] == 0):
________________game.obj_create(14362, location_from_axis (507, 484))
________________game.obj_create(14365, location_from_axis (505, 478))
________________game.global_vars[697] = game.global_vars[697] + 1
________return RUN_DEFAULT

The heartbeat goes off the moment u enter the room (yes, I could have used 'first heartbeat' for it too). Then the rooster and the sheep spawn. BUT you don't want them respawning at every heartbeat, so u only do it when a certain flag is at zero, and the instant it happens u increment the flag so it is never at zero again. Simple. (And yes that could have been done by using game.new_sid = 0 instead of wasting a flag, its already on the list of things to be done for DH2 (current release date - a long way off)).

A very handy if superseded manner of doing things. In this case, it was fool-proof - even if u entered the room with naked steel in your hand and cold murder in your heart and killed Mary instantly, there was no way u could stop that heartbeat - it would always spawn then go away. And Mary was always going to be there the first time u went in. Sooooooo, by influencing her heartbeat, u could make sure the sheep and rooster were always there too.

But what about adding a critter where there is NOTHING there to add a heartbeat or dialogue to - such as Clarisse in DH? (She, like Frank, I added partly to give you a reason to go into those otherwise empty houses - with Frank, I had to add the house interior too). Empty places cry out for NPCs in them, but also by their nature resist these two methods. And how did Mary spawn in the first place for that matter?

The answer to that is .mobs, or mobile onjects. To find out more about these, read the Mobile and Static Objects tutorial that comes with ToEEWB.

Mobs live in the map folder for each map, which in turn lives in the module folder (maps of course change from module to module, where other stuff stays the same). So, Mary's .mob is in

Atari\Temple of Elemental Evil\modules\ToEE\maps\Map-9-Nulb-Interior-Snake-Brothel-2nd-fl

(well, theoretically - actually, it is locked up in the .dats!)

and Clarisse's is fired from a heartbeat attached to a new .mob in

Atari\Temple of Elemental Evil\modules\Co8-4.0.0\maps\map1-int25-herdsman-house

Why make a .mob to fire a heartbeat to make a character? Well, prior to ToEEWB, thats how it had to be done: we could only make the most simple of .mobs, and we made one that was simple (and invisible etc) and gave it a heartbeat and then spawned stuff off its heartbeat. Complicated, and the invisible .mobs, despite all our efforts, still did stuff like turning up in combat if you let off a fireball near them. One of ToEEWB's great achievements is that it allows us to easily make complex .mobs (such as NPC's with merchant inventories, flags set etc). Its other great achievement in my opinion is its ability to add sectors to maps - without it, we could NOT sector new maps (it simply can't be done my hand, I reckon). I suspect there is other stuff that I haven't even discovered yet ;-)

But on with the show. Have you still got ToEEWB powered up? Choose your proto then, and lets make a some .mobs! I will be using 14018, which in KotB will be Porteous, the Provisioner.

Firstly, we stay on the opening page of ToEEWB (the objects page) and click 'new'. Now we have a new .mob (albiet blank). Its identified by the randomly generated Object GUID, which as u can see is so damn long it can randomly generate over and over and never come up with the same thing twice.

Next, we pick our prototype. Click the menu and scroll down. Note this is alphabetical and goes by the name in the description.mes, not necesarily the name u know. That is, I will be looking for 'Provisioner' not Porteous, becuase the prototype is for a provisioner - I only learn he is named Porteous if I chat to him in the game. If you don't know how this is done (its by setting an id number different to the prototype number in col 23 of ProtoEd) then you didn't do it when u made your prototype, and you don't have to worry about it! :-) But if u r ever looking for a prototype alphabetically and get lost, go over to the tab at the top, "Proto Descriptions", and you will find them by number just like in ProtoEd and description.mes.

Find your proto and click on it - note it automatically calls itself a obj_t_npc (you can't change that even if u want to!)

Next is location. Do u know where u want to put it? If not, make sure ed.py is in your data/scr folder (if not, its in ToEE World Builder\Tools\Editor's Assistant, yet another handy little tool thanks to Agetian) then power up the map in question and walk your leader (left-most party member, #0) to where you want to spawn the new character. Then, open the console and type in

from ed import * (then hit [enter] - that loads ed.py)

loc() ([enter])

Write down those numbers, they are the location, then put them in the X and Y things of location. Fine tuning can be done with X and Y offsets (put in 10 or -10 or something to move them slightly, requires tinkering to do).

Note: .mobing things in is FAR more locationally accurate than spawn-by-script. Take the pix of a guard by a bell u may have seen in KotB screenshots: I simply could NOT get him to stand under that bell by console-spawning, it was too close to the wall, despite the fact I had walked under there to get the location with loc(). But the mob placed him exactly where he should be.

For rotation, we can cut-n-paste from Agetian.

5.5 - northwest
5.0 - west
4.0 - southwest
3.0 - south
2.5 - southeast
2.0 - east
1.5 - east (sometimes it looks better than 2.0)
1.0 - northeast
0.5 - northeast (sometimes it looks better than 1.0)

This is the way he will face when he spawns. I'm choosing 3 for the moment.

Other than that, we just have to hit the 'dispatcher' box. Do that for NPCs (though not for other stuff). I forget why, but thats what Agetian said :-)

Now... on the right, you should see some flags. By all means look at them, but do NOT be tempted to click the activator thing at the top (in this case, should be Object Flags) to see them better. As far as I understand (from trial and ERROR) this sets up part of the .mob to hold these flags - once it does, it will crash the game when that .mob is introduced if those flags are the wrong sort (EVEN IF U DON'T SELECT ANY OF THE FLAGS!), and you CAN'T return the .mob to its original state once it is set up for flags (by un-clicking the top box). You'll have to throw it out and start again.

Shouldn't need any Object Flags for your NPC (I don't!) so we'll move on.

Secret doors? Nah.

Scenery? Nah.

NPC/critters? Bullseye!

Does your critter have any inventory? A monster with no loot may not (or a whore in the SnakePit, pre SaM ;-)) but if they do, click "Inventory (Loot/Worn)" - distinguishing it from inventory a merchant sells - and start adding whatever you want. To do so, select the pull-down menu and find what u want to add, then click "add new" (add existing will show you a menu of stuff already in the ToEE World Builder\Mobiles folder that you can attach). Figured it out? Thats right, every item you attach to an NPC is ITSELF saved as a .mob! It is given a GUID by ToEEWB and that is written into the NPC's .mob, so u have to keep them all together once you make them :-)

I am adding a spear, leather armour, shield and a few gp in accord with the KotB module, and some boots (a bare-foot merchant? No thanks). I set the "specific slot" thing of the spear to 220 - check the help/special NPC inventory slots thing to see where everything goes. It actually goes where u want automatically, but I DON'T want a shopkeeper brandishing a weapon so I put it in a different slot (does that work? No idea! We'll see... if not, I will scrap this bit). When I want him to use it, I just do san_enter_combat attachee.item_wield_best_all()

Really, thats about it. Check the NPC flags and both the critter flags sections to see if there is anything u really need (KOS - kill on sight - is important for monsters, but should probably be in the prototype). Otherwise, click save! Its not that hard to make a simple NPC, is it. Later you can make all sorts of complicated stuff, with waypoints and sellable inventories, but there are plenty of tutorials provided by Agetian for that.

Now... having saved, go (back) to ToEE World Builder\Mobiles. This is where your new .mobs are! There will be one for the NPC and one for each item he/she has. I have 7:

Provisioner
Shortspear
Leather Armour
Small wooden shield
Leather boots
Gold
Silver (I threw in a few SP even though the module didn't say - and a couple levels Ranger).

Select all these and copy them, then find your map. If it is not one that has been fiddled before by Co8, then u will have to crack the ToEE.dat with Zane's .dat extractor and go to ToEE/maps and find the map you want. Then, go to Atari\Temple of Elemental Evil\modules\Co8-4.0.0\maps and make a folder with the identical name there (probably you should make a new folder, paste the mobs in, then copy/paste the name of the map folder from the extracted .dat file). Thats it! Once your .mobs are in there, they will show up.

Now, if you don't use Toffee, while u have the maps folder open, CLEAR THE MAP CACHE! Or your new .mob won't show up in game!!!

And finally, if you only created the prototpe with ToEEWB, don't forget to copy that protos.tab and description.mes over to your data/rules folder.

You're done. Run the game, go to the map in question, and there's your new NPC. 8^D

We're done here. Tomorrow I will do a contents page index thingy of these tutorials (another sensible suggestion from Krunch). If anyone else has an idea for something I should write about, suggest away!