{"id":16125493,"url":"https://github.com/semibran/hitbox","last_synced_at":"2025-06-13T07:04:44.503Z","repository":{"id":57264405,"uuid":"90315470","full_name":"semibran/hitbox","owner":"semibran","description":":package: helper functions for handling two-dimensional axis-aligned bounding boxes","archived":false,"fork":false,"pushed_at":"2018-03-23T18:17:51.000Z","size":7,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-17T18:05:31.539Z","etag":null,"topics":["collision-detection","hitbox"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semibran.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-04T22:33:20.000Z","updated_at":"2020-09-09T02:26:19.000Z","dependencies_parsed_at":"2022-08-25T02:20:31.470Z","dependency_job_id":null,"html_url":"https://github.com/semibran/hitbox","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/semibran/hitbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semibran%2Fhitbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semibran%2Fhitbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semibran%2Fhitbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semibran%2Fhitbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semibran","download_url":"https://codeload.github.com/semibran/hitbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semibran%2Fhitbox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259599320,"owners_count":22882353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collision-detection","hitbox"],"created_at":"2024-10-09T21:29:48.419Z","updated_at":"2025-06-13T07:04:44.473Z","avatar_url":"https://github.com/semibran.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hitbox\n\u003e tiny helper functions for handling axis-aligned bounding boxes\n\nIf you remember [that one article on collision detection][article] written by the good folks over at Metanet Software, you may recall that we can model an [axis-aligned bounding box] by its central position and its halfsize vectors. If we were to translate this definition over to JavaScript, it might look something like this:\n\n```js\n{\n  halfsize: [ 8, 12 ],\n  position: [ 128, 128 ]\n}\n```\n\nNotice the use of array vectors, which enables us to further extend this definition into higher dimensions.\n\n```js\n{\n  halfsize: [ 10, 20, 30 ],\n  position: [ 100, 200, 150 ]\n}\n```\n\n`hitbox` provides flexible helper functions to enable easier reading and manipulation of these kinds of data structures in two and three dimensions. For example, the code snippet below employs generous use of these functions in order to simplify collision detection.\n\n```js\nfor (let block of world.blocks) {\n  if (intersects2D(actor.hitbox, block.hitbox)) {\n    if (dx \u003c 0) {\n      left(actor.hitbox, right(block.hitbox))\n      actor.velocity[0] = 0\n    } else if (dx \u003e 0) {\n      right(actor.hitbox, left(block.hitbox))\n      actor.velocity[0] = 0\n    }\n    if (dy \u003c 0) {\n      top(actor.hitbox, bottom(block.hitbox))\n      actor.velocity[1] = 0\n    } else if (dy \u003e 0) {\n      bottom(actor.hitbox, top(block.hitbox))\n      actor.velocity[1] = 0\n    }\n  }\n}\n```\n\n\n\n## usage\n[![npm badge]][npm package]\n\n### `left(hitbox[, x])`\nFinds the x-coordinate of the left edge of the hitbox, or sets it if `x` is provided.\n\n```js\nleft(hitbox) === hitbox.position[0] - hitbox.halfsize[0]\n```\n\n### `right(hitbox[, x])`\nFinds the x-coordinate of the right edge of the hitbox, or sets it if `x` is provided.\n\n```js\nright(hitbox) === hitbox.position[0] + hitbox.halfsize[0]\n```\n\n### `top(hitbox[, y])`\nFinds the y-coordinate of the top of the hitbox, or sets it if `y` is provided.\n\n```js\ntop(hitbox) === hitbox.position[1] - hitbox.halfsize[1]\n```\n\n### `bottom(hitbox[, y])`\nFinds the y-coordinate of the bottom of the hitbox, or sets it if `y` is provided.\n\n```js\nbottom(hitbox) === hitbox.position[1] + hitbox.halfsize[1]\n```\n\n### `back(hitbox[, z])`\nFinds the z-coordinate of the back of the hitbox, or sets it if `z` is provided.\n\n```js\nback(hitbox) === hitbox.position[2] - hitbox.halfsize[2]\n```\n\n### `front(hitbox[, z])`\nFinds the z-coordinate of the front of the hitbox, or sets it if `z` is provided.\n\n```js\nfront(hitbox) === hitbox.position[2] + hitbox.halfsize[2]\n```\n\n### `intersects2D(a, b)`\nDetermines if hitbox `a` and hitbox `b` are intersecting in two dimensions.\n\n```js\nif (intersects2D(actor.hitbox, enemy.hitbox)) {\n  actor.health-- // ouch!\n}\n```\n\n### `contains2D(a, b)`\nDetermines if hitbox `a` contains hitbox `b` in two dimensions.\n\n```js\nfor (let actor of world.actors) {\n  if (contains2D(viewport, actor.hitbox)) {\n    draw(actor)\n  }\n}\n```\n\n### `intersects3D(a, b)`\nDetermines if hitbox `a` and hitbox `b` are intersecting in three dimensions.\n```js\nif (intersects3D(actor.hitbox, enemy.hitbox)) {\n  actor.health-- // ouch but in 3D!\n}\n```\n\n### `contains3D(a, b)`\nDetermines if hitbox `a` contains hitbox `b` in three dimensions.\n\n```js\nif (!contains3D(package, product) \u0026\u0026 !intersects3D(package, product)) {\n  // oh no\n}\n```\n\n[npm package]:               https://npmjs.com/package/hitbox\n[npm badge]:                 https://nodei.co/npm/hitbox.png?mini\n[article]:                   http://www.metanetsoftware.com/technique/tutorialA.html\n[axis-aligned bounding box]: https://en.wikipedia.org/wiki/Axis-aligned_bounding_box\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemibran%2Fhitbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemibran%2Fhitbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemibran%2Fhitbox/lists"}