Choose Your Language

Monday, 23 February 2009

Patching A Module

After reading that Amraphael is close to releasing his Zork module for testing and enquiring about haks, I thought I would share this information again about my "Empty Hak" idea. It is a simple idea that allows builders to release haks of any size, and then continue to support their module with a much smaller manageable hak if need be. Not only that, but there is the added bonus that the hak allows the player to patch the module and continue playing within the same game without having to start again. Here is an edited copy of my original post that I made on the Bioware forums 13th July 2007.

THE PURPOSE: To allow players to simply update the module they are playing with latest fixes without having to start the module again.

THE CONCEPT: Use the hak facility to update code in a module that may require fixing.Using a hak to update code is possible because anything in a hak takes priority over the code that is within a module.

PREPARATION: The only real preparation for the builder is to have an "empty" hak (containing nothing apart from a readme.txt explaining what the hak is there for) that is separate from any other hak, which is associated with the module at build time, and that can easily be updated as patches are required. This hak MUST contain this readme file as the hak must contain a file to work.

PATCHING PROCEDURE: Should the builder have the need to change a script or a conversation, or even add items, then all they need to do, is have access to the "temp" folder within the modules directory while they make the alterations. Inside this temp directory are all the files that *can* be added to the hak to make alterations to original mod. For example, if you alter a script (and compile it), *before* saving the module, you can go to the temp directory (alter view by latest files updated) and notice the NCS and NSS files have been updated when last compiled. In this case, it is the NCS (compiled script) that we need to add to the hak that will take priority over the current one in the module. This could just have easily been a DLG (conversation) that had just been altered in some way.

CONSIDERATIONS: Sometimes, resolving the exact problem may not always be obvious, and the builder may have to use other scripts to help resolve the problem in the module. Here is an example of a problem I had with Soul Shaker that helps demonstrate the patching facility at work:


A situation was reported where someone could get themselves locked inside a room without the key to get out.

PATCHING PLAN OF ACTION: I had to find a way of doing the following:a) Check if the player was in this situation.b) Work out a way of adding the key to somewhere in the room if this was the case.

THE PATCH: This problem also required the need for a new item (the key), so in the toolset I built a new key blueprint (that would fit the door) and grabbed that from the temp folder (it was a UTI file). Then I did the following: There was a trigger in the room and so I altered its Onenter script to check if the player fell in the “patch required” category (did they need the key!). If they did, then the new script now created the new key on a nearby humanoid corpse placeable, which I located in the script with GetNearestObjectByTag, which was in the room.

THE PATCH AT WORK: So, I added the new UTI (key item) and NCS (trigger Onenter) files to the “unique” hak that I reserved for this purpose and uploaded it for people to use instead of the previously empty one. Now, when the module plays, it will refer to the scripts in the hak as priority over the “older” ones in the module and play out as explained above. NB: I imagine there may be *some* situations where there is no easy way to "disguise" a patch at work. In other words, if this room in the example above had no access to any nearby objects with scripts, then there may be no other solution than to add the "patch" as an alteration to the players OnEnter script if they meet the "patching" requirements and simply give them the item as they enter the game. Of course, if it is just a variable or other simple scripting process that needs fixing, then this should be very simple to do.

LATER PATCHES: Later patches simply continue to add to this hak as changes are made. I recommend you keep altered scripts in the newer module (even if you resolve the problem by simply changing the module - like placing a key in the room in the example above) because your altered scripts will then still be available for those who are playing an older version of the module and still *require* the altered code.


E.C.Patterson said...

Thanks for explaining your method! :)

Do you know if the "empty hak" can be used to patch previous hak contents? That is, if it's loaded last, I presume?

As well, if a campaign is used, could the campaign folder be used as the "empty hak". I do believe campaign files have precedence over mod files. Though I don't remember if they also have precedence over hak.

Lance Botelle (Bard of Althéa) said...

Hi E.C. Patterson,

Any "empty hak" that takes priority could be used. BUT, for players to not have to start again, the "empty hak" being updated would have to have been originally shipped with the module as part of its final build. There has to be something to update (as it were). As long as the module shipped with the "empty hak" as part of its set of haks, then it should work. Without it, a player would have to add the hak and save the module afresh before making use of it ... but it can work if someone takes this precaution before starting the mod. However, unless you know which scripts/files have been changed to add to the empty hak, it would not be of much use. You have to rely on the builder supplying them in the first place really.

I have not checked to see if the campaign folder takes priority over haks (or module scripts). If it did, then that would be an alternative method. My guess, however, is that it would not .. or there may be some anomolies.

When I get to that stage of my module building, I will know more and report back if I need to. :) For now, I will simply go with the "empty hak" as the safest means to patch my module. This will dave players a lot of restarting anbd frustration .. that's the hope anyway. ;)


Anonymous said...

This, really, is quite clever. In all my years of modding, NWN1 to now, I've never even considered this. How dare you, Lance, come up with such an idea! ;)

I think I might have to 'borrow' this idea. Really, quite interesting. Do you think there could be any potential problems with it, though? At the moment, I cannot, but NWN2 has some odd issues every now and again.


Lance Botelle (Bard of Althéa) said...

Thanks Derek! :)

I would encourage every builder to use this idea if possible, as it relieves the frustration of having to start again when a module is updated. :)

This is the reason I came up with the idea, to prevent players having to restart Soul Shaker as I patched it. At the time I did it, the idea was not used by anyone else, and it met with some great support by other modders and it even got a mention on the PodCast I took part in after winning Debut Author for a NWN1 module. :)

Please feel free to use it ... it's always nice to get a credit mention if you do. :)

I have not had the chance to fully test the idea with NWN2, but all testing to date has proven 100% working, and I had reports at the time (from another builder) that they too had had no problems when using the idea with NWN2.


Wyrin said...

Nice idea, and something to look into.

I can confirm that the Campaign folder does allow some patching. I had some campaign conversations that were broken, and uploading a dlg file fix for people to copy into the campaign folder solved that. And for module conversations/scripts. Not tested on hak content priority tho

Wyrin said...
This comment has been removed by a blog administrator.
Lance Botelle (Bard of Althéa) said...

Hi Wyrin,

(I deleted the second duplicate post that I guess was made by accident.)

Good to hear about the campaign folder. :) It would be interesting to see which has priority between hak and campaign folder. I am guessing the hak would take priority, and I know it does in many ways that the campaign folder *might* not do.

At least with the hak, you know it will work every time (as far as I have tested). I guess time and practice will tell in the future the best way to go. Both sound reasonable.

The hak idea was simply used because there was no campaign folder in NWN1. And come to think of it, there may be the occassion where a builder may not want to make their module using a campaign folder. In such cases, the standardised hak is a familiar concept to all potential players/builders.