{"id":18011288,"url":"https://github.com/johnnyjayjay/spigot-maps","last_synced_at":"2025-03-26T15:32:42.835Z","repository":{"id":138563310,"uuid":"181953441","full_name":"JohnnyJayJay/spigot-maps","owner":"JohnnyJayJay","description":"A library to simplify the use of customised maps in Spigot.","archived":false,"fork":false,"pushed_at":"2022-09-13T16:14:45.000Z","size":165,"stargazers_count":49,"open_issues_count":6,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-22T02:03:04.874Z","etag":null,"topics":["api","hacktoberfest","java","library","minecraft","spigot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JohnnyJayJay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2019-04-17T19:12:58.000Z","updated_at":"2024-11-19T11:50:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"75b77042-8038-4ff0-9931-4fa67d2f81e8","html_url":"https://github.com/JohnnyJayJay/spigot-maps","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnnyJayJay%2Fspigot-maps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnnyJayJay%2Fspigot-maps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnnyJayJay%2Fspigot-maps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnnyJayJay%2Fspigot-maps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JohnnyJayJay","download_url":"https://codeload.github.com/JohnnyJayJay/spigot-maps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245681556,"owners_count":20655218,"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":["api","hacktoberfest","java","library","minecraft","spigot"],"created_at":"2024-10-30T03:08:53.988Z","updated_at":"2025-03-26T15:32:42.821Z","avatar_url":"https://github.com/JohnnyJayJay.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spigot-Maps\n\nA small library that makes the use of customised maps in Spigot very easy.\n\n## Features\n- Dynamic map rendering (based on render context)\n- (Animated) Text, image and animated gif rendering with convenient usage\n- Base class for own renderer implementations\n- API to store renderers persistently\n- Tools to resize / crop / divide images so that they fit the minecraft maps\n- Convenient builder classes and factory methods\n\n**[YOU CAN FIND AN EXAMPLE PLUGIN HERE](./example-plugin)**\n\nTo test this plugin, do\n```\ngit clone https://github.com/johnnyjayjay/spigot-maps.git\ncd spigot-maps/example-plugin\n./gradlew shadowJar \n```\nThen add `example-plugin-1.0-TEST.jar` (found in `build/libs`) to your plugins folder\n\n## Add as dependency\n\n### Maven\n\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003ejcenter\u003c/id\u003e\n        \u003curl\u003ehttps://jcenter.bintray.com/\u003c/url\u003e\n    \u003c/repository\u003e\n \u003c/repositories\u003e\n\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.github.johnnyjayjay\u003c/groupId\u003e\n        \u003cartifactId\u003espigot-maps\u003c/artifactId\u003e\n        \u003cversion\u003e2.1.1\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### Gradle\n\n```groovy\nrepositories {\n    jcenter()\n}\n\ndependencies {\n    implementation(\"com.github.johnnyjayjay:spigot-maps:2.1.1\")\n}\n```\n\n### I don't use a build tool\n\nAn already built .jar file can be found [here](https://github.com/JohnnyJayJay/spigot-maps/releases).\nDownload it and add it to your project like any other jar file (Eclipse -\u003e Build Path, IntelliJ -\u003e Add as Library).\n\n## Quick Start\n\nYou've got various options when creating renderers and maps:\n\n```java\nBufferedImage catImage = ImageIO.read(file); // read an image from a source, e.g. a file\ncatImage = ImageTools.resizeToMapSize(catImage); // resize the image to the minecraft map size\nImageRenderer catRenderer = ImageRenderer.builder()\n        .addPlayers(player1, player2) // set the players this map should be rendered to (omitting this means it renders for everyone)\n        .image(catImage) // set the image to render\n        .build(); // build the instance\n\nDimension mapSize = ImageTools.MINECRAFT_MAP_SIZE; // the dimensions of a Minecraft map (in pixels)\nSimpleTextRenderer messageRenderer = SimpleTextRenderer.builder()\n        .addLines(\"Cats\", \"are\", \"so\", \"cute\") // set the lines that will be drawn onto the map\n        .addPlayers(player1, player2)\n        .font(myFont) // set a text font\n        .startingPoint(new Point(mapSize.width / 2, mapSize.height / 2)) // start in the middle\n        .build(); // build the instance \n\nRenderedMap map = MapBuilder.create() // make a new builder\n        .store(myStorage) // set a MapStorage for the map\n        .addRenderers(catRenderer, messageRenderer) // add the renderers to this map\n        .world(player1.getWorld()) // set the world this map is bound to, e.g. the world of the target player\n        .build(); // build the map\n\nItemStack mapItem = map.createItemStack(); // get an ItemStack from this map to work with\n```\n\nThis example would result in a map that has an image of a cat in the background and the text \"Cats are so cute\" in the foreground.\n\nYou can still mutate the renderers afterwards:\n```java\nmessageRenderer.setText(\"Cats\\nare\\nstill\\ncute\");\n```\nNote that this will only have effect if `renderOnce` is set to `false` while building. \nThe reason for that decision is performance. Only rendering once saves resources, but \ndisables later modification.\nIf you want to mutate a renderer after building but then leave it that way, you may call\n```java\nmessageRenderer.stopRendering();\n```\nto save the resources.\n\n### Shortcuts\n\nThere are even quicker ways to accomplish some of these operations.\n\n**Create an ImageRenderer with just an image**:\n\n```java\nImageRenderer renderer = ImageRenderer.create(image, player1, player2); // the player arguments are optional\n```\n\n**Create an ImageRenderer that renders a single color (e.g. as a background for text)**:\n\n```java\nImageRenderer backgroundRenderer = ImageRenderer.createSingleColorRenderer(Color.BLUE, player1, player2) // the player arguments are optional\n```\n\nSee `ImageTools.createSingleColoredImage(Color)` to get an instance of `BufferedImage` for that matter.\n\n**Create a TextRenderer with just some lines of text**:\n\n```java\nSimpleTextRenderer renderer = SimpleTextRenderer.create(\"This\", \"is\", \"noice\");\n```\n\n**Create a RenderedMap with just some MapRenderers**:\n\n```java\nRenderedMap map = RenderedMap.create(renderer1, renderer2); // not providing any renderers returns a map without renderers\n```\n\n### Advanced\n\n#### Gifs \n\nThis library can handle animated gifs using `GifRenderer` and `GifImage`.\nInstances of `GifImage` can be obtained via an instance of `GifDecoder` from this library's dependencies:\n```java\nGifDecoder decoder = new GifDecoder();\ndecoder.read(\"./example.gif\"); // this also works with URLs, InputStreams etc.\nGifImage gif = GifImage.fromDecoder(decoder);\n```\nFor more info about `GifDecoder`, look at [this](https://github.com/rtyley/animated-gif-lib-for-java).\n\nYou can also implement an algorithm to decode gifs yourself and then make use of `GifImage#create(List\u003cFrame\u003e)`.\n\n`GifRenderer`s are created like any other renderer:\n```java\nGifRenderer renderer = GifRenderer.builder()\n        .gif(gif) // set the GifImage we just created\n        .repeat(5) // repeat the gif 5 times: to repeat it indefinitely, omit this setting or set it to GifRenderer.REPEAT_FOREVER\n        .build();\n```\nThis renderer stops rendering automatically after 5 repetitions and \ncan now be added to a `MapView` / `RenderedMap` as shown above.\n\n#### Animated Text\n\nText doesn't have to be static. This library provides a map renderer that renders text character by character.\n```java\nAnimatedTextRenderer renderer = AnimatedTextRenderer.builder()\n        .addText(\"This text will appear char by char.\")\n        .charsPerSecond(10) // 10 characters should appear each second\n        .delay(20) // start the animation after 20 ticks (1 second)\n        .build();\n```\nThis renderer automatically stops rendering after having finished.\n\n#### Splitting images\n\nImages that take more than 1 map to display can be created using `ImageTools.divideIntoMapSizedParts(BufferedImage, boolean)`.\nThis uses an algorithm that makes a square version of the image first. How this is done can be determined via the second \n`boolean` parameter. If it is set to `true`, a square cropped out from the middle of the image will be used \n(if the image is big enough). If it is `false`, the whole image will be resized to 1:1.\n\n```java\nList\u003cBufferedImage\u003e parts = ImageTools.divideIntoMapSizedParts(image, true);\n```\n\n**The exact same methods are available to `GifImage`s.**\n\nTo turn these into map items:\n\n```java\nfor (BufferedImage part : parts) {\n    ImageRenderer renderer = ImageRenderer.create(part);\n    ItemStack mapItem = RenderedMap.create(renderer).createItemStack();\n    // do something with it\n}\n```\n\nOr, if you want to do it stream-like:\n```java\nparts.stream()\n        .map(ImageRenderer::create)\n        .map(RenderedMap::create)\n        .map(RenderedMap::createItemStack)\n        .forEach((mapItem) -\u003e {\n    // do something with it\n})\n```\n\n#### Using MapStorage\n\nThe `MapStorage` API makes it possible to save renderers persistently. To utilise it, you have to implement MapStorage:\n\n```java\npublic class FileStorage implements MapStorage {\n\n    @Override\n    public void store(int id, MapRenderer renderer) {\n        // serialize the renderer associated with the given id\n    }\n    \n    @Override\n    public boolean remove(int id, MapRenderer renderer) {\n        // remove the given renderer's association with the given id\n    }\n    \n    @Override\n    public List\u003cMapRenderer\u003e provide(int id) {\n        // fetch / deserialize / read all renderers stored for the given id\n    }\n}\n```\n\nThen, do the following (e.g. on start up):\n```java\nInitializationListener.register(new FileStorage(), plugin);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnyjayjay%2Fspigot-maps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnnyjayjay%2Fspigot-maps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnyjayjay%2Fspigot-maps/lists"}