IGameDataService API Reference

IGameDataService API reference

Core game-data access for the Radoub toolset — cached 2DA tables, TLK strings, game resources, soundsets, and palettes.

---

Table of Contents

• Overview
• Resource Resolution Chain
• 2DA Access
• TLK String Resolution
• Resource Access
• Soundset Access
• Palette Access
• Configuration
• Supporting Types

---

Overview

IGameDataService lives in Radoub.Formats.Services and is implemented by GameDataService. It wraps GameResourceResolver with caching and convenience methods.

Package: Radoub.Formats

Lifetime: singleton per tool. Implements IDisposable — dispose when done.

Construction:

// Auto-configured from RadoubSettings
using var service = new GameDataService();

// Explicit configuration
var config = new GameResourceConfig { GameDataPath = @"C:\Games\NWN\data" };
using var service = new GameDataService(config);

---

Resource resolution chain

Every resource lookup follows NWN's standard priority:

1. Override folder (loose files)     ← Highest priority
2. HAK files (in configured order)
3. Module resources
4. Base game BIF files (via KEY)     ← Lowest priority

flowchart TB
    Request[Find Resource] --> Override
    Override{Override Folder} -->|Found| Return[Return Data]
    Override -->|Not Found| HAK
    HAK{HAK Files} -->|Found| Return
    HAK -->|Not Found| Module
    Module{Module Resources} -->|Found| Return
    Module -->|Not Found| BIF
    BIF{BIF via KEY} -->|Found| Return
    BIF -->|Not Found| Null[Return null]

Loading

---

2DA access

2DA files cache on first load (including a negative cache for missing files).

Get2DA

TwoDAFile? Get2DA(string name)

Gets a 2DA file by name (without extension). Returns the cached instance on subsequent calls.

TwoDAFile? baseItems = service.Get2DA("baseitems");
TwoDAFile? races = service.Get2DA("racialtypes");

Get2DAValue

string? Get2DAValue(string twoDAName, int rowIndex, string columnName)

Convenience method for a single cell value. Combines Get2DA() with a row/column lookup.

string? raceName = service.Get2DAValue("racialtypes", 0, "Label");  // "Human"
string? baseAC = service.Get2DAValue("baseitems", 12, "BaseAC");

Has2DA

bool Has2DA(string name)

Checks whether a 2DA file exists in the resolution chain.

ClearCache

void ClearCache()

Clears every cached 2DA file. Call it after resource paths change (e.g., a module switch).

---

TLK string resolution

GetString (uint)

string? GetString(uint strRef)

Resolves a TLK string reference to text. Routes to the custom TLK automatically for StrRefs ≥ 16777216 (0x01000000).

string? text = service.GetString(12345);        // Base TLK
string? custom = service.GetString(16777300);    // Custom TLK (offset applied)

GetString (string)

string? GetString(string? strRefStr)

Resolves from a string value. Returns null for "****" and other non-numeric input.

string? text = service.GetString("12345");   // Resolves
string? none = service.GetString("****");    // Returns null
string? bad = service.GetString("abc");      // Returns null

HasCustomTlk

bool HasCustomTlk { get; }

Whether a custom TLK is currently loaded.

SetCustomTlk

void SetCustomTlk(string? path)

Sets the custom TLK file path for module-specific strings. Pass null to clear.

service.SetCustomTlk(@"C:\NWN\modules\mymod\customtlk.tlk");

---

Resource access

FindResource

byte[]? FindResource(string resRef, ushort resourceType)

Finds a resource by ResRef and type ID. Returns raw bytes or null.

byte[]? dlgData = service.FindResource("conv001", ResourceTypes.Dlg);
byte[]? utcData = service.FindResource("goblin01", ResourceTypes.Utc);

FindBaseResource

byte[]? FindBaseResource(string resRef, ushort resourceType)

Finds a resource in Override and BIF only, skipping HAK files. Use it when the resource must come from the base game regardless of HAK overrides (e.g., standard race skeletons that CEP HAKs may replace with incompatible versions).

byte[]? skelData = service.FindBaseResource("c_human", ResourceTypes.Mdl);

FindResourceWithSource

ResourceResult? FindResourceWithSource(string resRef, ushort resourceType)

Finds a resource and returns source information showing which layer in the resolution chain (Override, HAK, Module, or BIF) provided the data. Use it when callers need to display or log where a resource came from.

var result = service.FindResourceWithSource("goblin01", ResourceTypes.Utc);
if (result != null)
    Console.WriteLine($"Loaded from {result.Source}");

Defined in Radoub.Formats.Resolver.ResourceResult.

ListResources

IEnumerable<GameResourceInfo> ListResources(ushort resourceType)

Lists every resource of the given type across all sources.

var allDialogs = service.ListResources(ResourceTypes.Dlg);
foreach (var info in allDialogs)
    Console.WriteLine($"{info.ResRef} from {info.Source}");

---

Soundset access

GetSoundset

SsfFile? GetSoundset(int soundsetId)

Gets a soundset by its row index in soundset.2da. Returns the parsed SSF file.

GetSoundsetByResRef

SsfFile? GetSoundsetByResRef(string resRef)

Gets a soundset by ResRef (without the .ssf extension).

GetSoundsetResRef

string? GetSoundsetResRef(int soundsetId)

Gets the ResRef for a soundset from soundset.2da.

string? resRef = service.GetSoundsetResRef(42);  // e.g., "vs_fhuman_1"
SsfFile? ssf = service.GetSoundsetByResRef(resRef!);

---

Palette access

GetPaletteCategories

IEnumerable<PaletteCategory> GetPaletteCategories(ushort resourceType)

Gets palette categories from skeleton ITP files (e.g., creaturepal.itp for UTC type 2027).

var categories = service.GetPaletteCategories(2027);  // UTC palette
foreach (var cat in categories)
    Console.WriteLine($"[{cat.Id}] {cat.FullPath}");

GetPaletteCategoryName

string? GetPaletteCategoryName(ushort resourceType, byte categoryId)

Gets a category name by ID (matches the PaletteID field in blueprints).

string? name = service.GetPaletteCategoryName(2027, 5);  // e.g., "Animals"

---

Configuration

IsConfigured

bool IsConfigured { get; }

Whether the service has valid game paths configured. Check before calling other methods.

ReloadConfiguration

void ReloadConfiguration()

Reloads configuration from RadoubSettings. Call after the user changes game paths. Clears every cache.

ConfigureModuleHaks

void ConfigureModuleHaks(string moduleDirectory)

Enables module-aware HAK scanning by reading the module's IFO HakList. Only HAK files referenced by the module load into the resolver, avoiding the penalty of scanning every HAK on disk (80+ files, 15+ seconds). Clears every cache (2DA, SSF, palette) because resolution order changes.

service.ConfigureModuleHaks(@"C:\NWN\modules\MyModule");

---

Supporting types

GameResourceInfo

public class GameResourceInfo
{
    public required string ResRef { get; init; }
    public required ushort ResourceType { get; init; }
    public required GameResourceSource Source { get; init; }
    public string? SourcePath { get; init; }
}

GameResourceSource

public enum GameResourceSource
{
    Override,   // Override folder (highest priority)
    Hak,        // HAK file
    Module,     // Module resource
    Bif         // Base game BIF file (lowest priority)
}

PaletteCategory

public class PaletteCategory
{
    public byte Id { get; init; }
    public required string Name { get; init; }
    public string? ParentPath { get; init; }
    public string FullPath => string.IsNullOrEmpty(ParentPath)
        ? Name : $"{ParentPath}/{Name}";
}

---

See also

• Radoub-Formats — format library overview
• Game-Data-Integration-Guide — bootstrap and integration patterns
• Radoub-UI-Developer — shared UI components using IGameDataService

---

Home | Index

---

Page freshness: 2026-05-24