Dota 2 Compendium Scriptfiles

Dota 2 Compendiums are in-game items associated with leagues. They're described by a script file that third parties upload to the Dota 2 backend via the Edit League page on Dota2.com. This page will describe that script file, and the process we recommend to develop your compendium.

Building and Testing

First, ensure your league is allowed to have a compendium. You can contact the Valve league admin team via your League pages. Once compendiums have been enabled for your league, you should download the example compendium script file from your league's Edit page.

Compendiums should be built and tested on your local machine before they're uploaded to the Dota 2 backend. You can test your compendium using the test_compendium command. For example:

test_compendium "c:/compendium/example_compendium.txt"

Once your compendium is open, you can make changes to your script file and instantly reload the compendium with the test_compendium_refresh' command. We recommend doing all your script file editing live in this way, so you're testing quickly as you go.

Place any images for your compendium in the same directory as your script file, and they'll be found automatically while testing. Note that any selections in your compendium won't be actually saved, and some other data will be faked for testing purposes (progress bars will constantly move, the prize pool will roll forward, etc)

Once you're getting ready to publish, submit your compendium & images through the league admin page, but don't set it public yet. Non public compendiums will be visible to all the admins for your league. Start your Dota 2 client and look through the compendium to make sure you're happy with it. Once you are, submit it again and mark it as public, and then all players who've purchased a ticket for your league will have access to it.

Concepts

Compendiums contain several concepts that will be referred to throughout the script file.

Selections

Selections are used to store a dynamic value in the compendium. The value is either set by the player, or by the Dota 2 backend. Many elements inside compendiums can then interact with selection values. Each selection must have a unique index to identify it.

Selections are what you use any time you'd like to accept a player's input inside your compendium - to allow them to make a prediction on a future match, vote on who they'd like in a show match, to select a favorite Hero or item, etc. The actual UI method by which a user sets the selection can vary.

Selections that are set by players can be set to become locked at some point in time. Once locked, players cannot change them. Selections can also choose to lock themselves based on the value of other selections.

The Script file

The compendium script file is a KeyValues text file that's easily edited in any text editor. It contains a series of sections that each have a set of parameters, some required and some optional. The test_compendium command will report any errors it finds in your compendium when you try to open it.

Root Level Parameters

The root level of the script file must contain the following keys:

• "version" "3"

This is the version for the scriptfile. Don't change it.

• "table_of_contents_page" "<name of your table of contents page>"

The value should be the name of the page that you want the user to be taken to when they click the "Table Of Contents" button in the navigation controls.

• "table_of_contents_version" "<version of the Table of Contents>"

The value is simply a number that you increment whenever you like. Whenever a user opens your compendium, and this number is higher than it was the last time they opened it, an alert "!" image will be shown on the Table of Contents button in the navigation controls. We recommend increasing this number any time you add new pages to your compendium.

• "precache"

This section should contain a list of images that must be fully downloaded before the compendium opens. You definitely want to have you cover & page backgrounds here, but if you don't have large images you could make players download most/all of your compendium before it opens. Images not in this list will be downloaded when the user browses to the page with the image on it (i.e. they'll appear after a the download finishes).

 

Example	"precache" { "compendium2014_cover.jpg"       "1" "compendium2014_blankpage.jpg"   "1" "compendium2014_insidecover.jpg" "1" }

• "timers"

This section contains the master list of times that other elements will refer to. Timers must be specified in the following format:

"HH:MM:SS DD-MM-YYYY GMT+ZZZZ"     (timezone + can be a - instead)

 

Example	"precache" { "always_locked"    "00:00:00 01-01-2000 GMT+0000" "qualifiers_start" "12:00:00 12-05-2014 GMT-0500" "qualifiers_end"   "23:59:59 27-05-2014 GMT+0200" "mainevent"        "09:00:00 18-07-2014 GMT+0700" }

• "preregister_selections"

This section contains a list of selections that need to be defined before being used inside elements in the pages. Any selection that's set in some way other than a combo box must be registered here (combo boxes can contain the selection registration themselves). See Selection Parameters to see how to register an individual selection.

• "result_dialog_settings"

This section customizes the extra information dialog that pops up when the user clicks the "More Info" button associated with a selection combo box. Generally only used for prediction results. The parameters inside this section are as follows:

• "color_title" : The RGB color of the title text
• "color_bg" : Sets the RGB color for the flat, shaded background. Alternatively, use "image_bg_filename".
• "color_result" : The RGB color of the result text
• "color_extrainfo" : The RGB color of the extra information text
• "color_correctedness" : The RGB color of the CORRECT! / INCORRECT! text
• "image_bg_filename" : An image to be used as the background of the dialog, instead of the flat, shaded background.

• "templates"

This section contains a list of template definitions. See Compendium Templates for more information. Templates can also be specified inside pages themselves, using the "embedded template" element type. For templates that are only used inside a single page, this is preferable for organisational reasons, keeping your template definitions near where they're used.

• "pages"

This section contains the master list of pages, in the order that they should appear in the compendium. Each page then contains a list of elements. See Page Parameters to see how to layout individual pages.