Ru/Dota 2 Workshop Tools/Panorama/Javascript

Эта статья является «оторванной», на неё ссылается очень мало статей или в общем нет ссылок.
Вы можете помочь,  добавив ссылки на эту статью из других тематических статей.
January 2024

Panorama использует Javascript в качестве скриптового языка, позволяя пользовательскому интерфейсу динамически реагировать на действия пользователя и события игры. Код Javascript выполняемый в клиенте может взаимодействовать с кодом сервера пользовательской игры (реализованном в Lua.)

Javascript API

Panorama(en) JS API в основном расширенный вариант Scaleform ActionScript API.

Задокументировано: Dota 2 Workshop_Tools/Panorama/Javascript/API(en)

Рабочий процесс

Подключаем Scripts

Ваш Panorama XML может ссылаться на JS файлы в блоке 'scripts', или включать в себя Javascript в блоке 'script' (подходит только для не очень большого кода.)

<root>
	<scripts>
		<!--
			Это ссылка на script файл расположенного в:
			content/dota_addons/ADDON_NAME/scripts/custom_game/my_script_name.js
		-->
		<include src="file://{resources}/scripts/custom_game/my_script_name.js" />
	</scripts>
	<script>
		// Это встроенный Javascript в код (XML experts: Panorama automatically wraps your script block inside a CDATA section.)
		$.Msg( "Hello, world!" );
	</script>
	<Panel>
		<!-- (Иерархия Panel находится здесь.) -->
	</Panel>
</root>

(Данный script автоматически скомпилирован по адресу: game/dota_addons/ADDON_NAME/scripts/custom_game/my_script_name.vjs_c или может быть скомпилирован вручную с помощью resourcecompiler.)

Процесс перезагрузки

Когда panel перезагружается, связанный с ним javascript выполнится повторно. Это обычно приводит к заданному поведению, но иногда приводит к путанице. When iterating on a complicated UI, it's usually worth the trouble to ensure that your script is robust to being reloaded. Callbacks registered with the system for things like game events will automatically be ignored when they go stale - it's safe to re-register. However, if you're dynamically creating panels, consider checking to see if they're already there for a previous reload. A bit of careful checking can go a long way to improving your iteration speed.

Panels

Создание Panels

Мощным способом повторного использование частей вашего интерфейса, является динамически создаваемая панель. Например мульти-командная таблица результатов создаёт новую дочернюю панель для каждой команды, и в каждая командная панель создаёт новую дочернюю панель для каждого игрока. Таким образом интерфейс может адаптироваться под любое количество команд и игроков, с одной копией XML/CSS/JS для каждой концепции.

var parentPanel = $.GetContextPanel(); // корневая панель в текучем контексте XML
var newChildPanel = $.CreatePanel( "Panel", parentPanel, "ChildPanelID" );
newChildPanel.BLoadLayout( "file://{resources}/layout/custom_game/new_panel.xml", false, false );

Доступ к свойствам CSS из Javascript

К многим свойствам CSS можно обращаться из javascript с помощью MyPanel.style.property. Из-за синтаксического различия этих языков, их имена не являются идентичными в эквиваленте CSS (Так же в интернете), но легко выводимые: Слова разделенные дефисом преобразуются в равнозначный camelCase. Например background-color в CSS является style.backgroundColor в Javascript.

$ (Символ Доллар)

Несколько важных, глобальных процедур доступны через $ глобальный объект

JQuery-Like Selection

Как и с JQuery, вы можете найти в текущем контексте с помощью $( "#PanelID" ). Обратите внимание, что на данный момент имеются существенные ограничения: он может соответствовать только одной панели по ID. Если это не соответствует панели то возвращает null вместо пустого селектора, что может привести к неожиданным ошибкам в JS. (И отказ выполнения остальной части скрипта.)

$( "#MyLabel" ).text = "hello";

Msg

Для простой записи, используйте $.Msg() - поддерживает все типы Javascript и любое количество аргументов. (Будет печатать все аргументы последовательно на одной строке.)

// Напишет: Hello {"who":"world"}!
$.Msg( "Hello ", { "who": "world" }, "!" );

GetContextPanel

$.GetContextPanel() returns the root "context panel" that the script is running for. (Very similar to 'this' or 'self' in other languages.) This is the root panel of the XML that loaded the script.

<root>
	<script>
		$.GetContextPanel().SetHasClass( "context_panel", true ); // after this it will have both "context_panel" and "root_panel" classes
	</script>
	<Panel class="root_panel">
		<Label text="Hi" />
	</Panel>
</root>

Game APIs

Game Events

Javascript может зарегистрировать функцию на вызов когда игровое событие вызывается. Это работает для событий движка и нового Custom Game Events(en):

    function OnFoo( data ) { $.Msg( "foo_event: ", data ); }
    var handle = GameEvents.Subscribe( "foo_event_name", OnFoo );
    GameEvents.Unsubscribe( handle );

Custom Nettables

Custom nettables are a way to communicate persistent state from the server to clients. See: Dota 2 Workshop Tools/Custom Nettables(en)

Best Practices and Javascript Gotchas

"use strict"

Our example Javascript code employs the http://www.w3schools.com/js/js_strict.asp "use strict"(en) feature to increase safety, robustness, and sanity.

That Weird Anonymous Function Thing (IIFE)

In our example Javascript, you may see use of the http://getinstance.info/articles/javascript/immediately-invoked-function-expressions/ Immediately-invoked Function Expression (IIFE)(en) pattern.

(function () {
	$.Msg( "The panel associated with this javascript just got loaded or reloaded!" );
})();

Triple Equals

If you're familiar with C-family languages, you may be surprised to learn that Javascript has two equality operators: '==' and '==='

You can learn more about this https://developer.mozilla.org/docs/Web/JavaScript/Equality_comparisons_and_sameness here(en) or elsewhere on the web.

Variable Capture

If you're coming to Javascript from another language, you should know that nested functions capture their enclosing scope by reference, which can lead to unexpected results:

var closures_bad = [];
var closures_good = [];
function create()
{
	for (var i = 0; i < 5; i++)
	{
		closures_bad[i] = function()
		{
			$.Msg( "i = ", i );
		};
		closures_good[i] = (function( j ){return function()
		{
			$.Msg( "i = ", j );
		}}(i));
	}
}

function run()
{
	// prints "5 5 5 5 5" because loop variable 'i' is captured by reference above
	for (var k = 0; k < 5; k++)
	{
		closures_bad[k]();
	}
	// prints "0 1 2 3 4" because each value of loop 'i' is captured by a different function parameter 'j'
	for (var k = 0; k < 5; k++)
	{
		closures_good[k]();
	}
}

create();
run();

Misc

Panorama Javascript execution is handled by the Google V8 javascript engine.