NIF Format¶

.nif (NetImmerse Format) is the scene-graph format used by all Bethesda games since Morrowind. It encodes 3D geometry, materials, skinning, particle systems, and collision data as a flat array of typed "blocks" forming a directed acyclic graph.

File Structure¶

NIF Header
Block type strings  — list of unique type names used in this file
Block size table    — uint32 per block (byte size of each block's data)
Block data          — concatenated block payloads in index order
Footer              — root block indices

header_string   null-terminated ASCII — "Gamebryo File Format, Version x.x.x.x\n" or "NetImmerse..."
version         uint32    — e.g. 0x14020007 for most FO4 files
endian_type     uint8     — 1 = little-endian
user_version    uint32    — Bethesda-specific (e.g. 12 for FO4)
num_blocks      uint32
bs_version      uint32    — Bethesda stream version (e.g. 130 for FO4)
author          ShortString (uint8 length + chars)
process_script  ShortString
export_script   ShortString
num_block_types uint16
block_types     SizedString[num_block_types]  — each: uint32 length + chars
block_type_index uint16[num_blocks]  — maps each block to its type index
block_sizes     uint32[num_blocks]
num_strings     uint32
max_string_len  uint32
strings         SizedString[num_strings]
num_groups      uint32
groups          uint32[num_groups]

Block data follows immediately after; blocks are parsed sequentially by type.

num_roots  uint32
roots      uint32[num_roots]   — indices of root NiNode blocks

Block Types (Fallout 4)¶

Scene Graph Nodes¶

NiObject — abstract base; all blocks inherit from this.

NiObjectNET — adds:

name         NiStringRef   — index into string table
extra_data   uint32[]      — indices of extra data blocks
controller   uint32        — index of first controller (linked list)

NiAVObject — spatial object, adds:

flags        uint16
translation  Vector3 (3× float32)
rotation     Matrix33 (9× float32, row-major)
scale        float32

NiNode — scene graph node, adds:

num_children  uint32
children      uint32[num_children]   — block indices (0xFFFFFFFF = null)

BSFadeNode, BSMultiBoundNode, BSLeafAnimNode — specialized NiNode subclasses with small additional flags fields.

Geometry¶

NiTriBasedGeom → NiTriShape (legacy):

data      uint32   — index of NiTriShapeData block
skin      uint32   — index of NiSkinInstance
shader    uint32   — index of shader property block
alpha     uint32   — index of NiAlphaProperty

NiTriShapeData:

num_vertices    uint16
has_vertices    bool
vertices        Vector3[num_vertices]
has_normals     bool
normals         Vector3[num_vertices]
has_vertex_colors bool
vertex_colors   Color4[num_vertices]
has_uvs         bool
uv_sets         TexCoord[num_vertices]   — one set typically
num_triangles   uint16
triangles       Triangle[num_triangles]  — each: 3× uint16 vertex indices

BSTriShape (Fallout 4 primary mesh block):

FO4 replaces NiTriShape with a more compact format:

bounding_sphere  BSBound (center Vector3 + radius float32)
skin             uint32   — NiSkinInstance index (0xFFFFFFFF if none)
shader           uint32   — shader property index
alpha_property   uint32
vertex_desc      uint64   — bitfield encoding vertex attribute layout
triangles        Triangle[num_triangles]  — uint16 triplets
num_vertices     uint16
vertex_data      byte[]   — packed per vertex_desc flags

vertex_desc bitfield (BSVertexDesc):

Bits	Meaning
0–3	Vertex data size / 4
4–7	Dynamic vertex size / 4
8–11	UV size / 4
12–15	UV2 size
16–19	Unknown
20–23	Normal size
24–27	Tangent size
28–31	Color size
32–35	Skinning size
36–39	Landdata size
40–43	Eyedata size
44–53	Unused
54–63	Vertex attribute flags

Key vertex attribute flags: - 0x0001 — has vertex (position) - 0x0002 — has UV - 0x0008 — has normal - 0x0010 — has tangent - 0x0040 — has vertex color - 0x0080 — has skinning weights - 0x0100 — has eye data - 0x0200 — is full precision

When full precision is off, positions are packed as int16 with a scale factor stored in the bounding sphere radius. Normals and tangents are packed as byte components.

BSDynamicTriShape — like BSTriShape but with an additional dynamic vertex data buffer for morphing.

Skinning¶

NiSkinInstance:

data        uint32   — NiSkinData index
skin_part   uint32   — NiSkinPartition index
skeleton_root uint32 — NiAVObject index (root bone)
num_bones   uint32
bones        uint32[num_bones]   — NiAVObject indices (one per bone)

NiSkinData:

skin_transform  NiTransform   — transform from bind pose
num_bones       uint32
bone_list       BoneData[num_bones]

BoneData:

skin_transform  NiTransform   — bone-space bind transform
bounding_sphere BSBound
num_vertices    uint16
vertex_weights  SkinWeight[num_vertices]

SkinWeight:

index   uint16   — vertex index
weight  float32

NiSkinPartition — splits the skin into hardware-friendly partitions with 4 bones per partition. Each partition stores a local bone table and re-indexed vertices/weights.

Shader Properties¶

BSShaderProperty — base class, adds:

shader_flags_1  uint32   — see flag table
shader_flags_2  uint32
uv_offset       TexCoord (2× float32)
uv_scale        TexCoord (2× float32)

BSLightingShaderProperty — standard lit surface:

shader_type     uint32   — see shader types table
name            NiStringRef  — material file path (e.g. "Materials\foo.bgsm")
texture_set     uint32   — BSShaderTextureSet index
emissive_color  Color4
emissive_mult   float32
wetness_spec_scale float32
wetness_spec_power float32
wetness_min_var    float32
wetness_env_map_scale float32
wetness_fresnel_power float32
wetness_metalness float32
[additional fields per shader_type and shader_flags]

Shader types:

Value	Meaning
0	Default
1	Environment Map
2	Glow
4	Parallax
5	Face / Skin
6	(unused)
7	Parallax Occlusion
8	Multi-texture landscape
9	LOD landscape
11	Multi-layer parallax
14	Eye
16	Hair tint
17	Parallax occlusion multi

BSEffectShaderProperty — unlit / particle / glass surface:

name              NiStringRef   — material file path (e.g. "Materials\foo.bgem")
source_texture    NiString      — inline diffuse path
greyscale_texture NiString
env_map_texture   NiString
normal_texture    NiString
env_mask_texture  NiString
env_map_scale     float32
base_color        Color4
base_color_scale  float32
falloff_start_angle  float32
falloff_stop_angle   float32
falloff_start_opacity float32
falloff_stop_opacity  float32
emissive_color    Color4
emissive_mult     float32
soft_falloff_depth float32

BSSkyShaderProperty — sky dome rendering.

BSWaterShaderProperty — water surface rendering.

Textures¶

BSShaderTextureSet:

num_textures  int32  — always 9 in FO4
textures      NiString[9]

Texture slot semantics by index:

Index	Slot
0	Diffuse / albedo
1	Normal map
2	Environment map mask
3	Glow / emissive
4	Height / parallax
5	Environment map
6	Multilayer inner / backlight
7	Specular / smoothness
8	(unused in most shaders)

Collision¶

bhkCollisionObject — links a NiAVObject to a Havok rigid body.

bhkRigidBody, bhkRigidBodyT — Havok rigid body with mass, friction, restitution, collision layer, and shape reference.

bhkShape subtypes: bhkBoxShape, bhkSphereShape, bhkCapsuleShape, bhkConvexVerticesShape, bhkMoppBvTreeShape (MOPP for triangle mesh BVH), bhkNiTriStripsShape, bhkCompressedMeshShape.

Collision data is embedded in the NIF but uses its own Havok-specific serialization within the block payload.

Extra Data¶

NiStringExtraData:

name   NiStringRef
value  NiString

Common uses: BSX flags string, UPB ragdoll data, BGED animation graph path.

NiIntegerExtraData, NiBooleanExtraData, NiFloatExtraData — typed scalar extra data.

NiString Types¶

Type	Encoding
`NiStringRef`	uint32 index into the file-level string table
`NiString` (SizedString)	uint32 length + char[] data
`ShortString`	uint8 length + char[] data

Coordinate System¶

NIF uses a right-handed, Y-forward, Z-up coordinate system. Units are in game units where 1 unit ≈ 0.0142857 meters (70 units per foot, ~7000 units per 100 meters). Scale in Bethesda games is conventionally applied at the NiNode level.

BSShaderProperty Flags (common)¶

Shader Flags 1:

Bit	Flag
0	Specular
1	Skinned
2	Temp Refraction
3	Vertex Alpha
4	Greyscale to PaletteColor
5	Greyscale to PaletteAlpha
6	Use Falloff
7	Environment Mapping
8	Receive Shadows
9	Cast Shadows
10	Facegen Detail Map
11	Parallax
12	Model Space Normals
13	Non-Projective Shadows
14	Landscape (multi-texture)
15	Refraction
22	Soft Effect
23	ZBuffer Test

Shader Flags 2:

Bit	Flag
0	ZBuffer Write
4	Double-Sided
5	Vertex Colors
9	Glow Map
13	Envmap Light Fade
14	Wireframe
15	Weapon Blood