Dota 2 Workshop Tools/Panorama

Panorama is a new Valve-developed UI framework. It is heavily influenced by and closely resembles modern web authoring (HTML5/CSS/JS). It enables rapid development, high quality, and high performance interfaces as well as seamless integration with game content (3D models, particles, etc.)
Panorama has completely replaced Scaleform. The rest of Source 2 engine tools have a very different set of requirements and so are still implemented in C++ and Qt - they will not be migrated to Panorama.
== Panorama Concepts ==
=== Panels ===
See: Dota 2 Workshop Tools/Panorama/Panels
Panels are the building blocks of any Panorama UI. (In web terms, a Panel is basically an HTML element.) Everything you see in a Panorama UI - labels, images, buttons - is a Panel.
=== .XML (Layout Files) ===
XML files are the skeleton of your data: they describe what panels are in your UI and their hierarchical layout. They can be found here:
 content/dota_addons/ADDON_NAME/panorama/layout/custom_game/*.xml
A complex Panorama UI is usually authored as multiple XML files for simplicity and clarity. (This also allows repeated elements in the UI to be authored in a single place.) For example, a scoreboard may consist of a "root" XML file for the main scoreboard layout, a second "team" XML file that describes how each team is represented, and a third "player" XML file that describes how each player on each team is represented.
=== .CSS (Style Sheets) ===
CSS files describe how the elements from your XML are presented. They can be found here:
 content/dota_addons/ADDON_NAME/panorama/styles/custom_game/*.css
There are three sources for documentation about the supported CSS properties:
The CSS Properties page
The properties panel inside of the Panorama Debugger
The "dump_panorama_css_properties" console command, which will always print out the most up-to-date documentation
The Panorama Layout page is also a good resource for getting an overview about how the Panorama layout system works.
=== .JS (Javascript) ===
See: Dota 2 Workshop Tools/Panorama/Javascript
JS files are Javascript code that allows your UI to respond to user input or changing game state. They can be found here: 
 content/dota_addons/ADDON_NAME/panorama/scripts/custom_game/*.js
=== Events ===
See: Dota 2 Workshop Tools/Panorama/Events
Panorama events are a way to communicate between different Panels. They are similar to javascript functions, but have different rules around routing and handling. Events are useful to simplify many common tasks when creating custom UI with Panorama.
 
=== Similarity to the Web ===
If you are familiar with web development, a Panorama XML file closely resembles an HTML5 document, a CSS file is nearly identical to its web counterpart (without the complexity of browser compatibility), and JS files are the same JavaScript you're familiar with. (With a slightly different library of functionality.)
If you're not familiar with web development, you can still benefit from the similarity. Most Panorama features are sufficiently similar to their web counterparts that searching online for documentation can be very helpful. If you want to learn more about web development, a good place to start is: https://www.javascript.com
=== Differences from the Web ===
* Some parts of CSS have been tweaked to make them simpler or easier to use
* In javascript, the JQuery-style '$' panel selector is very limited. It can currently only match a single panel by ID. If there is no matching panel it will return null instead of a empty selector, which can result in unexpected JS errors.
* Some web features are simply missing, due to lack of need or their complexity/cost
== Authoring Panorama UI ==
=== Getting Started ===
The root of any custom game Panorama UI is the Custom UI Manifest: 
 content/dota_addons/ADDON_NAME/panorama/layout/custom_game/custom_ui_manifest.xml
=== Workflow ===
When running the Dota tools, XML, CSS, and JS files in the content/ folder are monitored like any other content files and auto-recompiled and reloaded when you make changes. (This will only happen when the UI is active - an unused XML will only be compiled once it's actually used.)
Panorama generally does a good job updating the UI to take into account these dynamic changes, but some changes are too drastic for it to correctly update the UI. If you are seeing unexpected results, you may need to reload your map (dota_launch_custom_game ADDON_NAME MAP_NAME) to ensure the UI is fully refreshed.
=== Panorama Debugger ===
The Panorama Debugger is an extremely useful tool for debugging your UI and learning how existing UI is put together.
=== Tips ===
* Inline style is not good practice but good for prototyping: <Panel style="border: 1px solid red;" /> (remember your closing ';' in the style!)
* If you're having a hard time finding your panel, it can be very helpful to add a temporary 'border: 1px solid red;' or explicit width/height.
* $.Msg( "In function foo():", some_data ); is your friend!
* You can use the 'dota_custom_ui_debug_panel <element_type>' debug command to force a type of UI to be visible when it otherwise wouldn't be. The element_type is a numeric value from DotaCustomUIType (eg. for end screen: 'dota_custom_ui_debug_panel 5')
=== Localization ===
Multi-language support in Panorama is described here: Dota 2 Workshop Tools/Panorama/Localization
== Valve-Provided Panorama UI ==
As part of our example game mode "Overthrow" we created several new UI components that can be used directly for your custom game, or as a starting point to create your own unique UI. These are primarily designed to handle a wide range of team and player arrangements beyond normal Dota 5v5.
See Valve Provided UI for more information.
== Additional Topics ==
=== Custom Loading Screens ===
Custom loading screens are separate from the normal UI manifest because they are loaded earlier.
The loading screen is a normal Panorama XML and will be loaded from: 
=== Custom Hud Elements ===
A simpler but less powerful API to display XMLs on clients directly from server Lua code.
Function 	Signature 	Description
CustomUI.DynamicHud_Create 	void DynamicHud_Create(int, string, string, handle) 	Create a new custom UI HUD element for the specified player(s). ( int PlayerID /*-1 means everyone*/, string ElementID /* should be unique */, string LayoutFileName, table DialogVariables /* can be nil */ )
CustomUI.DynamicHud_Destroy 	void DynamicHud_Destroy(int, string) 	Destroy a custom hud element ( int PlayerID /*-1 means everyone*/, string ElementID )
CustomUI.DynamicHud_SetDialogVariables	void DynamicHud_SetDialogVariables(int, string, handle)	Add or modify dialog variables for an existing custom hud element ( int PlayerID /*-1 means everyone*/, string ElementID, table DialogVariables )
CustomUI.DynamicHud_SetVisible 	void DynamicHud_SetVisible(int, string, bool) 	Toggle the visibility of an existing custom hud element ( int PlayerID /*-1 means everyone*/, string ElementID, bool Visible )
=== GameUI.SetMouseCallback ===
The GameUI.SetMouseCallback API can be used to register a function that is called before the main gameplay code processes the mouse. Dota 2 Workshop Tools/Panorama/GameUI_SetMouseCallback_Example This page contains an example of how to use this functionality.
== Common Mistakes ==
You may encounter these mistakes when writing XML, CSS and Javascript in Panorama:
Relevant Area	Error 	Solution
hud.xml 	Compile error "Found duplicate panel description"	There must only be one panel without an ID in the <root> element
game_info.xml	Compile error "Found duplicate panel description"	There must only be one panel without an ID in the <root> element
== Panorama Examples ==
* Custom Timer (Adds a WC3 like timer panel)
* Custom Hero Selection (Pick Screen)
* Simple Panel Animations
Category:Panorama Category:Dota 2 Workshop Tools