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.

Pages

The compendium is a virtual book containing pages. Each page contains a list of elements, which are used to display that page to the player. Elements range from visuals (like text fields and images) to input (like buttons and combo boxes) to layout helpers (like containers and templates).

Elements

Pages are made up of a list of elements. Each element must have a unique name, and an element type. Each type then has a list of required and optional parameters.

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.

Templates

Templates allow you to easily replicate a chunk of script Keys & Values throughout your script file. Templates must be registered with a unique name somewhere in your script file, and then they can be instantiated by name anywhere else in your compendium.

Templates also support "defines", which are essentially variables that instantiations of the template must provide values for. The template can then use those defines inside elements in the template, knowing that the defines will be replaced later by the values provided in instansiations. See Template Defines for syntax and examples.

Localization

Localization is automatically handled for you when you publish your compendium. Any text that appears in your compendium will be extracted and replaced with localization keys. The text is then published on the [Steam Translation Web page]. The other language strings for your compendium will be shipped after the community has finished translating them.

Some best practices for ensuring your compendium localizes well:

• Don't put text inside your images, because it can't be localized. Instead, ise text fields to overlay text over images.
• Don't rename pages or elements when updating your compendium after it's shipped. The localization keys are generated based on page & element names, so renaming them shifts localization keys around, which causes pain for our translators.
• Try and provide extra space for text in other languages. If you have text that fits exactly inside its textfield, it probably won't fit once it's translated to other languages.
• Try not to break sentences into multiple textfields. Some languages have concepts that prevent you from assembling valid sentences from multiple chunks of separately localized text (like gender specific nouns).
• You can force any text to not be localized by adding ^^ at the start of it. i.e. "text" "^^DON'T LOCALIZE".

The Script File Format

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.

Page Parameters

Each page must have a unique name, and contain a list of elements. A useful organisational technique is to also store templates used by the page inside the page itself, instead of in the global templates list (which is a good place to store templates used by multiple pages). See the "page_insidecover" in the example to see this.

 

Example	"pages" { "page_cover" { "elementlist" { "cover_image" { ... } } } "page_insidecover" { "templatelist" { "template_image" { "elementtype" "embedded_template" ... } } "elementlist" { "background_image" { ... } "some_text" { ... } } } }

Element Parameters

There a several types of elements. The first key in any element section should be the "elementtype" parameter, which tells the compendium what kind of element the section is describing. The remaining keys in the section will be parsed depending on the element type.

Valid element types:

• "textfield"

A blob of text. Text Element Parameters

• "image"

An image. Image Element Parameters

• "selection"

A combo box that allows users to set a selection value. Combo Box Selection Element Parameters

• "button"

A clickable button that performs a command, or sets a selection value. Button Element Parameters

• "timer"

A timer that shows the amount of time left until a registered timer expires. Timer Element Parameters

• "progressbar"

A progress bar that shows the amount of progress towards a goal. ProgressBar Element Parameters

• "video"

An embedded youtube / youku video. Video Element Parameters

• "container"

A container of other elements. Used in templates to contain a mix of elements, and for controlling visibility of block of elements. Container Element Parameters

• "embedded_template"

A template. Exactly like a section in the "templates" block above, except it's stored in a page somewhere. Useful for keeping your templates near where they're used. Template Element Parameters

• "generic"

A generic scaleform element by name. Currently only designed to support scrollable views within pages. Generic Element Parameters

Text Element Parameters

Text elements are fields that contain chunks of localizable text.

Parameters:

• "text"

Text to display. Can contain Text Escape Sequences.

• "font"

Can be one of the Dota fonts: "text", "textbold", "title". Or it can be the name of a font (like "courier" or "arial". Note that you can only really use fonts that are widely available in Windows, Linux, and OSX).

• "size"

Font size.

• "x"

Text X position. Pages are 512x608.

• "y"

Text Y position. Pages are 512x608.

• "w"

Text width. Make sure you leave enough room for other languages (good rule of thumb is to leave 2x the amount required for english)

• "h"

Text height. Another way to how localization is to provide enough height for an extra line of text beyond what you're using, so localized text can word wrap down to the next line.

• "align"

Must be one of these: "left", "right", "center" ("left" if unspecified).

• "depth"

Either "front" or "back" ("front" if unspecififed). Front text will be placed in front of existing content in the template. Back will be behind. Bear in mind that the order that elements are specified is the order they're placed on the page.

• "color"

RGB values of the text ("255 255 255" if unspecified).

• "link_to_page"

Value must match the name of one of your pages in your compendium. Clicking on this text will jump to that page. Great for Table Of Contents, or rapid jumps back & forth in your compendium.

• "link_to_url"

Value should be a URL. Clicking on this text will popup up that URL in an external browser.

• "min"

Minimum value used by the %prizepool_togo% and %prizepool_perc% Text Escape Sequences.

• "max"

Maximum value used by the %prizepool_togo% and %prizepool_perc% Text Escape Sequences.

• "show_selection_tooltip"

If set to the index of a Selection, rolling the mouse over this text will pop up a tooltip. The tooltip will be configured based on the "tooltip_data" section of the Selection (not this text field's). This allows custom tooltips per choice in the Selection.

• Standard Element Visibility Parameters

Used to control when this element is visible / non visible. Elements are always visible by default.

Text fields can also be setup to act as Textlists. A Textlist is a Text Element that dynamically updates the text it's displaying based on some other data (like the Compendium Level, or the League's Prizepool). A good example of what they're useful for is displaying text describing what the player will unlock once their compendium levels up. To setup a Text Element as a Textlist, you need to set the following parameters:

• "textlist_var"

The data value you want to use to decide which piece of dynamic text to display. Currently only "prizepool" (for the League Prizepool) and "level" (For the player's Compendium Level) are supported.

• "textlist_rule"

The mathematical way you want to compare the data value specified in "textlist_var" to the values in the "textlist" below when deciding which piece of dynamic text to display. Valid rules are "=", "!=", ">", "<", ">=", and "<="

• "textlist"

A section containing a list of all the dynamic text chunks that can be shown in this Text Element. The section's keys should be the number to compare against the the data value specified in "textlist_var" (using the mathematical rule in "textlist_rule"). The section's values should be the dynamic text chunks.

In this example, the text field is configured as a Textlist based on the player's Compendium Level. The text will be dynamically set to the entry in the "textlist" that has the key that's less than or equal the player's Compendium Level. So if the Compendium Level is 3, the text would be "Extra Loading Screen Treasures". If the level was 8, the text would be "Kunkka's Courier: Lieutenant Squawkins". If the levels was above 10, there would be no visible text.

 

Example

"recent_rewardname" { "elementtype"    "textfield" "text"           "" "font"           "title" "size"           "15" "x"              "40" "y"              "242" "w"              "432" "h"              "80" "align"          "center" "color"          "51 51 51" "textlist_var"   "level" "textlist_rule"  "<=" "textlist" {    "1"           "200% Battle Point Booster"    "3"           "Extra Loading Screen Treasures"    "4"           "Kunkka's Courier: Lieutenant Squawkins"    "10"           "220% Battle Point Booster" } }

Text Escape Sequences

Text elements can used escape sequences inside their "text" values. Escape sequences are chunks of text that will be replaced by dynamic information when the text is shown on screen.

Some escape sequences require extra information to be specified in the "min" and "max" keys of the textfield.

Valid escape sequences:

• %prizepool%

Will be replaced by the current value of the League's prize pool.

• %prizepool_togo%

Will be replaced by the difference between the League's current prize pool and the text field's "max" value.

• %prizepool_perc%

Will be replaced by the percentage that the League's current prizepool is between the text field's %min% and :%max% values.

• %prizepool_owner%

Will be replaced by the amount of money the compendium owner has contributed to the League's prizepool.

• %selection_X%

X must be a valid selection index. The escape sequence will be replaced with the current value of the Selection, based on the type of the selection.

• %owner%

Will be replaced by the Steam Profile name of the compendium owner.

• %level%

Will be replaced by the current level of the compendium.

• %levelup_pts%

Will be replaced with the amount of compendium points needed to reach the next compendium level.

• %textlistvalue_X%

X must the name of a valid textlist. Will be replaced by the currently visible text in the textlist.

• %price_X%

X must be the definition index of a Dota 2 virtual item. Will show the price of that item in the Dota 2 store, in the user's local currency.

• %action_X%

X must be a valid action ID. Will be replaced by the user's earned points for the specified action.

• %actionmax_X%

X must be a valid action ID. Will be replaced by the maximum possible points for the specified action.

• %actionscore_X%

X must be a valid action ID. Will be replaced by the user's score for the specified action.

Examples of valid escape sequence usage in textfield "text" keys:

 

Example	"text" "$%prizepool%" "text" "$%prizepool_togo% to go!" "text" "$%prizepool_owner%" "text" "You have won %selection_65211% of 10 games with your favorite hero." "text" "from %owner%" "text" "%levelup_pts% PTS TO NEXT LEVEL" "text" "LEVEL %textlistvalue_mytextlist%"