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 (or grab it directly from here: http://media.steampowered.com/apps/dota2/images/leagues/CompendiumExample.zip?v=11)

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)

To simulate the prize pool value you can use the following commands:

test_compendium_prizepool_min 1600000

Sets the starting (minimal) prize pool to whichever value you specify.

test_compendium_prizepool_max 6000000

Sets the ending (maximal) prize pool to whichever value you specify.

test_compendium_prizepool_inc 5000

Sets the amount by which the prize pool will be increased per second

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 instances 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 instances. See Template Element Parameters 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".

Points

Certain compendiums that are provided an event id by Valve can make use of points. Points can be accumulated through completing actions or using certain items associated with the compendium. These points can then be used to drive features within a compendium or provide rewards to users.

Actions

For compendiums that have an event id provided to them by Valve, actions can be defined. Actions are used to track events that have been performed and provide rewards for those actions such as granting points or rewards. An example of this would be an action that granted when a user makes all prediction selections and therefore are granted points.

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" "X"

This is the version for the scriptfile. New compendium features are added over time, but version numbers are only incremented when required to avoid old compendiums breaking - so backwards compatibility is maintained as long as you don't change your version number. Incrementing your version number to take advantage of the new features may require updating parts of your script file, due to format changes. If you're start a new compendium, it's probably best to start with the most recent version. A brief rundown of version history and the associated requirement change is as follows:

2: Aspect ratio was 512x608, used a mix of scaleform templates and some rudimentary custom elements.
3: Scaleform templates removed, pages moved to being entirely made of custom elements.
4: Aspect ratio changed to 512x576.
5: Containers became true containers (children are now within their heirarchy). Full depth implementation.

"event_id" "<event id provided to you by Valve>"

If your compendium makes use of points or actions, you'll need to contact Valve for an event id. This is a unique identifier used to identify actions and points for this compendium. If not using this feature just specify zero or omit this value.

"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.

"theme_color"

This should be an RGB value for the thematic color of your compendium. It will be used as the color for the various glows around the compendium navigation buttons.

"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	`"timers" { "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. See Template Element Parameters for format details.

"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.

"embedded_pages"

This optional section contains a list of pages that don't appear in the book itself, and instead are used as popups, dialogs or tooltips. See Embedded Pages for more information.

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" { ... } } }` `}`

In addition to the list of elements, pages have the following optional settings:

"crease"

The visibility of the darkened crease in the middle of the book. It should be a range from 0 - 1, where 1 is fully visible, and 0 is invisible. Only the value of the left-hand page is used. Useful if you want to have images or text that stretches across both visible pages.

Element Parameters

There are 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 collection of smaller elements that handles users making a selection and seeing the results. Selection Element Parameters

"button"

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

"line"

A line drawn directly on the page. Line 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

"generic"

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

In addition to an "elementtype", a section can also optionally contain an "embedded_template" key, set to "1". If done so, this element will be registered as a template instead of actually being instantiated on the page. It's exactly the same as putting the element in the root "templates" section, except that it's stored inside a page. Useful for keeping your templates near where they're used. See Template Element Parameters for additional template-only parameters.

Text Element Parameters

Text elements are fields that contain chunks of localizable text.

Parameters:

"text"

Text to display. Can contain multiple Text Escape Sequences, and standard HTML tags to override the other text settings on subsections of the text string. For example, the following value of the "text" key: "My text is size 10 here and green here" would use the size/color specified below, but the size & color would be overridden by the HTML tags for the sections of the text inside the tags.

"font"

Can be one of the Dota fonts: "text", "textbold", "title", or "titlebold". 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.

"bold"

Makes the font bold.

"italic"

Makes the font italic.

"glow"

Adds a soft alpha glow around the text.

"uppercase"

Forces the text to uppercase.

Standard Element Positioning Parameters

Specifies where this element is on the page.

"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.

"resize_to_fit"

If set to 1, the text field will resize itself to match the size of the text inside it. Generally only needed for text fields that have other elements depending on them (like the text inside an embedded page acting as a tooltip, where the background is being resized to match the text inside it)

"spacing_horizontal"

Horizontal spacing between each text character.

"spacing_vertical"

Vertical spacing between multiple lines of text in word wrapped elements.

"align"

Sets how the text inside the element will be aligned within the element's width & height. Must be one of these: "left", "right", "center" ("left" if unspecified).

"depth"

Either "front" or "back" ("front" if unspecified). Front elements 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).

"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 Tooltip Parameters

Used to make a tooltip popup when the user moves their mouse cursor over this element.

Standard Element Visibility Parameters

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

Standard Element Command Parameters

If you want this textfield to issue a command when clicked on by the user, this section is required.

Selection Points Displays

Instead of displaying normal text, a text element can elect to show the total points earned by the user for a set of Selections. Mostly used for showing the user's points earned for predictions. To do this, the text element needs a "Points" section setup in one of the two following ways:

List Selection indices individually by index (key is the selection index, value is just "1")
Specify a min & max selection index range with the "index_min" and "index_max" keys, which sums all indices between them inclusively.

These two methods can also be combined. Examples:

Example	`"points" { "1" "1" "3" "1" "6" "1" } "points" { "index_min" "8" "index_max" "11" } "points" { "index_min" "1" "index_max" "7" "10" "1" "11" "2"` `}`

Textlists

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" } `}`

Image Element Parameters

Image elements are used to display an image.

Parameters:

Standard Element Positioning Parameters

Specifies where this element is on the page.

"w"

Element width. The image will be scaled to fit.

"h"

Element height. The image will be scaled to fit.

"scaleX"

An amount to scale the image by horizontally. Defaults to 1. Negative values will flip the image, so -1 would draw the image fully flipped along the horizontal axis.

"scaleY"

An amount to scale the image by vertically. Defaults to 1. Negative values will flip the image, so -1 would draw the image fully flipped along the vertical axis.

"depth"

Either "front" or "back" ("front" if unspecified). Front elements 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.

"filename"

The filename of the image. It should match the filename of an image sitting in the same directory as the compendium script file. Alternatively, you can specify the relative path of an existing image inside Dota 2's resource\flash3 directory (i.e. "images/heroes/beastmaster.png" or "images/items/abyssal_blade.png")

"color"

An optional RGB value to multiply the image color by.

"tooltip_data"

An optional section describing the tooltip for this image, if you want one. See Tooltip Parameters.

"show_selection_tooltip"

If set to the index of a Selection, rolling the mouse over this image 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.

"show_selection_index"

If set to the index of a Selection, this image will change the image it's displaying to match the image specified in the "show_selection_images" section of the selection.

"imagestyle"

Set to "movie" if you want this image to show the Hero portrait movie of the Hero matching the value of the selection in the "show_selection_index" selection, instead of the static Hero icon.

Standard Element Command Parameters

If you want this image to issue a command when clicked on by the user, this section is required.

Line Element Parameters

Line elements are used to draw straight lines directly onto the page.

Parameters:

"color"

The RGB value of the line.

"thickness"

The thickness of the line.

"start_pos"

A section containing "x" and "y" values for the starting position of the line.

"end_pos"

A section containing "x" and "y" values for the ending position of the line.

Example	`"dividing_line"` `{ "elementtype" "line" "color" "120 117 108" "thickness" "1" "start_pos" { "x" "132" "y" "87" } "end_pos" { "x" "917" "y" "87" } }`

Selection Element Parameters

Selections require several parameters to tell Dota 2 how to store and display them. If the Selection is shown as a combo box in the compendium, those parameters can be specified in the combo box section itself. If the Selection isn't a combo box (i.e. it's set by a button, or it's set by something on the Dota 2 backend), then the parameters can be specified in the root "preregister_selections" section.

Parameters shared by all types of selections are as follows:

selection_index

The index of this selection. No two selections can share the same index. Other elements will use this index to refer to this selection.

"choice_type"

The type of choices that this selection is using. Available choices are:

"generic" - Choices are a list of strings and corresponding IDs. The strings will be used to display the choices, and the backend will store the IDs.
"hero" - Choices must be a list of Hero IDs. They'll be displayed with Hero names.
"all_heroes" - Choices will be automatically filled out for you with a list of all Hero names.
"all_items" - Choices will be automatically filled out for you with a list of all Item names.
"counter" - Set by the Dota 2 Backend, not selected by users. Displayed as a raw number.
"accountid" - Set by the Dota 2 Backend, not selected by users. Displayed as the profile name on the Steam Profile matching the account ID.
"timestamp" - Set by the Dota 2 Backend, not selected by users. Displayed as a date and time for the user's time zone.
"elapsedtime" - Set by the Dota 2 Backend, not selected by users. Displays the selection in a format of HH:MM where the selection is the number of seconds.

"choices"

This must be a section that lists all the valid choices for this selection. Not required for "all_heroes", "all_items", or "counter" selections. Each choice should have a text description, and a unique choice value. For selections of type "hero", the choice values should match the Hero IDs.

action

This is an array of actions that are linked to the selection. An action can be linked to multiple selections and will be granted only if all of the selections are made (or optionally if they specify min_to_grant). So if this is the only selection that references an action, that action will be granted when this selection is made. It will only be granted the first time that this selection is made, so changing it in the future will not grant the action again. Multiple actions can be specified, and should use the name of the action provided in the action definition. For example:

Example	`"action"` `{ "0" "collect_5_playercards" "1" "collect_playercard_team_test" "2" "collect_all_playercards" }`

"time"

The time at which this selection can no longer be changed by players. Should be set to the name of a timer specified in the root "timers" section.

"description"

The text description of this selection.

"backend_desc"

A description for this selection shown only to you when using the Edit League web page to view your compendium stats.

"points"

The number of points this selection is worth. Generally used only for predictions. If unspecified it defaults to 0, and won't be shown in the UI.

"selection_element_color"

In addition to being changeable by a combo box, selections can also be setup to be changeable by buttons. The standard method is to have a button that the player clicks (something like "CHOOSE A TEAM"), which then highlights a set of images on the page (such as a set of team logos), and once the player then clicks on one of those logos the selection is set to the matching team's ID. If this selection works like that, set "selection_element_color" to the RGB value that you want the highlight element around the images to have.

"selection_set"

An optional string that, if matching other selections in the compendium, ensures that no two selections in the set are ever set to the same choice. Useful for things like All-Star match votes, where you don't want players to be able to select the same player in multiple slots.

"disable_set_rollup"

When viewing your Compendium Stats on the League page, we'll roll up multiple selections in the same selection set into a single entry. This is useful for when you have a set of selections where users are voting on something (like the 10 players they'd like to see in a show match). But if you don't want the set rolled up, because you need to see the selections in the set separately, then set this key on each of the selections in the selection_set.

"empty_string"

An optional string that will be shown instead of "Make A Selection" when the user hasn't selected a choice.

"tooltip_data"

An optional section that lists all the choices for this selection, and their associated tooltip data. Any textfield setup to show the value of this selection will use the tooltip data for the current choice. See Tooltip Parameters to see how to setup an individual tooltip.

"show_selection_images"

An optional section that lists all the choices in this selection, and their associated image filename. Any image setup to show the image for this selection will use the image corresponding to the current choice.

"action"

The name of a registered action in the root "event_actions" list. If an action has selections listed for it, the action will be considered completed once all the selections for it have been set by the player. Not available to third party compendiums at this time.

"result"

A section used to specify the result for selections that are being used as predictions. The result section contains the correct answer for the selection, and any extra information for the user if they click the "More Info" button (shown only for combo box selections). The parameters inside the result section are:

"answer"

The choice value of the correct answer for this selection.

"answers"

If there were multiple right answers, then use this instead of "answer". This should be a section containing a list of choice values (key is the choice value, value can just be "1").

"info_dialog"

An optional section containing extra information about the result. If this exists, the "More Info" button will be shown on the selection's combo box UI. Parameters inside this section are:

"match_id"

If set the ID of a tournament match, the "Watch Replay" button will be shown, and clicking on it will start the replay downloading & watching process.

"info"

A string containing extra information about this result. Will be shown in the results popup dialog.

"result_override"

An optional string that overrides the result showing in the results popup dialog. By default, the popup dialog will show the correct answer using the text description of the choice value of the "answer" key. But if you have multiple "answers", it's generally best if you write a more custom description here (i.e. "Bob & Mike tied for first place with matching scores of 100").

Selections that are shown as combo boxes also require the following parameters:

Standard Element Positioning Parameters

Specifies where this element is on the page.

"textcolor"

The RGB color of the description text above the combo box.

"bgcolor"

The RGB color of the shaded background in the combo box itself.

"combotextcolor"

The RGB color of the text inside the combo box.

"style"

The visual style of the combo box. Right now, only "s_CompendiumSelectionPlain" is supported.

Examples

A selection holding the votes for arcana items. It's a generic choice type, so the heroes aren't specified by ID. The selection UI used a button and images, not a combo box, so it has the selection element color specified.

Example	`"arcana_select_group1"` { "selection_index" "301" "selection_element_color" "0 255 0" "time" "arcana" "description" "YOUR PICK FROM GROUP 1" "choice_type" "generic" "choices" { "Storm Spirit" "1" "Faceless Void" "2" "Huskar" "3" "Pudge" "4" "Spectre" "5" "Jakiro" "6" "Lone Druid" "7" } }

A selection holding the player's favorite team. This selection uses a combo box for the selection, but it's part of a full page with a "PICK YOUR PAVORITE TEAM" treatment. As a result, it leaves the "description" key blank, and specifies a "backend_desc" so that we can easily find the result in the compendium stats report. Note also that the team names have the ^^ escape sequence at the start of them to tell the localization system that these strings should not be localized.

Example

"favorite_team_selection"

{ "x" "100" "y" "20" "textcolor" "93 57 93" "bgcolor" "93 57 93" "combotextcolor" "243 234 217" "selection_index" "601" "time" "mainevent" "backend_desc" "Favorite Team" "choice_type" "generic" "choices" { "^^Alliance" "1" "^^Titan" "2" "^^EG" "3" "^^Fnatic" "4" "^^NewBee" "5" "^^VG" "6" "^^Na'Vi" "7" "^^DK" "8" "^^IG" "9" "^^C9" "10" "^^Empire" "11" "^^Na'Vi.US" "12" "^^Arrow Gaming" "13" "^^LGD Gaming" "14" "^^Mousesports" "15" "^^Liquid" "16" "^^MVP Phoenix" "17" "^^CIS-Game" "18" "^^Virtus.Pro" "19" } }

A selection that handles a combo box for predicting which Hero had the most kills. Since it's an "all_heroes" selection, it doesn't need a list of choices. Now that the prediction time is over, it contains the results in the form of Hero IDs - in this case, Axe & Slark tied. Note that it also contains an optional info dialog block with some extra information.

Example

"hero_with_most_kills"

{ "x" "100" "y" "150" "textcolor" "93 57 93" "bgcolor" "93 57 93" "combotextcolor" "243 234 217" "selection_index" "30" "description" "HERO WITH THE MOST KILLS" "points" "4" "choice_type" "all_heroes" "time" "qualifiers" "result" { "answers" { "2" "1" // Axe's Hero ID "93" "1" // Slark Hero ID } "info_dialog" { "info" "Axe and Slark tied with 22 kills" "match_id" "679787098" } } }

Custom Selection Layouts

If you'd like more control over your selection UI, you can manually assemble the components instead of using the entire "selection" element. Here's an example of a custom selection element that contains the components in a standard "selection" element, which you can use as a starting point:

Example

"custom_selection"

{ "elementtype" "container" "x" "20" "y" "200" "elementlist" { "combobox" { "elementtype" "combobox" "rx" "28" "ry" "17" "textcolor" "93 57 93" "bgcolor" "93 57 93" "combotextcolor" "243 234 217" "selection_index" "1021" "visibility_selection_index" "1021" "visible_when_selection_unlocked" "1" } "points" { "elementtype" "textfield" "rx" "378" "ry" "0" "text" "%selpoints_1021% pts" "font" "text" "size" "12" "w" "70" "h" "20" "align" "right" "color" "93 57 93" } "description" { "elementtype" "textfield" "rx" "26" "ry" "0" "text" "%seldesc_1021%" "font" "text" "size" "12" "w" "350" "h" "20" "color" "93 57 93" } "results" { "elementtype" "container" "rx" "0" "ry" "0" "visibility_selection_index" "1021" "visible_when_selection_results" "1" "visible_when_selection_unlocked" "0" "elementlist" { "yourselection" { "elementtype" "textfield" "rx" "27" "ry" "17" "text" "Your Selection:" "font" "text" "size" "12" "w" "100" "h" "20" "color" "93 57 93" "resize_to_fit" "1" } "choice" { "elementtype" "textfield" "relative_to" { "target" "custom_selection-results-yourselection" "point" "tr" "rx" "5" "ry" "0" } "text" "%selection_1021%" "font" "textbold" "size" "12" "w" "260" "h" "20" "color" "93 57 93" "glow" "1" } "infobutton" { "elementtype" "button" "style" "ButtonTextualRightPassport" "text" "Show More Info" "rx" "330" "ry" "12" "color" "93 57 93" "command" "popup_results:1021" } "checkmark" { "elementtype" "image" "rx" "0" "ry" "5" "w" "25" "h" "25" "filename" "checkmark.png" "depth" "front" "visibility_selection_index" "1021" "visible_when_selection_correct" "1" } } } } }

Button Element Parameters

Button elements are clickable buttons that allow users to provide input. Generally used as an alternative to combo boxes for setting selections.

Parameters:

Standard Element Positioning Parameters

Specifies where this element is on the page.

"style"

The style of the button. Valid styles are "button_transparent", "button_solid", "button_gradient", and "button_close".

"color"

An optional RGB value to multiply the button color by. Not all button styles support color setting at this time.

"text"

The text inside the button. Not all button styles support text ("button_close" is just an X, for instance)

"align"

How the X position of the button should be used, since button automatically expand to contain their text. "left" will make the button expand to the right (so the X position will be the left edge of the button), "right" will make it expand to the left (so the X position will be the right edge of the button), and "center" will make it expand equally in both directions (so the X position will be the middle of the button).

"tooltip_data"

An optional section describing the tooltip for this button, if you want one. See Tooltip Parameters.

Standard Element Visibility Parameters

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

Standard Element Command Parameters

If you want this button to issue a command when clicked on by the user, this section is required.

An example button for selecting a favorite hero. When the user clicks the button, a set of hero icons are highlighted to allow the user to click directly on the hero they want to choose. Note that this button is only visible when selection 301 is 0 (unset).

Example	`"selecthero1"` { "elementtype" "button" "style" "button_transparent" "text" "SELECT HERO" "x" "380" "y" "175" "align" "center" "color" "255 255 255" "visible_when_selection_is" "0" "selection_index" "301" "selection_elements" { "heroicon1" "15" "heroicon2" "22" "heroicon3" "36" "heroicon4" "41" "heroicon5" "50" "heroicon6" "65" "heroicon7" "77" } }

An example button that simply clears the specified selection. Note that it's only visible when selection 301 is not 0 (i.e. has been set).

Example	`"clearhero1"` { "elementtype" "button" "style" "Button_Close" "x" "435" "y" "145" "align" "center" "color" "255 255 255" "selection_index" "301" "selection_force_to" "0" "visible_when_selection_not" "0" }

Timer Element Parameters

Timer elements are non-interactive displays showing the amount of time left until a specified time is reached. Generally used as countdown displays on pages with user selections that close at some point.

Parameters:

Standard Element Positioning Parameters

Specifies where this element is on the page.

"time"

The name of the time entry in the root "timers" section that this timer display is referring to.

"textcolor_title"

The RGB value of the title text in the display.

"textcolor_sub"

The RGB value of the subtitle text in the display.

"maxseconds"

If you want to clamp the maximum time the timer is allowed to show, set this value to that max time (in seconds).

"timerstyle"

Can be set to "hero_challenge" for 24 Hour Hero Challenge timers. Should be left out otherwise.

Example	`"mainevent_timer"` `{ "elementtype" "timer" "x" "156" "y" "525" "time" "mainevent" "textcolor_title" "93 57 93" "textcolor_sub" "93 57 93" }`

ProgressBar Element Parameters

Progress Bars are non interactive elements designed to show the percentage progress towards something. Note that progress bar elements only draw the filled portion of a progress bar. It's generally best to place them on top of an image that acts as the underlying unfilled portion.

Parameters:

Standard Element Positioning Parameters

Specifies where this element is on the page.

"w"

Element width. This is the maximum width of the filled bar. The actual drawn width of the bar will be between 0 and this value.

"h"

Element height.

"data"

The data source that this progress bar is reading from. Currently supported sources are "prizepool" and "level" (of the compendium).

"min"

The value of the data source at which the bar should be 0 width. Values below this will be clamped.

"max"

The value of the data source at which the bar should be at 100% width. Values above this will be clamped.

"color"

The RGB color of the filled portion of the bar.

"filename"

If you'd like to use an image to represent the portion of the filled bar, instead of a filled block of color, then specify the image filename here. It should match the filename of an image sitting in the same directory as the compendium script file. Alternatively, you can specify the relative path of an existing image inside Dota 2's resource\flash3 directory (i.e. "images/heroes/beastmaster.png" or "images/items/abyssal_blade.png")

Example	`"main_progressbar"` `{ "elementtype" "progressbar" "x" "53" "y" "190" "w" "406" "h" "21" "data" "prizepool" "min" "1600000" "max" "6000000" "filename" "compendium2014_bar_stretchgoalbar_filler.png" }`

Video Element Parameters

Video elements display an embedded, playable video. Note that these videos are set to a fixed size of 494x278.

Parameters:

Standard Element Positioning Parameters

Specifies where this element is on the page.

"providers"

There are two currently supported providers: Youtube and Youku.

One or both may be supplied, with Chinese Dota 2 clients preferring to load the Youku video if present and the remaining clients preferring to load the Youtube video if present.

The value of the individual provider is the identifier of the video for that provider.

For example, the Youtube ID in the example below comes from this full URL: http://www.youtube.com/watch?v=Eqk9C1wVT0U

The Youku example comes from this URL: http://player.youku.com/embed/XNzQ2OTgzNjc2

Example	`"embedded_video"` `{ "elementtype" "video" "x" "9" "y" "150" "providers" { "youtube" "Eqk9C1wVT0U" "youku" "XNzQ2OTgzNjc2" } }`

Container Element Parameters

Container elements are invisible elements that contain other elements. Extremely useful for organisational purposes, and powerful tools in templates.

Parameters:

Standard Element Positioning Parameters

Specifies where this element is on the page.

"elementlist"

A section containing one or more child elements, to be created and contained inside this Container.

Relative Coordinates: "rx" & "ry"

Any child element inside a Container can also choose to use x/y positions relative to the Container's x/y. This allows you to easily position repeated blocks of elements. To use relative coordinates, the child element should use the "rx" and "ry" keys instead of the "x" and "y" keys.

Standard Element Visibility Parameters

Used to control when this element is visible / non visible. Elements are always visible by default. Note that elements contained inside this Container will only evaluate their own Visibility Parameters if this Container is visible. Hence, you can use visibility parameters inside Containers and their embedded children to do AND visibility operations.

This example container has three elements inside it. The container itself is only visible when selection 500 has a value of 0, and since the three elements are contained inside it, they follow the same rule. Note that the description text has additional visibility rules - it's only visible if selection 600 is not 0. That rule will only be evaluated if the container itself is visible, so the description text is only visible when selection 500 is 0 AND selection 600 is not 0. Note also that the lock button is using relative coordinates, so that its X & Y position are offset from the container's (resolving here to 55,100).

Example	`"favorite_hero_unset"` { "elementtype" "container" "x" "50" "y" "100" "visibility_selection_index" "500" "visible_when_selection_is" "0" "elementlist" { "selection_hero" { ... } "lockbutton" { "rx" "5" "ry" "0" ... } "description_text" { "visibility_selection_index" "600" "visible_when_selection_not" "0" ... } } }

Template Element Parameters

Templates are sections of KeyValues that can be easily replicated throughout your script file. They're essential for building easily maintainable compendiums. Note that templates must still specify an "elementtype", unless they expect all their instanced objects to specify one.

To build templates effectively, you must understand how they're implemented in the compendium. The easiest way to understand them is via an example. First, imagine we have a template called "template_pagetitle":

Example	`"template_pagetitle" { "embedded_template" "1" "elementtype" "textfield" "x" "0" "y" "46" "w" "512" "h" "20" "font" "title" "size" "16" "align" "center" "color" "93 57 93"` `}`

This is a useful template for our compendium - it's a textfield designed to show the title of a page. It has everything specified for a page title, minus the exact text to display. Note that it looks like a normal textfield, except that it has the "embedded_template" key set, which tells the compendium that it shouldn't create the textfield, it should register it as a template instead. Now we can instantiate that template in a page in the following way:

Example	`"page_example" { "elementlist" { "title" { "t" "template_pagetitle" "text" "MY BIG PAGE TITLE" "size" "20" } }` `}`

When the compendium system finds the "t" key, it goes looking for a template with the specified name. Once it finds the template, it merges all the template's keys into this section. Any keys that are in the derived instances will override any key inside the template, so in this case the larger size (20) will be left intact, and the template's smaller size (16) will be ignored. Post template resolution, the script file would be as follows:

Example	`"page_example" { "elementlist" { "title" { "text" "MY BIG PAGE TITLE" "size" "20" "elementtype" "textfield" "x" "0" "y" "46" "w" "512" "h" "20" "font" "title" "align" "center" "color" "93 57 93" } }` `}`

Note that the "embedded_template" key is not copied down into the instance, so that the instance doesn't become a template as well. As a result, if you have templates derived from other templates, you'll need to make sure they also have the "embedded_template" key set inside them, since they won't inherit it from their parent template.

Defines

Templates can also contain a section called "required_defines". This section contains a list of defines that any derived instances of the template can provide override values for. When the templates are resolved by the compendium system, the values of the derived defines will replace any instances of the defines inside the template. Any define that's not overridden by the derived instance will use the default value of the define (the default is the value of the define in the "required_defines" section).

Define names must also follow a strict format:

Start and end with the % character.
Start with %def_ or %defloc_. If the define will contain text that needs to be localized, use %defloc_. Otherwise, use %def_.

To understand, let's look at an example. Lets say we want every one of our compendium pages to have a title, and a nice border image under it. We could define a template as follows. It contains both the textfield and the image, and a define for the text inside the textfield. Note that we want the title text to be localized, so we use the %defloc_ preface for our define name.

Example	`"titlesection_template" { "elementtype" "container" "required_defines" { "%defloc_title%" "1" } "elementlist" { "titletext" { "t" "t_page_title" "text" "%defloc_title%" } "background_image" { "elementtype" "image" "filename" "compendium2014_titlebackground.png" "x" "185" "y" "35" "w" "142" "h" "42" "depth" "back" } }` `}`

We could then instantiate that template on a page as follows:

Example	`"page_example" { "elementlist" { "title" { "t" "titlesection_template" "defines" { "%defloc_title%" "MY PAGE TITLE" } } }` `}`

This page would now display the title text field and image. The instance should contain a "defines" block with a value for any of the defines listed in the template's "required_defines" that the instance wants to override. Any defines that aren't listed in the instance's "defines" block will use the template's default value.

The advantage of using defines are as follows:

Instances don't need to know the internal structure of the template. In the case above, the "title" instance of the "titlesection_template" template doesn't need to contain a matching elementlist to put the "text" key into the right place within the "titletext" textfield. This allows the template to be redesigned without breaking any derived instances.
The define can be used in multiple places in the template, reducing the chances of incorrect data being specified by instances.

Here's a slightly more complex example. Note how it uses the %defloc_name% define in multiple textfields. It also uses the %def_ prefix for the logo, because it's an image filename and hence shouldn't be localized.

Example	`"template_qualifier_attendee" { "embedded_template" "1" "elementtype" "container" "required_defines" { "%defloc_name%" "1" "%def_logo%" "1" } "elementlist" { "name" { "t" "attendee_name" "text" "%defloc_name%" } "logo" { "t" "img_teambig" "filename" "%def_logo%" } "tiny_name" { "t" "attendee_name" "size" "8" "text" "%defloc_name%" } }` `}`

Skipping Sections

Defines can also be used to allow instances to remove elements from the template. This can be great if you want to have a template that contains multiple different treatments for something, and you want instances to be able to select the treatment they want to use. The following keys can be specified as a parameter for any element in the compendium (and most usefully, in containers):

"skip_element_if"

This element will be skipped if the value of this key is 1.

"skip_element_if_not"

This element will be skipped if the value of this key is 0.

"skip_element_if_empty"

This element will be skipped if the value of this key is not "". Useful if you want some instances to be able to specify an optional chunk of text, and to have the template contain a set of images and textfields to be shown only if that text chunk isn't empty.

Nested Templates

One useful technique is having templates that derived from other templates. For instance, you may want to have a root textfield template that sets up your fonts and colors, and then some derived templates for titles, subtitles, and descriptive blocks. KeysValues inside nested templates are merged downwards through the template chain just like any other key - keys in the lower templates will override the keys in the upper templates.

Debugging

Liberal usage of templates and defines can lead to situations where your compendium script file is reporting bugs that are tricky to track down. A useful tool for debugging them is the "test_compendium_writeposttemplates" convar. If you set it to 1 in the Dota 2 console, and then run your "test_compendium" command, the compendium system will save your script file to disk after it's resolved all the templates in it.

You can find the resolved script file under your Dota 2 directory in the following file: \dota\compendium_datafile.txt

Generic Element Parameters

Generic elements are specific scaleform elements embedded in the compendium .FLA file. The only current usage for them is to create Scrolling View elements (i.e. embedded windows with scrollbars).

Standard Parameter Sections

Some parameters are available to more than one element type. This section contains a list of these standard parameter blocks.

Positioning Parameters

All elements can be positioned on their page in a number of ways. Note that the pages are 512x576 pixels (displayed fullscreen in 16x9), and are then resized according to the screen resolution (letterboxed in other aspect ratios).

The simplest method of positioning is to use straight X & Y coordinates on the page:

"x"

Element X position.

"y"

Element Y position.

If the element is inside a Container element, you can use relative coordinates.

"rx"

Element relative X position. Will be used as an offset to the parent container's X position.

"ry"

Element relative Y position. Will be used as an offset to the parent container's Y position.

Alternatively, elements can be positioned relative to any other element on the page:

"relative_to"

A section containing the following keys, explaining how to position this element:

"target"

The name of the target element to position this element relative to. The target element must be on this page, and must be specified before this element in the list of elements on the page. If the target element is inside a container, you must prepend the container's name, with a separating '-' character. i.e. "custom_selection-results-selectionbutton" is the name of an element called "selectionbutton" inside a container called "results", which is inside another container called "custom_selection".

"point"

The point on the target element that this element should be positioned relative to. Must be one of the following: "tl", "tr", "bl", "br", "tm", "bm", "lm", or "rm" (the letters corresponding to Top/Left/Right/Bottom/Mid). So specifying "rm" would position this element relative to the Right Mid point of the target element.

"rx"

Element relative X position. Will be used as an offset to the target element's point.

"ry"

Element relative Y position. Will be used as an offset to the target element's point.

Visibility Parameters

There are a wide variety of visibility controls that allow you to control the visibility of your elements. Combining multiple visibility controls in the same element can be confusing, so think of it this way: Elements are visible by default, and become invisible when they fail one of the rules below.

"visible_when_prizepool_less"

Element will only be visible when the League's prizepool is less than the specified value.

"visible_when_prizepool_more"

Element will only be visible when the League's prizepool is more than the specified value.

"visible_when_level_less"

Element will only be visible when the compendium level is less than the specified value.

"visible_when_level_more"

Element will only be visible when the compendium level is more than the specified value.

"visibility_selection_index"

This is the selection index used in the following two selection-based visibility keys.

"visible_when_selection_is"

Element will only be visible when the visibility selection's current choice matches the specified value.

"visible_when_selection_not"

Element will only be visible when the visibility selection current choice is not the specified value.

"visible_when_selection_less"

Element will only be visible when the visibility selection current choice is less than the specified value.

"visible_when_selection_more"

Element will only be visible when the visibility selection current choice is more than the specified value.

"visible_when_selection_locked"

Element will only be visible if the visibility selection is locked (i.e. the current time is greater than the selection's "time" field".

"visible_when_selection_unlocked"

Element will only be visible if the visibility selection is not locked (i.e. the current time is prior to the selection's "time" field".

"visible_when_selection_results"

Element will only be visible if the visibility selection has a results section.

"visible_when_selection_correct"

Element will only be visible if one of the visibility selection's answers matches the compendium owner's choice.

"visible_after_time"

The value should be the name of a timer inside the root compendium "timers" section. This element will only be visible when the current time is past the timer's time.

"visible_until_time"

The value should be the name of a timer inside the root compendium "timers" section. This element will only be visible when the current time is earlier than the timer's time.

"visible_when_game_live"

Element will only be visible when the League has a live game being played.

"visible_when_action_started"

Value must be a valid Action ID. Element will only be visible when the corresponding Action has been started.

"visibility_variable_name"

Value must be the name of a registered Local Variable.

"visible_when_variable_is"

Element will only be visible when the local variable specified in "visibility_variable_name" has a value that matches this specified value.

"visible_when_variable_not"

Element will only be visible when the local variable specified in "visibility_variable_name" has a value that doesn't match this specified value.

Tooltip Parameters

Text and Image elements support tooltips, and hence can contain the following tooltip settings. Selections can also contain a section with tooltip settings for every valid choice in the Selection - text fields that are showing the value of the Selection will then show the matching tooltip when moused over.

The following settings are used to configure a tooltip:

"style"

The layout style of the tooltip. Must be "tooltip_titleandtext", "tooltip_titletextandcountryflag", or the name of an embedded page, in which case the corresponding embedded page will be instantiated. See Embedded Pages for more information. When using an embedded page as a tooltip, the remaining tooltip parameters below are ignored (your embedded page can be customized as you'd like)

"tooltip_title"

The text shown in the title of the tooltip.

"tooltip_text"

The text shown in the body of the tooltip.

"color_title"

The RGB value of the title text of the tooltip.

"color_text"

The RGB value of the body text of the tooltip.

"color_bg"

The RGB value of the background of the tooltip.

"filename"

The filename of an image, required only if the tooltip style has an image in it. "tooltip_titletextandcountryflag" contains a small country flag image.

Command Parameters

Several element types are able to contain commands that are issues when the user clicks on the element. The data required to perform the command should be specified inside a "command" section in the element's parameters.

Inside the "command" section, the following parameters can be specified:

"show_confirmdialog"

If you want to show an Are You Sure? dialog when the user initiates this command, then this should be the descriptive text to be shown in the dialog. If unspecified, the command will apply its effects immediately.

"selection_index"

If you want this command to set the value of a selection when issued by the user, this should be the selection index of the selection you want to set. The selection must be described in the root "preregister_selections" section. Requires that you you also specify either "selection_elements" or "selection_force_to".

"selection_elements"

A section containing a list of elements that should be highlighted when the user issues this command. Each element must have a corresponding choice value. When the user clicks on one of the highlighted elements, the selection will be set to the choice value. If the element that issues this command is a button, it will automatically change to a "Cancel" button while the elements are being highlighted.

"selection_force_to"

If you want this command to immediately set the value of a selection when clicked by the user, this should be the choice value you want the selection to be set to.

"link_to_page"

Value must match the name of one of your pages in your compendium. Issuing this command 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. Issuing this command will popup that URL in an external browser.

"command"

A specific command that should be issued by this element. Valid commands are as follows:

"goto_tournament"

The compendium will close and the user will be taken to the Live Games section of the Watch tab.

"goto_offerings"

The compendium will close and the user will be taken to the Offerings section of the Armory.

"compendium_buy_and_useX"

X must be the index of an item definition. This will initiate the purchase of the specified item.

"popup:X"

X must be the name of an embedded page. The corresponding embedded page will be instantiated. See Embedded Pages for more information.

"close:X"

X must be the name of an embedded page. If the corresponding embedded page is currently visible, it will be closed. See Embedded Pages for more information.

"popup_results:X"

X must a valid selection index. The standard Selection Results Dialog will be popped up with the results for the specified selection.

"set_local_variable"

Sets the value of a Local Variable. Requires extra settings, see below.

"request_heroes", "reroll_heroes", and "roll_daily_hero"

These are used to handle the TI4 challenges, and are now obsolete.

"variable"

The name of a registered Local Variable. Required only if the command being issued is "set_local_variable".

"value"

The value to set the above local variable to. Required only if the command being issued is "set_local_variable".

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.

%selpoints_X%

X must be a valid selection index. The escape sequence will be replaced with the points value of the Selection.

%seldesc_X%

X must be a valid selection index. The escape sequence will be replaced with the description entry for of the Selection.

%selanswer_X%

X must be a valid selection index. The escape sequence will be replaced with the first answer in the "results" section 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%"`

Embedded Pages

Embedded pages are a powerful tool for adding an extra layer of information and interactivity to a compendium. An embedded page is laid out just like a normal page inside the root "embedded_pages" section, with the addition of some parameters describing how the embedded page should be displayed. Elements inside the standard pages are then setup to trigger the display of the embedded page.

The current methods of triggering the display of embedded pages are as follows:

By setting a button's "command" to "popup:<embedded page name>"
By setting the "style" of a tooltip to the name of an embedded page.

In addition to the standard Page Parameters, embedded pages have the following parameters:

"modal"

Tells this embedded page to act like a modal dialog when it appears. The rest of the compendium will be greyed out. The page will close if the user clicks outside it.

"w"

The width of the embedded page. This is used when the positioning rule (see below) requires knowledge of the page's overall size.

"h"

The height of the embedded page. This is used when the positioning rule (see below) requires knowledge of the page's overall size.

"positioning_rule"

Sets how this embedded page should be positioned when it's shown. Must be one of the following:

"fixed"

The page will be displayed at the X/Y position specified by the "x" & "y" parameters.

"centered_on_left_page"

The page will be centered on the left page of the book, and then offset by the "x" & "y" parameters. Requires "w" and "h" to be set.

"centered_on_right_page"

The page will be centered on the right page of the book, and then offset by the "x" & "y" parameters. Requires "w" and "h" to be set.

"centered_on_book"

The page will be centered on the middle of the book, and then offset by the "x" & "y" parameters. Requires "w" and "h" to be set.

"as_tooltip"

The page will be used as a tooltip, and positioned relative to the element it's showing a tooltip for. Requires extra data to be specified in the "as_tooltip_data" section (see below).

"resize_elements"

A section containing a list of elements inside this embedded page that need to be resized, and information on how to resize them. Entries in this section must have a name that matches one specified inside the embedded page's standard "elementlist". This feature is generally used for tooltips that expand dynamically to contain text - in those cases, the background image for the tooltip must be resized to contain the text.

Images set to resize must be precached in the root "precache" section, or they'll be incorrectly laid out the first time they appear (as the image is asynchronously loaded). Elements in the "resize_elements" section contain the following parameters:

"horiz_rule"

The rule describing in which direction this element should be horizontally resized. Can be "none", "left", or "right". For example, if set to "right", the element will only grow/shrink to the right to match the width of the embedded page.

"vert_rule"

The rule describing in which direction this element should be vertically resized. Can be "none", "up", or "down". For example, if set to "down", the element will only grow/shrink downwards to match the width of the embedded page.

"indent_x"

An optional amount added to the width of the embedded page when resizing this element. Useful for tooltip background images that want to add some padding around the content inside them.

"indent_y"

An optional amount added to the height of the embedded page when resizing this element. Useful for tooltip background images that want to add some padding around the content inside them.

"slice_x"

If the element being resized is an image, you can use this to perform a [9 way slice] of the image. Very useful for clean resizing of borders, boxes, etc. This X value will be used as an indent on either side of the image to create the 2 vertical slices.

"slice_y"

If the element being resized is an image, you can use this to perform a [9 way slice] of the image. Very useful for clean resizing of borders, boxes, etc. This Y value will be used as an indent on either side of the image to create the 2 horizontal slices.

"as_tooltip_data"

If the embedded page is being used as a tooltip, this section is required. It contains the following parameters describing how the tooltip should be handled:

"diamond"

The name of the image element inside the embedded page that should be used as the connecting arrow between the embedded page and the element it's showing a tooltip for. It should be a diamond shape so that it can be used as an arrow up/down/left/right.

"desired"

The desired direction that the tooltip should be positioned relative to the element it's showing a tooltip for. It must be one of the following: "at_element_tl", "at_element_tr", "at_element_bl", "at_element_br", "at_element_tm", "at_element_bm", "at_element_lm", "at_element_rm" - TL = Top Left, BR = Bottom Right, TM = Top Middle, RM = Right Middle, etc. The tooltip will attempt to position itself there by default. If the tooltip cannot fit onscreen at that position, the tooltip will attempt to find another position where it will be visible around the element it's showing a tooltip for.

"indent_x"

An optional horizontal amount to push the tooltip away from the element it's showing a tooltip for. Tweaking this generally requires adjusting resizing element indents, and the diamond element's width.

"indent_y"

An optional vertical amount to push the tooltip away from the element it's showing a tooltip for. Tweaking this generally requires adjusting resizing element indents, and the diamond element's height.

Here's an example of a template for an embedded page setup to be a tooltip. It contains a short title & description string, and the background image that resizes to contain the two. It uses defines for the two chunks of text, so that they're easily overridden with the right text in the elements using the tooltip.

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

Example

"embedded_tt_base"

{ "positioning_rule" "as_tooltip" "as_tooltip_data" { "diamond" "bg_diamond" "desired" "at_element_lm" "indent_x" "5" "indent_y" "5" } "resize_elements" { "bg" { "horiz_rule" "right" "vert_rule" "down" "indent_x" "15" "indent_y" "15" "slice_x" "6" "slice_y" "6" } } "elementlist" { "nodename" { "elementtype" "textfield" "font" "textbold" "size" "9" "x" "0" "y" "0" "w" "500" "h" "14" "text" "%defloc_title%" "color" "190 187 178" "depth" "front" "resize_to_fit" "1" } "description" { "elementtype" "textfield" "font" "textbold" "size" "9" "x" "0" "y" "15" "w" "150" "h" "400" "text" "%defloc_desc%" "color" "123 118 112" "depth" "front" "resize_to_fit" "1" } "bg_diamond" { "elementtype" "image" "w" "25" "h" "25" "depth" "back" "filename" "tooltip_diamondpointer.png" } "bg" { "elementtype" "image" "x" "0" "y" "0" "w" "50" "h" "28" "depth" "back" "filename" "tooltip_background.png" // Has been precached in the root level 'precache' section } } }

This is the tooltip background image, which is resized (using a 9-way slice) to contain the text:

This is the tooltip diamond image, used to generate the arrow from the element to the tooltip:

Local Variables

In addition to using selections to store data from clients, you are able to store data temporarily on their machine, on a per-session basis (it's thrown away when they close the compendium). The main purpose of this is to be able to build more interactive visual elements. Variables are registered by name, with a default value, and can then be set by any command from an element. Other elements are able to then use visibility checks to set their visibility based on variable states. The example compendium contains a page with some example usages.

To register a local variable, specify it and its default setting in the root "local_variables" section. The values are stored and compared as strings, so they don't have to be integers.

Example	`"local_variables"` `{ "example_tab" "1" "example_reward" "courier" }`

Setting a registered variable is done with the "set_local_variable" command in any command-issuing element (buttons, images, text). See Commands for more detail.

Example	`"command"` `{ "command" "set_local_variable" "variable" "example_reward" "value" "left" }`

Use "visible_when_variable_is" in Standard Element Visibility Parameters to control visibility of other elements based on your variables.

Event Actions

This block of the file starts with the key "event_actions", and contains a list of actions that can be granted by the compendium or used for compendium related rewards. This is only used if an event_id is set for the compendium which is provided by Valve for certain compendiums.

Each action looks like the following:

Example	`"<action name>"` `{ "action_id" "100" "max_grants" "4" "normal_points" "25" "add_to_web_request" "1" "min_to_grant" "8" "reward_id" "700" }`

"<action name>"

The root name of the action is a string that must be unique, and is used to identify this action in the selection. This is also used on the league compendium information page so it is handy to try and use descriptive names.

"action_id"

This is a unique integer identifier that represents the action. This value MUST NOT BE CHANGED, as it is used to uniquely identify which actions have been granted to each user and a different ID is considered a different action.

"max_grants"

This value limits how often a user can be granted this action. For something that a user should only be awarded once it should be one, but if it is something that can be repeated multiple times, this value should be set to the maximum number of times a user can receive the action. It is very dangerous to have this unnecessarily high to ensure that excessive points or items are not granted in exceptional cases.

"normal_points"

If specified, this will indicate how many points that a user will receive each time they complete this action. Note that this is not the total points they can get, for that you need to use max_grants * normal_points since they will receive these points each time. This is also effectively the granularity of the point distribution. For example if you want to give out 100 points for an action, you could do it as max_grants = 5 normal_points = 20, max_grants = 1 normal_points = 100, or even max_grants = 100 normal_points = 1. The right approach depends upon how the action is obtained. If for example there is an aspect that can give a user from 1 to 100 points, you would need to use the max_grants = 100 normal_points = 1, so that they could receive the action say 79 times if they scored 79 points.

"add_to_web_request"

This indicates whether or not the number of action grants for this action should be provided on the compendium stats web page 1 means include, 0 (the default) means exclude

"min_to_grant"

When setting up actions that are tied to selection sets, this indicates how many selections need to be set in order to receive this action. So for example if you have a set of ten selections that refer to this action but you want to grant it as soon as they have five selected, you would set this value to 5. If this is not specified, this assumes that all selections that reference this action must be set before the action is granted.

"reward_id"

This specifies a reward that should be granted each time the action is granted. Reward id's are setup by Valve and if appropriate you will be provided with reward id's that you can use to link actions to the rewards that were discussed.

This article has not been added to any content categories. Please help out by

adding categories.
January 2024

Dota 2 Compendium Scriptfiles

Building and Testing

Concepts

Pages

Elements

Selections

Templates

Localization

Points

Actions

The Script File Format

Root Level Parameters

Page Parameters

Element Parameters

Text Element Parameters

Selection Points Displays

Textlists

Image Element Parameters

Line Element Parameters

Selection Element Parameters

Examples

Custom Selection Layouts

Button Element Parameters

Timer Element Parameters

ProgressBar Element Parameters

Video Element Parameters

Container Element Parameters

Template Element Parameters

Defines

Skipping Sections

Nested Templates

Debugging

Generic Element Parameters

Standard Parameter Sections

Positioning Parameters

Visibility Parameters

Tooltip Parameters

Command Parameters

Text Escape Sequences

Embedded Pages

Local Variables

Event Actions

Navigation menu

Search