{"id":29097394,"url":"https://github.com/lambdaisland/witchcraft-plugin","last_synced_at":"2025-06-28T13:42:13.686Z","repository":{"id":62431858,"uuid":"399125306","full_name":"lambdaisland/witchcraft-plugin","owner":"lambdaisland","description":"Add Clojure support (and an nREPL) to any Bukkit-based Minecraft server","archived":false,"fork":false,"pushed_at":"2022-01-02T21:41:28.000Z","size":49,"stargazers_count":27,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-16T13:24:19.424Z","etag":null,"topics":["minecraft"],"latest_commit_sha":null,"homepage":"","language":"Clojure","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/lambdaisland.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2021-08-23T14:01:05.000Z","updated_at":"2025-04-30T04:17:22.000Z","dependencies_parsed_at":"2022-11-01T21:00:43.388Z","dependency_job_id":null,"html_url":"https://github.com/lambdaisland/witchcraft-plugin","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/lambdaisland/witchcraft-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fwitchcraft-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fwitchcraft-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fwitchcraft-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fwitchcraft-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambdaisland","download_url":"https://codeload.github.com/lambdaisland/witchcraft-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fwitchcraft-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261033536,"owners_count":23100299,"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":["minecraft"],"created_at":"2025-06-28T13:42:07.822Z","updated_at":"2025-06-28T13:42:13.681Z","avatar_url":"https://github.com/lambdaisland.png","language":"Clojure","funding_links":["http://opencollective.com/lambda-island"],"categories":[],"sub_categories":[],"readme":"# witchcraft-plugin\n\nA Clojure plugin for Bukkit-based minecraft servers (Paper, Spigot, Glowstone)\n\nIt provides\n\n- an embedded nREPL server for interactive creative coding\n- Clojure dependency management through `deps.edn`\n- loading of Clojure-based server modifications at boot\n\n## Installation\n\nDownload the plugin for your server type and version from the\n[releases](https://github.com/lambdaisland/witchcraft-plugin/releases) page, and\ndrop it in your server's `plugins/` directory.\n\n## Usage\n\nThe first time you start the server you should see something like this:\n\n```\n[09:33:14 INFO]: [Witchcraft] Enabling Witchcraft v0.0.7\n[09:33:14 INFO]: [Witchcraft] Setting PluginClassloader as Context classloader: PluginClassLoader{plugin=Witchcraft v0.0.7, pluginEnabled=true, url=plugins/witchcraft-plugin-0.0.7-for-paper-1.17-shaded.jar}\n[09:33:26 INFO]: [Witchcraft] No plugins/witchcraft.edn found, creating default.\n[09:33:26 INFO]: [Witchcraft] No deps.edn found, creating default.\n[09:33:29 INFO]: [Witchcraft] init: (require (quote lambdaisland.witchcraft))\n[09:33:30 INFO]: [Witchcraft] init: (lambdaisland.witchcraft/init-xmaterial!)\n[09:33:36 INFO]: nREPL server started on port 25555 on host localhost - nrepl://localhost:25555\n```\n\nNow you can connect with your nREPL-capable editor to port 25555 and start\nmanipulating the game. If you get any errors at this stage please file [an\nissue](https://github.com/lambdaisland/witchcraft-plugin/issues).\n\nIf you are new to Clojure and are unsure which development environment to pick\nthen we recommend [Calva](https://calva.io/) for Visual Studio Code. For a\nfairly complete list of Clojure-capable editors see this [overview by\npractical.li](https://practical.li/clojure/clojure-editors/).\n\n## Configuration\n\nThere are two files that are used to configure the plugin,\n`plugins/witchcraft.edn`, and `deps.edn`. Both are in the [EDN\nformat](https://github.com/edn-format/edn) (Extensible Data Notation) commonly\nused in the Clojure world.\n\n`plugins/witchcraft.edn` is the configuration for the plugin itself. Here you\ncan set things like the nREPL port, or configure code to load when the server\nstarts.\n\n`deps.edn` is Clojure's way of declaring dependencies, similar to a `pom.xml` or\n`package.json`.\n\nThe first time you run the server it will create a `deps.edn` and\n`plugins/witchcraft.edn`. It will also start an nREPL server, and invoke any\n`:init` commands you have in your `witchcraft.edn`.\n\n### witchcraft.edn\n\n```clojure\n{:nrepl\n {:port 25555\n  :middleware [refactor-nrepl.middleware/wrap-refactor\n               cider.nrepl/cider-middleware]}\n :init [(require 'lambdaisland.witchcraft)\n        (lambdaisland.witchcraft/init-xmaterial!)]\n :deps true}\n```\n\n- `:nrepl` are options passed to `nrepl.cmdline/dispatch-commands`, if you don't\n  want to run an nREPL server, use `:nrepl false`\n- `:deps` can be `true` (load dependencies from `deps.edn`), `false` (don't), or\n  a map with options for tools.deps, e.g. `:deps {:aliases [:my-alias]}`\n- `:init` is a sequence of Clojure forms that are evaluated after starting the\n  server. You can use this to load additional Clojure modifications when booting\n  the server\n  \n### deps.edn\n\nThe plugin JAR only bundles Clojure itself (the compiler and core library),\nnREPL (for interaction), and clojure.tools.deps (for `deps.edn` support). Any\nadditional dependencies (e.g. nREPL middleware,\n[Witchcraft](https://github.com/lambdaisland/witchcraft),\n[clj-minecraft](https://github.com/CmdrDats/clj-minecraft)) can be loaded by\nadding them to `deps.edn`.\n\nThrough `deps.edn` you can pull in dependencies from Maven/Clojars, or directly\nfrom Github. See the [Clojure Deps and CLI Guide](https://clojure.org/guides/deps_and_cli) \nfor how to set up `deps.edn`.\n\nWhen no `deps.edn` is present the plugin will create one on first use, which\nloads the [witchcraft library](https://github.com/lambdaisland/witchcraft), as\nwell as the CIDER and refactor-nrepl middlewares for nREPL, which will look\nsomething like this:\n\n```clojure\n{:deps\n {com.lambdaisland/witchcraft\n  {:git/url \"https://github.com/lambdaisland/witchcraft\"\n   :git/sha \"...\"}\n  refactor-nrepl/refactor-nrepl {:mvn/version \"2.5.1\"}\n  cider/cider-nrepl {:mvn/version \"0.26.0\"}}}\n```\n\nYou can use [lambdaisland/classpath](https://github.com/lambdaisland/classpath)\nto reload your `deps.edn` without having to restart the server. (see\n`lambdaisland.classpath/update-classpath!` or\n`lambdaisland.classpath.watch-deps/start!`).\n\n## Build\n\nTo build the plugin yourself you need a recent version of Clojure CLI, see the\n[Clojure getting started](https://clojure.org/guides/getting_started) guide. You\nalso need Java 16 (earlier versions from Java 12 onwards might work too).\n\n```\n$ clojure --version\nClojure CLI version 1.10.3.943\n\n$ java -version\nopenjdk version \"16.0.1\" 2021-04-20\n```\n\nThen use the build-plugin task, you need to tell it which server you will be\nusing, and the API version. \n\n```\nclojure -T:build-plugin build :server glowstone :api-version 1.12\nclojure -T:build-plugin build :server paper :api-version 1.17 \nclojure -T:build-plugin build :server spigot :api-version 1.17 \n```\n\nThese will create two files each \n\n- `target/witchcraft-plugin-\u003cversion\u003e-for-\u003cserver\u003e-\u003capi-version\u003e.jar`\n- `target/witchcraft-plugin-\u003cversion\u003e-for-\u003cserver\u003e-\u003capi-version\u003e-shaded.jar`\n\nIt is recommended to use the shaded version. For Glowstone you must use the\nshaded version. (Naether pulls in an old plexus-utils, which conflicts with\ntools.deps.alpha).\n\nCopy the plugin jar to your server's `plugins` directory\n\n```\n$ cp target/witchcraft-plugin-0.0.7-for-paper-1.17-shaded.jar ~/PaperMC/plugins/\n```\n\n\u003c!-- opencollective --\u003e\n## Lambda Island Open Source\n\n\u003cimg align=\"left\" src=\"https://github.com/lambdaisland/open-source/raw/master/artwork/lighthouse_readme.png\"\u003e\n\n\u0026nbsp;\n\nwitchcraft-plugin is part of a growing collection of quality Clojure libraries created and maintained\nby the fine folks at [Gaiwan](https://gaiwan.co).\n\nPay it forward by [becoming a backer on our Open Collective](http://opencollective.com/lambda-island),\nso that we may continue to enjoy a thriving Clojure ecosystem.\n\nYou can find an overview of our projects at [lambdaisland/open-source](https://github.com/lambdaisland/open-source).\n\n\u0026nbsp;\n\n\u0026nbsp;\n\u003c!-- /opencollective --\u003e\n\n\u003c!-- contributing --\u003e\n## Contributing\n\nEveryone has a right to submit patches to witchcraft-plugin, and thus become a contributor.\n\nContributors MUST\n\n- adhere to the [LambdaIsland Clojure Style Guide](https://nextjournal.com/lambdaisland/clojure-style-guide)\n- write patches that solve a problem. Start by stating the problem, then supply a minimal solution. `*`\n- agree to license their contributions as MPL 2.0.\n- not break the contract with downstream consumers. `**`\n- not break the tests.\n\nContributors SHOULD\n\n- update the CHANGELOG and README.\n- add tests for new functionality.\n\nIf you submit a pull request that adheres to these rules, then it will almost\ncertainly be merged immediately. However some things may require more\nconsideration. If you add new dependencies, or significantly increase the API\nsurface, then we need to decide if these changes are in line with the project's\ngoals. In this case you can start by [writing a pitch](https://nextjournal.com/lambdaisland/pitch-template),\nand collecting feedback on it.\n\n`*` This goes for features too, a feature needs to solve a problem. State the problem it solves, then supply a minimal solution.\n\n`**` As long as this project has not seen a public release (i.e. is not on Clojars)\nwe may still consider making breaking changes, if there is consensus that the\nchanges are justified.\n\u003c!-- /contributing --\u003e\n\n\u003c!-- license --\u003e\n## License\n\nCopyright \u0026copy; 2021 Arne Brasseur and Contributors\n\nLicensed under the term of the Mozilla Public License 2.0, see LICENSE.\n\u003c!-- /license --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaisland%2Fwitchcraft-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambdaisland%2Fwitchcraft-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaisland%2Fwitchcraft-plugin/lists"}