BLK File Format
The .blk (“block”) is a data block, the primary configuration format in
Dagor Engine. It is a configuration file similar to .ini, .cfg, and other
configuration files you may have encountered in other systems.
The Dagor Engine uses .blk files for storing settings, parameters, and other
essential information.
There are two types of .blk files: text and binary.
Text Format of .blk File
Text .blk files are regular text files with proprietary syntax.
File Syntax
The .blk file consists of a block name and optional parameters enclosed in
curly braces.
<block_name>{
<parameter_name>:<type>=<value>[;]
}
where
<block_name>: the name of the block, which must start with a Latin letter or an underscore and consist of Latin letters, digits, or underscores.<parameter_name>: the name of the parameter, which must start with a Latin letter or an underscore and consist of Latin letters, digits, or underscores.<type>: the type of the parameter, which is mandatory and can be one of the following:t: string, the<value>is a text string in quotes. If the string consists of only one word, quotes may be omitted. The string should not containLF,CR, orTABsymbols. Instead, use combinations of symbols:~r(CRsymbol),~n(LFsymbol),~t(TABsymbol).b: boolean, the<value>is one of the strings:yes,no,true,false,on,off,1,0.c: 32-bit color (E3DCOLOR), the<value>is a sequence of comma-separated integer numbers representing the color the formatR,G,Bor inR, G, B, Awith components ranging from0to255.r: floating-point number, the<value>is a floating-point number with truncated trailing zeros.m:matrix 3x4, the<value>is a string in the form of[[first line][second line][third line][fourth line]]. The lines are comma-separated floating-point numbers defining x,y,z vector (p3– see below).p2: Point2 vector, the<value>is comma-separated floating-point numbers defining x,y vector.p3: Point3 vector, the<value>is comma-separated floating-point numbers defining x,y,z vector.p4: Point4 vector, the<value>is comma-separated floating-point numbers defining x,y,z,w vector.ip2: IPoint2 vector, the<value>is comma-separated integer numbers defining x,y vector.ip3: IPoint3 vector, the<value>is comma-separated integer numbers defining x,y,z vector.
<value>: the value of the parameter, can be in quotes.[;]: if a semicolon is placed after the parameter, the next parameter may be on the same line. If the semicolon is omitted, the next parameter should be on a new line.Note
Use a tilde (
~) in quotes to represent special characters such as quotes. To write a tilde in a string, use two tildes (~~).
Parameters can be defined as an array:
<parameter_name>:<type>[] = [<values>]
where
<parameter_name>: the name of the parameter.<type>: the type of parameter.<values>: a list of values of the corresponding type separated by a semicolon or a new line.
Example:
param1:i[]=[42; 43; 44;]
param2:t[]=[
"parameter1"
"parameter2"
"parameter3"
]
Directives and Comments
.blk files may contain parser directives and comments.
Directive @include
All parameters of the file will be included as if they were initially presented
in the current file. Included files may contain other include files.
Including another .blk file:
include <file_name>
where <file_name> is a path to the included .blk file relative to the
current .blk file path. If the <file_name> starts with a slash (/), the
path is considered from the root of the engine, otherwise from the directory
where the .blk file is located. In tools, starting with # means from the
develop/ directory.
Directive @override
"@override:<name_of_block_or_parameter>"
"@override:block"{
"@override:parameter"i=10`
}
There are rules to follow when overriding:
Overriding a value that has not been declared before results in a log error.
If it’s unclear whether a value to be overridden has been declared before, it’s common practice to delete it first. This ensures there is no such variable from that point, allowing you to add the variable normally.
Example:
@override:video{
@delete:vsync:b=no
vsync:b=yes
}
The code above ensures that vsync is deleted first. If there was a vsync
before, it will be deleted; if not, then no action is taken. After that, vsync
does not need to be overridden and can be added normally, regardless of the
presence of vsync before it.
Directive @delete
"@delete:<name_of_block_or_parameter>"
Directive @clone-last
"@clone-last:<name_of_block_or_parameter>"
Block Types
Blocks can be of the following types: sequential, nested and combination of sequential and nested.
Sequential
block_name{
param_name:type=value
}
block_name{
param_name:type="value"
}
Example:
lod{
range:r=70;
}
lod{
range:r=10000; fname:t="billboard_octagon_impostor.lod01.dag";
}
Nested
block_name{
param_name:type=value
block_name{
param_name:type="value"
}
}
Example:
contents{
lod{
range:r=70;
}
}
Combination of sequential and nested
block_name{
param_name:type=value
block_name{
param_name:type="value"
}
block_name{
param_name:type=value
}
}
Example:
contents{
lod{
range:r=70;
}
lod{
range:r=10000; fname:t="billboard_octagon_impostor.lod01.dag";
}
}
Binary Format of .blk File
Binary .blk files are optimized for performance with a defined structure for
efficient data storage and retrieval.
File Structure
The data in a binary .blk file consists of header, name and string maps,
parameters, and blocks. The data is ordered as follows:
Header
Name map: parameter and block names
String map: string parameters
Root parameters: (may be nested)
paramCntparamNameId_1paramType_1param_1...paramNameId_CntparamType_Cntparam_Cnt
Root blocks: (may be nested)
blockCntBlock1 parameters:
paramCntparamNameId_1paramTypeCnt_1param_1...paramNameId_CntparamType_Cntparam_Cnt
Block1 blocks:
blockCntBlock1_1Block1_2...Block1_Cnt...
Block_Cnt parameters
Block_Cnt blocks
Useful tools
The dagor3_cdk has some useful tools for working with .blk:
binBlk.exe: converts binary and text.blkfiles to and from each other.blkDiff.exe: performs a syntactic diff between two.blkfiles.blkEditor-dev.exe: Facilitates the creation of a GUI editor with dynamic views for.blkfiles.
Comments
//: single-line comment/* ... */: multi-line comment