Привет, мир!

Если хотите сразу перейти к практике, начните с живого примера — он особенно полезен, если вы только знакомитесь с миром C#.

А этот пример уже немного сложнее и ближе к тому, как всё устроено внутри EyeAuras.

Первый запуск — сообщение в журнале

Добавьте действие C# Script в ауру и вставьте в тело скрипта:

Log.Info("Привет, мир!");

Запустите скрипт кнопкой Run в его редакторе. В журнале скрипта должна появиться строка Привет, мир!. Дополнительный пакет или свой логгер здесь не нужен: Log предоставляет песочница. Для запуска действием ауры настройте триггер и список actions, как описано ниже.

Если вынесете код в обычный .cs-класс, передайте логгер явно — члены песочницы не становятся глобальными функциями C#. Законченный пример такого переноса есть в карте runtime.

Что такое скрипты?

С самого начала в программе была возможность писать собственный код на C#. В ранних версиях (примерно весной 2021 года) это было неудобно и местами болезненно, но всё же работало. Весной 2023 года вышла вторая версия, где появились такие возможности, как использование внешней IDE для написания кода, а сам скриптинг стал заметно мощнее. Например, стало возможно создавать полноценный пользовательский интерфейс на Blazor. По сути, это открыло путь к действительно сильным скриптам, хотя ограничений и «особенностей» всё ещё хватало.

В третьем поколении скриптов можно подключать внешние NuGet-пакеты и использовать API работающей программы. Runtime помогает с отменой и диагностикой, но не защищает произвольный код от любых сбоев.

Порог входа тоже стал заметно ниже: появились новые API, улучшилась диагностика и не только.

Что под капотом

Программа построена на платформе .NET. Это быстро развивающаяся платформа с высокой гибкостью и производительностью. Возможности языка определяются версией Roslyn в host и настройками проекта; сгенерированный экспорт помогает увидеть фактические зависимости вашей версии.

Каждый написанный вами скрипт компилируется через Roslyn. Большая часть головной боли, связанной с тем, как подключать файлы, что можно делать, а что нельзя, уже решена внутри самой программы. Поэтому вы можете сосредоточиться именно на логике скрипта.

С чего начать

Ниже — три основных поверхности запуска кода. Они используют песочницу.

1. C# Action

Самый простой вариант. Достаточно добавить действие "C# Script". Оно подчиняется тем же правилам, что и любые другие действия, поэтому для запуска нужно добавить триггер. Например, можно использовать Hotkey Is Active, назначить его на кнопку и запускать скрипт по нажатию или удержанию.

2. C# Trigger

Более сложный вариант — ваш скрипт будет выполняться через определённые интервалы времени. Предполагается, что где-то в коде вы будете возвращать true/false или null, чтобы активировать или деактивировать триггер. После этого к триггеру можно привязать действия, в том числе и скриптовые.

Сложность здесь в том, что такой скрипт работает постоянно и управляется только через Enabling Conditions. Поэтому код нужно писать аккуратнее: иначе легко получить ситуацию, когда ошибка в скрипте постоянно перехватывает управление мышью/клавиатурой или съедает всю доступную память на компьютере.

3. C# Overlay и WebUI

Поверхность скриптинга для своего UI. Помимо всего, что доступно в actions/triggers, WebUI позволяет создавать собственный пользовательский интерфейс: кнопки, переключатели, поля ввода и другие элементы.

Для отрисовки интерфейса используется технология Blazor, — это компонентная модель интерфейса в .NET. У самой технологии, конечно, есть свои минусы — идеальных решений не бывает, — но EyeAuras предоставляет инструменты, которые сглаживают эти проблемы. В итоге ваши возможности ограничены в основном только фантазией.

Ниже — несколько примеров различных форм, собранных на WebUI.

Сервисы

И сама программа, и её API построены вокруг подхода под названием Dependency Injection. Проще говоря, программа разделена на небольшие части, каждая из которых отвечает за свою задачу. Как в большом доме: кто-то варит кашу, кто-то штопает носки, а кто-то ничего не умеет, но всё равно существует.

У каждой такой сущности в этом доме есть имя. Например, если вы хотите двигать мышь, нужно обратиться к ISendInputUnstableScriptingApi и вызвать MouseMoveTo. Если нужно воспроизвести звук, используйте IPlaySoundScriptingApi.

Обязанности у сервисов разные, и, как и в жизни, знание правильных названий критично для успеха. В этой документации будут перечислены основные и самые полезные сервисы, но приводить вообще всё не имеет смысла — пакет NuGet EyeAuras.SDK помогает исследовать контракты. Доступность живых сервисов зависит от host и подключённых модулей; опциональные SDK могут требовать отдельных пакетов и регистрации.

Внешние зависимости

Если бы каждый программист каждый раз начинал с нуля, человечество до сих пор коллективно изобретало бы колесо. Поэтому скрипты полностью поддерживают внешние пакеты. В инфраструктуре .NET почти всё хранится в NuGet — и официальные, и неофициальные библиотеки.

Существует множество подборок полезных пакетов; начать можно, например, с этой. В скриптах можно подключить почти любой из них. Сейчас ещё есть некоторые исключения, но работа над этим продолжается.

Версию пакета указывайте явно. Например, в начале Script.csx:

#r "nuget: Newtonsoft.Json, 13.0.3"
using Newtonsoft.Json;

Log.Info(JsonConvert.SerializeObject(new { Hello = "World" }));

При доступном и совместимом пакете результат — JSON в журнале. Не каждый пакет совместим с host; ссылка даёт типы, но не регистрацию сервиса. Подробнее о зависимостях.

Основные контракты этой страницы сверены со срезом EyeAuras 20fd3d4, PoeEye 0e02c98. Точные API проверяйте по SDK/XML своей версии: пакет EyeAuras.SDK предоставляет контракты, а живые сервисы — работающий host.