{"id":15722596,"url":"https://github.com/whiteboxdev/library-defold-grid-engine","last_synced_at":"2025-04-13T18:38:06.088Z","repository":{"id":64867146,"uuid":"266416593","full_name":"whiteboxdev/library-defold-grid-engine","owner":"whiteboxdev","description":"Defold Grid Engine provides grid-based movement, interactions, and utility features in a Defold game engine project.","archived":false,"fork":false,"pushed_at":"2024-05-24T16:19:42.000Z","size":11852,"stargazers_count":48,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-04T14:53:20.748Z","etag":null,"topics":["defold","defold-library"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whiteboxdev.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-23T20:45:00.000Z","updated_at":"2025-03-26T10:45:19.000Z","dependencies_parsed_at":"2024-04-19T22:34:33.033Z","dependency_job_id":"47563d76-d8d2-43b6-8672-bb00ae35ba74","html_url":"https://github.com/whiteboxdev/library-defold-grid-engine","commit_stats":null,"previous_names":["whiteboxdev/library-defold-grid-engine"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-grid-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-grid-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-grid-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-grid-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whiteboxdev","download_url":"https://codeload.github.com/whiteboxdev/library-defold-grid-engine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248762635,"owners_count":21157761,"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":["defold","defold-library"],"created_at":"2024-10-03T22:08:36.950Z","updated_at":"2025-04-13T18:38:06.070Z","avatar_url":"https://github.com/whiteboxdev.png","language":"Lua","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"# Defold Grid Engine\n\nDefold Grid Engine provides grid-based movement, interactions, and utility features to a Defold game engine project.\n\nPlease click the ☆ button on GitHub if this repository is useful or interesting. Thank you!\n\n![alt text](https://github.com/whiteboxdev/library-defold-grid-engine/blob/master/assets/thumbnail.png?raw=true)\n\n## Installation\n\nAdd the latest version to your project's dependencies:  \nhttps://github.com/whiteboxdev/library-defold-grid-engine/archive/master.zip\n\n## Configuration\n\nImport the dgrid Lua module into your character's script:\n`local dgrid = require \"dgrid.dgrid\"`\n\nThe grid system itself must be initialized before registering any characters:\n\n```\nlocal grid_box_size = 16\n\nlocal collision_map = {\n    { 2, 2, 2, 2, 2 },\n    { 2, 1, 1, 1, 2 },\n    { 2, 1, 1, 1, 2 },\n    { 2, 1, 1, 1, 2 },\n    { 2, 2, 2, 2, 2 }\n}\n\nlocal property_map = {\n    [\"31\"] = { bonus_points = 1000 },\n    [\"55\"] = { bonus_points = 2000 }\n}\n\nfunction init(self)\n    dgrid.set_stride(grid_box_size)\n    dgrid.set_collision_map(collision_map)\n    dgrid.set_property_map(property_map)\nend\n```\n\nThe `dgrid.set_stride()` function sets the size of each grid box. In the example above, each grid box is set to 16 pixels.\n\nThe `dgrid.set_collision_map()` function assigns a collision map to the grid. Collision maps consist of a two-dimensional array of integers, each of which corresponds to a collision tag. All tags can be found in the `dgrid.tag` [table](#dgridtag). Custom tags may be inserted into the `dgrid.tag` table if you wish to detect additional collision cases. dgrid will post a `dgrid.msg.collide_passable` or `dgrid.msg.collide_impassable` message to your character's `on_message()` function when your character collides with any grid box. If you did not specify a collision map, then `dgrid.msg.collide_none` will be posted instead.\n\nThe `dgrid.set_property_map()` function assigns a property map to the grid. Property maps consist of a table of custom data. The purpose of this map is to assign semantics to your grid boxes. Keys correspond to the x and y coordinates of the targetted grid box, while values correspond to the custom data. When a character collides with a grid box that contains custom data, the data is attached to the `dgrid.msg.collide` messages as the `message.property` field. In the example above, colliding with the grid box at coordinates \u003c3, 1\u003e will send a `message.property` value of `{ bonus_points = 1000 }`.\n\nIf the bottom-left of your tilemap is not located at the origin of the game world, you should call the `dgrid.set_map_offset()` function, which allows you to shift your collision and property maps to match up with the world position of your tilemap.\n\nConfiguration is complete. Next step is to register your characters:\n\n```\nlocal config = {\n    size = vmath.vector3(16, 32, 0),\n    direction = dgrid.direction.down,\n    speed = 3\n}\n\nfunction init(self)\n    self.dgrid = dgrid.register(config)\nend\n```\n\n1. `size`: Size of your character in pixels.\n2. `direction`: Initial direction in which your character is looking.\n3. `speed`: Movement speed in grid boxes per second. If `speed = 0`, then movement is instant.\n\ndgrid snaps your character into a grid box on registration. To do this, the bottom-center `stride x stride` square region of your character is used to properly position it onto the grid.\n\nFinally, make sure to call `self.dgrid.update()` and `self.dgrid.unregister()` in your character's script:\n\n```\nfunction update(self, dt)\n    self.dgrid.update(dt)\nend\n\nfunction final(self)\n    self.dgrid.unregister()\nend\n```\n\n## API: Properties\n\n### dgrid.direction\n\nTable for referencing character orientation:\n\n```\ndgrid.direction = {\n\tup = { value = 1, string = \"up\", offset = vmath.vector3(0, 1, 0) },\n\tleft = { value = 2, string = \"left\", offset = vmath.vector3(-1, 0, 0) },\n\tdown = { value = 3, string = \"down\", offset = vmath.vector3(0, -1, 0) },\n\tright = { value = 4, string = \"right\", offset = vmath.vector3(1, 0, 0) }\n}\n```\n\n1. `value`: Identification value of this direction.  \n2. `string`: Name of this direction.  \n3. `offset`: Coordinate offset of this direction.\n\n### dgrid.msg\n\nTable for referencing messages posted to your character's `on_message()` function:\n\n```\ndgrid.msg = {\n    move_start = hash(\"move_start\"),\n    move_end = hash(\"move_end\"),\n    move_repeat = hash(\"move_repeat\"),\n    collide_none = hash(\"collide_none\"),\n    collide_passable = hash(\"collide_passable\"),\n    collide_impassable = hash(\"collide_impassable\")\n}\n```\n\n1. `move_start`: Posted when your character starts moving from rest.\n2. `move_end`: Posted when your character stops moving.\n3. `move_repeat`: Posted when your character continues moving between grid boxes without stopping.\n4. `collide_none`: Posted when your character collides with any grid box which lies outside of the supplied collision map. The `message.property` field contains the user-defined data at this grid position.\n5. `collide_passable`: Posted when your character collides with any passable grid box. The `message.name` field contains the tag's hashed `name` string. The `message.property` field contains the user-defined data at this grid position.\n6. `collide_impassable`: Posted when your character collides with any impassable grid box. The `message.name` field contains the tag's hashed `name` string. The `message.property` field contains the user-defined data at this grid position.\n\n### dgrid.tag\n\nTable for referencing collision tags. Each key (index of tag) corresponds to an integer used in your collision map. Custom tags may be inserted if you wish to detect additional collision cases.\n\n```\ndgrid.tag = {\n    { name = hash(\"passable\"), passable = true },\n    { name = hash(\"impassable\"), passable = false }\n}\n```\n\n1. `name`: Hashed name of this tag.\n2. `passable`: `bool` indicating whether characters may pass through grid boxes assigned to this tag.\n\n## API: Functions\n\n### dgrid.get_stride()\n\nGets the size of each grid box in pixels.\n\n#### Returns\n\nReturns a number.\n\n---\n\n### dgrid.get_collision_map()\n\nGets the collision map.\n\n#### Returns\n\nReturns a table of lists of integers in the following format:\n\n```\n{\n    { \u003ctag\u003e, ... },\n    ...\n}\n```\n\n---\n\n### dgrid.get_property_map()\n\nGets the property map.\n\n#### Returns\n\nReturns a table of custom data. Keys correspond to the x and y coordinates of the targetted grid box, while values correspond to the custom data:\n\n```\n{\n    [\"xy\"] = { ... },\n    ...\n}\n```\n\n---\n\n### dgrid.get_map_offset()\n\nGets the collision and property map offset.\n\n#### Returns\n\nReturns a `vector3`.\n\n---\n\n### dgrid.get_tag(name)\n\nGets tag information.\n\n#### Parameters\n1. `name`: Hashed name of a tag.\n\n#### Returns\n\nReturns a table in the following format:\n\n```\n{\n    key = \u003ctag\u003e,\n    value = { name = hash(\"\u003ctag_name\u003e\"), passable = \u003cbool\u003e }\n}\n```\n\n---\n\n### dgrid.to_pixel_position(grid_position)\n\nConverts grid coordinates to pixel coordinates. The returned pixel coordinates point to the center of the grid box.\n\n#### Parameters\n1. `grid_position`: `vector3` denoting the grid box to convert. The `z` component remains unchanged.\n\n#### Returns\n\nReturns a `vector3`.\n\n---\n\n### dgrid.to_grid_position(pixel_position)\n\nConverts pixel coordinates to grid coordinates.\n\n#### Parameters\n1. `pixel_position`: `vector3` denoting the pixel to convert. The `z` component remains unchanged.\n\n#### Returns\n\nReturns a `vector3`.\n\n---\n\n### dgrid.to_map_position(grid_position)\n\nConverts grid coordinates to map coordinates. Map coordinates take into account the `map_offset`.\n\n#### Parameters\n1. `grid_position`: `vector3` denoting the grid box to convert. The `z` component remains unchanged.\n\n#### Returns\n\nReturns a `vector3`.\n\n---\n\n### dgrid.set_stride(stride)\n\nSets the size of each grid box in pixels.\n\n#### Parameters\n1. `stride`: Size of each grid box in pixels.\n\n---\n\n### dgrid.set_collision_map(collision_map)\n\nSets the collision map.\n\n#### Parameters\n1. `collision_map`: Table of lists of integers in the following format:\n\n```\n{\n    { \u003ctag\u003e, ... },\n    ...\n}\n```\n\n---\n\n### dgrid.set_property_map(property_map)\n\nSets the property map.\n\n#### Parameters\n1. `property_map`: Table of custom data. Keys correspond to the x and y coordinates of the targetted grid box, while values correspond to the custom data:\n\n```\n{\n    [\"xy\"] = { ... },\n    ...\n}\n```\n\n---\n\n### dgrid.set_map_offset(offset)\n\nSets the collision and property map offset. If the bottom-left of your tilemap is not loaded at the origin of the game world, then this function will allow you to shift your collision property maps to match up with the world position of your tilemap.\n\n#### Parameters\n1. `offset`: `vector3` denoting number of grid boxes to shift.\n\n---\n\n### dgrid.set_tag(name, passable)\n\nSets an existing tag's `passable` flag.\n\n#### Parameters\n1. `name`: Hashed name of tag.\n2. `passable`: `bool` indicating whether characters may pass through grid boxes assigned to this tag.\n\n---\n\n### dgrid.add_tag(name, passable)\n\nAdds a tag to the `dgrid.tag` table.\n\n#### Parameters\n1. `name`: Hashed name of tag.\n2. `passable`: `bool` indicating whether characters may pass through grid boxes assigned to this tag.\n\n#### Returns\n\nReturns the tag's integer value which may be used when constructing your collision map.\n\n---\n\n### dgrid.register(config)\n\nRegisters the current game object in the grid system.\n\n#### Parameters\n1. `config`: Table for setting up this character's properties.\n    1. `size`: `vector3` of integers specifying this character's dimensions in pixels.\n    2. `direction`: Initial `dgrid.direction` in which your character is looking.\n    3. `speed`: Movement speed in grid boxes per second. If `speed = 0`, then movement is instant.\n\n#### Returns\n\nReturns an instance of dgrid.\n\n---\n\n### self.dgrid.get_size()\n\nGets the size of this character in pixels.\n\n#### Returns\n\nReturns a number.\n\n---\n\n### self.dgrid.get_direction()\n\nGets the `dgrid.direction` in which this character is looking.\n\n#### Returns\n\nReturns an entry of the `dgrid.direction` [table](#dgriddirection).\n\n---\n\n### self.dgrid.get_speed()\n\nGets the speed of this character in grid boxes per second.\n\n#### Returns\n\nReturns a number.\n\n---\n\n### self.dgrid.is_moving()\n\nChecks if this character is moving.\n\n#### Returns\n\nReturns a `bool`.\n\n---\n\n### self.dgrid.is_forcing_movement()\n\nChecks if this character is able to move through impassable grid boxes specified by the collision map.\n\n#### Returns\n\nReturns a `bool`.\n\n---\n\n### self.dgrid.get_grid_position()\n\nGets the grid coordinates of this character.\n\n#### Returns\n\nReturns a `vector3`.\n\n---\n\n### self.dgrid.get_map_position()\n\nGets the map coordinates of this character. Map coordinates take into account the `map_offset`.\n\n#### Returns\n\nReturns a `vector3`.\n\n---\n\n### self.dgrid.reach()\n\nGets the position of the grid box directly in front of this character in grid coordinates.\n\n#### Returns\n\nReturns a `vector3`.\n\n---\n\n### self.dgrid.set_direction(direction)\n\nSets the `dgrid.direction` in which this character is looking. This affects the return value of funtions such as `self.dgrid.reach()`. This is also useful for simply turning a character in some direction without actually moving.\n\n#### Parameters\n1. `direction`: Entry in the `dgrid.direction` [table](#dgriddirection).\n\n---\n\n### self.dgrid.set_speed(speed)\n\nSets the speed of this character in grid boxes per second.\n\n#### Parameters\n1. `speed`: Speed of this character in grid boxes per second. If `speed = 0`, then movement is instant.\n\n---\n\n### self.dgrid.force_movement(flag)\n\nAllows this character to move through impassable grid boxes as specified by the collision map.\n\n#### Parameters\n1. `flag`: `bool` indicating whether to force movement.\n\n---\n\n### self.dgrid.add_lerp_callback(callback, volatile)\n\nAdds a lerp callback, which triggers upon each complete character movement.\n\n#### Parameters\n1. `callback`: Callback function.\n2. `volatile`: `bool` indicating whether to remove this callback after being triggered once.\n\n---\n\n### self.dgrid.remove_lerp_callback(callback, volatile)\n\nRemoves a lerp callback, which triggers upon each complete character movement. Does nothing if the specified callback does not exist.\n\n#### Parameters\n1. `callback`: Callback function.\n2. `volatile`: `bool` indicating whether to remove this callback after being triggered once.\n\n---\n\n### self.dgrid.set_grid_position(grid_position)\n\nSets the position of this character in grid coordinates.\n\n#### Parameters\n1. `grid_position`: `vector3` denoting the grid box to warp to.\n\n---\n\n### self.dgrid.move(direction)\n\nBegin moving in some direction. Movement will continue until `self.dgrid.stop()` is called.\n\n#### Parameters\n1. `direction`: Entry in the `dgrid.direction` [table](#dgriddirection).\n\n---\n\n### self.dgrid.stop(direction)\n\nStop moving in some direction.\n\n#### Parameters\n1. `direction`: Entry in the `dgrid.direction` [table](#dgriddirection). Omit this argument if you wish to stop movement in all directions instead of just one.\n\n---\n\n### self.dgrid.update(dt)\n\nUpdates all relevant properties. Must be called in this character's `update()` function.\n\n#### Properties\n1. `dt`: Change in time since last frame.\n\n---\n\n### self.dgrid.unregister()\n\nUnregisters this character from dgrid. Must be called in this character's `final()` function.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-grid-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-grid-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-grid-engine/lists"}