Sift Roblox beginner guide: Luau Setup & API Basics

Sift Roblox is a developer library for working with immutable data in Luau and roblox-ts. It is not a playable Roblox experience, character system, or progression mechanic. Instead, it gives creators utility functions for updating arrays, dictionaries, and sets without directly mutating the original data.

The project is heavily based on the Llama library, which is no longer maintained. Sift follows a similar purpose while using native Luau types, reorganized tests, generated documentation, and built-in TypeScript typings. These differences make it useful for projects that need predictable state updates or shared data utilities.

The central idea is simple: rather than changing a table in place, create an updated result while preserving the original value. This pattern can make inventory data, player settings, configuration objects, and replicated state easier to reason about.

Sift can be added to a Roblox development project in several ways. The best choice depends on how your team manages dependencies. Wally is suited to command-line package workflows, roblox-ts projects can use npm, and manual installation works when you prefer to place the model directly into Studio.

The reference documentation identifies Sift as available through Wally, Itch.io, the Roblox Library, and GitHub releases. It also notes that the project is free and open source, while an Itch.io page may be used for optional sponsorship.

Wally Setup

For a Wally project, add the dependency to the [dependencies] section of wally.toml. The documented format uses a v0.x version placeholder:

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

Replace 0.0.X with the version you intend to use, then run:

wally install

Keep the selected version visible in your project configuration. This makes it easier to reproduce the same dependency set across machines and reduces confusion when a newer minor release changes behavior.

roblox-ts Setup

The documentation states that Sift includes TypeScript typings and can be installed for roblox-ts with:

npm install @rbxts/sift

A basic import and dictionary operation may look like this:

import Sift from "@rbxts/sift"

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

The documented result is a dictionary containing a: 1 and b: 3. The Sift.None value removes the existing c entry during the merge.

Manual Installation

Manual installation means obtaining a copy from the Roblox Library or a GitHub release and placing it into Studio. The Sift model can also be synced with Rojo. This route is approachable for small experiments, but teams should record the release version and installation date so future updates remain manageable.

The fastest way to understand Sift is to practice one immutable update at a time. Begin with a small dictionary, inspect the returned value, and confirm that the original table remains the reference value for your application logic.

A dictionary merge is a useful first example:

local Sift = require(path.to.Sift)

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

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

In this pattern, the returned dictionary can represent the next state. The Coins value is replaced, while Title is removed through Sift.None. The exact import path depends on the installation method and project structure, so use the path generated by your dependency workflow.

Sift supports both Luau and roblox-ts, but the surrounding development experience differs. Luau users typically work directly in Roblox Studio or a Wally-managed project. roblox-ts users write TypeScript and compile it into Roblox-compatible code through their existing toolchain.

The library documentation emphasizes that Sift uses native Luau types and does not perform the runtime type checking previously associated with the older dependency approach. This means type correctness remains an important responsibility for the developer.

Choosing the Right Starting Point

Choose direct Luau if you are learning Roblox scripting or want the shortest path from Studio to a working example. Choose roblox-ts if your project already uses TypeScript and npm. Avoid changing languages only to use Sift; the library is designed to fit either workflow.

For Luau developers, pay attention to the difference between static guidance and runtime behavior. Native types can help describe intended values, but incorrect data may still produce runtime errors when functions receive unexpected inputs.

For roblox-ts developers, typings can improve editor feedback and make APIs easier to discover. However, compiled code still needs project-level testing, especially when data comes from player input, saved data, networking, or external systems.

A beginner-friendly Sift workflow depends less on memorizing every function and more on keeping data ownership clear. Decide which system owns a value, create a new result for updates, and avoid mixing mutable and immutable patterns without a reason.

Common Mistakes

• Editing the original table after creating a Sift result: This can make state history difficult to follow.
• Using an array function for dictionary data: Select the API based on the collection type, not simply the desired result.
• Assuming freezing repairs bad data: Freeze functions restrict changes; they do not validate the contents of a collection.
• Ignoring nested structures: A shallow freeze and a deep freeze have different effects.
• Upgrading v0.x dependencies without testing: Minor version increments may include breaking changes.
• Skipping project documentation: Record how Sift is installed and which version your project expects.

For reference, use the official Sift documentation page to review installation notes, v0.x stability guidance, and the available collection utilities. Keep this link in your project notes alongside the dependency configuration.

Sift is a practical option for developers who want structured immutable updates in Roblox projects. Begin with one collection type, use the installation path that matches your workflow, and treat v0.x upgrades as changes that require testing.