IGameDataService API Reference

IGameDataService API Reference

Core game data access for the Radoub toolset. Provides cached access to 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 is defined in Radoub.Formats.Services and 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

All resource lookups follow 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 are cached on first load (including negative cache for missing files).

Get2DA

TwoDAFile? Get2DA(string name)

Get a 2DA file by name (without extension). Returns 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 to get a single cell value. Combines Get2DA() + row/column lookup.

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

Has2DA

bool Has2DA(string name)

Check if a 2DA file exists in the resolution chain.

ClearCache

void ClearCache()

Clear all cached 2DA files. Call after resource paths change (e.g., module switch).

---

TLK String Resolution

GetString (uint)

string? GetString(uint strRef)

Resolve a TLK string reference to text. Automatically routes to custom TLK for StrRef >= 16777216 (0x01000000).

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

GetString (string)

string? GetString(string? strRefStr)

Resolve from a string value. Handles "****" and invalid values gracefully (returns null).

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)

Set 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)

Find 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);

ListResources

IEnumerable<GameResourceInfo> ListResources(ushort resourceType)

List all resources of a specific 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)

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

GetSoundsetByResRef

SsfFile? GetSoundsetByResRef(string resRef)

Get a soundset directly by its ResRef (without .ssf extension).

GetSoundsetResRef

string? GetSoundsetResRef(int soundsetId)

Get the ResRef string 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)

Get 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)

Get a category name by its ID (matches 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 making calls.

ReloadConfiguration

void ReloadConfiguration()

Reload configuration from RadoubSettings. Call after the user changes game paths in settings. Clears all caches.

---

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-02-13