Напишите свой первый скрипт JavaScript для GraalVM (2026)

Напишите свой первый скрипт JavaScript для GraalVM

Написание первого скрипта JavaScript для GraalVM включает в себя три небольших шага: регистрацию скрипта в точке входа хоста, привязку его к событию или модулю и сохранение в папку скриптов, чтобы движок мог его загрузить. Движок работает на базе GraalVM Polyglot API, поэтому скрипт является настоящим JavaScript и перезагружается без перекомпиляции какого-либо Java-кода.

Что вам понадобится в первую очередь

Программа-хост, которая встраивает движок. Хост поставляется с GraalVM JavaScript, предоставляет набор объектов для вызовов скриптами и отслеживает папку со скриптами. GraalVM вам устанавливать не нужно; он включен в хост. Вы пишете обычный JavaScript для объектов, которые предоставляет хост.

Понимание того, что эти объекты представляют, полезно, но для начала вам не потребуется писать ни строчки на Java. Если вы раньше писали на JavaScript, схема вам будет знакома: хост действует как библиотека, которую вы импортируете, и вы используете её для доступа к внутренним компонентам программы.

Три шага

1. Найдите папку со скриптами

   Хост загружает скрипты из известной директории при запуске. Точный путь можно найти в документации хоста. Обычно это папка scripts/ в директории установки.

2. Создайте файл сценария

   Создайте новый файл .js в этой папке. Хост обнаружит его при следующей загрузке скриптов, либо при запуске, либо при выполнении команды перезагрузки, если она поддерживается.

3. Зарегистрироваться и подключиться

   Внутри файла зарегистрируйте скрипт с точкой входа хоста, затем подключите поведение к событию или определите модуль, который распознает хост.

Вот и всё. Сохраните файл, перезагрузите, и скрипт заработает. Без этапа сборки, без компиляции, без ожидания. Просто редактируйте и перезагружайте.

Минимальный пример

Большинство хостов предоставляют скрипту одну точку входа для регистрации и несколько прокси-объектов, которые связывают JavaScript с программой. Точные имена зависят от хоста, но структура одинакова. Первый скрипт обычно просто объявляет о себе и реагирует на одно событие:

// Register the script with the host.
script.register({
  name: "hello-world",
  version: "1.0.0",
});
 
// React to an event the host exposes.
script.on("enable", () => {
  client.print("Hello from my first script.");
});

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

Горячая перезагрузка во время работы

Сохраните файл и перезагрузите скрипты (или перезапустите хост, если он не поддерживает живую перезагрузку). Изменения вступают в силу без пересборки. Этот быстрый цикл — главная причина использования скриптов вместо компиляции мода: скрипт перезагружается за секунды, в то время как скомпилированный мод необходимо пересобрать и перезапустить.

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

Что могут и чего не могут делать скрипты

Скрипт может вызывать объекты, которые предоставляет хост, и ничто больше. Хост объявляет, какие классы и методы скрипты могут затрагивать, через белый список доступа хоста GraalVM Polyglot, а по умолчанию доступ запрещён. Это обеспечивает безопасность и предсказуемость скриптов. Если нужный вам объект не предоставлен, хост должен добавить его; вы не можете обойти белый список со стороны скрипта.

Это особенность, а не ошибка. Это означает, что скрипты не могут случайно (или злонамеренно) нарушить работу хоста, вызывая внутренние методы или обращаясь к объектам, к которым им не следует обращаться. Это также означает, что разработчики хоста имеют четкий контроль над тем, что поддерживается, а что нет.

Часто задаваемые вопросы