{"id":14969731,"url":"https://github.com/cerus/maps","last_synced_at":"2025-04-13T09:37:47.334Z","repository":{"id":50376205,"uuid":"411468069","full_name":"cerus/maps","owner":"cerus","description":"maps is a simple Spigot plugin and api for creating clientside maps and map screens.","archived":false,"fork":false,"pushed_at":"2024-12-15T05:20:37.000Z","size":367,"stargazers_count":51,"open_issues_count":5,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-27T01:10:01.598Z","etag":null,"topics":["2d-engine","2d-graphics","alpha-blending","bukkit","bukkit-plugin","game-mod","hacktoberfest","java","minecraft","minecraft-maps","minecraft-plugin","modtoberfest","spigot","spigot-plugin"],"latest_commit_sha":null,"homepage":"","language":"Java","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/cerus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":["cerus"]}},"created_at":"2021-09-28T23:33:07.000Z","updated_at":"2025-02-20T03:25:27.000Z","dependencies_parsed_at":"2024-04-24T01:35:58.726Z","dependency_job_id":"927f2aaf-6880-44f9-a308-77fd3daf2a0e","html_url":"https://github.com/cerus/maps","commit_stats":{"total_commits":96,"total_committers":2,"mean_commits":48.0,"dds":"0.48958333333333337","last_synced_commit":"1917b7c9f40f06bc8c8fe64b6c37d0e5c51c543b"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmaps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmaps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmaps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmaps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cerus","download_url":"https://codeload.github.com/cerus/maps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248691708,"owners_count":21146424,"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":["2d-engine","2d-graphics","alpha-blending","bukkit","bukkit-plugin","game-mod","hacktoberfest","java","minecraft","minecraft-maps","minecraft-plugin","modtoberfest","spigot","spigot-plugin"],"created_at":"2024-09-24T13:42:17.254Z","updated_at":"2025-04-13T09:37:47.312Z","avatar_url":"https://github.com/cerus.png","language":"Java","funding_links":["https://github.com/sponsors/cerus"],"categories":["Java"],"sub_categories":[],"readme":"\u003cimg width=\"25%\" height=\"25%\" align=\"left\" src=\"https://i.ibb.co/0h1Z8M2/mc-map-item.png\" alt=\"Minecraft map item\"\u003e\n\n\u003ch2 align=\"center\"\u003emaps\u003c/h2\u003e\n\u003cp align=\"center\"\u003emaps is a simple Spigot plugin and api for creating clientside maps and map screens. It is the successor\nof \u003ca href=\"https://github.com/cerus/packet-maps\"\u003epacket-maps\u003c/a\u003e.\u003c/p\u003e\n\n\u003chr\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003csup\u003eMade with ♥ by \u003ca href=\"https://github.com/cerus\"\u003eCerus\u003c/a\u003e\u003c/sup\u003e\u003c/sub\u003e\u003c/p\u003e\n\u003cbr\u003e\n\n### Navigation\n\n• [Features](#Features)\\\n• [Quick start for developers](#Quick-start-for-developers)\\\n• [Building](#Building)\\\n• [FAQ](#FAQ)\\\n• [Contributing](#Contributing)\\\n• [Sources](#Sources)\n\n\u003chr\u003e\n\n### Features\n\n\u003e **Please note:** This is not a standalone plugin, it is a toolkit for other plugins. You will only be able to create and manage map screens with\n\u003e this plugin.\n\n• Clientside maps\\\n• Map screens (arrangement of clientside maps)\\\n• Simple and reasonably lightweight\\\n• Easy to use developer api\\\n• Advanced engine features\nlike [alpha compositing](https://en.wikipedia.org/wiki/Alpha_compositing) ([Image](https://cerus.dev/img/maps_alpha_composition.png))\\\n• Efficient click handling\\\n• Supports 1.16.5 - 1.21.4\n\n**What is the point of the plugin module?**\\\nSee [FAQ](#FAQ)\n\n\u003chr\u003e\n\n### Quick start for developers\n\n\u003e Please take a look at the wiki for an in-depth explanation of the api.\n\n**Maven setup**\n\n```xml\n\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003edev.cerus.maps\u003c/groupId\u003e\n        \u003cartifactId\u003ecommon\u003c/artifactId\u003e\n        \u003cversion\u003e3.8.9\u003c/version\u003e\n        \u003cscope\u003eprovided\u003c/scope\u003e \u003c!-- \"provided\" if the maps plugin is on the server, \"compile\" if not --\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- You need the plugin module to access the map screen registry of the plugin. --\u003e\n    \u003c!-- Don't add this dependency if you have your own storage solution. --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003edev.cerus.maps\u003c/groupId\u003e\n        \u003cartifactId\u003eplugin\u003c/artifactId\u003e\n        \u003cversion\u003e3.8.9\u003c/version\u003e\n        \u003cscope\u003eprovided\u003c/scope\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n**Quickstart**\n\n```java\nimport dev.cerus.maps.api.ClientsideMap;\nimport dev.cerus.maps.api.MapScreen;\nimport dev.cerus.maps.api.graphics.ClientsideMapGraphics;\nimport dev.cerus.maps.api.graphics.ColorCache;\nimport dev.cerus.maps.api.graphics.MapGraphics;\nimport dev.cerus.maps.plugin.map.MapScreenRegistry;\nimport dev.cerus.maps.version.VersionAdapterFactory;\nimport org.bukkit.Bukkit;\nimport org.bukkit.command.Command;\nimport org.bukkit.command.CommandSender;\nimport org.bukkit.entity.Player;\nimport org.bukkit.inventory.ItemStack;\nimport org.bukkit.inventory.meta.MapMeta;\nimport org.bukkit.map.MinecraftFont;\nimport org.bukkit.plugin.java.JavaPlugin;\n\npublic class MyPlugin extends JavaPlugin {\n\n    @Override\n    public void onEnable() {\n        // This example depends on the \"common\" and \"plugin\" dependency.\n\n        for (final MapScreen screen : MapScreenRegistry.getScreens()) {\n            final MapGraphics\u003c?, ?\u003e graphics = screen.getGraphics();\n            graphics.fillComplete(ColorCache.rgbToMap(255, 255, 255)); // Convert rgb(255, 255, 255) to map color and fill the screen\n            graphics.drawText(5, 5, \"There are \" + Bukkit.getOnlinePlayers().size() + \" players on the server\", ColorCache.rgbToMap(0, 0, 0), 2);\n            screen.spawnFrames(Bukkit.getOnlinePlayers().toArray(new Player[0])); // Send the screen frames to all online players\n            screen.sendMaps(true); // Send map data to all online players\n        }\n        getCommand(\"mapstest\").setExecutor(this);\n    }\n\n    @Override\n    public boolean onCommand(final CommandSender sender, final Command command, final String label, final String[] args) {\n        // It's been ages since I've used the normal Bukkit command system \n        // so please forgive me if I use any bad practices here\n        if (!(sender instanceof Player player)) {\n            return true;\n        }\n        if (!command.getName().equals(\"mapstest\")) {\n            return true;\n        }\n\n        // This is really unsafe. Always do proper checks before casting \n        // things, but this will do for the sake of this quick start.\n        final ItemStack item = player.getInventory().getItemInMainHand();\n        final MapMeta mapMeta = (MapMeta) item.getItemMeta();\n        final int mapId = mapMeta.getMapView().getId();\n\n        final ClientsideMap clientsideMap = new ClientsideMap(mapId); // Create clientside map with given id\n        final ClientsideMapGraphics graphics = new ClientsideMapGraphics(); // Create graphics buffer\n\n        graphics.fillComplete(ColorCache.rgbToMap(0, 0, 0)); // Fill with rgb(0, 0, 0)\n        graphics.drawText(5, 5, \"Hello,\", ColorCache.rgbToMap(255, 255, 255), 1); // Draw text\n        graphics.drawText(5, 5 + MinecraftFont.Font.getHeight() + 5, player.getName(), ColorCache.rgbToMap(255, 255, 255), 2);\n\n        clientsideMap.draw(graphics); // Draw the buffer onto the map\n        clientsideMap.sendTo(new VersionAdapterFactory().makeAdapter(), player); // Send the map to the player\n        return true;\n    }\n\n}\n```\n\n\u003chr\u003e\n\n### Building\n\nRequirements: Java 21, Git, Maven, CraftBukkit 1.16.5, 1.17.1, 1.18.1, 1.18.2, 1.19.1, 1.19.3, 1.19.4, 1.20, 1.20.2, 1.20.4, 1.20.6 and 1.21 installed in local\nMaven repo\n\nSimply clone the repository, navigate into the directory and run `mvn clean package`. The plugin will be in `plugin/target` and the api\nin `common/target`.\n\n\u003chr\u003e\n\n### FAQ\n\n**Why is there a plugin module if maps is not a standalone plugin?**\\\nThe plugin handles the creation, management and storage of map screens. You do not need the plugin if you make your own creation, management and\nstorage solution.\n\nPlease feel free to open an issue or contact me if you have any questions that were not answered here.\n\n\u003chr\u003e\n\n### Contributing\n\nThank you for your interest in contributing to this project! Before you do anything though please read the [contribution guidelines](CONTRIBUTING.md)\nthoroughly. Contributions that do not conform to the guidelines might be rejected.\n\n\u003chr\u003e\n\n### Sources\n\nLots of graphics features were implemented with the help of the following resources:\n\n- [Alpha Compositing - Wikipedia](https://en.wikipedia.org/wiki/Alpha_compositing#Alpha_blending)\n- [Alpha Compositing - Bartosz Ciechanowski](https://ciechanow.ski/alpha-compositing/)\n- [So you want to write a GUI framework](http://www.cmyr.net/blog/gui-framework-ingredients.html)\n- [Line drawing on a grid](https://www.redblobgames.com/grids/line-drawing.html)\n- [Midpoint ellipse drawing algorithm - GeeksforGeeks](https://www.geeksforgeeks.org/midpoint-ellipse-drawing-algorithm/)\n- [Flood fill - Wikipedia](https://en.wikipedia.org/wiki/Flood_fill)\n- [Box blur - Wikipedia](https://en.wikipedia.org/wiki/Box_blur)\n- [Porter/Duff Compositing and Blend Modes - Søren Sandmann Pedersen](http://ssp.impulsetrain.com/porterduff.html)\n- StackOverflow","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerus%2Fmaps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcerus%2Fmaps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerus%2Fmaps/lists"}