{"id":13407928,"url":"https://github.com/dmulloy2/ProtocolLib","last_synced_at":"2025-03-14T12:31:52.599Z","repository":{"id":23327849,"uuid":"26688026","full_name":"dmulloy2/ProtocolLib","owner":"dmulloy2","description":"Provides read and write access to the Minecraft protocol with Bukkit.","archived":false,"fork":false,"pushed_at":"2024-10-28T02:33:44.000Z","size":30632,"stargazers_count":1032,"open_issues_count":161,"forks_count":258,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-10-29T14:51:29.546Z","etag":null,"topics":["bukkit","packets","protocol","spigot"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"aadnk/ProtocolLib","license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmulloy2.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"License.txt","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":["dmulloy2"],"custom":["https://paypal.me/dmulloy2"]}},"created_at":"2014-11-15T17:43:47.000Z","updated_at":"2024-10-28T11:39:54.000Z","dependencies_parsed_at":"2023-02-10T13:31:20.705Z","dependency_job_id":"937b20a7-7a89-4869-80c0-240b8777df39","html_url":"https://github.com/dmulloy2/ProtocolLib","commit_stats":{"total_commits":1606,"total_committers":98,"mean_commits":"16.387755102040817","dds":"0.48256537982565384","last_synced_commit":"1e3fa2d36eaf115461a59e91903324613f1b9b43"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmulloy2%2FProtocolLib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmulloy2%2FProtocolLib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmulloy2%2FProtocolLib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmulloy2%2FProtocolLib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmulloy2","download_url":"https://codeload.github.com/dmulloy2/ProtocolLib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243104058,"owners_count":20236944,"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":["bukkit","packets","protocol","spigot"],"created_at":"2024-07-30T20:00:49.535Z","updated_at":"2025-03-14T12:31:52.590Z","avatar_url":"https://github.com/dmulloy2.png","language":"Java","readme":"# ProtocolLib\n\nCertain tasks are impossible to perform with the standard Bukkit API, and may require\nworking with and even modifying Minecraft directly. A common technique is to modify incoming\nand outgoing packets, or inject custom packets into the\nstream. This is quite cumbersome to do, however, and most implementations will break\nas soon as a new version of Minecraft has been released, mostly due to obfuscation.\n\nCritically, different plugins that use this approach may _hook_ into the same classes,\nwith unpredictable outcomes. More than often this causes plugins to crash, but it may also\nlead to more subtle bugs.\n\n### Resources\n\n* [Spigot Page](https://www.spigotmc.org/resources/protocollib.1997/)\n* [Dev Builds](https://ci.dmulloy2.net/job/ProtocolLib)\n* [JavaDoc](https://ci.dmulloy2.net/job/ProtocolLib/javadoc/index.html)\n* [Protocol Wiki](https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol)\n\n### Compilation\n\nProtocolLib is built with [Gradle](https://gradle.org/). If you have it installed, just run\n`./gradlew build` in the root project folder. Other gradle targets you may be interested in \ninclude `clean`, `test`, and `shadowJar`. `shadowJar` will create a jar with all dependencies\n(ByteBuddy) included.\n\n### A new API\n\n__ProtocolLib__ attempts to solve this problem by providing an event API, much like Bukkit,\nthat allows plugins to monitor, modify, or cancel packets sent and received. But, more importantly,\nthe API also hides all the gritty, obfuscated classes with a simple index based read/write system.\nYou no longer have to reference CraftBukkit!\n\n### Using ProtocolLib\n\nTo use this library, first add ProtocolLib.jar to your Java build path. Then, add ProtocolLib\nas a dependency or soft dependency to your plugin.yml file like any other plugin:\n\n````yml\ndepend: [ ProtocolLib ]\n````\n\nYou can also add ProtocolLib as a Maven dependency:\n\n````xml\n\u003crepositories\u003e\n  \u003crepository\u003e\n    \u003cid\u003edmulloy2-repo\u003c/id\u003e\n    \u003curl\u003ehttps://repo.dmulloy2.net/repository/public/\u003c/url\u003e\n  \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003ecom.comphenix.protocol\u003c/groupId\u003e\n    \u003cartifactId\u003eProtocolLib\u003c/artifactId\u003e\n    \u003cversion\u003e5.1.0\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n````\n\nOr use the maven dependency with gradle:\n\n```gradle\nrepositories {\n    maven { url \"https://repo.dmulloy2.net/repository/public/\" }\n}\n\ndependencies {\n    compileOnly 'com.comphenix.protocol:ProtocolLib:5.1.0'\n}\n```\n\nThen get a reference to ProtocolManager in onLoad() or onEnable() and you're good to go.\n\n````java\nprivate ProtocolManager protocolManager;\n\npublic void onLoad() {\n    protocolManager = ProtocolLibrary.getProtocolManager();\n}\n````\n\nTo listen for packets sent by the server to a client, add a server-side listener:\n\n````java\n// Disable all sound effects\nprotocolManager.addPacketListener(new PacketAdapter(\n    this,\n    ListenerPriority.NORMAL,\n    PacketType.Play.Server.NAMED_SOUND_EFFECT\n) {\n    @Override\n    public void onPacketSending(PacketEvent event) {\n        event.setCancelled(true);\n    }\n});\n````\n\nIt's also possible to read and modify the content of these packets. For instance, you can create a global\ncensor by listening for Packet3Chat events:\n\n````java\n// Censor\nprotocolManager.addPacketListener(new PacketAdapter(\n    this,\n    ListenerPriority.NORMAL,\n    PacketType.Play.Client.CHAT\n) {\n    @Override\n    public void onPacketReceiving(PacketEvent event) {\n        PacketContainer packet = event.getPacket();\n        String message = packet.getStrings().read(0);\n\n        if (message.contains(\"shit\") || message.contains(\"damn\")) {\n            event.setCancelled(true);\n            event.getPlayer().sendMessage(\"Bad manners!\");\n        }\n    }\n});\n````\n\n### Sending packets\n\nNormally, you might have to do something ugly like the following:\n\n````java\nPacketPlayOutExplosion fakeExplosion = new PacketPlayOutExplosion(\n    player.getLocation().getX(),\n    player.getLocation().getY(),\n    player.getLocation().getZ(),\n    3.0F,\n    new ArrayList\u003c\u003e(),\n    new Vec3D(\n        player.getVelocity().getX() + 1,\n        player.getVelocity().getY() + 1,\n        player.getVelocity().getZ() + 1\n    )\n);\n\n((CraftPlayer) player).getHandle().b.a(fakeExplosion);\n````\n\nBut with ProtocolLib, you can turn that into something more manageable:\n\n````java\nPacketContainer fakeExplosion = new PacketContainer(PacketType.Play.Server.EXPLOSION);\nfakeExplosion.getDoubles()\n    .write(0, player.getLocation().getX())\n    .write(1, player.getLocation().getY())\n    .write(2, player.getLocation().getZ());\nfakeExplosion.getFloat().write(0, 3.0F);\nfakeExplosion.getBlockPositionCollectionModifier().write(0, new ArrayList\u003c\u003e());\nfakeExplosion.getVectors().write(0, player.getVelocity().add(new Vector(1, 1, 1)));\n\nprotocolManager.sendServerPacket(player, fakeExplosion);\n````\n\n### Compatibility\n\nOne of the main goals of this project was to achieve maximum compatibility with CraftBukkit. And the end\nresult is quite flexible. It's likely that I won't have to update ProtocolLib for anything but bug fixes\nand new features.\n\nHow is this possible? It all comes down to reflection in the end. Essentially, no name is hard coded -\nevery field, method and class is deduced by looking at field types, package names or parameter\ntypes. It's remarkably consistent across different versions.\n","funding_links":["https://github.com/sponsors/dmulloy2","https://paypal.me/dmulloy2"],"categories":["Protocol","Projects","Plugins"],"sub_categories":["Packets","Utility"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmulloy2%2FProtocolLib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmulloy2%2FProtocolLib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmulloy2%2FProtocolLib/lists"}