{"id":16188461,"url":"https://github.com/konsumer/minecraft-python-example","last_synced_at":"2026-03-18T18:20:02.909Z","repository":{"id":46691602,"uuid":"280485507","full_name":"konsumer/minecraft-python-example","owner":"konsumer","description":"An example server for writing plugins in python","archived":false,"fork":false,"pushed_at":"2023-01-07T20:12:45.000Z","size":4594,"stargazers_count":2,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-07T13:41:16.205Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","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/konsumer.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}},"created_at":"2020-07-17T17:26:24.000Z","updated_at":"2022-09-18T20:39:48.000Z","dependencies_parsed_at":"2023-02-08T00:30:56.804Z","dependency_job_id":null,"html_url":"https://github.com/konsumer/minecraft-python-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/konsumer/minecraft-python-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fminecraft-python-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fminecraft-python-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fminecraft-python-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fminecraft-python-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/konsumer","download_url":"https://codeload.github.com/konsumer/minecraft-python-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fminecraft-python-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28620572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T23:49:58.628Z","status":"ssl_error","status_checked_at":"2026-01-20T23:47:29.996Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-10-10T07:27:02.863Z","updated_at":"2026-01-21T01:02:01.376Z","avatar_url":"https://github.com/konsumer.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# minecraft python server example\n\nThis will walk you through setting up a minecraft server that can be extended with python \u0026 writing some plugins. It uses [minecraft-python](https://github.com/Macuyiko/minecraft-python) to make things more fun \u0026 easy than writing plugins directly in java.\n\n![my dev-environment](./screenshots/1.png)\n\n## server\n\nFirst, we need to setup a server:\n\n* Install [java](https://www.java.com/ES/download/) on your system\n* Install a text-editor. I like [VSCode](https://code.visualstudio.com/). I also like to install `Python` and `Python Indent` extensions.\n* Make a directory called `server/`\n* Download [paper](https://papermc.io/downloads) (choose latest version) and save it in `server/`\n* Copy files in `server/` from this repo to your `server/` dir\n* Open a cmd-shell (windows) or terminal in `server/`. Run `./start` to start the server once, and edit eula.txt to accept it.\n* Download the latest [minecraft python.jar](https://github.com/Macuyiko/minecraft-python/releases) and put it in `server/plugins`\n* Run `./start` again, and then `op` yourself in the minecraft-terminal, so you can run everything.\n\nIf you are using [VSCode](https://code.visualstudio.com/), you can open the built-in terminal (with `Ctrl-Backtick`), and run these directly.\n\n### REPL\n\nThere is a [python REPL](https://mcpyrepl.surge.sh) available for the server running on localhost, so you can try stuff out, and explore the available APIs. Even through it's a remote website, nothing is sent to the remote server, and it communicates directly with your local python plugin.\n\n### file-locations\n\n* `server/python-plugins` - put your plugins here\n* `server/python` - put your shared library files here, so you can share code between different plugins. Minecraft python makes a script called `mcapi.py`, which you should have a look at (see the stuff below `Built-in helper functions`) that gives you some utilities for your plugins, but you can add whatever you want in this dir, and use it in your plugins.\n\n## plugins\n\nYour first goto-reference for how to do things should be the [Bukkit API docs](https://hub.spigotmc.org/javadocs/bukkit/index.html). The python API mostly follows java-bukkit, but sometimes there are little things you have to do, to work around jython-binding complexity. You can see some examples of this, if you look at `server/python/mcapi.py`.\n\n### yell-o world\n\nOur first plugin will just tell all players about minecraft python, every time someone joins. Make a script `server/python-plugins/yell-o.py` that looks like this:\n\n```python\nfrom mcapi import *\nfrom org.bukkit.event.player import PlayerJoinEvent\n\n# when a player joins, yell at everyone\n@asynchronous()\ndef yello_event(e):\n    player = e.getPlayer()\n    yell(\"%s just joined. Hope they like python!!!\" % (player.getName()))\n\nadd_event_listener(PlayerJoinEvent, yello_event)\n```\n\nWe decorate the handler with `@asynchronous()`, to make sure it runs asynchronously (non-blocking, multiple events at once.) Most event-handlers should look like this.\n\nRun `/reload confirm`. After this, when a new player joins, it will spam everyone about python. \n\n\n### exploding chickens\n\nLet's make a new command that spawns a chicken, and explodes it. We want it to warn everyone, countdown, and then explode.\n\nMake a script `server/python-plugins/chickenboom.py` that looks like this:\n\n```python\n# -*- coding: utf-8 -*-\nfrom mcapi import *\nfrom time import sleep\n\n# deploy an exploding chicken\n@asynchronous()\ndef cmd_chickenboom(caller, params):\n    yell(u\"§cWARNING!!!§f Exploding chicken deployed by %s!\" % caller.getName())\n    chicken = spawn(lookingat(caller))\n    for i in range(5, 0, -1):\n        yell(\"T minus %d and counting...\" % i)\n        sleep(1)\n    explosion(location(chicken), power=2)\n\nadd_command('chickenboom', cmd_chickenboom)\n```\n\nI use [color-codes](https://www.digminecraft.com/lists/color_list_pc.php) to make my warning stand-out, and use a count-down (using python's `sleep`) to give players some warning. Make sure to add the `u` to your message, so python knows it has special characters, and also `# -*- coding: utf-8 -*-` to setup the correct extended language for the file. I also included the name of the player that deployed the chicken, so everyone knows.\n\nRun `/reload confirm`, and you can run `/chickenboom` to spawn an exploding chicken.\n\n#### Make it your own\n\nMaybe you don't want an exploding chicken, but instead an exploding parrot. Maybe also you don't want a countdown. Obviously, this is extremely dangerous, but the wizard's life is frought with peril. You can choose what `spawn()` spits out with the `type` parameter. Here is my `/parrotboom` spell:\n\n```python\n# -*- coding: utf-8 -*-\nfrom mcapi import *\nfrom time import sleep\n\n# deploy an exploding parrot\n@asynchronous()\ndef cmd_parrotboom(caller, params):\n    yell(u\"§cWARNING!!!§f Exploding parrot deployed by %s!\" % caller.getName())\n    parrot = spawn(lookingat(caller), EntityType.PARROT)\n    sleep(1)\n    explosion(location(parrot), power=2)\n\nadd_command('parrotboom', cmd_parrotboom)\n```\n\nI added a `sleep` for 1 second, just so the newly-created parrot has a second to contemplate their existance, before being turned into a bomb.\n\nYou can use the [python REPL](https://mcpyrepl.surge.sh) to discover other `EntityType`s:\n\n```python\nfrom mcapi import *\ndir(EntityType)\n```\n\n\n### lightning blocks\n\nLet's make it so whenever a player breaks a block, lightning strikes. Make a file called `server/python-plugins/lightningblock.py`\n\n```python\nfrom mcapi import *\nfrom org.bukkit.event.block import BlockBreakEvent\n\n# when a player breaks a block, shoot lightning\n@asynchronous()\ndef block_break_event(e):\n    player = e.getPlayer()\n    yell('you break a block, you get lightning %s!' % player.getName())\n    bolt(lookingat(player))\n\nadd_event_listener(BlockBreakEvent, block_break_event)\n```\n\n#### fireworks\n\nYou can also make it do fireworks:\n\n```python\nfrom mcapi import *\nfrom org.bukkit.event.block import BlockBreakEvent\n\n# when a player breaks a block, shoot fireworks\n@asynchronous()\ndef block_break_event(e):\n    player = e.getPlayer()\n    yell('you break a block, you get fireworks %s!' % player.getName())\n    fireworks(lookingat(player))\n\nadd_event_listener(BlockBreakEvent, block_break_event)\n```\n\n## more to come\n\nI will work out some other tutorials. Here are some ideas:\n\n* Items that do something when wielded\n* Figure out how to chat to just 1 user\n* AI for NPCs\n* Generate a maze\n* build a schematic file\n* Adventure-mode RPG (with custom advancements)\n* Other ideas?","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonsumer%2Fminecraft-python-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkonsumer%2Fminecraft-python-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonsumer%2Fminecraft-python-example/lists"}