Editing Modding Etiquette

== Mod Name, Author, Description==
=== Naming the Mod===
* Don't include version number in mod name, '''''unless''''' new version is incompatible with previous version.
** If new mod is just an expansion of previous mod (and you have avoided mistakes that break backward compatibility), then users should be able to upgrade to your new mod without losing or breaking anything.
* Avoid common names. "Cryon Chorrol House.esp", instead of "My House.esp".
* Avoid starting with _ (underscore) or numbers or odd characters.
* Avoid starting with "The", "A", "An". 
** Some tools allows sorting mods by name. Using articles numbers or odd characters makes the mod list sort in unexpected ways, so that the user has to look in different places (e.g. is the name of the mod "The Ayleid Steps.esp" or "Ayleid Steps.esp".)
* Avoid long names. Long names may not show up in full in some lists (e.g. in Wrye Bash).
** If you will have a number of optional mods, then pick an acronym (or very short name) as your base and then name other mods accordingly. E.g. TIC.esm, TIC - Warfare.esp, TIC - More Magoos.esp, TIC - Less Widgets.esp).

=== Fill in Mod Details ===
Fill in the author name and description. Some tools can display and sort by author name. Also the description should give a basic description of the mod.

=== Include Bash Tags ===
If Bash tags are relevant for your mod, then include them in the description.

=== Include Version Number===
Include a line in the description specifying the version number like so "Version: 1.03". This makes it easy for users to know which version number they're using. Also Wrye Bash's mod list includes such version numbers in the mod lists it generates, which helps other users to diagnose problems with mod lists.

==Documentation==
===Include a Readme===
Include a detailed '''Readme''' file along with your mod. A good readme provides a description of the mod's features, any potential bugs or technical issues, a list of changes made to existing objects, possible sources of conflict with other mods, and some information on how to contact you in the event that a user encounters a problem with your plugin. Creating the readme as a plain text file (such as one written in Notepad) ensures that everyone will be able to read it. And to avoid overwriting another mod's readme, give it a unique name, such as "YourModName - Readme!"
* Here's a sample [http://www.tessource.net/files/file.php?id=4793 readme template] (modder's resource) that includes instructions for how to best deal with ArchiveInvalidation problems.  
* You can also use the [http://lhammonds.game-host.org/obmm/tools_readme_generator1.asp Readme Generator] to quickly build a custom-tailored and professional-looking text file with very little effort. 
* Alternatively, [http://wrye.ufrealms.net/#WryeBash Wrye Bash] (0.42 or later) has readme templates and [http://wrye.ufrealms.net/Wrye%20Bash.html#WikiTextFormat wikitext to html conversion] built in.

If installation is complicated, be sure to include install instructions in the readme.

===Flag Alpha/Beta Releases===
Flag an unfinished mod as alpha or beta release. Unfinished mod include those that have known bugs you weren't able to fix yet as well as mods with missing or awkwardly substituted stuff (for example a pants-icon as placeholder-icon for a new skirt model)

== Packaging ==
=== Archive Naming===
Keep in mind that Bain uses mod archives directly. A well named package is a lot easier to find in a (typically long) list of archives. Same reasoning applies for users doing manual installs who hang onto their archives for future re-use.
* Give your archive a descriptive, unique name. (E.g. not "Manual Install.7z", but "Ayleid_Steps_1-17.7z".)
* Name the archive after the name of the package and include the version number. (E.g. "Wrye Morph 07.7z".)
** Don't use generic names (e.g. NOT "Manual Install.7z").
** Don't start with numbers, underscores or arbitrary symbols (e.g. NOT "_My Cool Mod.7z" and NOT "1_Cool Mod.7z").
** Don't end the archive name like "-1234.7z". TesNexus appends package id numbers to uploaded archives, which Bain uses for it's "Open at TesNexus" command. Hence a number which looks like a TesNexus id, but is not will result in Bain opening the wrong package at TesNexus.
** Don't use ' - ' in the name. Mod sites will convert such names to "Yadda_-_Yadda.yz", which is unattractive. Either skip the dash (Yadda_Yadda.7z) or skip the spaces (Yadda-Yadda.7z).
* When including version number in mod name, use either no punctuation or use an underscore. E.g. for version 1.31, use "131" or "1_31". The reason for this is that some upload sites automatically remove non-extension '.'s in the archive name.
* If mod consists of several downloads (e.g. core plus patch or resource), then start all names the same -- this will cause them to group together when sorted alphabetically.

=== Archive Format ===
Only the following three compression formats should be used:
* Zip is an old standard is easily created/viewed in Windows. 
* Rar is provides a little better compression, but not a lot.
* 7z provides much better compression than zip or rar.

All three of these formats are readable by Bain and OBMM. Other formats (e.g. Ace) are not readable by Bain. 

Large mods should be packed in 7z to reduce download time and reduce the load on download sites. However, you may want to compare it to rar and zip compression levels for particular packages.

=== Archive Structure ===
There are currently two main mod installers: OBMM and [[Bain]]. Many (or rather most) users install mods manually. It's possible to create archives that work well with all three installation methods (OBMM, Bain, Manual). For simple packages, this is fairly easy. For complicated packages (with optional and/or alternate files), triple mode archives are possible, though a bit more complicated to create.

For '''simple packages''' (with no optional/alternate files), the top level of the archive should correspond to the top level of the Oblivion\Data directory. 
* If you include docs, those should go at the top level, or in a subdirectory named "Docs".
* If you include screenshots, those should go at the top level, or in a subdirectory named "Screenshots".

For '''complicated packages''' (with optional/alternate files), the top level should be divided into subpackages as described on the [[Bain]]. This works well for both Bain and manual installs.

===OBMM Support===
OBMM will work readily with simple packages. For complex packages, you can use Bain style sub-packaging, but you'll also need to include an installation script to install all mod files. 

You can provide further support for OBMM by including an omod conversion data\config file in your archive. This can be created using OBMM (e.g. by creating the OMOD and then exporting to an omod-ready archive), or can be created using Bain (v261 or higher) through the "Omod Info..." command for projects.

Summary: the omod conversion data can have four files:
* config: This contains the mod name, version, author, website, email and short description of the mod. This cannot be written by hand, but must be generated by either OBMM or Bain.
* screenshot: This is a screenshot in jpg format (but without the '.jpg' extension). Any jpg image should work, so long as it is renamed to 'screenshot'.
* script.txt: This is the installation script. It can be written/edited in a text editor. 
* info.txt: This is generated by the omod archive export, but isn't actually required. You can skip it.

=== Patch Archives ===
For large mods, its usually desirable to release both full downloads and patch downloads, where the patch download allows users who downloaded a previous version to upgrade to latest version without having to re-download the full mod.

Patch downloads should always be cumulative. I.e. don't require the the download to download one patch that goes from v145 to 146, then another from 146 to 147, etc. Instead, have one patch download that will go from v145 (or higher) to whatever the current version is. 

Patch archives should be named to indicate both the version that they're patching from and the version that they're patching to. E.g. "Cobl 145 to 159.7z". A patch named this way is then expected to patch from v1.45 (or higher) to 1.59.

Tip: Bain users should have two projects: One for the full release and a second for the patch release.

=== Resource Archives ===
For mods that have a large, fairly unchanging resource set, it's sometimes desirable to release that resource set as a separate archive package. E.g. Better Cities follows this approach.

Note: Cobl provides a number of resources (e.g. hair and eyes) that other mods can take advantage of.

== Bug Avoidance ==
* Don't alter anything in cell (3,3) in any existing worldspace. Due to an engine bug, when the player has a mod with edits to this cell active and the cell is loaded, all markers including the player's marker on the local map will disappear. Removing any edits to (3,3) from your mod will fix the problem. This bug does appear by itself even with no mods active, but (3,3) edits will make it worse.
* If your mod adds a bow weapon, or edits any existing bow, be sure to change the Reach value to something other than zero. The suggested value is one. Otherwise, you will trigger a very nasty bug for a small percentage of users where equipping the bow doesn't just crash Oblivion, but can result in a Blue Screen Of Death or a reboot of the PC, depending on their system settings.
* See [[:Category:Troubleshooting|Troubleshooting]] for more bugs and other tips.

== Efficiency ==
* Don't unnecessarily make references persist. Persistent objects are always loaded in memory.

* Check "No Low Level Processing" for actors (creatures or NPCs, even dead/disabled ones) that are never intended to leave a given cell. Low level processing causes their scripts and AI to run once every 5 (?) seconds or so, even if PC is not near.

* Do NOT check '''Quest Item''' unless necessary. Scripts for Quest Item objects run every frame of the game even if PC is nowhere near. If quest item status is necessary, then it's best to turn it on and off using scripts as required.

* Keep your scripting as efficient as possible. Scripts can very rapidly add up and kill performance if too many are running at once - ensure that your scripts are '''only''' running when they need to be. Avoid [[Global Scripts]] as much as possible.
** Avoid using '''GameMode''' blocks if possible. (E.g., if you can use an '''OnLoad''' block instead, do so.)
** If all the script does is enable/disable, consider enabling/disabling from an external script, or if there is a group of related references, assign them all to a single parent reference and enable/disable the parent reference through a script.
** Use quick exits from '''GameMode''' block scripts when possible. I.e., rather than letting the script fall through several lengthy '''If''' statements, instead do a single test at the top to see if rest of script should be skipped, and if so, return.
** When initializing the state of multiple objects (e.g., setting three actor references to attack player under a certain condition), use a single script on one object which sets all, rather than scripting each of them separately. 

* Avoid [[Script_Processing#Remote_Ref_Heartbeat|Remote Ref Heartbeat]] -- Do '''not''' set local variables in every frame of persistent ref scripts.

* Avoid using [[PlaceAtMe]] to create new copies of an object when you could simply use [[MoveTo]] on an existing object. Apparently, placed items are never deleted from the world and if used enough can cause savegame size to expand significantly. (E.g., earlier versions of Harvest Flora had this problem.)

== Design ==
=== Maintain Game Balance ===
Keep game balance in mind when creating mods.  Making an item that would normally need recharging use no charges or creating ''super spells'' with little or no magicka cost will severely alter the balance of game play.

== Integration ==
=== Balance Weapons to MOBS ===
If you're releasing a weapon, try to fit the weapon to MOBS (''Medieval Oblivion Equipment Balance System - an existing and popular weapons balance mod.'')

=== Use Standardized Option Setting ===
Option settings should be done using the Options Prototype. The prototype package provides a starter mod which can be modified and integrated with your mod to provide an option setting mechanism which follows a standard design. 

The option prototype takes the form of a misc item. When Cobl is present, the item will automatically move to Cobl's options menu, and work as usual from there. When Cobl is not present, the item will remain in the players inventory. Equipping it from inventory will bring up the options menu.

== Use Cobl ==
Cobl (Common Library) is a mod that provides a large set of common resources, facilities and items for other mods to use. It provides: hairs, eyes and races; survival mod integration; alchemical sorters; standard options menu; death handling and much, much more. Many compatibility problems and redundancies can be resolved by building on top of Cobl, and your mod can be enriched by drawing from Cobl's large base of objects.

Objections to using Cobl:
* Users must download and install Cobl separately from your mod. However, this is somewhat offset by Cobl's growing popularity -- many mod players already have Cobl installed. 
* Cobl adds quite a bit of stuff which users may not want. This is actually not a problem -- users can choose to not install/activate the various Cobl esp files. Without the "glue" esp files present, Cobl adds very little to the world.

==(Or) Be Cobl Ready==
Even if it's not desirable to make the main mod itself dependent on Cobl, its sometimes possible to build the mod so that it can be patched to integrate with Cobl. In particular:

===Activator Water Wells===
Instead of using statics for water wells, use activators. Such activators can be readily patched to use Cobl water well scripts, which in turn will make them functional with all cobl-aware thirst mods.

===Buffet Plates===
Similarly, buffet plate activators can be added to inns and taverns. These can be patched to provide act as Cobl type buffet plates.

[[Category:Getting Started]]
[[Category:About Modding Etiquette]]
@@ Line 108: / Line 108: @@
 * Avoid using [[PlaceAtMe]] to create new copies of an object when you could simply use [[MoveTo]] on an existing object. Apparently, placed items are never deleted from the world and if used enough can cause savegame size to expand significantly. (E.g., earlier versions of Harvest Flora had this problem.)
-== Compatibility ==
-*Don't alter objects that exist in Oblivion.esm unless your mod is specifically designed to alter them. Examples of bad alterations include changing the contents of a chest, the destination of a load door, the properties of objects, adding a script to an object, or changing a magic effect. Changes like this will affect all instances of that object in the game. To avoid that, copy the existing object with a new ObjectID before making any changes.
-* Keep your mod clean. Information on cleaning mods can be found in the [[Mod Cleaning Tutorial]].
-* Keep any new dialogue clean. Information on unclean dialogue can be found in the [[Unclean Dialogue|Unclean Dialogue Tutorial]].
-* Don't create self-centered dialogue that adds topics or greetings to all NPCs in the world, without a means to avoid them. Another modder might want to create a NPC that knows absolutely nothing about current events or doesn't care about them. If you want to add generic topics to all NPCs, add them to the quest "'''Generic'''" or make your own quest and test for "'''[[GetIsPlayableRace]] == 1'''" and "'''[[GetInFaction]] ForgottenOnesFaction == 0'''".
-* Don't click on '''Recompile All''' in the Script Edit window of the TES Construction Set.  Doing so includes all of the scripts from currently open TES Files in your mod making it bigger in file size and possibly interfering with somebody else's mod.
-* Avoid making any changes to the '''Magic Effects''' menu since your changes could interfere with a new expansion or could conflict with another mod altering the same '''Magic Effect'''. Even if that particular '''Magic Effect''' seems to be unused, it may have a planned use at a future date.
 == Design ==