Tes4Mod:Cobl/Modding/Dinner Plate

Overview
Cobl Dinner provides a dinner plate metaphor for integrating food handling between various food and survival/needs mods. This is not required to be used, but can be used if a survival mod chooses.

This page covers how home modders can use the place dinner plate (aka Home Plate). Modders interested in adding foods and/or supporting hunger mods should instead see Home Plate.

Flow
The dinner plate is managed bye the cobEatQ quest. The script for that (cobEatQS) is well documented and should be the first source of info on how to work with the dinner plate. The general program flow goes like:
User triggers the dinner plate by equipping the +Dinner misc. item from inventory. 
Note that in order for the dinner plate to appear, cobMenuQ.rShowDinner must be set to a valid reference. Survival mods should do this, setting rShowDinner to a reference owned by the survival mods. (See Registration Refs.)
Alternatively the dinner plate can be trigged by an external object -- e.g. a plate or menu in a tavern. In this case the trigger should be configured so that it will draw foods from a local food container rather than the player's inventory. Also, the trigger should be configured to do nothing if cobMenuQ.rShowDinner == 0.)
cobEatQ starts several other quests to run in tandem with itself and do additional work. 
The tandem quests are:
cobEatVanillaQ: Foods from vanilla Oblivion.
cobEatSiQ: Foods from Shivering Isles.
cobEatCoblQ: Foods from Cobl.
cobEatEffectsQ: Survival mod.
cobEatQ than uses its state variable to signal the tandem quests to:
10: Move food from source to destination
40: Calculate the amount of different types of food eaten (meat, dairy, etc.)
60: Apply food eaten to hunger mod (cobEatEffectsQ only)
In between these stages, cobEatQ has additional stages to manage user actions and perform cleanup (e.g. move uneaten foods back to the source container).

Adding Foods
There are two ways to make additional foods be recognized by Cobl. The first is simple, but requires OBSE and Wrye Bash. Conversely for the second.

OBSE
Just add the desired foods to the relevant leveled lists in Cobl. The lists are cobEatDairy, cobEatFruit, etc. Simply create a mod which adds one instance of the food type to the appropriate list (set count and level to 1). Note that Cobl assigns the nutritional value of a given food proportional to that food's weight. So, make sure that the foods have a reasonable weight. E.g. for a hamburger a weight of 1.0 would be about right. See weights of foods in vanilla Oblivion for a guide. (And assume that Oblivion berries are the size of melons. :))

Note that there is one mixed food type list: cobEatMeatVeggieGrain. This is for sandwiches, meat pies, etc. For items in this list, the nutritional value of the food is split equally into meat, veggie and grain categories. Also note that the value of items in cobEatFruit is split equally into fruit and water categories. I.e. half the weight of all fruits goes towards satisfying thirst rather than nutrition.

If more than one mod makes changes to the cobEat lists, then the lists will need to be merged using Wrye Bash. (I.e. using the "Leveled List" component of the Bashed Patch.)

Non-OBSE
If a mod wants to add non-Cobl foods to be recognized by the system, then it needs to add an always on quest script to operate in tandem with cobEatQ. This script should have an fQuestDelayTime of 0.5 seconds or faster. (cobEatQ waits 1 second between 1) signaling tandem scripts to fill the dinner plate and 2) actually opening the dinner plate. It does a similar wait after signalling tandem scripts to calculate amount of food eaten. When writing such a script follow the example of one of the tandem scripts (but be sure that the script continues to run rather than terminating itself).

Hunger Mods
Hunger mods should override the cobEatEffectsQS. When doing this, be sure (as with all such Cobl overrides) to neither add nor delete variables! Adding/deleting variables in overridden scripts runs a very high risk of causing CTD conflicts with other mods.

When overiding the script:
If your mod also provides foods, then it should handle stages 10 and 40 just like a food mod. If not, then it should wait until state 60.
At state 60:
Read the various "ate" variables (cobEatQ.ateMeat), which indicate the sum of each type of food eaten and then figure that into your hunger. 
Reset the "ate" variables to zero.
Set cobEatQ.state back to 0.
Stop cobEatEffectsQ.

Hunger mods should also set cobMenuQ.rShowDinner to a registration ref in order to enable the Dinner Plate menu.

Food Factors
cobEatQ can be configured to:
Exclude types of food from the dinner plate (cobEatQ.noXXX; default: 0)
Set the weighting factor for different types of food (cobEatQ.fXXX; default: 1.0)

These can be overridden in several ways:
Override cobEatFactorsQ: This is the script that actually sets values in cobEatQ.
Set cobEatFactorsQ.likeRace to -2,-1, or 1-10 to have food requirements like a particular race. This is useful for custom races that are desired to act like one of the existing races.
Set cobEatFactorsq.isBloodDrinker. This will cause cobEatFactorsQ to behave like normal except that cobEatQ.noBlood will be set to zero (usually this is only set to zero if pc is a vampire).
St cobEatFactorsQ.rBypass to a registration ref. This will suspend cobEatFactorsQ entirely so that the factors in cobEatQ can be set directly and not overwritten by cobEatFactorsQ.

It would probably be best if hunger mods overrode cobEatFactorsQ, while race adding mods set cobEatFactorsQ.likeRace as needed for custom races.