KV Files

Welcome to the wonderful world of KV (Kivy), or KeyValue language. The name implies its structure: Keys on the left, Values on the right, forming pairs. KeyValues are stored information used primarily by LUA scripts. When invoked, these scripts trigger actions, pulling from the KeyValues when required

Tools You'll need

SublimeText 3 (free software)

Setup SublimeText 3 to highlight using Dota KV:

• Ctrl+Shift+P -> Package Control: Install Package -> Dota KV
• Ctrl+Shift+P -> Set Syntax Dota KV

Arhowk.github.io (website)

• Easy online Sample Debugger for KV language.

Git/Github (free software)

Git is a version control system (VCS) used in the AAA project as a way of updating everyone's game as work is done ("aaa" sending game-data downstream to users) and as a way to receive contributors' work (users sending game-data upstream to "aaa")
Github is an app/website used to manage "aaa"s files.

Node.js (custom software)

For compiling lots of KeyValue files into a single file (such as with npc data found in the /npc directory)
Certain specific KV files go into specific directories such as "npc/Items" and "npc/Abilities". A console package called "Node.js" is used to compile (aka gulp) individual KV files into the large combined files used by Dota 2. Run "Node.js Command Prompt".
Commands:

• npm i - The initial setup command.
• gulp - compiles all the individual files from within a directory e.g. "npc/Items" into a single file e.g. "npc/npc_items_custom.txt"

Structure

Here's a very simplified breakdown of what you should expect to see when you look at a KeyValue file.

"ParentOne"
{
	// <- Notice the indent. Implies child-parent relationship of the {} enclosed set.
	"Key"				"Value"
	"Key"				"Value"
	// The following is an array of values.
	"Key"				"1 2 3 4 5 6"
	// 
	"ParentTwo"
	{
		// These values are the child of the parent element so they indent further.
		"Key"			"Value"
		"Key"			"Value"
		"Key"			"Value"

	}
}

Dota 2 KV Guidelines

• "ID" is one of the few required Keys for NPC data. It is also a Unique ID. Do not duplicate "ID"s, do not change "ID"s.
• "BaseClass" is also a required Keys for NPC data. It defines the way in which the set of KeyValues hooks into the rest of Dota 2.
• Nesting - Indent your code when nesting, please. It helps everyone visualize the database's structure.
• Comment Code - If you comment, then other contributors will know what's up. Commenting can also be used to remove data without deleting it. Comment code by putting "//".
• Debug frequently
• Whether you're editing existing KV files or creating new ones, you should write them and also keep them as seperate files even after Gulping them together into a single master file e.g. "npc_abilities_override.txt".
• If an array of values has the same values, you can reduce them to a single value, like:

"SomeAbility"
{
	"Damage"				"0 0 0 0 0"
	// Can be reduced to:
	"Damage"				"0"
}

• "var_type" stands for variable type, and it's "Value" defines the acceptable subset of values in the pair following it.

"MegaBuster"
{
	"var_type"				"FIELD_INTEGER"
	// Integers are whole numbers. The "Damage" Key must be paired with whole number Values.
	"Damage"				"2000"
}

Workflow

Setup

Ideally you should use Git to create your own development branch (see Git tutorial). This way you can change any files you want without disturbing your master copy of aaa.

Author

When making KV files, you should always start with a valid, up-to-date template, many of which can be found at www.ModDota.com.

Compile

When you think you've got your files the way you want, run Node.js and gulp. This generates the file used by the game.

Debug

Copy the contents of the KeyValue file you wish to debug into http://arhowk.github.io. Fix any errors in the individual KV files not in the compiled file. Once you've fixed all the errors, gulp again. This will put the updated KV files into the compiled form again.

Test in aaa

Launch Dota 2 Tools; Load "aaa" addon; Load Console by pressing "~"; Launch the addon using the following command:

"dota_launch_custom_game aaa aaa"

Points/HeroSelection etc.

Atom editor has a port of the Sublime Text 3 KV syntax package: https://atom.io/packages/language-dotakv by Faultless
Install with apm install language-dotakv
or in Settings -> Install: search for language-dotakv.

He also ported https://atom.io/packages/language-dotalua

Fountain

npc/units/oaa_fountain.txt

• Is a building for the purposes of Town Portal
• Located in the exact middle of the start-area for Town Portal
• Has ability oaa_fountain

npc/abilities/oaa_fountain.txt

• Links to script file oaa_fountain.lua

vscripts/abilities/oaa_fountain.lua

• Applies regen modifier
• Modifier has entity reject based on IsTouching or similiar

Laser

npc/units/oaa_lazor.txt

• is not a building
• is the tip of the tesla coil
• Has ability oaa_lazor

npc/abilities/oaa_lazor.txt

• Links to script file oaa_lazor.lua

vscripts/abilities/oaa_lazor.lua

• Applies lazor
• Modifier has entity reject based on IsTouching or similiar

PS. all the starting area stuff is in a single Prefab now in /structures.