Blockhead

Features

• Unrestricted camera movement in the race edit menu.
• The ability to override the inventory menu’s idle animations.
• The ability to override head and body assets of NPCs on a per-NPC/per-Race basis.
• The ability to override animations of NPCs on a per-NPC/per-Race basis.
• Tidyman’s carpets.

Fine Print

The camera in the race/sex menu can be controlled with the directional keys (arrow keys and WSAD) and the mouse (while holding down the Shift key). It can be reset to its original position by clicking on the left mouse button and dragging. Movement and rotation speeds can be configured in the plugin’s INI file.

Inventory idle animation overriding allows custom idle animations to be applied on the inventory menu’s 3D player model without resorting to replacing existing assets. There are 8 available overrides, from which one is automatically selected by the engine depending upon the player character’s equipped weapon. The override values in the INI file should be set to the filename+extension of a valid KF file placed inside the Meshes\Characters\_Male directory.

Blockhead implements a 3-tier override tool for customizing NPC body/head textures and meshes:

• Tier 1 (Script)
  Applied by using script commands. Refer to the command list below.
  
• Tier 2 (Per-NPC)
  Applied by placing assets (textures/models) in the following folder: <Textures\Meshes>\Characters\<Body\Head>AssetOverrides\PerNPC\<ModFileName.ext>.
  Asset naming convention: 00XXXXXX_<PartName>.<ext>, where XXXXXX – FormID of the NPC (without the mod index).
  Auxiliary files such as normal maps, TRI, EGM, EGT files, etc. need to be similarly named, i.e, <FileNameAsAbove>_n.dds.
  
• Tier 3 (Per-Race)
  Body: Applied by placing assets in the following folder: <Textures\Meshes>\Characters\BodyAssetOverrides\PerRace\<M\F> (where M\F corresponds to the gender of the NPC).
  Asset naming convention: XXX_<BodyPartName>.<ext>, where XXX – Name (nottheeditorID) of the race.
  
  Head: Head part asset overrides work differently. Since all head part related paths are defined, by default, at the Race level, overrides are only used to support gender variance. The override file paths are automatically derived from the originals defined in the Race record.
  Asset naming convention: <Original Path\Filename>_<M\F>.<ext>, where M/F – Gender.
  As with Tier 2, auxiliary files need to be renamed appropriately.
  

Valid BodyPart Names:

• UpperBody
• LowerBody
• Hand
• Foot
• Tail

Valid HeadPart Names:

• Head
• EarsMale
• EarsFemale
• Mouth
• TeethLower
• TeethUpper
• Tongue
• EyesLeft  (Model override only)
• EyesRight  (Model override only)

Order of precedence: Tier 1 > Tier 2 > Tier 3 > Default Asset.

Tier 1 overrides do not persist between game sessions and therefore need to be reapplied on loading a save game.

Body/Head parts without a pre-assigned asset can also be overridden, i.e., parts that do not have a valid model/texture path assigned in the editor. Tier 3 overrides for such head parts, however, must be placed in the following directory:

<Textures\Meshes>\Characters\HeadAssetOverrides\PerRace\<M\F> (where M\F corresponds to the gender of the NPC)
…with the following naming convention: XXX_<HeadPartName>.<ext>

Body EGT file overrides work in the same way as body mesh overrides.

In addition to the aforementioned head parts, Blockhead adds limited overriding support for the following:

• Hair – Hair assets can be assigned gender-specific files by adding a ‘-M’ or ‘-F’ suffix to their filenames.
• Age Overlays – Age textures can be overridden on a per-NPC basis through script commands or custom assets placed in the following folder: Textures\Characters\AgeTextureOverrides\<ModFileName.ext>.
  
  File naming convention: 00XXXXXX_YY.dds, where XXXXXX – FormID of the NPC (without the mod index), and YY – Age. Script overrides supersede the latter but do not persist b’ween game sessions.

NPC animations can be overridden on a per-NPC/per-Race basis too. Animation overrides are implemented as special animations internally. All animation files need to be placed in the following directory: Meshes\Characters\_Male\SpecialAnims.

• Per-NPC – Override files must use the following naming convention: <Filename>_BLKD_PERNPC_XXX_00YYYYYY.kf, where XXX – Name of the mod file name + extension, YYYYYY – FormID of the NPC record, without the mod index.
• Per-Race – Override files must use the following naming convention: <Filename>_BLKD_PERRACE_XXX_Y.kf, where XXX – Name (not editorID) of the race, Y – Gender (M/F).
  
  The first part of the filename must follow the same naming convention as the vanilla game’s, e.g., BowIdle_PERRACE_Impossibly-Endowed Marshmallow Elf_M.

An NPC can be affected by more than one override at the same time – The engine has the final say on which animation file gets used (the actual mechanics of the picking logic is yet to be discovered/understood).

Equipment override – Mods can register a user function script as a handler that will get called every time an item is equipped by an actor (player or otherwise). It basically works like this:

1. Control script calls RegisterEquipmentOverrideHandler with the following parameters:
   • Handler user function (ref) – A user function that takes the following parameters: (you can pass zero as a filter argument, which will consequentially skip that particular filter check
     • Equipped Item (ref) – Base form of the inventory item being equipped
     • NPC (ref) – NPC base form of the calling actor
     • Race (ref) – Race of the calling actor
     • Female (int) – 1 if female
   • Filter reference (ref) – A NPC reference in the game world.
   • Filter NPC (ref) – A NPC base form.
   • Filter race (ref) – A race base form.
   • Filter equipped item (ref) – An inventory item base form.
2. The command returns an ID for the handler that can be used to unregister it with the UnregisterEquipmentOverrideHandler command. As with the other scripted override commands, they are only valid within the active game session, i.e, the handlers will need to be registered at every game load.
3. When an actor’s 3D is about to be loaded, the handler is called with the corresponding parameters (the handler’s calling reference is set to the actor) if its filters match.
4. If the handle decides to override the model, it must return an array (not a string map) with the following elements (in the same order):
   • Priority – A number b’ween 0 and 100.
   • Override model source – An inventory item base form that is of the same type as the item being equipped.
5. The plugin will call all registered handlers and collect their results. It will then sort the results according to priority (if priorities are equal, the last registered handler wins), pick the one with the highest and apply the corresponding override.

This essentially enables model overriding at an actor reference level. It will not work for the following item slots: (Back/Side)Weapon/Shield/Quiver/Torch. Note that handlers can be called multiple times for a single equip sequence.

The plugin’s INI file is generated after first run (in the same folder as the DLL file) and contains options to toggle its features.

Command List

SetBodyAssetOverride
Applies a body asset (script) override to the calling ref’s NPC form. Returns true if successful. The path must be relative to the Data\<Textures\Meshes> folder and must point to a valid asset file.

        (success:bool) ref.SetBodyAssetOverride overridePathFormatString:string var1 var2 … var20 bodyPart:int assetType:int (opt)baseNPC:ref

GetBodyAssetOverride
Returns the (script) override asset path of a body part. Returns an empty string when no override is found.

        (path:string) ref.GetBodyAssetOverride bodyPart:int assetType:int (opt)baseNPC:ref

ResetBodyAssetOverride
Removes a body part’s (script) override asset.

        (nothing) ref.ResetBodyAssetOverride bodyPart:int assetType:int (opt)baseNPC:ref

SetHeadAssetOverride
Applies a head asset (script) override to the calling ref’s NPC form. Returns true if successful. The path must be relative to the Data\<Textures\Meshes> folder and must point to a valid asset file.

        (success:bool) ref.SetHeadAssetOverride overridePathFormatString:string var1 var2 … var20 headPart:int assetType:int (opt)baseNPC:ref

GetHeadAssetOverride
Returns the (script) override asset path of a head part. Returns an empty string when no override is found.

        (path:string) ref.GetBodyAssetOverride headPart:int assetType:int (opt)baseNPC:ref

ResetHeadAssetOverride
Removes a head part’s (script) override asset.

        (nothing) ref.ResetHeadAssetOverride headPart:int assetType:int (opt)baseNPC:ref

GetFaceGenAge
Returns the age of the calling ref’s NPC form.

        (age:float) ref.GetFaceGenAge (opt)baseNPC:ref

SetFaceGenAge
Sets the NPC’s age. Age values must lie between 15 and 65.

        (nothing) ref.GetFaceGenAge age:int (opt)baseNPC:ref

RefreshAnimData
Refreshes the calling reference’s animation state.

        (nothing) ref.RefreshAnimData

SetAgeTextureOverride
Overrides the age texture base path for the calling ref’s NPC form. Returns true if successful. The path must be relative to the Data\Textures folder and the corresponding textures must use the following naming convention: <BasePath><Age>.dds

        (nothing) ref.SetAgeTextureOverride overridePathFormatString:string var1 var2 … var20 (opt)baseNPC:ref

ResetAgeTextureOverride
Removes the NPC’s age texture base path override.

        (nothing) ref.ResetAgeTextureOverride (opt)baseNPC:ref

ToggleAnimOverride
Enables/Disables Blockhead’s animation overrides on the NPC. RefreshAnimData needs to be called for immediate effect.

        (nothing) ref.ToggleAnimOverride state:bool (opt)baseNPC:ref

RegisterEquipmentOverrideHandler
Registers a user-defined function script as an equipment override handler. Returns the ID of the registered handler if successful or 0 otherwise.

        (id:long) RegisterEquipmentOverrideHandler handlerScript:ref (opt)filterRef:ref (opt)filterNPC:ref (opt)filterRace:ref (opt)filterEquippedItem:ref

UnregisterEquipmentOverrideHandler
Unregisters an existing equipment override handler script.

        (success:bool) UnregisterEquipmentOverrideHandler handlerID:long

Valid Body Parts:

UpperBody   – 2

LowerBody   – 3

Hand        – 4

Foot        – 5

Tail        – 15

Valid Head Parts:

Head       – 0

EarsMale    – 1

EarsFemale  – 2

Mouth       – 3

TeethLower  – 4

TeethUpper  – 5

Tongue      – 6

EyesLeft    – 7

EyesRight   – 8

Valid Asset Types:

Texture     – 1

Model       – 2

Body EGT    – 3

Asset related changes will not take effect until the reference’s 3D is reloaded.

Compatibility

This plugin is compatible with every other OBSE plugin there is.
Animation overrides will not work on NPCs that use non-standard file paths for their skeletons, i.e., skeleton meshes must be placed in the Meshes\Characters\_Male directory. Special animations added using OBSE’s ToggleSpecialAnim script command may be superseded by Blockhead’s overrides occasionally. Overrides for some animation groups (such as Cast) may not work consistently.

Known Issues:

• The player’s body model may no update correctly when loading a save game with a player character of a different sex. Equipping/unequipping wearable items fixes this issue.
• Gender-variant hair models may not show up correctly in the race selection menu. Changing the player’s eye models fixes this issue by refreshing the 3D data.

How to install Blockhead:

1. Download and install Oblivion Script Extender (OBSE).
2. Download Blockhead. Extract the “Blockhead_v11.0.7z” archive to any folder and go to the directory where you unpacked it. Right mouse click on the folder named OBSE and select Copy from the right click menu.
3. Now navigate until you can see your game install’s Data folder. Right click on the Data folder and select Paste from the right click menu. You should get a prompt about merging the contents of the source OBSE folder with the OBSE folder that is already in your game’s Data folder … answer Yes to all of the prompts. If you don’t get that prompt then either you haven’t previously installed Oblivion Script Extender (OBSE) or you are pasting into the wrong folder.
4. Launch the game with the OBSE launcher.
   When you first start the game Blockhead will create it’s INI file. Look in your Oblivion\Data\OBSE\Plugins folder for a file named Blockhead.ini … if you have it Blockhead is working, if not you’ve messed up somewhere (you should see Blockhead.dll and Blockhead.ini in the Plugins folder).

Note: when you upgrade to a new version, delete the plugin’s INI.

Uninstall:

1. Delete the following files/folders:

Data\OBSE\Plugins\Blockhead.dll

Data\OBSE\Plugins\Blockhead.ini