the CreationKit Wiki

Difference between revisions of "TES5Edit Documentation"

TES5Edit Documentation (edit)

Revision as of 15:10, 23 February 2017

3,969 bytes removed ,  15:10, 23 February 2017
→‎Mod Cleaning and Error Checking
imported>Sharlikran
imported>Sharlikran
Line 497: Line 497:


Here is a video demonstrating how to make a Manual Patch: [https://www.youtube.com/watch?v=NPKrwES9Cb4]
Here is a video demonstrating how to make a Manual Patch: [https://www.youtube.com/watch?v=NPKrwES9Cb4]
= Mod Cleaning and Error Checking =
== Overview ==
XEdit provides several tools that help mod authors to clean their mods of extraneous / duplicated references, fix deleted references and to merge plug-ins together. These utilities can help a mod author avoid many conflicts with other mods and is considered a best practice. It is highly recommended that mod authors clean their mods before they are released to the general public, which can avert silly and embarrassing compatibility problems after release and make for a more professional showing in the community.
Mod quality is a community wide problem and needs to be addressed on that level. If everyone just tweaks their load order around and cleans mods they installed that's not going to move us forward as a community. It is important that if there are general issues with a mod that these be made public and the author of the mod fixes them. With many of the possibly conflicting changes that a mod makes, it becomes a question of intent when cleaning them up, and only the mod author can give an authoritative answer to that.
This chapter is really dedicated to mod authors, and can be safely ignored by mod-users (whew!). Mod Authors that use the GECK should realize that the GECK can set the modified flag on a thing very easily, and that gets saved into your mod as an override to some standard object. The problem comes when players integrate your mod with others that make intentional changes to the standard object that you inadvertently saved – which is the cause of more conflicts than any other kind between mods today.
Note: Those not convinced by now to read-through and understand the mod cleaning and merging process are sloppy and should be sacked. For the honorable modders who want to contribute to the community in the right way, read-on.


== Mod Cleaning Process ==
== Mod Cleaning Process ==
Line 514: Line 502:
What is the mod cleaning process anyway? The mod cleaning process involves cleaning a mod file of duplicate/un-necessary records and un-deleting objects in the Masters that were inadvertently deleted - setting them to disabled instead. We also check for errors as well as looped level lists. The itemized cleaning process is:
What is the mod cleaning process anyway? The mod cleaning process involves cleaning a mod file of duplicate/un-necessary records and un-deleting objects in the Masters that were inadvertently deleted - setting them to disabled instead. We also check for errors as well as looped level lists. The itemized cleaning process is:
# Identifying and removing records in a mod file that is identical to those in the Master files, which are useless in a mod-file and can cause conflicts with other mods. Removing these from your mod file is a primary goal of this process.
# Identifying and removing records in a mod file that is identical to those in the Master files, which are useless in a mod-file and can cause conflicts with other mods. Removing these from your mod file is a primary goal of this process.
# Identifying any records in the Master files which have been marked as deleted, which XEdit un-deletes and marks as, “disabled” instead. This ensures that any change made to that object by other mods won‟t cause crashes or conflicts, which can happen if a modder accidentally deletes a base object, which is modified by another mod and you get a null pointer – poof!
# Identifying any records in the Master files which have been marked as deleted, which XEdit un-deletes and marks as, “disabled” instead. This ensures that any change made to that object by other mods won't cause crashes or conflicts, which can happen if a modder accidentally deletes a base object, which is modified by another mod and you get a null pointer – poof!
# Identifying any infinite loops in the leveled-lists, and ensure there are no physical/data errors with the mod file to round-out the clean-up.
# Identifying any infinite loops in the leveled-lists, and ensure there are no physical/data errors with the mod file to round-out the clean-up.


For example, modder A inadvertently double-clicks on a wine bottle and it gets marked for save – becoming one of the changes introduced by modder A‟s plug-in. Modder A makes things worse by deleting the whiskey bottle record, removing it from the game!
For example, modder A inadvertently double-clicks on a wine bottle and it gets marked for save – becoming one of the changes introduced by modder A's plug-in. Modder A makes things worse by deleting the whiskey bottle record, removing it from the game!
 
Mod B is added to the player‟s mod-list, which changes the wine bottle making it stronger. Mod A‟s plug-in however conflicts with this and can over-ride Mob B‟s changes without cause (as Mod A‟s author did not intend


to change the wine bottle). Furthermore all occurrences of the whiskey bottle are now bogus. When Mod B tries to change the whiskey bottle, it finds no whiskey bottle to change and Fallout: New Vegas will crash.
Mod B is added to the player's mod-list, which changes the wine bottle making it stronger. Mod A's plug-in however conflicts with this and can over-ride Mob B's changes without cause (as Mod A's author did not intend to change the wine bottle). Furthermore all occurrences of the whiskey bottle are now bogus. When Mod B tries to change the whiskey bottle, it finds no whiskey bottle to change and Fallout: New Vegas will crash.


Modder A could avoid both of these issues with the mod cleaning process, which un-deletes references that were deleted on accident and un-does inadvertent changes to things in the game that were not intended. The screenshot below illustrates the start of the process, in which you must load-up XEdit and follow the steps herein:
Modder A could avoid both of these issues with the mod cleaning process, which un-deletes references that were deleted on accident and un-does inadvertent changes to things in the game that were not intended. The screenshot below illustrates the start of the process, in which you must load-up XEdit and follow the steps herein:
Line 529: Line 515:
Note that you can also, “Select All” or “Invert Selection”, which gives you additional controls over which mod-files are selected for loading into XEdit. For the mod cleaning process, we only want to load the plug-in being cleaned. You can do this using the, “Select None” menu option, and then clicking on the mod file to be cleaned.
Note that you can also, “Select All” or “Invert Selection”, which gives you additional controls over which mod-files are selected for loading into XEdit. For the mod cleaning process, we only want to load the plug-in being cleaned. You can do this using the, “Select None” menu option, and then clicking on the mod file to be cleaned.


You should only clean one mod file at a time, and you should not clean other people‟s mod files! There is no harm in running through the process to see if mod A or mod B is filled with dirty edits (after which you can send them a PM on the forums!), but it is considered a bad idea to clean other people‟s mods.
You should only clean one mod file at a time, and you should not clean other people's mod files! There is no harm in running through the process to see if mod A or mod B is filled with dirty edits (after which you can send them a PM on the forums!), but it is considered a bad idea to clean other people's mods.


Once loaded into XEdit, we need to apply a Filter to detect all of the Identical to Master references in the mod being cleaned as shown below:
Once loaded into XEdit, we need to apply a Filter to detect all of the Identical to Master references in the mod being cleaned as shown below:


Clicking on, “Apply Filter” (B) will present the Filter window, just as it did with the Conflict Resolution Process. This filter window however will utilize different options than with conflict detection, as in this case we are only looking at one mod file and one specific kind of conflict – the Identical to Master references.
Clicking on, 'Apply Filter' (B) will present the Filter window, just as it did with the Conflict Resolution Process. This filter window however will utilize different options than with conflict detection, as in this case we are only looking at one mod file and one specific kind of conflict – the Identical to Master references.


The options to select for Mod Cleaning are:
The options to select for Mod Cleaning are:
Line 550: Line 536:
The total number of records filtered and the elapsed time are given, which should be quick. Also note the Yellow/Green text and backgrounds in the screenshot above, which are the references to be cleaned out.
The total number of records filtered and the elapsed time are given, which should be quick. Also note the Yellow/Green text and backgrounds in the screenshot above, which are the references to be cleaned out.


The records to be cleaned will be shown in the View Tab, though at first you won‟t see anything in the view. This is because the default setting for the View Tab is the, “Hide no conflict rows”, which means any rows that don‟t have a conflict are normally not shown (as they play no role in conflict resolution, they are not conflicted!). The screenshot below shows you the simple operation you can perform to see the records that need cleaning:
The records to be cleaned will be shown in the View Tab, though at first you won't see anything in the view. This is because the default setting for the View Tab is the, “Hide no conflict rows”, which means any rows that don't have a conflict are normally not shown (as they play no role in conflict resolution, they are not conflicted!). The screenshot below shows you the simple operation you can perform to see the records that need cleaning:


Once you un-check the, “Hide no conflict rows” setting in the View Tab, you will be able to see all of records just as you do during conflict detection.
Once you un-check the, “Hide no conflict rows” setting in the View Tab, you will be able to see all of records just as you do during conflict detection.
Line 556: Line 542:
Note the grey text with green background in the mod we are cleaning; indicating that they are identical to the Master versions of the same record and should be removed (cleaned). These are often called, “dirty edits”.
Note the grey text with green background in the mod we are cleaning; indicating that they are identical to the Master versions of the same record and should be removed (cleaned). These are often called, “dirty edits”.


A simple visual inspection between the FalloutNV.ESM and BetterCaravans mod reveals the duplicated records that really don‟t need to be in the BetterCaravans mod at all. Removing these will have no negative impact on the mod or Fallout: New Vegas. The process of removing the duplicated, “identical to Master” records involve applying a slightly different filter to the mod, followed by several context menu options as shown below:
A simple visual inspection between the FalloutNV.ESM and BetterCaravans mod reveals the duplicated records that really don't need to be in the BetterCaravans mod at all. Removing these will have no negative impact on the mod or Fallout: New Vegas. The process of removing the duplicated, “identical to Master” records involve applying a slightly different filter to the mod, followed by several context menu options as shown below:


=== Removing “Identical to Master” Records ===
=== Removing “Identical to Master” Records ===


Clicking on the, “Apply Filter” button from the Left-Side Panel‟s context menu will present the Filter window once again. This time choose the Mod Cleaning settings as shown below:
Clicking on the, “Apply Filter” button from the Left-Side Panel's context menu will present the Filter window once again. This time choose the Mod Cleaning settings as shown below:


As before the status of the filtering process is shown in the upper-right menu bar, and once complete the log-file output is shown in the Messages Tab. This filter will load only the data that needs to be cleaned from the mod. The screenshot below again shows how the output may look from this step – which should take just a few seconds:
As before the status of the filtering process is shown in the upper-right menu bar, and once complete the log-file output is shown in the Messages Tab. This filter will load only the data that needs to be cleaned from the mod. The screenshot below again shows how the output may look from this step – which should take just a few seconds:


With the Mod Cleaning filter applied, Golly! It‟s time to get out the Mr. Clean and make this puppy sparkle with goodness! Grab the mop by Left-clicking on the mod that you want to clean, in our case BetterCaravans (A). Splash the Mr. Clean on by Right-clicking the shiny white space beneath the mod your cleaning (B), and spin
With the Mod Cleaning filter applied, Golly! It's time to get out the Mr. Clean and make this puppy sparkle with goodness! Grab the mop by Left-clicking on the mod that you want to clean, in our case BetterCaravans (A). Splash the Mr. Clean on by Right-clicking the shiny white space beneath the mod your cleaning (B), and spin


that mop into action by clicking on, „Remove “Identical to Master” records‟ (C) – and watch as XEdit puts the shine on that puppy!
that mop into action by clicking on, „Remove “Identical to Master” records' (C) – and watch as XEdit puts the shine on that puppy!


You will be presented with the Warning screen, press, “Yes” when prompted:
You will be presented with the Warning screen, press, “Yes” when prompted:
Line 588: Line 574:
looking for any records that you may have deleted by accident. If it finds some, it will un-delete them and then set the reference to, “disabled” so that it will never be seen in-game nor affect your mod.
looking for any records that you may have deleted by accident. If it finds some, it will un-delete them and then set the reference to, “disabled” so that it will never be seen in-game nor affect your mod.


This ensures that if another mod tweaks/changes the item you deleted, that the item will still be in the files (just disabled), and thus won‟t cause Fallout: New Vegas to crash. If your mod file loads with the item deleted and another mod tries to change it, Fallout: New Vegas will crash!  These are among the more serious conflicts that can occur and the reason why it is important for mod authors to run this function as part of the mod cleaning process. The screenshot below illustrates how to activate it:
This ensures that if another mod tweaks/changes the item you deleted, that the item will still be in the files (just disabled), and thus won't cause Fallout: New Vegas to crash. If your mod file loads with the item deleted and another mod tries to change it, Fallout: New Vegas will crash!  These are among the more serious conflicts that can occur and the reason why it is important for mod authors to run this function as part of the mod cleaning process. The screenshot below illustrates how to activate it:


Note that you must Right-click on the mod in the Left-Side Panel to pull the right context menu. In this case you do not want to click on open-space.
Note that you must Right-click on the mod in the Left-Side Panel to pull the right context menu. In this case you do not want to click on open-space.
Line 594: Line 580:
The screenshot below shows the results, which show the log-file output in two places (A and B) in the Messages Tab and on the lower status bar:
The screenshot below shows the results, which show the log-file output in two places (A and B) in the Messages Tab and on the lower status bar:


Now we know for sure that other mods will not run into missing references that were a consequence of changes made in the mod your cleaning. With the second step in the cleaning process complete, it‟s time for the final step.
Now we know for sure that other mods will not run into missing references that were a consequence of changes made in the mod your cleaning. With the second step in the cleaning process complete, it's time for the final step.


=== Purging un-used Master File References ===
=== Purging un-used Master File References ===
Line 604: Line 590:
The screenshot below illustrates how to activate the, “Clean Masters” function:
The screenshot below illustrates how to activate the, “Clean Masters” function:


Unfortunately there is no log-file output for this function, so you‟ll have to trust me that this works correctly.
Unfortunately there is no log-file output for this function, so you'll have to trust me that this works correctly.


The screenshot below illustrates how the BetterCaravans mod looks now that it‟s clean, with its new sparkly (bold)-Green text in both the View Tab (B) and the Left-Side Panel (A):
The screenshot below illustrates how the BetterCaravans mod looks now that it's clean, with its new sparkly (bold)-Green text in both the View Tab (B) and the Left-Side Panel (A):


At this point you should save your mod and load it up in-game to make sure that everything is still happy. There are a few notes about the process to be aware of:
At this point you should save your mod and load it up in-game to make sure that everything is still happy. There are a few notes about the process to be aware of:


Note: You should not clean other people‟s mods! It is the responsibility of each mod owner to clean their own mods, and with the creation of this tutorial there is no longer any excuse why people can do this. If you find a dirty mod, send the mod author a PM on Nexus and tell them they have a dirty mod and reference them to XEdit (please?)
Note: You should not clean other people's mods! It is the responsibility of each mod owner to clean their own mods, and with the creation of this tutorial there is no longer any excuse why people can do this. If you find a dirty mod, send the mod author a PM on Nexus and tell them they have a dirty mod and reference them to XEdit (please?)
 
Note: Make sure that you run Master Update again before testing your mod in-game, as the cleaning process will undoubtedly change references and you want to make sure XEdit synchs everything up. This has shown to prevent crashes.
 
== Checking For Reference Errors ==
 
The “Check for Reference Errors” function reports any case in which the information contained in a module file does not match the XEdit record definitions. There is a very minimal chance that something that's reported as an error is actually an oversight in the XEdit record definitions and not in the module, but all cases should be reported to be safe). Note that there are errors in the FalloutNV.ESM and the DLCs. Both Elminster and Quarn have gone through them all to ensure they are genuine errors. Running the check is a recommended practice as part of the mod-cleaning process as shown below:
 
When the error-check is complete, the screenshot below shows you how the output will look when errors are found in a module:
 
In this example we found both kinds of errors (Ouch!), which was ideal for our tutorial. In the first case XEdit found reference errors where data is missing such as Flags and Idle Timer Settings (A). These errors should be corrected by the mod author and not by you! The error we see in (B) is the result of an unknown Flags type, (Unknown: 15), which XEdit did not understand. These kinds of errors should be sent to Elminster for to ensure XEdit has the right information, or if the mod has some strange error.
 
== Checking for Circular Leveled Lists ==
 
With mods it is possible to have Leveled Lists that reference other Leveled Lists that are perfectly valid. However, it's possible in some cases that a mod builds a circular reference (with as little as 2 leveled lists directly referencing each other, or any number of additional leveled lists in the chain). When the game engine then tries to resolve that leveled lists down to a particular item/creature/NPC, it can get caught in the endless loop and crash. This function looks for such cases and identifies them if they exist:


I have not yet found an example in any mod of such a circular leveled list, but I do know that they exist and that XEdit can spot them. If you don‟t get any output from running this function, then the checked mod is clean of such loops.
Note: Make sure that you run Master Update again before testing your mod in-game, as the cleaning process will undoubtedly change references and you want to make sure XEdit syncs everything up. This has shown to prevent crashes.


= Managing Mod Files =
= Managing Mod Files =
Anonymous user
Retrieved from "https://ck.uesp.net/wiki/Special:MobileDiff/16384"