Справочник API Roblox Engine: классы, методы и события

Где находится Engine API Reference и как в нём искать

Engine API Reference — это официальная справка по объектам и функциям движка Roblox: классы, типы данных, перечисления, свойства, методы, события и колбэки. В ней вы находите точные названия и ограничения, чтобы код в Studio работал предсказуемо.

Чаще всего вы начинаете с поиска по названию: сервиса (DataStoreService), объекта (RemoteEvent) или типа (RBXScriptSignal). Если вы не знаете имя, ищите по задаче: например, 'remote' для общения клиента и сервера, или 'datastore' для сохранений.

• Ищете объект в сцене или в Explorer — сначала находите его класс, потом открываете страницу класса в справочнике.
• Ищете 'как вызвать' — почти всегда это метод (Method) на странице класса.
• Ищете 'когда срабатывает' — почти всегда это событие (Event).

Быстрый способ найти нужное

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

1. Назовите объект словами: 'сохранение', 'чат', 'ввод', 'анимация', 'сеть'.
2. Попробуйте угадать сервис: например, 'сохранение' почти всегда ведёт к DataStoreService.
3. Откройте страницу класса и пролистайте до нужного блока: Properties, Functions/Methods, Events, Callbacks.
4. Проверьте, где это работает: на сервере, на клиенте или везде. Если перепутать контекст, код не сработает.

Если вы часто прыгаете между объектом в Studio и справкой, держите под рукой Roblox Studio и окно Explorer: там видно класс выделенного объекта и его место в дереве.

Как читать страницу класса: свойства, методы, события, колбэки

Страница класса — это карта возможностей объекта. Обычно там есть:

• Properties — значения, которые можно читать/менять (например, включено ли что-то, текущий режим, имя).
• Methods/Functions — действия, которые вы вызываете (например, отправить событие, получить хранилище, сделать запрос).
• Events — события, к которым вы подключаетесь через RBXScriptSignal (например, 'кто-то нажал', 'что-то изменилось').
• Callbacks — свойства-обработчики, куда вы присваиваете функцию (часто встречается у RemoteFunction).

Главная ошибка новичка — видеть слово 'Event' и пытаться вызвать его как функцию. События не вызывают; на них подписываются. А колбэк не 'подключают'; ему присваивают обработчик.

Вижу в справке	Что это значит	Что делать в коде
Event	Сигнал, который срабатывает при событии	Подписаться (Connect/Once) и обработать параметры
Method/Function	Действие, которое вы вызываете сами	Вызвать метод у объекта
Callback	Место для вашей функции-обработчика	Присвоить функцию свойству колбэка

Событие и колбэк: в чём разница

Коротко о разнице:

• Событие (RBXScriptSignal) может иметь много слушателей и срабатывает, когда движок или другой код 'пожарил' событие.
• Колбэк обычно один: вы задаёте функцию, и движок вызывает её в нужный момент (типичный пример — обработчик у RemoteFunction).

Если в документации написано, что что-то 'fires' — это почти всегда событие. Если написано 'assign a function' или показано свойство вида OnServerInvoke — это колбэк.

Пометки на странице: контекст, ограничения, устаревание

На страницах API часто встречаются пометки и примечания. Их стоит читать раньше, чем копировать пример.

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

Если поведение не совпадает с ожиданиями, сначала перепроверьте: где выполняется ваш код (Script или LocalScript), и есть ли ограничение по контексту на странице API.

База: Instance, дерево объектов и сервисы

Почти всё в Roblox — это объекты, унаследованные от Instance. Это базовый класс, от которого строится иерархия объектов в дереве игры.

В практике это означает: вы работаете с объектами через их свойства и методы, а реагируете на изменения через события.

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

Сервисы надёжнее получать через game:GetService. Так вы меньше зависите от того, как сервис отображается в дереве и как он называется.

Почему почти всегда стоит использовать game:GetService

Если вы пишете учебные примеры, может казаться, что можно просто обращаться к сервисам как к детям объекта game. Но на практике GetService удобнее и стабильнее:

• Код становится одинаковым во всех проектах: один шаблон доступа к сервисам.
• Вы явно фиксируете, какой именно сервис нужен.
• Легче читать чужой код: видно, что берётся именно сервис, а не случайный объект в дереве.

Мини-проверка для себя: если строка внутри GetService выглядит как название встроенной системы (Players, ReplicatedStorage, DataStoreService) — это сервис.

Где выполняется код: Script и LocalScript

Контекст исполнения зависит от типа скрипта. В общих словах: Script выполняется на сервере, а LocalScript — на клиенте.

Это важно для API: например, сетевые вызовы и события работают по-разному на разных сторонах, и многие проблемы начинаются с перепутанного контекста.

Если вы делаете	Где обычно код	Почему это важно для API
Логику правил игры, сохранения, античит	Script (сервер)	Сервер имеет доступ к DataStore и принимает решения
Интерфейс, локальные эффекты, ввод	LocalScript (клиент)	Клиент отвечает за UI и получает ввод игрока
Обмен данными	Обе стороны	Нужны RemoteEvent/RemoteFunction и валидация

События и сигналы: RBXScriptSignal и подключения

События в Roblox представлены типом RBXScriptSignal. Это объект-сигнал, на который можно подписаться функцией-слушателем. Когда событие происходит, движок вызывает всех подписчиков с параметрами события.

Сигналы есть у многих объектов: касание (Touched), изменение свойства, вход игрока, сетевые сообщения. В справочнике события обычно перечислены в блоке Events на странице класса.

Частая ошибка — подписываться на событие в месте, которое выполняется много раз (например, внутри цикла обновления или при каждом открытии UI). Это создаёт дублирующиеся подписки и приводит к 'двойным' срабатываниям.

Connect и Once: как подписываться без лишних ловушек

У события есть два базовых варианта подписки:

• Connect — подписка, которая остаётся активной, пока вы её не отключите.
• Once — подписка на одно срабатывание: удобна, когда нужно дождаться одного события и сразу остановиться.

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

Что происходит	Вероятная причина	Что сделать
Событие срабатывает по два раза	Вы подключили Connect повторно	Проверьте, где создаётся подписка; переносите подписку в одно место и отключайте старую
Утечки памяти/падение FPS со временем	Накопились подключения, которые никто не отключает	Сохраняйте подключения и отключайте их при завершении сценария
Нужно дождаться одного ответа	Connect не отключили после первого срабатывания	Используйте Once или отключайте Connect вручную

Сигналы изменения свойств: когда они удобнее цикла

У многих объектов есть удобный паттерн: событие 'свойство изменилось'. Оно полезно, когда вы хотите реагировать на конкретное свойство, а не опрашивать его в цикле.

Если вы подписываетесь на изменение свойства, проверяйте две вещи: правильно ли написано имя свойства (оно чувствительно к регистру) и не пытаетесь ли вы слушать свойство на стороне, где оно не меняется (например, серверное состояние в чисто клиентском скрипте).

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

Клиент ↔ сервер: RemoteEvent и RemoteFunction

Roblox разделяет выполнение на клиент и сервер. Клиент отвечает за локальный интерфейс и ввод, сервер — за правила игры, сохранения и итоговые решения. Чтобы обмениваться данными, используют RemoteEvent и RemoteFunction.

В справочнике RemoteEvent и RemoteFunction выглядят похоже, но их назначение разное: одно — сообщения, другое — запрос-ответ. Ошибка выбора приводит к задержкам, зависаниям или логике, которую легко сломать.

RemoteEvent: сообщения без ожидания ответа

RemoteEvent нужен, когда вы отправляете сообщение и не ждёте синхронного ответа. Это удобно для событий: 'нажал кнопку', 'попросил открыть дверь', 'сообщил о выборе в меню'.

• Клиент отправляет на сервер через FireServer.
• Сервер слушает через OnServerEvent.
• Сервер может отправлять клиенту (например, обновление UI или результат) отдельным сообщением.

Важно помнить деталь: когда клиент вызывает FireServer, обработчик на сервере получает первым параметром игрока-отправителя. Это помогает не передавать Player вручную и снижает риск подмены.

RemoteFunction: запрос-ответ и колбэки

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

Ключевая деталь: у RemoteFunction есть колбэк, которому вы присваиваете функцию-обработчик. Если пытаться 'подключиться' как к событию, ничего не произойдёт.

Задача	Что выбрать	Почему
Сообщить о действии игрока	RemoteEvent	Не нужно блокировать поток ожиданием ответа
Попросить сервер проверить и вернуть результат	RemoteFunction	Нужен ответ прямо сейчас
Передать много мелких обновлений (например, эффекты UI)	RemoteEvent	Проще контролировать частоту сообщений

Сетевая безопасность: что проверять на сервере

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

Если вы только начинаете, держитесь практичного мини-алгоритма валидации запросов клиента: кто отправил, что просит сделать, имеет ли право, и не выходит ли запрос за лимиты.

Что происходит	Вероятная причина	Что сделать
Игрок может 'выдать себе' предмет	Сервер принимает число/ID без проверок	Проверяйте право игрока и допустимые значения на сервере
Удалённые вызовы спамят и грузят сервер	Нет лимитов на частоту	Вводите ограничение частоты и очередь обработки
Логика зависит от UI клиента	Сервер принимает решение по состоянию интерфейса	Сервер хранит и проверяет состояние сам

Данные и внешние запросы: DataStoreService и HttpService

Два самых частых вопроса у новичков: как сохранить прогресс и как обратиться к внешнему сервису. За сохранения отвечает DataStoreService, а за web-запросы — HttpService.

Важно сразу зафиксировать: DataStore работает на сервере, и это нормально. Клиент не должен напрямую писать в хранилище. А HTTP-запросы по умолчанию выключены и включаются в настройках опыта.

DataStoreService: базовые принципы хранения

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

Что профессионально проверить перед первым сохранением:

• Код сохранения находится на серверной стороне (Script), а не в LocalScript.
• Ключи данных стабильны (например, построены на UserId игрока), иначе вы сами 'потеряете' прогресс.
• Сохранение не вызывается слишком часто (у DataStore есть ограничения на скорость запросов).

Бюджеты и ограничения DataStore: почему запросы тормозят

Если сохранения иногда не проходят или внезапно появляются задержки, часто причина не в 'баге', а в лимитах. DataStore выдаёт бюджет запросов по типам операций. Когда бюджет низкий, запросы начинают ожидать или отклоняться (throttle).

Что делать, если подозреваете лимиты:

1. Сведите количество запросов: собирайте изменения и сохраняйте пачками, а не по каждому шагу.
2. Разделите частые и редкие данные: не сохраняйте каждый кадр или каждую секунду.
3. Добавьте повтор с задержкой и логирование, чтобы видеть, когда именно начинаются задержки.

HttpService и Allow HTTP Requests: включение и частые ошибки

HttpService позволяет серверу отправлять HTTP-запросы во внешний мир (например, к вашему API или к сервису аналитики). Отправка запросов делается методами вроде RequestAsync, но сначала нужно включить доступ в настройках опыта.

Где включить: откройте Experience Settings и в разделе Security включите Allow HTTP Requests.

Типовые причины, почему запросы не работают:

Что происходит	Вероятная причина	Что сделать
Ошибка про отключённые HTTP requests	Allow HTTP Requests выключен	Включите настройку в Experience Settings и сохраните изменения
Запросы работают в Studio, но не в опубликованной игре	Настройка включена не для того места/опыта	Проверьте, что меняете настройки именно нужного опыта и версия опубликована
Сервер зависает на запросе	Запрос слишком долгий или внешний сервис не отвечает	Ставьте таймауты и обрабатывайте ошибки ответа

Важное: ответы внешних сервисов тоже нужно проверять. Не считайте, что внешний API всегда вернёт корректный JSON или код 200.

Secrets: как хранить ключи и почему это связано с HTTP

Если вы храните ключи доступа (например, токены внешних сервисов), не вставляйте их прямо в скрипт. Для этого используют Secrets: они отделяют секретные значения от кода и позволяют управлять доступом.

Есть практическая связка: чтобы пользоваться секретами в опыте, обычно требуется включить Allow HTTP Requests в настройках безопасности.

• Секреты помогают не светить токены в репозитории и ассетах.
• Скрипт получает секрет во время выполнения, а не хранит его в тексте.
• Доступ к секретам проще ограничивать и менять без правок логики.

Инструменты для отладки и профилирования

Когда API 'не работает', чаще всего проблема не в справочнике, а в месте, где выполняется код, или в ошибке в параметрах. Поэтому два первых инструмента — это логи и консоль.

Для чтения ошибок в Studio используйте окно Output и Developer Console. Они показывают сообщения, ошибки и полезные вкладки про сеть и память.

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

Output и Developer Console: где видеть ошибки и контекст

Что проверять сначала, прежде чем искать 'магическую настройку' в API:

1. Есть ли ошибка в Output (обычно она говорит, в какой строке и что именно сломалось).
2. Не идёт ли ошибка из другого скрипта (иногда вы чините не тот файл).
3. Если ошибка про сеть/HTTP/датастор — проверьте настройки безопасности и контекст (клиент/сервер).

Developer Console удобен тем, что даёт больше контекста: кроме логов, там есть технические вкладки, которые помогают увидеть, что происходит во время тестирования.

MicroProfiler: когда он нужен и как подходить к анализу

MicroProfiler — это инструмент, который помогает понять, где именно 'съедается' время кадра: скрипты, физика, рендер или другое.

Практичный подход: сначала убедитесь, что проблема воспроизводится стабильно, затем снимите профиль на коротком промежутке и ищите самый 'толстый' участок. Дальше уже возвращайтесь к коду или настройкам и проверяйте изменения по результату.

Как следить за изменениями API: ReflectionService и метаданные

Справочник Engine API большой и периодически обновляется. Для ручной работы обычно хватает поиска и страниц классов, но для инструментов (плагины, автодополнение, анализ проекта) полезна программная инспекция API.

Для этого существует ReflectionService: сервис, который возвращает сведения о классах движка и их членах (свойства, методы, события) в виде структур данных.

Идея простая: вместо того чтобы хранить огромный 'дамп' API внутри проекта, вы запрашиваете информацию у движка тогда, когда она нужна.

ReflectionService: для чего его используют

Что обычно делают с ReflectionService:

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

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

API dump: когда он нужен и почему это неудобно

До появления ReflectionService многие инструменты опирались на внешние дампы API. Такой подход всё ещё встречается, но у него есть минусы: файлы большие, их нужно обновлять, а иногда они создают лишние проблемы при публикации ассетов или модулей.

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

Частые ошибки: причина → что делать

Ниже — частые ситуации, когда вы открываете справочник, делаете «по инструкции», а в игре всё равно не работает. Логика простая: по признаку проблемы ищем типовую причину и проверяем первые шаги.

Ситуация	Вероятная причина	Что сделать
Метод или свойство из справочника не появляется в автодополнении	Вы используете не тот класс или переменная имеет другой тип	Проверьте класс объекта в Explorer и откройте страницу документации именно этого класса
Событие не срабатывает	Вы пытаетесь вызвать Event как функцию или перепутали сторону (клиент/сервер)	Проверьте, что вы подписались на событие и что скрипт выполняется в нужном контексте
RemoteEvent.OnServerEvent не срабатывает	Клиент не вызывает FireServer или используется другой экземпляр	Проверьте, что клиент обращается к тому же экземпляру RemoteEvent и что объект существует у клиента
RemoteFunction не возвращает ответ	Обработчик не назначен или код ожидает ответ там, где его не будет	Назначьте обработчик у RemoteFunction на нужной стороне и убедитесь, что он возвращает значение
Ошибка о отключённых HTTP requests	Параметр Allow HTTP Requests выключен	Включите настройку в Experience Settings и повторите тест
Сохранения выполняются нестабильно	Лимиты и бюджеты DataStore, слишком частые запросы	Сократите частоту запросов, сохраняйте пакетами и логируйте случаи снижения бюджета
Ошибки возникают, но не отображаются	Не открыто окно Output или выбран не тот режим тестирования	Откройте Output и Developer Console и проверьте сообщения во время запуска

Мини-словарь терминов

Короткие определения, чтобы легче читать справочник:

• Класс (Class) — тип объекта движка со списком свойств, методов и событий.
• Instance — базовый класс объектов в дереве игры; большинство объектов наследуются от него.
• Сервис (Service) — встроенный объект-менеджер, который даёт функциональность уровня игры и обычно существует в одном экземпляре.
• Свойство (Property) — значение, которое хранит объект и которое можно читать или менять (если разрешено).
• Метод/функция (Method/Function) — действие, которое вы вызываете у объекта.
• Событие (Event) — сигнал (RBXScriptSignal), который можно слушать через подписку.
• Колбэк (Callback) — свойство, куда вы присваиваете функцию, чтобы движок вызывал её в нужный момент.
• Контекст (Client/Server) — где выполняется код: на клиенте, сервере или в обоих местах.