¶ Что это вообще такое?
Песочница это штука, в которой запускаются ваши скрипты. С точки зрения кода это класс, от которого наследуются все пользовательские скрипты и у которого есть некоторое количество контроля над ними.
¶ Зачем она нужна?
¶ Хранит в себе состояние между запусками
Когда вы создаете какое-то свойство или службу, отрисовываете картинку на экране или распознаете текст, то во избежание многократного создания одного и того же, песочница сохраняет и переиспользует данные от предыдущих запусков. Это увеличивает производительность и делает написание скриптов более простым
¶ Подчищает за скриптом мусор
Когда скрипт закончил работу, неплохо было бы убраться за собой - освободить память, стереть надписи на экране и т.п. Но убираться не любит никто, поэтому пускай лучше за нами подчищают роботы. Однако, не все, что создают скрипты можно подчистить в автоматическом режиме. Об этом будет в отдельной статье про управление ресурсами.
¶ Предоставляет набор базового функционала
Чтобы было проще жить, в абсолютно любом скрипте по умолчанию присутствует набор неких базовых сервисов - возможность писать логи, возможность работы с файлами программы и т.п. Однако, во избежание накопления лишнего веса, этот функционал очень и очень ограничен. Предполагается, что пользователь пользуется методом GetService<> чтобы добавить скрипту любые нужные ему возможности. Об этом чуть ниже
¶ Что там по коду
Давайте рассмотрим методы и свойства, которые есть у абсолютно любого скрипта
¶ Логгирование
IFluentLog Log { get; }
Почти любому скрипту на одном из этапов жизни нужно давать какую-то обратную связь - текущие значения переменных, отладочные сообщения и т.п.
Log отвечает именно за это. С его помощью можно писать сообщения как в файлы логов программы, так и в окошко Event Log.
У каждой строчки лога есть один из уровней: Debug, Info, Warn, Error
Чем выше уровень - тем важнее сообщение, Error самые важные. В Event Log вы можете регулировать от какого уровня показывать сообщения. По умолчанию от Info и выше
Log.Info("Hello!");
Log.Debug("Hello from debug level!");
¶ Любителям поспать
void Sleep(TimeSpan delay);
void Sleep(int delayMs)
Этот метод приостанавливает выполнение скрипта на указанное время. Внутри он использует Task.Delay.
Sleep(2000); //приостанавливаем скрипт на 2 секунды
Sleep(TimeSpan.FromMilliseconds(100)); //приостанавливаем на 100 миллисекунд
Если по какой-то причине программа попросит скрипт остановиться (к примеру, ауру со скриптом выгрузили), то
Sleepпрервется заранее и скрипт будет остановлен
¶ Dependency Injection
T GetService<T>()
Самый могучий метод в песочнице. Это связь вашего скрипта с внешним миром и возможность получить доступ к разным частям функционала программы.
Используя GetService вы можете запросить у программы ниточки, дергая за которые будете получать тот или иной эффект.
Вместо тысячи слов:
var sendInput = GetService<ISendInputUnstableScriptingApi>();
sendInput.MouseMoveTo(200, 100); // передвинет мышь в Х200 Y100
sendInput.MouseRightClick(); // тыкнет правую кнопку мыши
using PoeShared.Audio.Services; // важно указать! Так вы говорите, где именно искать эту службу. Для разных служб будет разным
var sound = GetService<IPlaySoundScriptingApi>();
sound.PlaySound(AudioNotificationType.Minions); // проиграет звук