{"id":"gamingguy84/flux","name":"flux","scope":"gamingguy84","platform":"roblox","description":"Idiomatic state replication package.","version":"0.2.0","latest":"0.2.0","versions":["0.1.9","0.2.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"data-oriented-house/lemonsignal":{"version":"^1.11.0","alias":"lemonsignal"},"ivasmigins/replica":{"version":"^0.1.0","alias":"replica"}},"integrity":"b7146463a41c10c04aabc734f50f47a5dcb57ac97b69fc386dafb86fc6c0ba41","likes":0,"downloads":0,"install":"forest install gamingguy84/flux","url":"https://forest.dev/p/roblox/gamingguy84/flux","files":"https://api.forest.dev/ai/package/roblox/gamingguy84/flux/files","readme":"<p align=\"center\">\r\n  <picture>\r\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://i.imgur.com/NTfLC8e.png\">\r\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"https://i.imgur.com/N9nF6vz.png\">\r\n    <img alt=\"Project banner\" src=\"images/image-light.png\">\r\n  </picture>\r\n</p>\r\n\r\nFlux is a lightweight Luau state layer for Roblox built on top of Replica. It gives you a schema-aware, proxy-based server state and a mirrored, event-driven client view for shared data.\r\n\r\n---\r\n\r\n## Features\r\n\r\n- Proxy-based server state with natural table syntax\r\n- Server-side schema validation for writes\r\n- Batched updates with `:Batch(...)`\r\n- Replica-backed replication to clients\r\n- Event-driven client signals for changes, descendants, arrays, and dictionaries\r\n- Simple `Get` and `OnReady` APIs for client-side reads\r\n\r\n---\r\n\r\n## Installation\r\n\r\nPlace Flux in a shared location such as ReplicatedStorage and require it from scripts on both sides:\r\n\r\n```lua\r\nlocal Flux = require(path.to.Flux)\r\n```\r\n\r\nThe module exposes two entry points:\r\n\r\n```lua\r\nlocal client = Flux.client\r\nlocal server = Flux.server\r\n```\r\n\r\n---\r\n\r\n## Server Example\r\n\r\n```lua\r\nlocal Flux = require(path.to.Flux)\r\nlocal server = Flux.server\r\n\r\nlocal state = server.new(\"PlayerState\", {\r\n    Schema = {\r\n        Health = true,\r\n        Stats = {\r\n            Damage = true,\r\n        },\r\n    },\r\n    Data = {\r\n        Health = 100,\r\n        Stats = {\r\n            Damage = 10,\r\n        },\r\n    },\r\n})\r\n\r\nstate.Health = 90\r\n\r\nstate:Batch(function()\r\n    state.Health = 80\r\n    state.Stats.Damage = 15\r\nend)\r\n\r\nstate:Destroy()\r\n```\r\n\r\n---\r\n\r\n## Client Example\r\n\r\n```lua\r\nlocal Flux = require(path.to.Flux)\r\nlocal client = Flux.client\r\n\r\nlocal state = client.OnNew(\"PlayerState\")\r\n\r\nstate:OnReady(function()\r\n    print(\"Health:\", state:Get({\"Health\"}))\r\nend)\r\n\r\nlocal healthSignal = state:GetChangedSignal({\"Health\"})\r\nhealthSignal:Connect(function(newValue, oldValue, path)\r\n    print(\"Health changed:\", newValue, oldValue, path)\r\nend)\r\n```\r\n\r\n---\r\n\r\n## API\r\n\r\n### Server\r\n\r\n```lua\r\nlocal server = Flux.server\r\n\r\nlocal state = server.new(Name: string, Params: {\r\n    Schema: {[string]: boolean | any},\r\n    Data: T? | {}\r\n})\r\n```\r\n\r\nMethods:\r\n\r\n```lua\r\nstate:Batch(callback)\r\nstate:Destroy()\r\n```\r\n\r\nThe server-side object is a proxy, so writes such as `state.Health = 100` are routed through the replica layer.\r\n\r\n### Client\r\n\r\n```lua\r\nlocal client = Flux.client\r\n\r\nlocal state = client.OnNew(Name: string)\r\n```\r\n\r\nMethods:\r\n\r\n```lua\r\nstate:OnReady(callback)\r\nstate:Get(path: {string})\r\nstate:GetChangedSignal(path)\r\nstate:GetDescendantsChangedSignal(path)\r\nstate:GetArrayInsertedSignal(path)\r\nstate:GetArrayRemovedSignal(path)\r\nstate:GetArrayChangedSignal(path)\r\nstate:GetDictionaryAddedSignal(path)\r\nstate:GetDictionaryRemovedSignal(path)\r\nstate:GetDictionaryChangedSignal(path)\r\n```\r\n\r\n---\r\n\r\n## How It Works\r\n\r\nFlux uses Replica as the replication transport. On the server, updates are written to a proxy-backed state object and forwarded to a Replica instance. On the client, the same Replica is observed and mirrored into a local state table. The result is a natural table-like API that still stays synced across the network.\r\n\r\n---\r\n\r\n## Limitations\r\n\r\n- Best suited for small-to-medium state trees rather than large ECS-style worlds\r\n- Server writes are validated against the provided schema\r\n- The client view is a snapshot of the currently replicated state and updates through change signals\r\n- The package assumes you are already using or are willing to use Replica as the transport layer\r\n","readmeTruncated":false}