arz

ARZ

The arz library contains tools to parse content of ARZ-files, which have been used in Grim Dawn game as archives of parameters. It is named after .arz extension of the files. The project also provides a description of the format of the files.

Usage

The usage is mainly about calls to function Decode and methods of instances of type Db, pointers at which are returned by the function:

import "codeberg.org/alex-ichukov/arz"

func main() {
	// Get content of an ARZ-database in form of slice of bytes
	data := …

	// Decode the data
	db, err := arz.Decode(data)
	if err != nil {
		// Process the error
	}

	for _, r := range db.Records {
		// Doesn't allocate a string
		if string(db.Tag(r)) == "WeaponHunting_Ranged2h" {
			// Process a record of a two-handed ranged weapon
			…
		}
	}
}

Instances of type Db hold inside provided slices of data. Methods of the type return subslices of the slice for the maximum efficiency. The instances serve as a kind of god-objects, as instances of the types Record and Field provide only minimal data. Even fields of a record are accessed through an intermediate object of type Fields, which is managed as a part of an instance of Db. Such an approach allows to unpack compressed content of the fields on-fly, transparently for a user.

Accordingly to the format of the records, every record can have many fields, and every field can have many values of one single type: 32-bit signed integer, single-precision floating-point number, string or boolean. String values are represented by indices in the array of strings of the database. This makes processing of the values tricky. An example of such a processing can be found within an application in examples directory of the project. Any database of the game sports dozens of thousands of records and millions of fields in total, and most of the fields are single-valued. To process all the situations efficiently, method Seq of type Fields uses an optimization: it yields a field with a possible sub-iterator over values of the field. If the field has only one value, nil is yielded instead of the sub-iterator, and the value is stored within the field directly. Thus, the following situation arises frequently:

import "codeberg.org/alex-ichukov/arz"

func main() {
	…
	for _, r := range db.Records {
		for f, values := range db.Fields(r).Seq {
			if values == nil {
				// Process f.Value()
			} else {
				for v := range values {
					// Process v
				}
			}
		}
	}
}

Original databases of the game are pretty big (and, to mention, proprietary), and sometimes a small generated ARZ-database is required for, say, testing purposes. For that, function Encode of the library could be used. It takes a slice of records of type EncRec (which are completely distinct from instances of Record), which represent the database of interest. Its usage can be depicted in the following way:

import "codeberg.org/alex-ichukov/arz"

func main() {
	r := []arz.EncRec{
		{
			Name: "record1",
			Tag:  "tag1",

			Ints: map[string][]int32{
				"field1": {0},
				"field5": {9},
				"field9": {1, 2, 3},
			},

			Floats: map[string][]float32{
				"field2":  {0.0},
				"field6":  {3.7},
				"field10": {3.7, 3.14159, 2.71828},
			},

			Strings: map[string][]string{
				"field3":  {""},
				"field7":  {"singlestring"},
				"field11": {"arraystring1", "arraystring2"},
			},

			Bools: map[string][]bool{
				"field4":  {false},
				"field8":  {true},
				"field12": {false, true},
			},
		},
		{
			Name:  "record2",
			Tag:   "tag2",
			Bools: map[string][]bool{"field1": {false}},
		},
	}

	data := arz.Encode(r)
	// Process data
	…
}

The function assumes, that the input slice is not extreme in amount of records or fields, so it doesn't even return an error value.

License

The library is licensed under MIT license.