Tes4Mod:Cobl/Modding/Techniques

The UESPWiki – Your source for The Elder Scrolls since 1995

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.

Contents 1 Naming Standards 1.1 Package Namespaces 1.2 Variable Names 2 Registration Refs 3 Container Menus 4 Override Scripts 5 Tandem Scripts 6 Obsolete Records

[edit] Naming Standards

[edit] Package Namespaces

• Root names
  • All Cobl content starts with 'cob'.
  • Cobl auxiliarary content (added in a cob esp) starts with 'cab'.
• Package names
  • All records within Cobl belong to a package, which is indicated by what comes after 'cob'. E.g., cobWater for water wells, barrels, etc.
  • Packages in the main part of Cobl are usually named by function.
  • Pure resource packages are usually named by the author. (cobTexWater for Texian's Water meshes.
  • Obsolete records are renamed to add 'old' before their package name.
    • E.g. cobEatPower becomes cobOldEatPower.
• Package naming considerations:
  • The namespace root should be fairly short ('cobSal' for Salmo the Baker).
    • Shorter names are easier to type (in most TESCS record lists, you can jump to a group of names by typing the name out).
    • Shorter names work better in TESCS sometimes narrow columns for editor ids.
• Editor End Codes
  • OS: Object script
  • QS: Quest script
  • MS: Magic effect script.
  • Q: Quest (not always used)

[edit] 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 < numSpells...
• Functional Activators
  • When an activator is constructed to be used as a function:
  • xxxFA: Activator base object.
  • xxxFAS: Script for activator base object.
  • xxxFAR: Placed activator reference.
• Array Variables (OBSE/Pluggy only)
  • Start array variables with 'a'
  • E.g. aShapes, aTargets, aSpells.
  • Might also use a second prefix to indicate type of variables stored in array.
    • E.g. arTargets (array of references), aaShapes (array of shape arrays).
• String Variables (OBSE/Pluggy/Tibixe's String Function Collection only)
  • Start array variables with 'sp' for Pluggy strings, 'st' for TSFC strings
• Number variables
  • Other variables can use prefixes (f for float; b for boolean; ?? for short/long).
  • However, it's usually more natural to not use such prefixes.
    • E.g. hasWater reads more naturally than bHasWater.
    • waterlevel reads more naturally than fWaterLevel.
  • Generally only use prefixes for numbers when there is likely to be confusion over their type.

[edit] Registration Refs

Cobl has a number of features that are designed to be turned on, activated or temporarily owned by Cobl Aware mods. Registration ref variables are used to indicate: 1) that the feature is activated/owned, and 2) which mod or mod function is doing the owning.

One of the distinct advantages of registration refs is that they are self-de-registering. I.e. registration refs occupied a refs from some mod will automatically de-register (become equal to zero) if the mod is removed from the load order.

Example: To enable the dinner plate menu, a survival mod needs to set cobMenuQ.rShowDinner to a ref owned by the survival mod. If that survival mod is later removed by the user, rShowDinner becomes == 0, and so Cobl will disable the menu (remove the item from the user's inventory).

Example: Survival mods differ in the sophistication with which they handle water barrels. More sophisticated mods may need to use some of the "extra" variables that Cobl provides for water barrels (state, afloat, ashort). However, interpretation of these variables will depend on the particular mod used. To ensure consistent behavior, a survival mod can/should take ownership of the barrel like so:

if rOverride != myToken
    set rOverride to myToken
    set state to [initial value]
    set ashort to [initial value]
    set afloat to [initial value]
endif

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.

[edit] 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.

[edit] 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.)

[edit] 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).

[edit] 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.