charm/README.md

Charm

Atomic state management for Roblox.
npm package →

Charm is a Roblox state management library, inspired by Jotai. Designed to be an alternative to Reflex, Charm aims to bring an atomic and composable approach to your game's state.

Note

Charm is incomplete and not ready for use.

📦 Setup

TypeScript

Install Charm through your package manager of choice.
React is optional, but highly recommended.

npm install @rbxts/charm
yarn add @rbxts/charm
pnpm add @rbxts/charm

Wally

Add littensy/charm to your wally.toml file.

[dependencies]
Charm = "littensy/charm@VERSION"

📚 Documentation

Core

atom(state)

derive(...atoms, combiner)

subscribe(atom, listener)

observe(atom, observer)

split(atom, keyExtractor?)

Atom

Atom(state?)

Atom.get(selector?)

Atom.set(state)

Atom.memo(equalityFn)

Atom.readonly()

Atom.writable(onSet?)

Atom.named(label)

Atom.unmount()

React

useAtom(atom, selector?)

useAtomState(atom)

useSetAtom(atom)

Sync

sync.client(options)

Client.sync(payload)

sync.server(options)

Server.onSync(callback)

Server.hydrate(player)

🚀 Examples

Counter atom

import { atom, derive, subscribe } from "@rbxts/charm";

const counterAtom = atom(0);
const doubleCounterAtom = derive(counterAtom, (counter) => counter * 2);

subscribe(doubleCounterAtom, (value) => {
	print(value);
});

counterAtom(1);
counterAtom((count) => count + 1);

Counter component

import React from "@rbxts/react";
import { useAtom } from "@rbxts/charm";
import { counterAtom } from "./counter-atom";

function Counter() {
	const [count, setCount] = useAtom(counterAtom);

	return (
		<textlabel
			Text={`Count: ${count}`}
			Size={new UDim2(0, 100, 0, 50)}
			Event={{
				Activated: () => setCount(count + 1),
			}}
		/>
	);
}

🙋 Concerns

In Jotai, atom() returns an atom config, and its state is managed entirely by the Provider. However, in Charm, atom() returns something closer to a store, and its state is managed by the atom itself.

Charm does this for simplicity in use cases outside of React, but this might go against Jotai's focus on pure functional programming. More insight is needed to determine if this is a good idea.

---

Charm is released under the MIT License.