scripting

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

ВАЖНО! Требует C#9 (или Unity >=2021.2).

ВАЖНО! Проверено на Unity 2021.3 (не зависит от нее) и содержит asmdef-описания для компиляции в виде отдельных сборок и уменьшения времени рекомпиляции основного проекта.

ВАЖНО! Не потокобезопасно в пределах одного экземпляра ScriptVm. Разные экземпляры ScriptVm не конфликтуют при работе в разных потоках.

ВАЖНО! Нет защиты от бесконечной рекурсии.

Социальные ресурсы

Официальный блог: https://leopotam.ru

Установка

В виде unity модуля

Поддерживается установка в виде unity-модуля через git-ссылку в PackageManager или прямое редактирование

Packages/manifest.json

"ru.leopotam.scripting": "https://gitverse.ru/leopotam/scripting.git",

В виде исходников

Код так же может быть склонирован или получен в виде архива со страницы релизов.

Прочие источники

Официальная работоспособная версия размещена по адресу https://gitverse.ru/leopotam/scripting, все остальные версии (включая nuget, npm и прочие репозитории) являются неофициальными клонами или сторонним кодом с неизвестным содержимым.

Интеграция в VSCode

Для подсветки синтаксиса можно установить плагин "vscode.vsix" - на вкладке расширений из контекстного меню в заголовке выбрать

Install from VSIX...

и указать путь до файла. После этого появится возможность выбора языка

ScriptVM

для корректной работы синтаксиса.

Основные понятия

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

Хост

- основное приложение, из которого будет выполнятся вызов функций скрипт-языка.

ВАЖНО! Язык является регистрозависимым.

Типы

Штатно поддерживаются 3 типа:

Number - float32-число с плавающей точкой. Научная запись числа не поддерживается.
String - набор utf8-символов. Строки ограничиваются одиночными кавычками за исключением случая, когда внутри требуется наличие одиночной кавычки - в этом случае допускается использование двойных кавычек.
Undefined - отсутствие данных.

Все новые типы должны реализовываться на хосте с предоставлением соответствующего апи.

Синтаксис

В качестве разделителя выражений используется перевод строки,

;

не используются в принципе (невозможно написать несколько выражений в одной строке).

Скрипт-функции

Являются основной атомарной единицей, которую можно выполнить, вызвав из хоста.

Синтаксис функции без параметров можно описать следующей конструкцией:

где

FunctionName

- произвольное уникальное имя, идентифицирующее функцию для дальнейшего вызова из других функций или хоста.

ВАЖНО! Допускается использование любых символов, за исключением
(){},"'
и пробела.

Синтаксис функции с параметрами:

где

a

и т.д - параметры, разделенные запятой. Если функция будет вызвана с меньшим количеством параметров, то недостающие будут инициализированы как

Undefined

Вызов функции выполняется следующим образом:

Хост-функции

Являются логическими блоками, предоставляемые хостом для их запуска из скрипта. Для работы с ними их сперва надо зарегистрировать (см. "Регистрация хост-функций")

Переменные

Для использования локальных переменных достаточно присвоить нужной значение через специальную конструкцию:

ВАЖНО! Область видимости локальных переменных всегда функция, вложенные блоки не создают новых областей видимости.

ВАЖНО! Для установки глобальных переменных вместо
set
следует использовать setGlobal.

Условное ветвление

Поддерживается ветвление с опциональным

else

-блоком:

ВАЖНО!
expr
должно быть числом, истина определяется его ненулевым значением.

Цикл

Поддерживается повторение блока кода нужное количество раз:

x - произвольное имя переменной-итератора, которая будет содержать актуальное значение итерации внутри тела цикла.
fromExpr - числовое выражение/константа, определяющее стартовое значение итератора.
toExpr - числовое выражение/константа, определяющее конечное выражение итератора (не включая его).

ВАЖНО! Итерации идут от
fromExpr
до toExpr, не включая toExpr. Значения округляются до целых, итерирование идет с шагом 1. Если fromExpr больше toExpr, то итерирование идет с шагом -1.

Принудительный выход

Поддерживается раннее прерывание потока выполнения:

Так же поддерживается прерывание потока выполнения во вложенных блоках:

Интеграция

Весь скрипт-код работает внутри экземпляра класса

ScriptVm

: код нужно загрузить, распарсить и запустить на выполнение.

Загрузка и парсинг

Скрипт-код хранится в виде исходников и может быть загружен по сети или с диска.

ВАЖНО! Если код не меняется, достаточно его загрузить один раз, а потом только вызывать нужные функции.

ВАЖНО! При загрузке нового кода старый выгружается.

Запуск функции

Запускать можно именованные как хост-, так и скрипт-функции, но не отдельные выражения. Скрипт:

Загрузка, парсинг и запуск:

Вызов возвращает результат работы функции и возникшую ошибку, если она произошла.

Запуск функции с параметрами

В функцию можно передавать параметры, порядок их добавления соответствует порядку аргументов:

ВАЖНО! После передачи списка аргументов в метод
Run()
он становится невалидным и его нельзя использовать повторно!

Регистрация хост-функций

В скрипт-языке нет штатных хост-функций, по сути код работает в полностью изолированной пустой песочнице. Для добавления функционала, доступного внутри скрипт-языка, его следует зарегистрировать в виде хост-функции. Скрипт:

Запуск:

ВАЖНО! Хост-функции должны быть зарегистрированы до загрузки кода, иначе парсер не сможет найти их.

ВАЖНО! Внутри хост-функций нельзя делать вызовы других функций в текущем экземпляре
ScriptVm
через ScriptVm.Run().

ВАЖНО! Внутри хост-функций нельзя делать выгрузку старого и загрузку нового скрипт-кода в текущий экземпляр
ScriptVm
через ScriptVm.Unload() / ScriptVm.Load().

Лицензия

Расширение выпускается под лицензией MIT-ZARYA, подробности тут.