{"id":19731381,"url":"https://github.com/clpsplug/hexagonal_map","last_synced_at":"2025-05-08T03:13:21.140Z","repository":{"id":87856564,"uuid":"142735799","full_name":"Clpsplug/hexagonal_map","owner":"Clpsplug","description":"Hexagonal map and cells data structure helper based on https://www.redblobgames.com/grids/hexagons/","archived":false,"fork":false,"pushed_at":"2018-08-12T07:41:32.000Z","size":212,"stargazers_count":6,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-08T03:13:15.891Z","etag":null,"topics":["csharp","hexagonal-grids","hexagonal-tiles"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Clpsplug.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-07-29T06:13:08.000Z","updated_at":"2024-04-03T13:21:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"45b8fa95-5808-4d05-8016-a9c921296931","html_url":"https://github.com/Clpsplug/hexagonal_map","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fhexagonal_map","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fhexagonal_map/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fhexagonal_map/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fhexagonal_map/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Clpsplug","download_url":"https://codeload.github.com/Clpsplug/hexagonal_map/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252990003,"owners_count":21836668,"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":["csharp","hexagonal-grids","hexagonal-tiles"],"created_at":"2024-11-12T00:20:40.746Z","updated_at":"2025-05-08T03:13:21.133Z","avatar_url":"https://github.com/Clpsplug.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hexagonal Map Coordinates Helper\n\n[Red Blob Games Website](https://www.redblobgames.com/grids/hexagons/)で\n説明されている立方体座標・QR座標のC#での実装  \nThis C# code implements Cube- and QR-based coordinates \ndescribed in [Red Blob Games Website.](https://www.redblobgames.com/grids/hexagons/)\n\n# Usage\n\n## Coordinates\n\nThere are 2 coordinates supported - Cube and QR(Axial.)  \nConstructors of those value objects are private, and\nyou must make through specific methods, `fromCube` and `fromQR`\nrespectively.\n\nThe supported coordinates makes creating concentric hexagonal map\neasy. Better supports for map that spreads in the form of a rectaingle \nare planned through offset coordinates.\n\n**Note** that whether your hexagonal map is pointy-topped or flat-topped\nis completely up to you.\nThese coordinates should work fine under both circumstances.\n\n**Also note** that you MUST NOT directly change the value for the \ncoordinates. You can't. If you want to modify the value and save it\nsomewhere else, just create new coordinate object with modified value.\n\n### Cube Coordinates\n\n\u003e Let's take a cube grid and slice out a diagonal plane at `x + y + z = 0.`\n\u003e This is a _weird_ idea but it helps us make hex grid algorithms simpler. \n\u003e In particular, we can reuse standard operations from cartesian coordinates: \n\u003e adding coordinates, subtracting coordinates, multiplying or dividing by a scalar, \n\u003e and distances.  \n\u003e  \\- Red Blob Games\n\nUse `HexagonalMap.Domain.HexMap.CubeCoordinate` to represent\nthe cube coordinates.\n\n```c#\n// The center\nvar center = CubeCoordinate.fromCube(0,0,0);\n// Top hexagon (in flat-top system)\nvar top = CubeCoordinate.fromCube(0,1,-1);\n// You can access each coordinate via:\ntop.x // -\u003e 0\ntop.y // -\u003e 1\ntop.z // -\u003e -1\n// Note that in Cube coordinate, x + y + z is always 0. If they aren't, it will yield an exception.\nvar fail = CubeCoordinate.fromCube(1,2,3); // -\u003e ArgumentException\n```\n\nAddition and Deduction are implemented. This is important\nwhen finding the 6 neighbours.\n\n```c#\n// CubeCoordinates has a method to return a list of relative positions\n// of the 6 neighbours. \nvar relativeNeighbours = CubeCoordinate.AdjacentRelatives();\nvar origin = CubeCoordinate.fromCube(0,0,0);\nforeach (var relative in relativeNeighbours) {\n    origin + relative // -\u003e is the coordinate for one of the neighbour of origin.\n}\n```\n\nFind if two coordinate match simply using `==`\n(or don't match using `!=`)\n\n```c#\nvar a = CubeCoordinate.fromCube(0,0,0);\nvar b = CubeCoordinate.fromCube(0,0,0);\nvar c = CubeCoordinate.fromCube(1,0,-1);\n\na == b // -\u003e true\na != b // -\u003e false\na == c // -\u003e false\na != c // -\u003e true\n```\n\n### QR Coordinates (Axial Coordinates)\n\n\u003e The axial coordinate system, sometimes called \n\u003e “trapezoidal” or “oblique” or “skewed”, \n\u003e is built by taking two of the three coordinates \n\u003e from a cube coordinate system.   \n\u003e \\- Red Blob Games\n\nThis coordinate is extremely useful for drawing, since you can convert\nthe hexagons' position with little math.\n\nUse `HexagonalMap.Domain.HexMap.QRCoordinate` to represent\nthe QR coordinates.  \n\n```c#\n// The center\nvar center = QRCoordinate.fromQR(0,0);\n// Top hexagon (in flat-top system)\nvar top = QRCoordinate.fromQR(0, -1);\n// Get values of each coordinate\ntop.q // -\u003e 0\ntop.r // -\u003e -1\n```\n\n`QRCoordinates` cannot give you the relative coordinate of 6 neighbours,\nbut addition, deduction, equality checks are implemented.\nSee Cube Coordinates for usage.\n\n## Converting Coordinates\n\nCube Coordinates and QR Coordinates can be converted into each other.\nSimply call:\n\n```c#\nvar qr = QRCoordinate.fromQR(0,0);\nvar cube = CubeCoordinate.fromCube(0,0,0);\nQRCoordinate.fromCube(cube); // -\u003e returns a QR coordinate for the given Cube coordinate\nCubeCoordinate.fromQR(qr); // -\u003e returns a Cube coordinate for the given QR coordinate\nqr.toCube(); // -\u003e converts itself (QR) into Cube coordinate\ncube.toQR(); // -\u003e converts itself (Cube) into QR coordinate\n```\n\nYou can also directly create those coordinates with values for other system:\n\n```c#\nvar qr = QRCoordinate.fromCube(0,0,0); // -\u003e is a QR coordinate that is equal to Cube coordinate (0,0,0)\nvar cube = CubeCoordinate.fromQR(0,0); // -\u003e is a Cube coordinate that is equal to QR coordinate (0,0)\n```\n\n## Field and Cells\n\n### Cells\n\nIf any of your object in your games needs to know its hexagonal position,\ninherit `HexagonalMap.Domain.HexMap.Cell`.  \nTo initialize its position, call `initPosition()`. Get its position\nthrough `Position` parameter.  \n\n```c#\npublic class Block: Cell\n{\n    public int Score { get; set; }\n}\n```\n\n### Field\n\n`HexagonalMap.Domain.HexMap.Field` can hold objects inheriting `Cell`.\n\nIf you need a hexagonal field, inherit `Field` to your class.  \nThis will help you finding cells in your game fields.  \n\nHere are few things to remember:\n\n1. You need to add your `Cell`s into the field before the field can find them.  \n\n```c#\nvar map = new Map(5);\nvar block = new Block(CubeCoordinate.fromCube(0,0,0), 50);\nmap.AddCell(block);\n```\n\n2. Since you shouldn't change your `Cell`s position directly, if you want cells to move\nto another place, you need to remove it from the map, create new `Cell`\nwith different location, and add it back to the `Field`.\n3. `Field` cannot have more than 1 cell at the same spot. Forcing so will\nget you an `ArgumentException`. You can use it to detect collision, if you like.\n\n```c#\n// Moving a cell at the center...\n// Remove it from the field first. RemoveCellAt gives you the removed cell.\nvar removedCell = map.RemoveCellAt(CubeCoordinate.fromCube(0,0,0));\n// Recreate your cell data with the new location\nvar movedCell = new Block(CubeCoordinate.fromCube(1,0,-1), block.Score);\n// Adding back might yield exception. If it does, resolve the situation first.\ntry {\n    map.AddCell(movedCell);\n}\ncatch (ArgumentException e)\n{\n    // Collision! It might be that your cell bumped into an enemy.\n}\n```\n\n\nInheriting `Field` grants you following benefits:\n\n1. You can find a cell at a given coordinate.\n\n```c#\nvar foundByCube = map.FindCellAt(CubeCoordinate.fromCube(0,0,0));\nvar foundByQR = map.FindCellAt(QRCoordinate.fromQR(0,0));\n```\n\n2. You can find the 6 neighboring cells (if it exists on the `Field`.)\n\n```c#\nmap.FindNeighborsOf(foundByCube); // -\u003e returns list of cells up to 6.\n```\n\n# Glitchy behaviors?\n\nOpen the issue in this repository! If you provide some reproducable codes,\nthings will go smoother!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclpsplug%2Fhexagonal_map","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclpsplug%2Fhexagonal_map","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclpsplug%2Fhexagonal_map/lists"}