{"id":"mark-marks/hammer","name":"hammer","scope":"mark-marks","platform":"roblox","description":"Mirrored from the Wally registry.","version":"0.3.0","latest":"0.3.0","versions":["0.2.0","0.2.1","0.3.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"ukendio/jecs":{"version":"^0.9.0","alias":"jecs"}},"integrity":"0c17f5b0fc1a6d27e5b67547494e44d8bf43a7aaf95679f5cc72b90333776617","likes":0,"downloads":0,"install":"forest install mark-marks/hammer","url":"https://forest.dev/p/roblox/mark-marks/hammer","files":"https://api.forest.dev/ai/package/roblox/mark-marks/hammer/files","readme":"

\r\n \r\n

\r\n\r\n[![CI](https://img.shields.io/github/actions/workflow/status/mark-marks/hammer/ci.yml?style=for-the-badge&label=CI)](https://github.com/mark-marks/hammer/actions/workflows/ci.yml)\r\n[![CI](https://img.shields.io/github/actions/workflow/status/mark-marks/hammer/release.yml?style=for-the-badge&label=CD)](https://github.com/mark-marks/hammer/actions/workflows/release.yml)\r\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](https://github.com/Mark-Marks/hammer/blob/main/LICENSE)\r\n\"Wally\"\r\n\"Pesde\"\r\n\r\nA set of utilities for [Jecs](https://github.com/ukendio/jecs)\r\n
\r\n\r\n\r\n\r\n## ⛓️‍💥 Installation\r\n\r\nHammer is available on pesde @ `marked/hammer` and Wally @ `mark-marks/hammer`.\\\r\nFor standalone installation using the automatically built `rbxm`, make sure to replace all instances of `../../jecs` in the utilities with a path to a Jecs module.\r\n\r\n## 📄 Changelog\r\n\r\nTo view per-version changes, see [the changelog](/CHANGELOG.md).\r\n\r\n## 🔨 Usage\r\n\r\nAll utilities that require a Jecs world to function are exposed via a constructor pattern.\\\r\nFor instance, to build a `ref`:\r\n```luau\r\nlocal ref = hammer.ref(world)\r\n```\r\nThis is the easiest solution for passing a world that doesn't sacrifice readability internally and externally or bind the developer to a Jecs version that hammer is currently using.\r\n\r\nA recommended approach to initialize the utilities which need a world is to place them in a shared ECS `std` folder, which's utilities you can use later:\r\n```luau\r\n-- std/ref.luau\r\nlocal world = require(\"./world\")\r\nreturn hammer.ref(world)\r\n```\r\n```luau\r\n-- my_system.luau\r\nlocal ref = require(\"@std/ref\")\r\n...\r\n```\r\nInitializing them in every file on require shouldn't be a problem, though, as all of them are cached by world (spare for command buffers!).\r\n\r\n### Collect\r\n\r\n[Collect](/lib/utilities/collect.luau) collects all arguments fired through the given signal into a queue, and exposes an iterator to flush it.\\\r\nIts purpose is to interface with signals in ECS code, which ideally should run every frame in a loop.\r\n\r\nFor instance, take Roblox's RemoteEvents:\r\n```luau\r\nlocal pings = hammer.collect(events.ping.OnServerEvent)\r\nlocal function system()\r\n for _, player, ping in pings do\r\n events.ping:FireClient(player, \"pong!\")\r\n end\r\nend\r\n```\r\n\r\nCollect works with any signal which:\r\n- Is a function which sets a callback\r\n- Exposes a `:connect` or `:Connect` method\r\n\r\nCollect also returns a cleanup function to stop listening to the event.\\\r\nIf the signal doesn't return an object with a `:disconnect`, `:Disconnect`, `:destroy`, `:Destroy` method or a cleanup function, it's simply a no-op.\r\n\r\n### Command Buffer\r\n\r\nA [command buffer](/lib/utilities/command_buffer.luau) lets you buffer world commands in order to prevent iterator invalidation.\\\r\nIterator invalidation refers to an iterator (e.g. `world:query(Component)`) becoming unusable due to changes in the underlying data.\r\n\r\nTo prevent this, command buffers can be used to delay world operations to the end of the current frame:\r\n```luau\r\nlocal command_buffer = hammer.command_buffer(world)\r\n\r\nwhile true do\r\n step_systems()\r\n command_buffer.flush()\r\nend\r\n\r\n-- Inside a system:\r\ncommand_buffer.add(entity, component) -- This runs after all of the systems run; no data changes while things are running\r\n```\r\n\r\n### Ref\r\n\r\nA [ref](/lib/utilities/ref.luau) allows for storing and getting entities via some form of reference.\\\r\nThis is particularly useful for situations where you reconcile entities into your world from a foreign place, e.g. from across a networking boundary, or need an easy way to get an entity from an object, e.g. a player.\r\n```luau\r\nlocal ref = hammer.ref(world)\r\n\r\nfor id in net.new_entities.iter() do\r\n local entity = ref(`foreign-{id}`) -- A new entity that can be tracked via a foreign id\r\nend\r\n```\r\n\r\nRefs by default create a new entity if the given value doesn't reference any stored one. In case you want to see if a reference exists, you can find one:\r\n```luau\r\nlocal entity[: Entity?] = ref.find(`my-key`)\r\n```\r\n\r\nRefs can also be deleted:\r\n```luau\r\nlocal entity = ref(`my-key`)\r\nref.delete(`my-key`) -- `entity` still persists in the world, but `my-key` doesn't refer to it anymore.\r\n```\r\n\r\nRefs are automatically cached by world. `ref(world)` will have the same underlying references as `ref(world)`.\\\r\nIn case you need an unique reference store, you can omit the cache via `ref(world, true)`.\r\n\r\n### Observers\r\n\r\n[Observers](/lib/utilities/observers.luau) allow for observing entities of a matching query.\r\n\r\nObservers can be seen as a reactive counterpart to systems, similar to hooks, albeit allowing for more flexibility, as they operate on queries in place of singular components.\r\n```luau\r\nhammer.observer(world:query(Position, Velocity), function(entity)\r\n --- Ran whenever an entity matching the query has any of its terms changed.\r\n --- In this instance, the callback would be ran whenever an entity which has a position and velocity has either of the two modified.\r\nend)\r\n```\r\n\r\nMonitors are a special kind of observer, which run whenever an entity starts or stops matching a query.\r\n```luau\r\nlocal monitor = hammer.monitor(world:query(Position, Velocity))\r\nmonitor.added(function(entity)\r\n --- Ran whenever an entity starts matching the query.\r\n --- In this case, the entity began to have both a position and velocity.\r\nend)\r\nmonitor.removed(function(entity)\r\n --- Ran whenever an entity stops matching the query.\r\n --- In this case, the entity stopped having either a position or a velocity.\r\nend)\r\n```\r\n\r\nBoth kinds of observers return tables which contain a disconnect function serving as a way to clean the observer up.\r\n```luau\r\nlocal observer = hammer.observer(...)\r\nobserver.disconnect()\r\n```\r\n\r\nRemember to be careful! Observers aren't without their costs.\r\n\r\nThe [Flecs article on observers](https://www.flecs.dev/flecs/md_docs_2ObserversManual.html) contains more useful information about them, albeit the Jecs and Flecs implementations and interfaces don't fully match.\r\n\r\nObservers are a direct copy of [the addon in the Jecs repo](https://github.com/Ukendio/jecs/blob/main/addons/ob.luau), licensed under MIT.\r\n\r\n### Interval\r\n\r\n[Intervals](/lib/utilities/interval.luau) allow for throttling systems to only run every `n` seconds. This can, for instance, be useful to throttle networking events, or physics.\r\n\r\n```luau\r\nlocal replication_throttle = hammer.interval(1 / 10) -- Run every 100ms\r\nlocal function replication()\r\n if not replication_throttle() then\r\n return\r\n end\r\n -- Only runs every 100ms\r\n\r\n for player, packet in replicator:collect_packets() do\r\n ...\r\n end\r\nend\r\n```\r\n\r\n### IsA\r\n\r\n[IsA](/lib/utilities/is_a.luau) allows for transitive inheritance relationships. In essence, this means that you can express an entity as being equivalent to another, without the reverse needing to be true.\r\n\r\nA nice use of this is for entity prefabs, allowing you to have a \"template\" entity you can create copies of via adding the relationship.\r\n```luau\r\nlocal IsA = hammer.is_a(world)\r\n\r\nlocal Spaceship = world:component()\r\nworld:set(Spaceship, Health, 250)\r\nworld:set(Spaceship, Shields, 50)\r\nworld:set(Spaceship, Damage, 35)\r\nworld:set(Spaceship, Position, vector.create(100, 20, 100))\r\nworld:set(Spaceship, Velocity, vector.create(10, 0, 4))\r\n\r\nlocal my_spaceship = world:entity()\r\nworld:add(my_spaceship, pair(IsA, Spaceship))\r\n-- `my_spaceship` now has all of the components of `Spaceship`, alongside the component `Spaceship` itself. Be careful while iterating spaceships though - to not include the prefab, make sure to add `pair(IsA, Spaceship)` to your query!\r\n-- You can override the components by operating on the world like usual:\r\nworld:set(spaceship, Health, 230)\r\n```\r\n\r\nA further read can be found at the [Flecs relationships article](https://www.flecs.dev/flecs/md_docs_2Relationships.html#the-isa-relationship), and specifically the section about IsA relationships.\r\n\r\nThe implementation is based on [the IsA gist](https://gist.github.com/Ukendio/0d839428324bd10b7e4a16568cb856c8) created by the Jecs author, albeit further optimized to skip creating intermediate archetypes.\r\n\r\n## ⚖️ License\r\n\r\nThis project is licensed under the terms of the MIT license. To further explore the terms, read [here](/LICENSE).\r\n","readmeTruncated":false}