Sift Roblox: руководство для начинающих по настройке Luau и основам API

Sift Roblox — библиотека для разработчиков, предназначенная для работы с неизменяемыми данными в Luau и roblox-ts. Это не игровое приключение Roblox, не система персонажей и не механика прогрессии. Вместо этого библиотека предоставляет создателям вспомогательные функции для обновления массивов, словарей и множеств без непосредственного изменения исходных данных.

Проект во многом основан на библиотеке Llama, которая больше не поддерживается. Sift преследует похожую цель, но использует нативные типы Luau, переработанные тесты, сгенерированную документацию и встроенные определения типов TypeScript. Благодаря этим отличиям библиотека полезна для проектов, которым нужны предсказуемые обновления состояния или общие утилиты для работы с данными.

Основная идея проста: вместо изменения таблицы на месте создаётся обновлённый результат, при этом исходное значение сохраняется. Такой подход упрощает работу с данными инвентаря, настройками игрока, объектами конфигурации и реплицируемым состоянием.

Добавить Sift в проект разработки Roblox можно несколькими способами. Лучший вариант зависит от того, как ваша команда управляет зависимостями. Wally подходит для рабочих процессов с пакетами через командную строку, проекты roblox-ts могут использовать npm, а ручная установка удобна, если вы предпочитаете размещать модель непосредственно в Studio.

Согласно справочной документации, Sift доступен через Wally, Itch.io, Roblox Library и релизы на GitHub. В ней также отмечается, что проект является бесплатным и открытым, а страница на Itch.io может использоваться для добровольной поддержки.

Настройка Wally

В проекте Wally добавьте зависимость в раздел [dependencies] файла wally.toml. В документации используется следующий формат с заполнителем версии v0.x:

[dependencies]
Sift = "csqrl/sift@0.0.X"

Замените 0.0.X на нужную вам версию, затем выполните:

wally install

Храните выбранную версию в конфигурации проекта. Это упростит воспроизведение того же набора зависимостей на разных компьютерах и уменьшит путаницу, если новый минорный релиз изменит поведение.

Настройка roblox-ts

В документации указано, что Sift включает определения типов TypeScript и может быть установлен для roblox-ts с помощью:

npm install @rbxts/sift

Базовый импорт и операция со словарём могут выглядеть так:

import Sift from "@rbxts/sift"

const updated = Sift.Dictionary.merge(
  { a: 1, c: 2 },
  { b: 3, c: Sift.None }
)

Результатом, описанным в документации, является словарь, содержащий a: 1 и b: 3. Значение Sift.None удаляет существующую запись c во время объединения.

Ручная установка

Ручная установка означает получение копии из Roblox Library или релиза на GitHub и размещение её в Studio. Модель Sift также можно синхронизировать с помощью Rojo. Этот способ удобен для небольших экспериментов, однако командам следует записывать версию релиза и дату установки, чтобы будущими обновлениями было проще управлять.

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

Объединение словарей — полезный первый пример:

local Sift = require(path.to.Sift)

local original = {
    Coins = 100,
    Title = "Rookie",
}

local updated = Sift.Dictionary.merge(original, {
    Coins = 125,
    Title = Sift.None,
})

В этом примере возвращённый словарь может представлять следующее состояние. Значение Coins заменяется, а Title удаляется с помощью Sift.None. Точный путь импорта зависит от способа установки и структуры проекта, поэтому используйте путь, созданный вашим рабочим процессом управления зависимостями.

Sift поддерживает и Luau, и roblox-ts, но окружающий процесс разработки отличается. Пользователи Luau обычно работают непосредственно в Roblox Studio или в проекте, управляемом Wally. Пользователи roblox-ts пишут на TypeScript и компилируют код в совместимый с Roblox формат с помощью существующей цепочки инструментов.

В документации библиотеки подчёркивается, что Sift использует нативные типы Luau и не выполняет проверку типов во время выполнения, которая ранее была связана со старым подходом на основе зависимостей. Это означает, что ответственность за корректность типов по-прежнему лежит на разработчике.

Выбор подходящей отправной точки

Выберите прямой Luau, если вы изучаете скриптинг Roblox или хотите кратчайший путь от Studio к рабочему примеру. Выберите roblox-ts, если ваш проект уже использует TypeScript и npm. Не меняйте язык только ради использования Sift: библиотека рассчитана на оба рабочих процесса.

Разработчикам на Luau следует обращать внимание на разницу между статическими подсказками и поведением во время выполнения. Нативные типы помогают описывать предполагаемые значения, но некорректные данные всё равно могут привести к ошибкам выполнения, если функции получают неожиданный ввод.

Разработчикам на roblox-ts определения типов могут улучшить подсказки редактора и упростить поиск API. Однако скомпилированный код всё равно нуждается в тестировании на уровне проекта, особенно если данные поступают от игрока, из сохранений, по сети или из внешних систем.

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

Распространённые ошибки

• Изменение исходной таблицы после создания результата Sift: это может усложнить отслеживание истории состояния.
• Использование функции массива для данных словаря: выбирайте API на основе типа коллекции, а не только желаемого результата.
• Предположение, что заморозка исправляет плохие данные: функции заморозки ограничивают изменения, но не проверяют содержимое коллекции.
• Игнорирование вложенных структур: поверхностная и глубокая заморозка имеют разные эффекты.
• Обновление зависимостей v0.x без тестирования: увеличение минорной версии может содержать ломающие изменения.
• Отсутствие документации проекта: записывайте способ установки Sift и версию, которую ожидает проект.

Для справки используйте официальную страницу документации Sift, чтобы ознакомиться с примечаниями по установке, рекомендациями по стабильности v0.x и доступными утилитами коллекций. Сохраните эту ссылку в заметках проекта рядом с конфигурацией зависимостей.

Sift — практичный вариант для разработчиков, которым нужны структурированные неизменяемые обновления в проектах Roblox. Начните с одного типа коллекции, используйте способ установки, соответствующий вашему рабочему процессу, и рассматривайте обновления v0.x как изменения, требующие тестирования.