State
The State class is used to manage state for anything. It can be used to store data for the game, UI, or any other feature.
Usage example
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
local connection: RBXScriptConnection = state.Changed:Connect(function(newState, prevState)
print(prevState, newState)
end)
state:Set("val", 11)
print(state:Length()) -- expect 3
state:Set(function(state)
state.val = 111
end)
state:Set({
val = 1111
})
state.val = 11111
state:Remove("val") -- Removes val from the state
state:Reset() -- Reset the state to the initial state
connection:Disconnect()
state:Destroy()
local success = pcall(function()
state:Set("val", 1)
end)
print("state destroyed:", not success) -- expect: state destroyed: true
Signals
State.Changed :: Signal.Signal<newState: T, prevState: T>
Signal that is fired when the state changes
Install with wally by adding the following to your wally.toml:
State = "dig1t/state@1.2.1"
Functions
new
Creates a new state instance
Length
State:Length() → numberReturns the size of the state if the state is a table.
Example:
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
print(state:Length()) -- expect 3
Get
State:Get(path: string | number?--
The path to the value to get. Leave empty to get the entire state
) → anyReturns the value at the given path. The path parameter can only be used if the state is a table.
Example:
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
print(state:Get("val")) -- expect 1
print(state:Get("nest.val")) -- expect 123123
-- True as the argument returns the entire state
print(state:Get()) -- expect { val = 1, time = tick(), nest = { val = 123123 } }
Push
State:Push(keyOrValue: any,--
The key of the pushed value or the value itself if the state is an array
value: any?--
The value to push
) → any--
The key of the pushed value
Pushes a new value to the state.
The state must be a table to use this method.
Example:
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
state:Push("val", 2)
print(state:Get("val")) -- expect 2
Reset
State:Reset() → ()Resets the state to the initial state
Example:
local state = State.new({
val = 1
})
state:Set("val", 2)
state:Reset()
state:Get() -- expect { val = 1 }
Set
State:Set(newState: T--
The new state value
) → ()Sets the state with a new value.
Example:
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
state:Set({
val = 1111
}) -- Change val to 1111
SetCallback
State:SetCallback(modifier: (T) → ()) → ()Sets the state with a new value.
The modifier function should NOT yield as it can cause issues or data loss.
This function should be used as a shortcut to modify the state.
For example
local value = state:Get()
value.number += 1
state:Set(value)
Turns into:
state:SetCallback(function(context)
context.number += 1
end)
Example:
type NumberState = {
val: number
}
local state: State.State<NumberState> = State.new({
val = 1
})
state:SetCallback(function(prevState: NumberState)
prevState.val = 111
end) -- Change val to 111
SetPath
State:SetPath(pathString: string,--
The path to set
value: any?--
The value to set
) → ()Sets the state with a new value
Example:
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
state:SetPath("nest.val", 11111) -- Change nest.val from 123123 to 11111
Remove
State:Remove(path: string | number--
The path to the value to remove
) → ()Removes a value from the state
Example:
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
state:Remove("val") -- Removes val from the state
state:Get() -- expect { time = tick(), nest = { val = 123123 } }
Destroy
CleanupState:Destroy() → ()Destroys the state
Example:
local state = State.new({
val = 1,
time = tick(),
nest = {
val = 123123
}
})
state:Destroy()
local success = pcall(function()
-- This should throw an error since the state object was destroyed
state:Set("val", 1)
end)
print('state destroyed?', not success) -- expect: true