Hi, I'm trying to use this tutorial to learn the very basics of IE modding. My question is: How do I create the custom itm file for this tutorial?

I'm trying to use the tutorials in this site to learn the very basics of IE modding. Can you explain what the example talk is about? Is it a file you create as a base for the actual mod or is it something else? What are those funny letters and numbers in parenthesis (to v5b.1)?

I want to use these tutorials to learn the very basics of IE modding, but I'm getting overwhelmed with so many tutorials. Which of these would be recommended for beginners?

I've noticed that many links are broken. Some examples of broken links are the ones to Gibberlings 3, igi's DLTCEP setup tutorial, IE modding 101, Adding a trigger to an existing map via WeiDU, and Explaining Creature Patching by .tp2: An introduction.

Thank you, @jastey, that was so helpful . Some questions:

What is the format of dialogue state names?

What language is this? I think I read somewhere that IE scripts are based on a funny scripting language developed in a Brazilian university.

this is the conditions for which this state is called

What conditions can be used to call a dialogue state? What is the purpose of calling a dialogue state?

either PC reply options or other so called "transactions", i.e. actions that will be performed after the NPC line when the player clikcs on "CONTINUE".

What kinds of transactions exist?

I have an awful lot of mod ideas. I have published the list here. As I say in that thread, many of them are not very suitable for a complete beginner, so I would like to start with one of the easiest ones. From the conversation in that thread it looks like some easy ones are:

- Combat log: Say when a character uses a wand or some other magical item.

- Fix Zone of Sweet Air.

- Improve the descriptions of some spells.

Looks like the last one would be the easiest one, I imagine it's just changing a piece of text.

Thank you for all the effort you're putting into helping with this.

What is the format of dialogue state names?

Do you mean why for the tutorial the name "v5b.1" was chosen? Basically, inside the d-file it is whatever you want to name it so you can read your dialogue comprehensibly. So, it's any name+number+symbol combination you want to use to keep track of your states and flow of dialogues. Important: no space inside the name. I name the whole dialogue something I can see which dialogue it is, say "first_meeting" for the greetings dialogue. Then the following states that still belong to this dialogue (because you have some chat options with the NPC) would be first_meeting_01, first_meeting_02, etc.

OK, but why use a funny name like v5b.1 when you could use something like first_meeting_01? That "v5b.1" sounds like an important format that he's using for something...
 

you have a script block in his script which sets a variable, let's call it "Global("xxxNPCReactionY","GLOBAL",1)". The engine then searches through the appropriate dlg-file of that NPC top to bottom. And what it expects to find is a dialogue state with the trigger "Global("xxxNPCReactionY","GLOBAL",1)"

Does it mean that every time you change the value of a variable in an NPC script a dialogue state is called?
 

For NPC PID, the "always true" trigger is "IsGabber (Player1)", meaning "it is the HC talking to me!".

What is an "always true" trigger?
 

What kinds of transactions exist?

Basically anything from here.

But you said that transactions come after the CONTINUE button. One of the actions in that page is, for instance, attacking. But attacking cannot come after the Continue button, because after the Continue button there is always another dialogue part, and it's not possible to attack while a dialogue is on. Attacking can only come after the End dialogue button.
 
Back to the tutorial itself, what's the meaning of all the text colours?
 

Rule 1: Every line should start with a tilde (~) and end with a tilde(~).

Not a single line in the dialogue state we've been discussing starts with a tilde.
 

Every line NPC says should start with a SAY.

This is the opposite of what he said in the previous paragraph.
 

If NPC says several lines, all NPC lines after the one starting with SAY should start with an equals sign (=).

And this is the opposite of the two things he said before.

I think that I can guess what he means, but it looks like he's actually saying the opposite of what he means. Which feels quite confusing, especially for beginners.
 

Rule 3: PC replies should look this way: ++ ~Reply~ + NPC_answers_this_line

What is NPC_answers_this_line?
 

Note: if a line only works under a special condition

What does it mean that "a line only works under a special condition"?

Thanks, that looks promising. So what would be the full contents of the tp2 file?

Yeeeeha! I have created my first mod! I'm the best!

At least in my computer it works. Would you like to check if it also works in yours?

Will remove them.

Now that we've made it work, I'm wondering if we can make it a bit more handy. I want to do the same for many spells, and that can make the tp2 file grow a lot and become quite cumbersome. I'm wondering if we can store the improved descriptions in an external file and use references to that external file in the tp2. That would make the mod much easier to handle. Is it possible to do something like that?

I tried that, but I didn't manage to make it work. When I try to install, WeiDU says Install Component [UNDEFINED STRING:   @1]? I upload the updated version in case you want to have a look.

And, anticipating my next move even before the current one is completed: Is it possible to use more descriptive names for the string references in setup.tra? I'm thinking about something like @blur_description instead of @2.

I tried that, but I still have the same problem. Anything else I might be missing? I attach the updated mod.

Thank you, jastey, don't know how that mistake crept in.

For the spell Protection from evil, 10’ radius I want to change the name of the spell, because it's actually a 15' radius. Will changing the name have any negative impact in the rest of the game? If not, what is the field name for the spell name?

Thank you, that worked. We're getting closer!

I have already edited thirteen spell descriptions, and I'm starting to realize that this is an awful lot of work. Eventually I'm gonna edit hundreds of descriptions, so I think it would save me a lot of time if I could export all those descriptions and their file names (SPIN943.spl and the like) to a big text file and work directly with that text file, instead of having to find and copy the spell descriptions and their file names one by one in NearInfinity. I have tried a couple of ideas in this sense, but none has helped:

- I tried the Mass export tool in NearInfinity, but it just exports a few thousand spl files in binary format. I guess the references to the dialog.tlk strings must be there somewhere, but I don't know how to find them (or even if they would be useful if I did).

- I had a look at the dialog.tlk file, and yes, the spell descriptions are there in plain text, which is nice. They are tangled in funny ways with other strings, but that shouldn't be a problem, I can untangle them. The problem is that I don't have a mapping of these descriptions to their file names (like SPIN943.spl), and without that mapping the descriptions are useless to me. I could still edit the dialog.tlk file directly, but you told me at the beginning of this thread that doing so is "frowned upon" because it is "destructive compatibility-wise", so that's a no-no.

So I'm wondering if there might be any way of exporting the text of the spell descriptions linked to their file names.

That sounds great, Gwendolyne. Take your time.

I wanted to use this tutorial to learn some basics of IE modding, but this is a very complex topic (not for beginners in my opinion) and it's taking us a lot of  effort to clarify the concepts discussed here. I have a lot of mod ideas, but I don't think that these concepts are helpful for the kind of mods I want to create. So I think it's better to leave this area for now and focus on learning the concepts that are relevant for my mod ideas. Maybe I can come back to this tutorial when I have more experience with modding.

Thank you again for all your answers and clarifications.

Thank you, Gwendolyne, that worked like a charm!
 
In order to streamline my workflow I modified a bit that routine to make it generate also the spell file name, apart from the spell name and the spell description. I attach the generated file to illustrate what I'm doing. My goal is to use just string references, rather than string literals, in my tp2 file. This is what I want to do:

COPY_EXISTING @100001 ~override~
SAY NAME1 @100002
SAY UNIDENTIFIED_DESC @100003

Here, @100001 would be something like SPWI201.spl. However, it looks like doing this breaks some syntax rule, WeiDU complains about that @100001 reference. I attach the debug file with the error. What am I doing wrong?

Thanks again, Gwendolyne, that worked very well and the mod is essentially finished now. I ran into a minor issue, though: I removed some of the entries in my list of spells, which means that there is no longer a string for every single reference checked in the loop. Now WeiDU complains that it expected a string for one of the empty references. I guess fixing the code to deal with that should be very straightforward, a simple case of skipping the loop when the text references are empty. But with my almost non existent knowledge of WeiDU I can't figure out how to do it. Can you give me a clue?

Your intuition is very good, Gwendolyne, that also worked

Looks like I have a fully functional mod now. I attach it to this post in case someone wants to try it. If you do try it, though, bear in mind that I'm still changing some descriptions. In that regard the mod is still incomplete, so you'll find mistakes and inconsistencies in the text.

As I work with spell descriptions I've realized that many of them are repeated. For instances, the files cdstaf12.spl, OHBWI308.spl, SPCL722.spl, SPDR301.spl, SPIN579.spl, SPIN714.spl, SPWI002.spl, SPWI308.spl, SPWI399.spl and SPWI997.spl are all copies of Lightning Bolt. That means that every time I change a bit of the description of Lightning Bolt I have to repeat that change ten times. That happens with hundreds of spells. Given the amount of changes I'm doing, that means an awful lot of repeated work. Therefore, even though the mod is perfectly functional as it is, I'd like to modify it to remove the repeated descriptions, so that when I change a description I only have to do it once.

That would be almost trivial in a language I'm familiar with, like Java, but in WeiDU I've no idea of how to do it. It would involve two steps:

1. Modify setup.tra: For each set of duplicated name/description pairs remove all the duplication and leave only one unique name/description pair. Associate each of these pairs with the names of the files to which they belong. This association can be done in several ways. I think the easiest would be to use some sort of numeric pattern in the string ids. I would do this manually.

2. Modify the tp2 file: Adapt the code to the modifications done in setup.tra in the previous step. This probably involves using arrays of strings (or the equivalent data structure in WeiDU) to handle the group of file names associated to each name/description pair.

I'm pretty sure it should be quite easy to do, 10-12 lines of code max. Any tips on how to go about this?

Thank you, Mike and Gwendolyne. I've revamped the whole mod following your suggestions. However, for some reason the tp2 code doesn't work. I guess it must be some very basic syntax problem, but in this case I just cannot figure out what it might be. I attach the mod again so you can check it.

I feel a bit silly asking basic syntax questions like this one, but so far I haven't managed to find any documentation that I can understand. I've tried the WeiDU readme several times, but it looks like it assumes that the reader is a BG modding veteran and it gives for granted many concepts that are unknown for me.

Thank you, Mike, I corrected that and the mod works again (and it's much easier to maintain now).

Once again the mod is fully functional, but it is still incomplete: It changes the spell descriptions for spells, but not for the scrolls used to learn those spells. In order to update the scroll descriptions the first step is to extract the descriptions of the scrolls, just like we did before with spells. For that we used Gwendolyne's description extractor routine. In order to do so I'm modifying Gwendolyne's routine, editing the block that processes spells to make it process scrolls instead.

In this block I want to start by checking what kind of item is in each item file. If it is not a scroll, I ignore it and move on to the next item. Apparently item files store their item types in the "General name" field, so I need to read that field and check its contents. I'm stuck there because I don't know the syntax. This is my rough attempt, which WeiDU doesn't like, of course:

ACTION_FOR_EACH item IN ABAZRING ABISRED1 ACIDBL ACIDMIST ACIDOOZ1 ACIDOOZ2 ACIDOOZ3 BEGIN

    ACTION_IF (FILE_EXISTS_IN_GAME ~%item%.itm~) BEGIN

        COPY_EXISTING ~%item%.itm~ ~override~
            READ_LONG 0x08 item_type
            READ_LONG 0x50 scroll_description
            READ_LONG 0x?? scroll_name  // How do I figure out the offset for the scroll name (identified name)?
            PATCH_IF (scroll_description > 0 AND item_type > 0 AND scroll_name > 0) BEGIN   // Syntax?
                GET_STRREF %item_type% str_item_type
                PATCH_IF (str_item_type == "Scroll") BEGIN // Syntax?
                    GET_STRREF %scroll_name% str_name
                    SPRINT str_name EVAL "@%iter% = ~%str_name%~%WNL%"
                    SET iter = iter + 1
                    GET_STRREF %scroll_description% str_desc
                    SPRINT str_desc EVAL "@%iter% = ~%str_desc%~%WNL%"
                    SPRINT output EVAL "%output%%WNL%%item%%WNL%%str_name%%str_desc%"
                    SET iter = iter + 1
                END
            END
        BUT_ONLY
    END
END

The comments mark the problematic lines, the lines where I'm obviously doing something wrong. Any tips on how to make this work?

This works quite inconsistently in my machine. The colours of the syntax highlighting change very often after I do some editing, but so far I haven't managed to see a pattern of what kind of editing provokes this change. In the picture attached I'm editing a tra file and using the Replace function to remove the line "Saving Throw: None". After removing one line the text above the line removed changes its colours:

Thanks, Gwendolyne, but that doesn't seem to be the problem in my case. For instance, right now the colour highlighting just changed when I reduced the indentation of a few lines. However, increasing the indentation again or even undoing all the indentations doesn't change the colours back.

For the record, a few days ago I tried reinstalling Notepad++ and updating to v7.7 (I was still using v7.6), but that didn't help.

Thank you, Mike, that worked. It took me hours of editing, but I finally have my tra and 2da files updated with the info about scrolls. I could use two 2da tables for this, but I thought it would be more sensible and easier to maintain to keep everything in a single table. In order to do this, though, I had to include the file extensions (spl or itm) in the 2da file, for otherwise there would be name conflicts. So I added some logic to my tp2 file to distinguish between scrolls and spells:

COPY - ~AlonsosMod/spells.2da~ ~AlonsosMod/spells.2da~
READ_2DA_ENTRIES_NOW ~r2en_spells~ 3
FOR (row = 0; row < r2en_spells; row += 1) BEGIN
    READ_2DA_ENTRY_FORMER ~r2en_spells~ row 0 resource
    READ_2DA_ENTRY_FORMER ~r2en_spells~ row 1 name
    READ_2DA_ENTRY_FORMER ~r2en_spells~ row 2 description
    
    INNER_ACTION BEGIN
        ACTION_IF (FILE_EXISTS_IN_GAME ~%resource%~) BEGIN
            COPY_EXISTING ~%resource%~ ~override~
            ACTION_IF (~%resource%~ STRING_CONTAINS_REGEXP ~spl~) BEGIN
                SAY NAME1 (AT name)
                SAY UNIDENTIFIED_DESC (AT description)
            END
            ACTION_IF (~%resource%~ STRING_CONTAINS_REGEXP ~itm~) BEGIN
                SAY NAME1 (AT name)
                SAY DESC (AT description)
            END
        BUT_ONLY
    END
END

WeiDU complained about that, though, so I must have broken some syntax rule there. Can you tell what the problem is?

Thanks, Mike, that fixed it.

And my mod is finished now! 

Who wants to be my guinea pig and try it in their computer?

Thank you, I forgot about this when I started my first mod a few weeks ago. Now I have completed the tutorial, but it's not quite working. It installs and it copies the sword and the dragon to the override folder, but the dragon doesn't have the sword. Can you have a look?