Charm

Charm v0.11 introduced breaking changes. Key migration points include:

1. API Renames & Changes:
   • peek() $\rightarrow$ untracked()
   • atom(value, options) $\rightarrow$ atom(value, equalityFunction)
   • computed(getter, equality) $\rightarrow$ computed(getter) (the callback now receives the previous value for manual equality checks).
   • Removed the cleanup argument from effect callbacks.
2. Charm Sync: Modules now act as singletons. Use CharmSync.client or CharmSync.server directly.
3. Strict/Frozen Flags: In Roblox Studio, strict (errors on yielding in effects/signals) and frozen (deeply freezes tables in signals) are enabled by default.
4. Nested Effects: Effects created inside another effect are now automatically cleaned up when the parent re-runs or is disposed. To prevent this, wrap the inner effect in untracked(). You can temporarily disable this via flags.trackInnerEffects = false.

Charm uses a fine-grained reactivity model to manage game state. The core building blocks are:

• Signals: Reactive state containers that hold values. You interact with them via a getter and a setter.
• Effects: Code blocks that re-run automatically whenever the signals they access change.
• Computed Signals: Memoized functions that derive new values from other signals. They only re-calculate when their dependencies change.

Example: Reactive Todo List

This example demonstrates creating a reactive UI where a list of todos is observed, and each todo item is represented by a TextLabel that updates its text and visibility based on a search query.

local getTodos, setTodos = signal({} :: { string })
local getQuery, setQuery = signal("")

-- observe reacts to changes in the getTodos signal
observe(getTodos, function(todo: string, index: number)
	local instance = Instance.new("TextLabel")

	-- getText is a computed signal that only re-runs if the specific todo at this index changes
	local getText = computed(function()
		return getTodos()[index] or ""
	end)

	-- effect re-runs whenever getText() or getQuery() changes
	effect(function()
		instance.Text = getText()
		instance.Visible = string.match(getText(), getQuery()) ~= nil
	end)

	instance.LayoutOrder = index
	instance.Size = UDim2.new(1, 0, 0, 40)
	instance.Parent = screenGui

	-- The return function acts as a cleanup callback when the item is removed from the list
	return function()
		instance:Destroy()
	end
end)

setTodos({ "Buy milk", "Buy eggs", "Play Roblox" })
setQuery("Buy")

Charm Sync allows you to replicate state from the server to clients using signals, atoms, or computed values.

Workflow

1. Server: Define state in a store. Use server.addSignalsToClient to subscribe players to specific signals. Use server.connect to define how updates are transmitted (e.g., via a RemoteEvent).
2. Client: Define local writable signals. Use client.addSignals to map server keys to these local setters. Use client.patch to apply incoming updates from the server.

Important: Key Uniqueness

On the server, every player must have the same key for global signals. For player-specific signals, you must use a unique key (e.g., using player.UserId) to avoid collisions and warnings. If two players are assigned different signals for the same key, Charm will emit a warning.

-- SERVER SETUP
playerReadyEvent.OnServerEvent:Connect(function(player)
	server.addSignalsToClient(player, {
		status = store.getStatus,
		-- Use unique keys for player-specific data
		[`inventory-{player.UserId}`] = computed(function()
			return store.getInventories()[player.Name]
		),
	})
end)

server.connect(function(player, updates)
	syncEvent:FireClient(player, updates)
end)

-- CLIENT SETUP
local getInventory, setInventory = signal({} :: Inventory)

client.addSignals({
	status = store.setStatus,
	[`inventory-{Players.LocalPlayer.UserId}`] = setInventory,
})

syncEvent.OnClientEvent:Connect(function(updates)
	client.patch(updates)
end)