{"id":18187753,"url":"https://github.com/bonka-software/mirage","last_synced_at":"2025-04-02T03:31:23.764Z","repository":{"id":252514470,"uuid":"840668771","full_name":"Bonka-Software/Mirage","owner":"Bonka-Software","description":"Custom map loading system for minecraft servers. It's able to reset maps to their saved state on server startup and during runtime. The world tracking system also allows for runtime rollbacks without kicking players.","archived":false,"fork":false,"pushed_at":"2025-01-31T14:43:24.000Z","size":110,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-16T08:11:32.261Z","etag":null,"topics":["management","minecraft","paper","plugin","spigot","world"],"latest_commit_sha":null,"homepage":"https://bonka.gg/","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/Bonka-Software.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":"2024-08-10T10:16:35.000Z","updated_at":"2025-02-16T11:05:11.000Z","dependencies_parsed_at":"2024-10-27T20:11:19.296Z","dependency_job_id":"6f41a926-5802-4d5a-819d-29aa3bb7f8fd","html_url":"https://github.com/Bonka-Software/Mirage","commit_stats":null,"previous_names":["bonka-software/mirage"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonka-Software%2FMirage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonka-Software%2FMirage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonka-Software%2FMirage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonka-Software%2FMirage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bonka-Software","download_url":"https://codeload.github.com/Bonka-Software/Mirage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246751197,"owners_count":20827848,"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":["management","minecraft","paper","plugin","spigot","world"],"created_at":"2024-11-03T02:03:09.949Z","updated_at":"2025-04-02T03:31:23.757Z","avatar_url":"https://github.com/Bonka-Software.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mirage\n\n[Available on Spigot](https://www.spigotmc.org/resources/mirage.119105/)\n\nCustom map loading system for minecraft servers.\nIt's able to reset maps to their saved state on server startup and during runtime.\nThe world tracking system also allows for runtime rollbacks without kicking players.\n\n![WorldReset-optimize](https://github.com/user-attachments/assets/35efe830-a17c-4dc8-9181-56f070bf9401)\n\n---\n\n#### Version 1.1.6\nThis version of Mirage contains:\n- Mirage world loading\n- Backup system\n- Rollbacks\n- Per world (in-game) configurability\n- Per player chunk rendering (Mainly available through the API)\n\n![WorldSwitching-ezgif com-optimize](https://github.com/user-attachments/assets/b2a496a7-3b4b-4d18-8eb5-2f7d5fd5ea2a)\n\nThese are all the same world, just rendering as different mirage worlds! Using /world renderas \u003cname\u003e \u003cworld\u003e \u003cvisualizer\u003e\n\n---\n\n## Maven\n\n```xml\n\u003crepository\u003e\n    \u003cid\u003ebonka\u003c/id\u003e\n    \u003curl\u003ehttps://nexus.bonka.gg/repository/maven-public/\u003c/url\u003e\n\u003c/repository\u003e\n```\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003egg.bonka\u003c/groupId\u003e\n    \u003cartifactId\u003eMirage\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.6\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\n---\n\n## API\n\nMirage uses 2 singletons from where you can easily save, load, backup and rollback mirage worlds!\nThese singletons are `WorldsDirectoryManager` and `WorldsTracker`.\n\nMirage 1.1 also introduces a new Singleton `ChunkRenderingSystem` for rendering fake chunks.\n\nAlso, don't forget to add mirage as a dependency in you `plugin.yml`:\u003cbr\u003e\n`depend: [Mirage]` or `softdepend: [Mirage]`\n\n### WorldsDirectoryManager\n\nThe worlds directory manager is what makes Mirage tick.\nUse `WorldsDirectoryManager.getMirageWorld(String worldName)` to convert any world into a mirage world!\nYou can then use `WorldsDirectoryManager.getInstance()` to save, load, remove, or backup the world.\nAlthough it's important to note that the WorldsDirectoryManager is not responsible for runtime worlds!\nSo make sure you unload your worlds before doing anything with them.\n\nexample: \n```java\nvoid deleteWorld(String worldName) {\n    World world = Bukkit.getWorld(worldName);\n\n    for(Player player : world.getPlayers()) {\n        player.kick(Component.text(\"World is being deleted!\"));\n    }\n\n    Bukkit.unloadWorld(world, false);\n\n    WorldsDirectoryManager.getInstance().removeWorldAsync(WorldsDirectoryManager.getMirageWorld(worldName), (success, message) -\u003e {\n        if (success) {\n            player.sendMessage(Chat.format(String.format(\"World: %s has been removed successfully!\", worldName), ChatColor.SUCCESS));\n        } else {\n            player.sendMessage(Chat.format(message, ChatColor.ERROR));\n        }\n    });\n}\n```\n\nI generally recommend using the Async WorldsDirectoryManager methods, keep in mind that the callback is also on that async though!\n\n### WorldsTracker\n\nOnly relevant for worlds that have use-rollback enabled!\nStores the initial state of chunks in memory and actively keeps track of changed blocks of the worlds it is tracking.\n\nUse `WorldsTracker.getInstance().getTrackedWorld(String worldName)` to get a tracked world.\nYou can either update the tracked world, meaning you save the current state of the world to memory (Not to disk, you can only do that through the WorldsDirectoryManager).\nOr you can reset the world to its previous state (again, memory only, the world won't get reloaded from disk, this is impossible without kicking players from the world).\n\nThese function are: `trackedWorld.updateSave()` and `trackedWorld.reset()`.\n\n![WorldSave](https://github.com/user-attachments/assets/bf5177c4-435f-4ced-88e5-f7dd992fc19c)\n\n### ChunksRenderingSystem\n\nUsed to render different chunks or worlds for different players.\nThis system may be useful if you run a RPG server, or other very linear games.\nKeep in mind that this is rendering only, players can't really interact with fake chunks out of the box.\nYou'll have to implement some other programming trickery to support interactions. \nBut this system is perfect for rendering out of bounds chunks!\n\nThis system can be accessed via the `ChunksRenderingSystem` singleton.\n\n```java\nvoid RenderWorldAs(Player player, World world, World visualizer) {\n    //Renders the world as the visualizer for the given player\n    ChunkRenderingSystem.getInstance().renderWorldAs(player, world, visualizer);\n\n    //Don't forget to reload the player's chunks when you change their chunks\n    ChunkRenderingSystem.getInstance().updateChunks(receiver);   \n}\n```\n\n---\n\n## Server version Paper 1.21.4\n[Download directly here](https://api.papermc.io/v2/projects/paper/versions/1.21.4/builds/134/downloads/paper-1.21.4-134.jar)\nor [Browse paper builds](https://papermc.io/downloads/all)\n\n---\n\n## How to start:\n- Download all maven dependencies\n- Follow the steps described in [paper nms maven plugin's readme](https://github.com/Alvinn8/paper-nms-maven-plugin)\n- Follow the steps described in the [Server Readme](server/README.md)\n- Run jetbrains .run config and a test server automatically starts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonka-software%2Fmirage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonka-software%2Fmirage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonka-software%2Fmirage/lists"}