NiForge

A robust and efficient C++ library for parsing NetImmerse / Gamebryo File (.nif) formats.

---

Table of Contents

• Overview
• Prerequisites
• Integration Methods
  • Option 1: CMake FetchContent (Recommended)
  • Option 2: Git Submodule or Subdirectory
  • Option 3: Pre-built Binaries (Imported Target)
• Usage Example
• Contributing
• License

---

Overview

NiForge is a modern C++ library designed for parsing and working with NetImmerse and Gamebryo .nif files (specifically targeted and tested with Gamebryo 20.6 / Wizard101 assets). It provides:

• Fast binary parsing directly from file paths or memory buffers.
• Structured access to NIF headers, block lists, strings, and node hierarchies.
• Type-safe block filtering (getBlocksOfType<T>()) and reference resolution (Ref<T>).
• Full support for NiMesh, NiTriShapeData, vertex streams (positions, normals, colors, UVs), materials, texturing, and transforms.

---

Prerequisites

• C++ Compiler: A modern C++ compiler supporting at least C++20 (MSVC 2019+, GCC 10+, or Clang 12+).
• CMake: Version 3.20 or later.

---

Integration Methods

Depending on your workflow and project structure, you can integrate NiForge in three different ways:

Option 1: CMake FetchContent (Recommended)

Requires no manual cloning or submodules. CMake downloads, configures, and builds NiForge automatically at configure time.

cmake_minimum_required(VERSION 3.20)
project(MyProject)

# NiForge requires C++20 or newer
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)

FetchContent_Declare(
    NiForge
    GIT_REPOSITORY https://github.com/phill030/NiForge.git
    GIT_TAG        master # Or specify a release tag / commit hash
)

FetchContent_MakeAvailable(NiForge)

# Define your application or library target
add_executable(MyProject src/main.cpp)

# Link against the NiForge target (automatically adds include directories)
target_link_libraries(MyProject PRIVATE NiForge)

# On Windows: NiForge builds as a shared library (DLL).
# Copy NiForge.dll next to your executable automatically after build:
if(WIN32)
    add_custom_command(TARGET MyProject POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
        $<TARGET_FILE:NiForge>
        $<TARGET_FILE_DIR:MyProject>
    )
endif()

---

Option 2: Git Submodule or Subdirectory

If you prefer vendoring dependencies directly inside your repository (e.g. in external/NiForge or third_party/NiForge):

1. Add the submodule:

   git submodule add https://github.com/phill030/NiForge.git third_party/NiForge

2. Add it to your CMakeLists.txt:

   cmake_minimum_required(VERSION 3.20)
   project(MyProject)
   
   set(CMAKE_CXX_STANDARD 20)
   set(CMAKE_CXX_STANDARD_REQUIRED ON)
   
   # Add NiForge subdirectory
   add_subdirectory(third_party/NiForge)
   
   add_executable(MyProject src/main.cpp)
   target_link_libraries(MyProject PRIVATE NiForge)
   
   # Copy DLL on Windows post-build
   if(WIN32)
       add_custom_command(TARGET MyProject POST_BUILD
           COMMAND ${CMAKE_COMMAND} -E copy_if_different
           $<TARGET_FILE:NiForge>
           $<TARGET_FILE_DIR:MyProject>
       )
   endif()

---

Option 3: Pre-built Binaries (Imported Target)

If you have already built NiForge.dll and NiForge.lib and wish to link against them without compiling NiForge from source:

cmake_minimum_required(VERSION 3.20)
project(MyProject)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Define an imported shared library target
add_library(NiForge SHARED IMPORTED)

set_target_properties(NiForge PROPERTIES
    IMPORTED_IMPLIB "${CMAKE_CURRENT_SOURCE_DIR}/lib/NiForge.lib"
    IMPORTED_LOCATION "${CMAKE_CURRENT_SOURCE_DIR}/bin/NiForge.dll"
    INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}/include/NiForge"
)

add_executable(MyProject src/main.cpp)
target_link_libraries(MyProject PRIVATE NiForge)

# Copy NiForge.dll to the output directory
if(WIN32)
    add_custom_command(TARGET MyProject POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
        $<TARGET_FILE:NiForge>
        $<TARGET_FILE_DIR:MyProject>
    )
endif()

---

Usage Example

#include <Core/NiFile.hpp>
#include <Blocks/NiMesh.hpp>
#include <Blocks/NiNode.hpp>
#include <iostream>

int main() {
    try {
        // Load a NIF file from disk
        NiFile file("path/to/model.nif");

        std::cout << "Loaded NIF file successfully!\n";
        std::cout << "Total blocks: " << file.blocks.size() << "\n";

        // Query all root nodes in the hierarchy
        auto roots = file.getRootNodes();
        std::cout << "Root node count: " << roots.size() << "\n";

        // Query specific blocks by type
        auto meshes = file.getBlocksOfType<NiMesh>();
        for (NiMesh* mesh : meshes) {
            std::cout << "Found Mesh: " << mesh->name << "\n";
        }

    } catch (const std::exception& e) {
        std::cerr << "Failed to parse NIF file: " << e.what() << "\n";
        return 1;
    }

    return 0;
}

---

License

NiForge by Phill030 is licensed under CC BY-NC-SA 4.0

Acknowledgments