Что это вообще такое?

Песочница это штука, в которой запускаются ваши скрипты. С точки зрения кода это класс, от которого наследуются все пользовательские скрипты и у которого есть некоторое количество контроля над ними.

Зачем она нужна?

Хранит в себе состояние между запусками

Когда вы создаете какое-то свойство или службу, отрисовываете картинку на экране или распознаете текст, то во избежание многократного создания одного и того же, песочница сохраняет и переиспользует данные от предыдущих запусков. Это увеличивает производительность и делает написание скриптов более простым

Подчищает за скриптом мусор

Когда скрипт закончил работу, неплохо было бы убраться за собой - освободить память, стереть надписи на экране и т.п. Но убираться не любит никто, поэтому пускай лучше за нами подчищают роботы. Однако, не все, что создают скрипты можно подчистить в автоматическом режиме. Об этом будет в отдельной статье про управление ресурсами.

Предоставляет набор базового функционала

Чтобы было проще жить, в абсолютно любом скрипте по умолчанию присутствует набор неких базовых сервисов - возможность писать логи, возможность работы с файлами программы и т.п. Однако, во избежание накопления лишнего веса, этот функционал очень и очень ограничен. Предполагается, что пользователь пользуется методом 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); // проиграет звук