[image: BasicState]

BasicState is a really simple key-value based state management solution. It makes use of BindableEvents to allow your project to watch for changes in state, and provides a simple but comprehensive API for communication with your state objects. Think Rodux, but easier!

Installation

Rojo

You can use git submodules to clone this repo into your project's packages directory:

$ git submodule add https://github.com/csqrl/BasicState packages/BasicState

Once added, simply sync into Studio using the Rojo plugin.

0.5.x

Download/clone this repo on to your device, and copy the /src directory into your packages directory.

Wally

Add BasicState to your wally.toml and run wally install

[package]
name = "user/repo"
description = "My awesome Roblox project"
version = "1.0.0"
license = "MIT"
authors = ["You (https://github.com/you)"]
registry = "https://github.com/UpliftGames/wally-index"
realm = "shared"

[dependencies]
BasicState = "csqrl/BasicState@^0.2.6"

$ wally install

Roblox-TS (unofficial)

While this package doesn't officially support TypeScript, bindings are available under the @rbxts/basicstate package, which can be installed using npm or yarn.

$ npm i @rbxts/basicstate
$ yarn add @rbxts/basicstate
$ pnpm add @rbxts/basicstate

TypeScript bindings are provided by @tech0tron. Please file any issues for the npm package over on their repo.

Manual Installation

Grab a copy from the Roblox Library (Toolbox), or download the latest .rbxm/.rbxmx file from the releases page and drop it into Studio.

Usage

Here's a quick example of how BasicState can be used:

local BasicState = require(path.to.BasicState)

local State = BasicState.new({
    Hello = "World"
})

State:GetChangedSignal("Hello"):Connect(function(NewValue, OldValue)
    print(string.format("Hello, %s; goodbye %s!", NewValue, OldValue))
end)

State:SetState({
    Hello = "Roblox"
})

--[[
    Triggers the RBXScriptConnection above and prints
    "Hello, Roblox; goodbye World!"
--]]

Usage with Roact:

-- Store.lua
local BasicState = require(path.to.BasicState)

local Store = BasicState.new({
    Hello = "World"
})

return Store

-- MyComponent.lua
local Roact = require(path.to.Roact)
local MyComponent = Roact.Component:extend("MyComponent")

local Store = require(script.Parent.Parent.Store)

function MyComponent:render()
    return Roact.createElement("TextButton", {
        Text = string.format("Hello, %s!", self.state.Hello),
        --> Displays "Hello, World!"

        [Roact.Event.MouseButton1Click] = function()
            Store:SetState({ Hello = "Roblox" })
            --> Will re-render and display "Hello, Roblox!"
        end
    })
end

-- Wrap the component with the BasicState store
return Store:Roact(MyComponent)

Documentation

Please refer to the documentation site for a full overview of the exported API and further examples on how to use this module.