Tes4Mod:Cobl/Modding/Techniques

This page is dedicated to various standards and techniques used in Cobl. Some of this is particular to Cobl design and use, while other techniques are usable in other mods.

Naming Standards
Variable Names
Common Names:
Show: Will cause something to appear if true.
Override: As a flag of the overriding script.
Bypass: Script is being bypassed. (E.g. cobEatFactorsQ.)
Ref Variables
Ref type variables should almost always be prefixed with 'r'.
E.g. rRealDeath, rBypass, rShowDinner, rNpcRef, rNpcBase.
Even when using OBSE to store other types of formids, use 'r'.
Ref vs. Base variables (OBSE only)
To distinguish between ref vars that hold references and ref vars that hold base objects, use the suffixes "Ref" and "Base" to distinguish between them.
E.g. rTargetRef vs. rTargetBase
Loop control: iXXX, numXXXs
E.g. iSpell, numSpells, rSpell for looping over an npcs spells.
iXxx is the loop counter. numXxxs is the number of elements to loop over.
Counter should run from 0 to 1 less than numXxx.
E.g set iSpell to 0. if iSpell  

Example: Death handling. The rRealDeath and rFakeDeath refs are used to indicate which mod currently owns that function. Since several death handlers may be simultaneously vying to control death handling, these variables provide a way to determine which of the candidates currently owns death handling. Specifically:
If rRealDeath == 0, then a mod is free to take ownership.
After taking ownership, rRealDeath should be checked periodically to ensure that ownership is retained. (It may be that some higher priority mod has taken ownership.)

Note: While ref variables will automatically go to zero if the source mod is de-activated, they will not go to zero if the original ref is removed from the mod, but the mod is left in the savegame.

Container Menus
Container menus are convenient because:
Allow multiple mods to contribute to the container.
Can be provided with a consistent interface to the user.

For more info, see Cobl/Projects/Menu Containers.

Override Scripts
Some scripts in Cobl are designed to be overridden. Several of the survival scripts work this way (cobEatEffectsQS, cobWaterWellOS, cobWaterBarrelOS). 

When overriding these, Cobl-aware mods should never add or remove variables! Not even temporarily! The reason for this is due to the way that variable values stored in the savegame relate back to variables defined in mod scripts. The major danger here is a conflict between Cobl and Cobl-aware mod, or between two different Cobl-aware mods. Such problems can cause CTDs and other strange behavior.

(If errors are accidentally introduced into a script, there are ways to repair it using Tes4Edit, however, this is a fairly advanced technique, and won't repair damage already done to savegames.)

Tandem Scripts
In some places, Cobl supports co-ordination through supporting tandem scripts. Tandem scripts are typically quest scripts designed to operate in parallel. While this is a bit more complicated than Override scripts, its also more powerful since it allows several Cobl aware mods to do the same thing simultaneously. It's also somewhat safer since it's much less prone to variable add/remove errors.

For scripts designed to work in tandem, usually one of the scripts is the "leader" and the other scripts are the "followers". Followers sychronize with the leader by monitoring state variables in the leader.

E.g. the dinner plate has a leader quest cobEatQ which manages the general flow, and several followers (cobEatVanillaQ, cobEatSiQ, etc.) which handle specific sets of foods. The followers do the food moving and calculation based on state variables in cobEatQ. While these followers are all started and stopped by the leader (cobEatQ), a Cobl aware mod could add a new follower quest as a permanently running script; and so long as it followed correctly it would have exactly the same effect as the cobl-supplied followers.

E.g. Death handling mods provide scripts that act as followers to the leader cobMortQ script. These typically operate in two modes: 1) Waiting to become owner; 2) As owner. When the death handler is operating as owner, it may manipulate the state of the leader at times (e.g. forcing the cobMortQ.timer to -10 to prevent it from going to the next state).

Obsolete Records
When records become obsoleted, the original record should be left in the mod. Also, the record eid should be changed to insert an 'Old' just before the package name. E.g. cobEatPower becomes cobOldEatPower.

Scripting Standards
 
Script Types:
  
 
 
 
 
 
Object/Quest/Effect - General, catch-all script types. Use these if no other script type seems applicable and script seems unique. Alternatively, you can create a new script type.
Functional Activator is an object script designed specifically to be used as a function.
 
Service is a "just in time" quest script that is started to provide some short lived functionality and then shuts down. E.g cobEatVanillaQ.
Monitor is a quest script that isn't really for a quest, but rather runs persistently, monitoring and making changes as needed. E.g. cobMortQ.
Monitor scripts can act much like service scripts -- i.e. they can be mostly passive until something else triggers them to provide an additional service. E.g. Wrye Morph's main script runs continuously in monitor mod (where it does periodic checks), but it also runs in service mode after being triggered to provide a morph, new form or teleport.