{"id":"uxnknwn/jecs-util","name":"jecs-util","scope":"uxnknwn","platform":"roblox","description":"Reusable utilities for Jecs 0.11 and Roblox ECS projects","version":"0.1.0-alpha.4","latest":"0.1.0-alpha.4","versions":["0.1.0-alpha.1","0.1.0-alpha.2","0.1.0-alpha.3","0.1.0-alpha.4"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"ukendio/jecs":{"version":"^0.11.0","alias":"Jecs"}},"integrity":"b7a5a9e42fc4cc28faae0f13c5db99001f29d83dd179b7fe18715008400e10ac","likes":0,"downloads":0,"install":"forest install uxnknwn/jecs-util","url":"https://forest.dev/p/roblox/uxnknwn/jecs-util","files":"https://api.forest.dev/ai/package/roblox/uxnknwn/jecs-util/files","readme":"# jecs-util\n\nSmall utilities for Jecs 0.11.0 and Roblox ECS projects.\n\n## Requirements\n\n- Roblox\n- Luau\n- Jecs `0.11.0`\n\nThis package targets Jecs `0.11.0` only.\n\n## Installation\n\n### Wally\n\n```toml\n[dependencies]\njecs-util = \"uxnknwn/jecs-util@0.1.0-alpha.2\"\nJecs = \"ukendio/jecs@0.11.0\"\n```\n\nThen run:\n\n```bash\nwally install\n```\n\n### Pesde\n\n```bash\npesde add uxnknwn/jecs_util\n```\n\nPesde currently requires the underscore form in the package id, so the published Pesde name stays `uxnknwn/jecs_util`.\n\nThe package depends on Jecs `0.11.0`.\n\n## Import\n\nUse your project’s actual dependency paths:\n\n```luau\nlocal jecs = require(path.to.jecs)\nlocal jecsUtil = require(path.to[\"jecs-util\"])\n```\n\nThe exact Instance names can vary with dependency aliases.\n\n## Registry\n\n`registry` maps a category and key to a Jecs entity.\n\n```luau\nlocal world = jecs.World.new()\nlocal registry = jecsUtil.registry.new(world)\n\nlocal entity = world:entity()\nregistry:Define(\"Players\", 12345, entity)\n```\n\nBasic operations:\n\n```luau\nlocal entity = registry:Get(\"Players\", 12345)\nlocal exists = registry:Has(\"Players\", 12345)\nlocal removed = registry:Undefine(\"Players\", 12345)\n\nregistry:Delete(\"Players\", 12345)\nregistry:Clear(\"NPCs\")\nregistry:Clear()\n```\n\n## Collect\n\n`collect` turns a Roblox signal into a FIFO queue.\n\n```luau\nlocal event = Instance.new(\"BindableEvent\")\nlocal pop, connection = jecsUtil.collect(event.Event)\n\nevent:Fire(\"RoundStarted\", 10)\nevent:Fire(\"RoundEnded\", 20)\n\nlocal function processEvents()\n\twhile true do\n\t\tlocal eventName, duration = pop()\n\n\t\tif eventName == nil then\n\t\t\tbreak\n\t\tend\n\n\t\tprint(\"event:\", eventName, duration)\n\tend\nend\n\nprocessEvents()\n\nconnection:Disconnect()\nevent:Destroy()\n```\n\nTrailing `nil` values are preserved:\n\n```luau\nevent:Fire(\"A\", nil, \"C\", nil)\n\nlocal result = table.pack(pop())\nprint(result.n) -- 4\n```\n\n## API\n\n### `registry.new(world)`\n\nCreates an independent registry using a Jecs-compatible world.\n\n### `registry:Define(category, key, entity)`\n\nStores an entity under a category and key.\n\n### `registry:Get(category, key)`\n\nReturns the mapped entity or `nil`.\n\n### `registry:Has(category, key)`\n\nReturns whether a mapping exists.\n\n### `registry:Undefine(category, key)`\n\nRemoves and returns a mapping without deleting the entity.\n\n### `registry:Delete(category, key)`\n\nRemoves the mapping and deletes the entity from the world.\n\n### `registry:Clear(category?)`\n\nDeletes one category or every registered entity.\n\n### `collect(signal)`\n\nReturns a FIFO `pop` function and the signal connection.\n\n## License\n\nMIT\n","readmeTruncated":false}