4 replies to this topic

[Wisp]

Sorry for dragging my feet on this. I started on a full-on documentation project, but since that will evidently take a while I'll post the more pressing now and the rest when/if it's completed.

Item Randomiser is designed to be a customisable mod. This is in part because it is easier for me that way and in part because I realised early on that there could well be a demographic that would appreciate not being locked in by my, or anyone else's, preferences. If you want to add or remove items, introduce new tiers or overhaul the location lists, it's all possible. This set of Do-It-Yourself articles will aim to guide you through the steps of customising these aspects of Item Randomiser to better suit your individual taste.

You'll need a text editor, e.g. Notepad. There are also more powerful and feature-rich editors to choose from (note that, e.g., MS Word will not work, because it's not a text editor). A proper text editor would probably be a good idea, if only because Notepad is too dense to understand any line breaks but CRLF.

I would also recommend some file-comparison utility, e.g. if you want an easy time importing your changes into a new version of Item Randomiser. There are a number of good, free file-comparison programs available, both with graphical and command-line interface. For more information on specific file-comparison programs I'll refer you to this Wikipedia page.

Questions, comments, etc. go here.

Index:

• Documentation of the item-list format
  
• How to keep an item from being randomised
  
• How to add items to the randomisation pool
  
• How to remove locations

Edited by Wisp, 01 November 2011 - 04:33 PM.

[Wisp]

Item lists control which items are randomised under which circumstances.
There are 4 item lists:

• bg1item.2da - Main item list for BG1.
  
• weidu_bg1item.2da - Extension list used by Mode 2 for BG1.
  
• itemlist.2da - Main item list for BG2.
  
• weiduitem.2da - Extension list used by Mode 2 for BG2.

Item lists follow a 6-column format, with each row corresponding to 1 item. A column is a whitespace-separated sequence of characters. If a row is deleted from a list (or is made to contain less than 6 columns), that item will not be randomised when the mod is installed.

The 6 columns are Item, Replacement, Source, Tier, Token and Ident:

Item
This column holds the filename of the item, sans the file extension (.itm). This is commonly known as the resource reference, or resref for short. A resref can never be longer than 8 characters. If the item does not exist it will not be randomised.

Replacement
If this column holds an item resref that item will replace the randomised item. The entry "blank" is the canonical value for no replacement item. If Source is a creature the replacement item must be of the same type as the randomised item.

Source
This column holds the full filename of the file the randomised item is to be taken from. The entry "blank" is the canonical value for randomising the item without removing it from anywhere. If the Source does not exist the item will not be randomised.

Tier
The tier the item belongs to.

Token
The item's token. Each token must be unique within each tier. For the main list (Mode 1) there's a soft limit of 25-30 (any more and the randomisation takes forever) and a hard limit of 36 items per tier.

Ident
The item's identifier. A case-insensitive value of exactly "x" means the item has no identifier. An identifier should be absolutely unique. The results of a duplicated identifier are currently undefined. The primary purpose of the identifier is to connect an item and a location. Locations have identifiers as well. If an item with a non-x identifier is removed from an item list the corresponding location will be skipped as well.

Edited by Wisp, 10 October 2011 - 01:25 PM.

[Wisp]

Keeping an item from being randomised is fairly easy. You do this by editing one or more text files before installing the mod.

Refer to the section on item lists for more information on that subject.

As an example, say we wanted to remove the Robe of Vecna from the BG2 list, so it'd show up in its usual place in Deirdre's shop. To do that we first need to know what the item file is called. As of version 5, this information is included in the spoilers document. Secondly, we need to know which list to edit. This information can also be obtained from the spoilers document.

In our example, the Robe of Vecna is wa2robe and since it's a BG2 item that isn't exclusively randomised by Mode 2 we know the list is itemlist.2da. Next, we open the list file in a plain-text editor (e.g. Notepad but not MS Word) and find the row where the first column holds the item we want.

clck26	  blank	   sahramb3.cre 7	02	i34
wa2helm	 blank	   wmart2.sto   7	03	x
wa2robe	 blank	   wmart2.sto   7	04	x
wa2shiel	blank	   wmart2.sto   7	05	x
waflail	 blank	   wmart1.sto   7	06	x

We delete the row, like so:

clck26	  blank	   sahramb3.cre 7	02	i34
wa2helm	 blank	   wmart2.sto   7	03	x

wa2shiel	blank	   wmart2.sto   7	05	x
waflail	 blank	   wmart1.sto   7	06	x

Then we save the file. When the mod is installed the Robe of Vecna will not be randomised.

[Wisp]

Adding an item to the pool of items to be randomised is generally not difficult. However, there are a few caveats:

• Item Randomiser has two kinds of items lists: a main list and an extension list. The latter is used exclusively by Mode 2, but the main list is used by both Mode 1 and Mode 2. When you add an item you can choose to have the item taken from somewhere else or to have the item simply be added. The main list can only take items from area, creature and store files (there are two exceptions, but that's just what they are: exceptions). If the items needs to be taken from somewhere else it needs to go in the extension list.
  
• Beware of "scripted" items. These items are the ones that are tied into the game in a more complex manner than usual, usually through one or more scripts. Examples include the Dragonslayer sword and the Dragon Scale Shield at Firkraag's or the Constitution tome in BG1. Randomising "scripted" items is outside the scope of this tutorial.
  
• Some tiers have "special" locations. These locations are handled by specialised tp2 code and behave differently depending on what item is randomised there. Examples include the Machine of Lum the Mad or Jermien at Umar Hills. Both these locations tailor the reward text after what item is given as the reward. There is always a fall-back option to cover unhandled items (that is, you don't have to do anything) but it is something to be aware of.
  
• Some items have interactions with other mods and that can result in complications. E.g., Jasper from Dungeon-Be-Gone will give you a Girdle of Bluntness regardless of whether the Girdle in the dungeon is actually there or if it's been randomised. Item Randomiser has systems for handling this, but using them is not altogether straight-forward and is outside the scope of this tutorial.

There are a few things to adding items. First, you obviously need to know what item you want to add. Second, you need to decide if the item should be taken from anywhere, or simply be added. If the item should be taken, you need to know where to take it from. Third, you need to decide what tier the item should be added to, and whether it should be added to the main list or the list for Mode 2.

You'll probably need Near Infinity (NI).

The item
The best way to find out what the item is called is by using NI. Start NI and select Search->CRE/ITM/SPL/STO... and select Items. Enter the name of the item (or part of it) and hit Search. You'll get a list of all items matching the entered name. You want the "item code," which is actually part of the file name. E.g., if you searched for "Gauntlets of Fumbling" you want "brac08."

The source
NI also has the ability to find references to a particular file in other files. This can be used to find the "source" file, from which our item should be taken. We can also use it to assess if it is safe to randomise our item. Open the item in NI (e.g., by finding it through a search) and switch to the Edit tab. At the bottom there's a button called "Find..." Select Find...->references to this file. Select all of ARE, BCS, CRE, DLG, EFF, SPL and STO and deselect everything else and hit Search. You will most likely come across a couple of errors, two concerning XR2400.ARE and XR2600.ARE. These are probably harmless; the two about AR2400.ARE and XR2600.ARE certainly are.

When the search has completed you'll be presented with a list of files that reference our item file. If there's just a single file it's all green. That file is our "source" and it means it is safe to randomise the item. If the search result includes more than one file it gets a bit more tricky. Some items are not unique, others may be "scripted" and yet others may have something else going on.

If you know where the item you are interested in is supposed to be that may be enough. E.g., if you want to randomise the Girdle of Bluntness from Irenicus' Dungeon, you can ignore the references in ppumb01.sto and temtalos.sto because those are both stores and refer to other instances of the girdle. Areas starting with "XR" is cruft left over from when Bioware was making and testing the game and are to be ignored. All real areas start with "AR" is BG2, BGT and BG1 (they start with "FW" in Tutu). Hence AR0603.ARE is our "source" file.

If the search result includes .BCS, .DLG, .EFF or .SPL files and the item itself is not awarded by a script or a dialogue, the item is most likely "scripted" and cannot be safely randomised without additional work (outside the scope of this tutorial). However, there are a few exceptions. E.g., the Helm of Balduran in BG1 is referenced by one area file and one dialogue file, but the dialogue file is unrelated to how the helm is found (the scene with Degrodel will play out the same regardless of how and where you acquired the helm). Consequently the helm can be safely randomised if you are so inclined. If you are in doubt about whether the item is safe or not you can always ask.

Adding the item
So you know what the item is called and you know where it should be taken from (if applicable). The next step is constructing the appropriate line and adding it to the right item list.

Open the item list in a text editor (e.g., Notepad but not MS Word). The line you want to add should follow the same format as the rest of them. You can find more details in the appropriate section.

It does not matter much where you add your line. You can add at the end of the file, or somewhere in the middle or wherever you prefer. All lines of 6 or more columns are considered. The order of the lines does not matter.

When you are done, save the file and (re)install the mod.

[Wisp]

In a way removing locations is very simple; you just delete a line in the appropriate location list and you are done. However, for the uninitiated there may be a stumbling block or two. There is also one caveat.

First off, the locations used by Item Randomiser are controlled by location lists. There are 4 location lists:

• bg1location.2da - Main location list for BG1.
  
• weidu_bg1location.2da - Extension list used by Mode 2 for BG1.
  
• locationlist.2da - Main location list for BG2.
  
• weidulocation.2da - Extension list used by Mode 2 for BG2.

You can find out which list and tier a particular location belongs to by consulting the spoilers document. To proceed you need to know which line to delete. However, this may be a little more tricky. There is unfortunately no good, general way to find out what I chose to call a particular location.

For some locations there may be a helpful comment. For locations that have an ident you may be able to figure it out by knowing which item you normally find there and cross-referencing with the item list. You may also be able to deduce it from the area or the Target file name. If all else fails you can always ask.

Anyway, once you have the line, you remove the location by deleting the line. When you then install the mod no items will be placed at that location (note that a location may be present multiple times in the same list).

Important: For locations with an ident (something other than "x" in the Ident column) I strongly recommend you instead remove the item with the corresponding ident (see the section on removing items). For script (.bcs), dialogue (.dlg), spell (.spl) and most ".fl" locations you must do it this way or you'll get duplicated items.

Removing the corresponding item means you'll find the original item in that location instead of a random item. I.e., the item will not be randomised. However, this way of doing it is safe, unlike arbitrarily removing locations.