Документация Sift для Roblox: руководство по настройке и шаблоны API

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

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

Хорошей отправной точкой является репозиторий Sift на GitHub. В нем содержатся инструкции по установке, информация о релизах, примеры и ссылки на сгенерированную документацию.

Для чего лучше всего подходит Sift

Sift особенно полезен, когда код регулярно преобразует структурированные данные, но вы не хотите, чтобы каждая система изменяла одну и ту же ссылку на таблицу. Распространенные примеры:

• Создание нового профиля игрока из нескольких источников данных.
• Объединение настроек по умолчанию с сохраненными предпочтениями.
• Удаление записей без вызова table.remove или ручного присваивания nil.
• Предсказуемое обновление состояния интерфейса.
• Совместное использование вспомогательных функций коллекций в кодовых базах Luau и roblox-ts.

Важный контекст проекта

Библиотека является утилитой с открытым исходным кодом, а не Roblox-игрой или игровой системой. Она не предоставляет карты, персонажей, боевые механики, задания или функции прогрессии. Ее задача — помогать разработчикам структурировать и преобразовывать данные внутри проектов Roblox.

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

Sift можно добавить в проект Roblox через Wally, roblox-ts или вручную. Выберите один способ и придерживайтесь единой структуры зависимостей во всей команде. Смешивание методов установки без четкой причины может усложнить отслеживание версий и развертывание.

Сравнение способов установки

Настройка Wally

В проекте на основе Wally добавьте Sift как зависимость в wally.toml:

[dependencies]
Sift = "csqrl/sift@x.x.x"

Замените x.x.x версией, выбранной для проекта. Затем выполните:

wally install

После установки убедитесь, что пакет появился в ожидаемом расположении, а сопоставление Rojo в проекте включает путь к зависимости. Точная структура папок зависит от шаблона проекта, поэтому проверяйте сгенерированное дерево, а не предполагайте, что во всех репозиториях используется одинаковая структура.

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

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

npm install @rbxts/sift

Простое объединение словарей может выглядеть так:

import { Dictionary, Sift } from "@rbxts/sift"

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

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

Операции со словарями являются наиболее практичной отправной точкой для многих систем Roblox. Словарь — это таблица «ключ-значение», например профиль, содержащий валюту, настройки и разблокированный контент. При неизменяемых обновлениях каждая операция создает новое значение вместо изменения общей таблицы на месте.

Распространенные цели преобразований

Маркер Sift.None особенно полезен в коде, использующем объединение. В приведенном в документации примере объединение { a: 1, c: 2 } с { b: 3, c: Sift.None } создает { a: 1, b: 3 }. Удаление становится частью преобразования, а не отдельным шагом изменения данных.

const base = {
  displayName: "Builder",
  soundEnabled: true,
  tutorialSeen: true
}

const next = Dictionary.merge(base, {
  soundEnabled: false,
  tutorialSeen: Sift.None
})

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

Почему важно сохранять входные данные

Прямая мутация может создать скрытую связанность:

profile.Coins += 50

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

Неизменяемый подход делает переход состояния более осознанным:

local updatedProfile = Dictionary.merge(profile, {
    Coins = profile.Coins + 50,
})

Точный импорт модуля зависит от структуры проекта. Главное — вычислить updatedProfile как новое значение, а затем передать его системам, которым требуется обновленное состояние.

Делайте преобразования небольшими

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

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

Sift предназначен для поддержки рабочих процессов Luau и roblox-ts. Концептуальный API остается похожим, но окружающие инструменты отличаются. В проектах Luau обычно используются Wally и Rojo, а проекты roblox-ts используют npm и компиляцию TypeScript.

Выбор между Luau и TypeScript

Тестирование неизменяемого поведения

Полезный тест должен проверять и результат, и исходные входные данные:

local original = {
    Coins = 100,
    Rank = 2,
}

local updated = Dictionary.merge(original, {
    Coins = 150,
})

assert(updated.Coins == 150)
assert(original.Coins == 100)

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

Зависимость является частью технической поверхности вашего проекта. Перед использованием Sift в новой производственной системе изучите активность репозитория, историю релизов, лицензию, доступность пакета и совместимость с текущим набором инструментов Roblox.

Контрольный список проверки зависимости

Практические инженерные правила

1. Не изменяйте общее состояние случайно. Рассматривайте таблицы профилей и конфигурации как значения, которые следует намеренно заменять.
2. Сохраняйте четкие границы пакетов. Утилитарная библиотека должна преобразовывать данные, а системы сохранения и сетевого взаимодействия — отвечать каждая за свою область.
3. Проверяйте данные на границах. Статические типы не гарантируют, что сохраненные данные или удаленный ввод имеют ожидаемую структуру.
4. Предпочитайте явные промежуточные значения. Такие имена, как mergedDefaults, playerSettings и nextProfile, упрощают проверку преобразований.
5. Тестируйте поведение удаления. Отсутствующий ключ, значение nil и Sift.None могут иметь разные значения в операции объединения.
6. Документируйте выбранную версию. Это особенно важно, если проект будут сопровождать участники, которые не выбирали исходную зависимость.

Рекомендуемая структура документации

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