How to use replace package

Structure of info_replace.xml

This is simple replace in itemdescriptor.ndb file. This example adds support for A-99 weapon for NPC.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<Games>

</Games>

<Name>NPC Weapons Support</Name>

<Description>Adds NPC support for weapons. NPC now can use some weapons that weren't created for using by NPC.</Description>

<field hash="CBF95ACC" addNode="1" type="String">weaponproperties:fcx.autopistols.a-99</field>

</object>

</Replace>

</Replaces>

</PackageInfoReplace>

There are some standard tags as DefaultInclude, Description, etc...

Now the new tags:

Replaces -- there are defined replace actions, you can add as many as you want, see more below
Replace -- this is replace for one or only in one file. It needs attribute RequiredFile which is complete file name of file in which will be the replace created.

Also, take care of new root tag name -- PackageInfoReplace

Now inside Replace tag there are all fields which will be changed. So, now how to make them?

Replacing a value in FCB

As an example I took adding NPC support to A-99 weapon. We need to change:

text_ tmplWeaponNpcPropertiesName -- hash CBF95ACC
tmplWeaponNpcPropertiesName -- hash 6993CC7C

So, now open converted FCB file. Use FCBConverter for converting files from fcb to xml.

Converted item descriptor for A-99 looks like this:

<field hash="CF68E402" name="text_hid_DTCTH_ClassName" type="String">CItemDescriptor</field>

<field hash="25368426" name="hid_DTCTH_ClassName" type="ComputeHash32">CItemDescriptor</field>

<field hash="D91FFFD3" name="disDbObjectName" type="String">Weapons/Handguns/A-99</field>

<field hash="CF68E402" name="text_hid_DTCTH_ClassName" type="BinHex">CWeaponDescriptorData</field>

<field hash="25368426" name="hid_DTCTH_ClassName" type="BinHex">CWeaponDescriptorData</field>

<field hash="AB0AAEB9" name="selItemAddedStatisticEnum" type="BinHex">FFFFFFFF</field>

<field hash="298E6C00" name="text_tmplWeaponPropertiesName" type="String">weaponproperties:fcx.autopistols.a-99</field>

<field hash="E45A0A1B" name="tmplWeaponPropertiesName" type="ComputeHash32">weaponproperties:fcx.autopistols.a-99</field>

<field hash="6993CC7C" name="tmplWeaponNpcPropertiesName" type="BinHex">FFFFFFFF</field>

<field hash="CB3EDEF1" name="text_hid_DbRefT" type="String">IItemDescriptor</field>

<field hash="57C4D76B" name="hid_DbRefT" type="ComputeHash32">IItemDescriptor</field>

</object>

</object>

<field hash="CB3EDEF1" name="text_hid_DbRefT" type="String">IItemDescriptor</field>

<field hash="57C4D76B" name="hid_DbRefT" type="ComputeHash32">IItemDescriptor</field>

</object>

</object>

<field hash="CB3EDEF1" name="text_hid_DbRefT" type="String">CFCXLootDroppedContainer</field>

<field hash="57C4D76B" name="hid_DbRefT" type="ComputeHash32">CFCXLootDroppedContainer</field>

</object>

The program needs to know which field with hash 6993CC7C you want to replace, because if you search the hash, you will see there are many fields with this hash, so you must define it's parent. In this case the best is to select whole weapon descriptor entry, so you do this:

</object>

Tag primaryKey means that the program will search only objects with hash 59F2984F which has in child fields field with hash 8EDB0295 and its value is 7366C26342072000

You can also add more primaryKey tags if you want to replace more config entries with same values.

Now the other, you define full path to a field which you want to replace, so like this:

<field hash="CBF95ACC" addNode="1" type="String">weaponproperties:fcx.autopistols.a-99</field>

</object>

Attribute addNode with value 1 means that the program add new field with defined hash, type and value.

Field with hash 6993CC7C doesn't have defined type. Why? Because the field exists in config entry, so you don't have to add it to replace. Only if you add new fields, you must define it.

In primaryKey you can use hash or name. The value of primaryKey can be any type, simply add attribute type and set type.

Also, you can use only name attribute, whole replace can be hash-less.

<field name="text_tmplWeaponNpcPropertiesName" addNode="1" type="String">weaponproperties:fcx.autopistols.a-99</field>

<field name="tmplWeaponNpcPropertiesName" type="ComputeHash32">weaponproperties:fcx.autopistols.a-99</field>

</object>

Removing whole config entry

Sometimes you want to remove a config entry. You can do it like this:

</object>

Result:

</object>

This will delete whole object with hash 59F2984F which has child field with hash 8EDB0295 and value 7366C26342072000

You define primaryKey and add attribute removeParent="1". If you add removeParent="2" then two upper parents (objects) will be deleted.

Cleaning whole object

To clean the whole object, for example for adding new fields, use clearNodeBeforeInsert. As the name says, it will clean the object node and after that it can add new fields or objects, or even templates. Value of the attribute is always 1.

Example:

<field hash="CBF95ACC" type="String">weaponproperties:fcx.autopistols.a-99</field>

</object>

will result into:

</object>

Making a duplicate of an object

This can be useful if you want to add a new entry with the same values but only change one or two fields. Notice the newHash attribute which will set the new object's hash.

Example:

This is original config entry:

<field hash="CBF95ACC" type="String">weaponproperties:fcx.autopistols.a-99</field>

</object>

This is prepared replace:

<field hash="CBF95ACC" type="String">new value</field>

</object>

will result into:

<field hash="CBF95ACC" type="String">weaponproperties:fcx.autopistols.a-99</field>

</object>

<field hash="CBF95ACC" type="String">new value</field>

</object>

Notice the changed value of the field.

Making a duplicate of a field

Same as duplicate of an object but for a field. Its value is ignored - it's taken from the source field, so it can be used only as duplication.

Advanced - sorting / reordering objects

Some config entries require to be sorted according to some field values. For this action there are attributes reorder_object, reorder_by and reorder_type. Those attributes must be used together and they're applied to object.

Example:

<field name="SomeFieldName" type="String">SomeValue - Tree</field>

</object>

<field name="SomeFieldName" type="String">SomeValue - House</field>

</object>

<field name="SomeFieldName" type="String">SomeValue - Bench</field>

</object>

Result:

<field name="SomeFieldName" type="String">SomeValue - Bench</field>

</object>

<field name="SomeFieldName" type="String">SomeValue - Tree</field>

</object>

<field name="SomeFieldName" type="String">SomeValue - House</field>

</object>

So, how to define it:

reorder_object - it's a hash of children objects which will be sorted
reorder_by - it's a field in the child object, its value is taken to sorting
reorder_type - type of sorting, it can be asc or desc

Duplicating parent object of primaryKey

This is somehow the same as other makeObjectDuplicate and makeFieldDuplicate, but this one is used only with primaryKey. The attribute name is makeParentDuplicate, value is always 1.

Example:

</object>

As you can see, it will make duplicate of object 59F2984F and change value of field 8EDB0295 which is also used as primaryKey. In this case it makes duplicate and also does some replacing in the newly duplicated object.

Find fields which contains string via primaryKey

There can be situations when you want to find several fields which start with the same string but end with different strings, in this case this feature can be useful. Attribute name is contains, value is always 1.

<primaryKey hash="D91FFFD3" contains="1" type="String">Databases\UI\ShoppingItems_Bowmore\Clothing</primaryKey>

</object>

This will find all objects BB96607D which have a field D91FFFD3 with a string which contains "Databases\UI\ShoppingItems_Bowmore\Clothing".

First-only child primaryKey occurrence

If you want to find primaryKey only in the first child of an object, you can use primaryKeyExact. Classic primaryKey searching fields in all descendants of parent object.

</object>

The reason for usage can be that there can be two fields with the same hash and value in child objects and if you want to select only the first one, then this is the solution.

Replacing fields where cannot be primaryKey set

Sometimes there are config entries which have the same names, but they are like arrays. Like this:

</object>

</object>

</object>

</object>

</object>

And we want to replace field which has value 13. So we make this:

</object>

I added attribute count="3". It means that fourth (because it counts from zero) object will be selected. And now we have selected what we wanted.

This example also shows that I didn't use primaryKey even in object with hash 90E76EC8. And why? Because if you search for hash 90E76EC8 in nomadobjecttemplates_rt.fcb you will see that it is there sixth times and I want to replace all sixth objects.

And now a little more. What if you want to replace only one of the six objects? Do you know how to do it? If not, look below.

We must find parent object of object with hash 90E76EC8.
It is an object with hash C9762625 named as Health. But this is also sixth times there. So we must go upper.
Next parent is an object with hash B96328AF named as StatsAndCounters. But still same. Go upper.
Finally we found object with hash 6E167DD5 named Template. It has child with hash C821B0C6 named FullName. Value of this field is unique -- this is what we need.

So, here is complete replace for only one specific object of six.

</object>

</object>

</object>

</object>

</object>

Also, all strings in primaryKey must be in hex.

What if primaryKey will not exist?

Nothing will happen. primaryKey is like search, if nothing is found, then whole parent object of primaryKey is ignored.

Using replace for field array

There are some config fields with arrays. It means there are multiple values like several Vector3 values.

There are two ways to use replace on array fields - first one is replacing the whole field with new values, the second one is replacing one item in the array.

This is a sample config entry taken from material. It's a field with a Vector4 array defining a color.

</field>

</object>

Here is an example for the first way. We want to replace whole array with own values, so we make a replace:

</field>

</object>

Notice that type was added to the field. It's required because the Mod Installer needs to know what type of array items is used.

This first way is useful when we want to change every item of the array.

Now let's try the second way. It's useful when we want to replace just a single item from an array.

</object>

Notice that type was added to the field. It's required because the Mod Installer needs to know what type of array items is used.

Also notice that arrayIndex attribute was added. It's required for defining what item we want to replace. It's counted from zero so it means the first item has index 0.

In this example we're replacing item with index 10 which is the one before the last one in the sample config entry.