Roboto.Dbc.Generator 1.0.1

Roboto.Dbc.Generator

A C# source generator that turns WoWDBDefs .dbd definition files into strongly-typed classes for reading World of Warcraft DBC files.

Instead of (string)row["MapName_lang"], you get map.MapNameLang — resolved at compile time against the exact client build you configure.

Installation

dotnet add package Roboto.Dbc.Generator

Install-Package Roboto.Dbc.Generator

This package contributes no runtime assembly of its own — the generated code is compiled against Roboto.Dbc.Reader, which it depends on, so that arrives automatically.

If you are building a library that others will consume, reference both explicitly instead, so the analyzer stays out of your own package's dependencies while the reader still flows to your consumers (your generated types appear in their API surface):

<ItemGroup>
  <PackageReference Include="Roboto.Dbc.Reader" Version="1.0.0" />
  <PackageReference Include="Roboto.Dbc.Generator" Version="1.0.0" PrivateAssets="all" />
</ItemGroup>

Requirements

Any netstandard2.0-compatible target framework — the same as the reader. Generated code carries no using directives, fully qualifies every type, and uses no language feature beyond C# 7.3, so it compiles regardless of your project's ImplicitUsings, LangVersion, Nullable, or GenerateDocumentationFile settings, and cannot collide with types you declare yourself.

Setup

1. Add a DbcGenerator.json

Anywhere in your project. Both keys are required.

{
  "Namespace": "MyGame.Dbc",
  "Build": "3.3.5.12340"
}

Build takes the form expansion.major.minor.build. It selects which version block of each .dbd to use and, for pre-Cataclysm builds, how many columns a localized string occupies.

2. Register the config and your .dbd files as additional files

<ItemGroup>
  <AdditionalFiles Include="DbcGenerator.json" />
  <AdditionalFiles Include="Definitions\*.dbd" />
</ItemGroup>

In Visual Studio this is the "C# analyzer additional file" build action. Files that are merely Content or None are invisible to the generator.

Download the .dbd files for the tables you need from https://github.com/wowdev/WoWDBDefs/tree/master/definitions. The file name must match the DBC name — Map.dbd describes Map.dbc — because the generated class name is derived from it.

3. Read a table

using DBDefsLib;
using MyGame.Dbc;          // the namespace from DbcGenerator.json
using Roboto.Dbc.Reader;

var reader = new DbcReader(new Build("3.3.5.12340"), DbcLocale.EnUS, @"C:\Games\WoW-3.3.5a\dbc");

// Resolves "<dbcsDirectory>/Map.dbc"
foreach (Map map in reader.ReadMap())
{
    Console.WriteLine($"{map.ID,4}  {map.MapNameLang}  ({map.Directory})");
}

What gets generated

For each .dbd, a partial class named after the file, plus extension methods on DbcReader. For Map.dbd at build 3.3.5.12340:

public partial class Map
{
    public int      ID               { get; set; }   // $id$ID<32>
    public string   Directory        { get; set; }
    public int      InstanceType     { get; set; }
    public string   MapNameLang      { get; set; }   // locstring, resolved for your DbcLocale
    public float    MinimapIconScale { get; set; }
    public float[]  Corpse           { get; set; }   // Corpse[2]
    // ... and the rest of the columns for that build
}

public static partial class DbcReaderExtensions
{
    public static IEnumerable<Map> ReadMap(this DbcReader reader);                // <dbcsDirectory>/Map.dbc
    public static IEnumerable<Map> ReadMap(this DbcReader reader, string file);
    public static IEnumerable<Map> ReadMap(this DbcReader reader, Stream stream); // e.g. from an MPQ/CASC archive
}

Column names are converted to PascalCase, so MapName_lang becomes MapNameLang and ID stays ID. Comments from the .dbd are carried through as XML doc comments. In a .dbd, <32> is signed and <u32> is unsigned, so ID<32> generates an int.

When a definition marks a column with $id$, you also get a container indexed by it:

var maps = new MapContainer(reader);   // loads Map.dbc from the reader's directory

Map kalimdor = maps[1];                // indexer: throws if absent
Map maybe = maps.Get(999999);          // Get: returns null if absent
var instances = maps.Where(m => m.InstanceType != 0).ToList();   // IEnumerable<Map>

Because the container uses the parameterless Read<Name>() overload, the DbcReader you pass it must have been constructed with a dbcsDirectory.

Every generated class is partial, so you can add behaviour without touching generated output:

namespace MyGame.Dbc;

public partial class Map
{
    public bool IsInstance => InstanceType != 0;
    public override string ToString() => $"{MapNameLang} [{ID}]";
}

The property list is build-specific: the same Map.dbd at a different build generates a different set of properties in a different order. Changing Build is a source-breaking change to your own code, by design.

Diagnostics

The generator never throws. Every problem it detects is reported as an RDBC001–RDBC010 diagnostic pointing at the offending file, so it appears in the IDE error list and in build logs like any compiler message. The two you are most likely to meet first:

• RDBC002 — no DbcGenerator.json among the additional files.
• RDBC008 — a configuration was found but no .dbd files were registered, usually a forgotten build action.

A malformed or non-matching definition (RDBC009, RDBC010) is reported per file and skips only that table; the rest still generate. Severities are adjustable through .editorconfig, for example dotnet_diagnostic.RDBC010.severity = error.

The full table is in the documentation.

Scope

Supports the WDBC format only — the classic layout used from Vanilla through roughly Cataclysm. The WDB2/WDB5/WDB6 and WDC1–WDC5 .db2 formats used from Warlords of Draenor onward are not handled, and neither is the binary .bdbd definition format.

All the actual binary parsing is done by Roboto.Dbc.Reader, which this generator calls into at compile time to resolve schemas — so the two always agree on types, sizes, name sanitization and field ordering. See that package for the reader API and its limitations.

Documentation and feedback

Full documentation: https://github.com/r-o-b-o-t-o/dbc#readme

Issues and questions: https://github.com/r-o-b-o-t-o/dbc/issues

Built on DBDefsLib and the definitions maintained by the wowdev community.