{"id":"dubalda/mercs","name":"mercs","scope":"dubalda","platform":"roblox","description":"ECS for Luau and Roblox built on inverted bitsets, with a jecs-like API","version":"1.3.0","latest":"1.3.0","versions":["0.1.0","0.1.1","0.1.2","0.2.0","0.2.1","0.2.2","0.2.3","0.2.4","1.0.0","1.0.1","1.1.0","1.2.0","1.3.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"2fe6f09843513f01108673d98785f6e06b8a324cdd53200c30c4a94b1ff94372","likes":0,"downloads":0,"install":"forest install dubalda/mercs","url":"https://forest.dev/p/roblox/dubalda/mercs","files":"https://api.forest.dev/ai/package/roblox/dubalda/mercs/files","readme":"# mErCS\nECS (an entity component system) for Luau and Roblox built on inverted bitsets\n\nInstead of archetypes, every component, tag and pair keeps a bitset of the entities that have\nit. Adding or removing a component never moves an entity and never creates an archetype, so\nfrequent structural changes — state tags, relationships, spawning and despawning — stay O(1),\nmemory does not grow with the number of component combinations, and there is nothing to clean\nup. The API follows [jecs](https://github.com/Ukendio/jecs); moving jecs code over takes a few\nmechanical changes (see [Migrating from jecs](docs/comparison/jecs.md#migrating-from-jecs)).\n\nVersion 1.3.0 is validated with the standalone `luau` 0.740 CLI (interpreter and native code\ngeneration); the [Benchmarker](docs/comparison/benchmarker.md) results were captured in Roblox\nStudio with 1.0.0, and the full Studio check (`studio/`) is pending.\n\nThe [1.3.0 reference workload report](https://github.com/dubalda/mErCS/blob/main/bench/results/1.3.0.md)\ncompares this version with 1.2.0 and includes raw measurements, controls and reproduction commands.\n\n## Why\n\n| | jecs 0.11.0 | mErCS 1.3.0 |\n|---|---|---|\n| add / remove a component | moves the entity, copies all its columns | sets a bit and a value: O(1) |\n| new combination of components | creates an archetype, kept until `world:cleanup()` | nothing to create |\n| pair with many targets | an archetype per target | one small record per pair, freed when unused (in batches) or with its target |\n| a synthetic game frame (interpreter / native) | 6.1 / 5.31 ms | 2.54 / 1.76 ms |\n| heap growth with changing targets after 5000 frames (interpreter) | +15.38 MiB | +0.32 MiB |\n| memory per entity with 4 components | 320 B | 131 B |\n\nOn the [query cases](docs/comparison/jecs.md#query-cases) where an archetype ECS is\nexpected to be at its best, mErCS 1.3.0 takes 0.45–0.86× of the time of jecs 0.11.0 in native\ncode. The [comparison](docs/comparison/jecs.md#performance) gives the ranges and the raw\nsamples; [ecr](docs/comparison/ecr.md) has a page of its own, and the Roblox Studio screenshots\nare on [Benchmarker](docs/comparison/benchmarker.md).\n\nBeyond jecs: `query:each` (the fastest loop), OR terms, batch operations on query matches,\ntoggles, change tracking by ticks and of new entities, disabled entities, hierarchies of any\ndepth, slot pools, a read of a component that an entity must have (`world:expect`, an error\nthat names both instead of `nil`), a debug world that names the wrong argument of a call\n(`world:query: id 2 is nil`). Query\nmonitors (`query:monitor()`) take the place of the monitors of the jecs addon `modules/OB`.\n\n## Installation\n\nCopy `src/init.luau` into your project as a ModuleScript (for example\n`ReplicatedStorage.mErCS`; `src/jabby.luau` is an optional child module for the jabby\ndebugger), or sync the repository with Rojo (`default.project.json`), or depend on it through\nWally (`mercs = \"dubalda/mercs@1.3.0\"`). The module has no dependencies; `--!native` is enabled\nat the top of the file.\n\n## Quick start\n\n```luau\nlocal ecs = require(ReplicatedStorage.mErCS)\nlocal world = ecs.world()\n\nlocal Position = world:component() :: ecs.Component<Vector3>\nlocal Velocity = world:component() :: ecs.Component<Vector3>\nlocal Frozen = world:entity() -- any entity can be used as a tag\n\nlocal e = world:entity()\nworld:set(e, Position, Vector3.zero)\nworld:set(e, Velocity, Vector3.xAxis)\n\n-- the fastest loop: a callback per entity\nworld:query(Position, Velocity):without(Frozen):each(function(entity, position, velocity)\n    world:set(entity, Position, position + velocity)\nend)\n\n-- or a for-in loop, as in jecs\nfor entity, position, velocity in world:query(Position, Velocity) do\n    world:set(entity, Position, position + velocity)\nend\n\n-- relationships\nlocal parent = world:entity()\nworld:add(e, ecs.pair(ecs.ChildOf, parent))\nprint(world:parent(e) == parent) --> true\nworld:delete(parent) -- deletes e as well (ChildOf cascades)\n\n-- one change to every match of a query\nworld:query(Position):with(Frozen):remove_all(Velocity)\n```\n\n`examples/basics.luau` is a runnable tour: `luau examples/basics.luau`.\n\n## Documentation\n\nThe [documentation site](https://dubalda.github.io/mErCS/) holds the API reference (built\nfrom the doc comments of `src/`) and these pages:\n\n- [Guide](docs/guide/README.md) — worlds, components, queries, batch operations, relationships,\n  hooks, query monitors, change tracking, the jabby adapter, types.\n- [Comparison](docs/comparison/README.md) — the Benchmarker screenshots, 1.3.0 against 1.2.0,\n  and jecs and ecr: design, differences, benchmarks, migrating.\n- [Development](docs/development/README.md) — layout, tests, checks, benchmarks, Roblox Studio,\n  CI and releases.\n\n## License\n\nMIT\n","readmeTruncated":false}