{"id":26062008,"url":"https://github.com/okaeripoland/okaeri-poly","last_synced_at":"2025-04-11T10:58:21.793Z","repository":{"id":119535953,"uuid":"414347520","full_name":"OkaeriPoland/okaeri-poly","owner":"OkaeriPoland","description":"Enterprise grade Minecraft scripting adapter for Groovy (formerly also JavaScript, and Python)","archived":false,"fork":false,"pushed_at":"2024-08-09T22:14:38.000Z","size":431,"stargazers_count":13,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-25T07:22:21.744Z","etag":null,"topics":["bukkit","groovy","javascript","minecraft","paper","python","script","scripting","spigot"],"latest_commit_sha":null,"homepage":"","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/OkaeriPoland.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":"2021-10-06T19:38:48.000Z","updated_at":"2024-12-28T22:01:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"d14c2fcc-5ba3-4fa5-8be5-67df4f47a1df","html_url":"https://github.com/OkaeriPoland/okaeri-poly","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OkaeriPoland%2Fokaeri-poly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OkaeriPoland%2Fokaeri-poly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OkaeriPoland%2Fokaeri-poly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OkaeriPoland%2Fokaeri-poly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OkaeriPoland","download_url":"https://codeload.github.com/OkaeriPoland/okaeri-poly/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248381678,"owners_count":21094524,"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","groovy","javascript","minecraft","paper","python","script","scripting","spigot"],"created_at":"2025-03-08T15:49:02.935Z","updated_at":"2025-04-11T10:58:21.769Z","avatar_url":"https://github.com/OkaeriPoland.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Okaeri Poly\n\n![License](https://img.shields.io/github/license/OkaeriPoland/okaeri-poly)\n![Total lines](https://img.shields.io/tokei/lines/github/OkaeriPoland/okaeri-poly)\n![Repo size](https://img.shields.io/github/repo-size/OkaeriPoland/okaeri-poly)\n![Contributors](https://img.shields.io/github/contributors/OkaeriPoland/okaeri-poly)\n[![Discord](https://img.shields.io/discord/589089838200913930)](https://discord.gg/hASN5eX)\n\nEnterprise grade Minecraft scripting adapter for Groovy (formerly also JavaScript, and Python). Created with [okaeri-platform](https://github.com/OkaeriPoland/okaeri-platform).\n\n## Requirements\n\nJava 17 or newer. It is recommended not to run other plugins using Groovy, with the exception to plugins using Poly as a script provider and a dependency.\n\n## Supported platforms\n\n- **[Bukkit](https://github.com/OkaeriPoland/okaeri-poly/tree/master/bukkit)**: Spigot/Paper minecraft server plugin (**disclaimer**: requires version `1.13` or newer)\n- ~~**[Velocity](https://github.com/OkaeriPoland/okaeri-poly/tree/master/velocity)**: Velocity minecraft proxy plugin~~ (incoming)\n\n## Installation\n\nGrab latest [release](https://github.com/OkaeriPoland/okaeri-poly/releases) jar for your platform and install it like any other plugin, e.g. put in `plugins/` for Spigot/Paper and Velocity\nservers.\n\nPut your script files inside `plugins/Poly/scripts/` directory. File extension will determine backend to be used (`groovy`, `js`, `py`).\n\n## Development\n\nCommand support, event listeners, and scheduler can be accessed through `script` object/variable helper. This ensures script unloading unregisters commands, listeners, and cancels pending tasks.\n\n```groovy\n@BaseScript BukkitGroovyScript script\n\nimport eu.okaeri.poly.api.bukkit.BukkitGroovyScript\nimport groovy.transform.BaseScript\nimport org.bukkit.event.player.PlayerJoinEvent\n\n// groovy example (with @BaseScript)\nlisten(PlayerJoinEvent) { event -\u003e\n    logger.info(\"${event.player.name} joined the game!\")\n}\n```\n\n```groovy\nimport org.bukkit.event.player.PlayerJoinEvent\n\n// groovy example (dynamic properties)\nscript.listen(PlayerJoinEvent) { event -\u003e\n    logger.info(\"${event.player.name} joined the game!\")\n}\n```\n\n### Bukkit\n\n| Backend    | Helper                                                                                                                                                   | Note                                                                                                                               |\n|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|\n| Groovy     | [BukkitGroovyHelper](https://github.com/OkaeriPoland/okaeri-poly/blob/master/bukkit-api/src/main/java/eu/okaeri/poly/api/bukkit/BukkitGroovyHelper.java) | Exposes additional closure based methods for even better typing support. Use is optional and BukkitScriptHelper should work too.   |\n\nAdditional global variables:\n\n- `plugin`: instance of `eu.okaeri.poly.bukkit.PolyPlugin`\n- `logger`: instance of `java.util.logging.Logger`\n- `server`: instance of `org.bukkit.Server`\n\nDemo project: [bukkit-example-groovy](https://github.com/OkaeriPoland/okaeri-poly/tree/master/bukkit-example-groovy), [bukkit-example-javascript](https://github.com/OkaeriPoland/okaeri-poly/tree/master/bukkit-example-javascript)\n\n### Velocity\n\n| Backend    | Helper                                                                                                                                                           | Note                                                                                                                               |\n|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|\n| Groovy     | [VelocityGroovyHelper](https://github.com/OkaeriPoland/okaeri-poly/blob/master/velocity-api/src/main/java/eu/okaeri/poly/api/velocity/VelocityGroovyHelper.java) | Exposes additional closure based methods for even better typing support. Use is optional and VelocityScriptHelper should work too. |\n\nAdditional global variables:\n\n- `plugin`: instance of `eu.okaeri.poly.velocity.PolyPlugin`\n- `logger`: instance of `org.slf4j.Logger`\n- `proxy`: instance of `com.velocitypowered.api.proxy.ProxyServer`\n\nDemo project: [velocity-example](https://github.com/OkaeriPoland/okaeri-poly/tree/master/velocity-example)\n\n### Dependency\n\n### Maven\n\nAdd repository to the `repositories` section:\n\n```xml\n\u003crepository\u003e\n    \u003cid\u003eokaeri-repo\u003c/id\u003e\n    \u003curl\u003ehttps://storehouse.okaeri.eu/repository/maven-public/\u003c/url\u003e\n\u003c/repository\u003e\n```\n\nAdd dependency to the `dependencies` section:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eeu.okaeri\u003c/groupId\u003e\n    \u003cartifactId\u003eokaeri-poly-[platform]-api\u003c/artifactId\u003e\n    \u003cversion\u003e1.3.0\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle\n\nAdd repository to the `repositories` section:\n\n```groovy\nmaven { url \"https://storehouse.okaeri.eu/repository/maven-public/\" }\n```\n\nAdd dependency to the `maven` section:\n\n```groovy\ncompileOnly 'eu.okaeri:okaeri-poly-[platform]-api:1.3.0'\n```\n\n### IDE\n\n#### IntelliJ (Groovy)\n\n```console\nmy-poly-project/\n    src/\n        main/\n            groovy/\n                script1.groovy\n                script2.groovy\n    pom.xml\n```\n\n- **Using @BaseScript (recommended):**\n  - Create new (maven/gradle) project or use existing project of your choice.\n  - Add poly-\\[platform]-api as a provided dependency.\n  - Add platform provided dependencies (e.g. spigot-api).\n  - Use BaseScript annotation in your scripts:\n  ```groovy\n  @BaseScript BukkitGroovyScript script\n  \n  import eu.okaeri.poly.api.bukkit.BukkitGroovyScript\n  import groovy.transform.BaseScript\n  ```\n- **Using dynamic properties:**\n  - Create new (maven/gradle) project or use existing project of your choice.\n  - Add poly-\\[platform]-api as a provided dependency.\n  - Add platform provided dependencies (e.g. spigot-api).\n  - Open any `.groovy` script with Groovy support enabled.\n  - Point your cursor on the `script` variable.\n  - Press `Alt + Enter` and choose `Add dynamic property 'script'`.\n  - Set property type to matching helper type (see sections above).\n  - Optionally add additional variables that are specified.\n\n### Details\n\nOtherwise, standard implementation practices/limitations apply. This software is intended for advanced users that are not afraid to explore. See provider repos for more details:\n\n- Groovy: [apache/groovy](https://github.com/apache/groovy), docs: [groovy-lang.org](https://groovy-lang.org/documentation.html)\n\n## Backend comparison\n\n| Backend                      | Performance (OpenJDK 11) | Performance (GraalVM 11) | IDE Support (IntelliJ) | Interoperability |\n|------------------------------|--------------------------|--------------------------|------------------------|------------------|\n| ⭐ Groovy (w. @CompileStatic) | ⭐ Excellent              | ⭐ Excellent              | ⭐ Excellent            | ⭐ Excellent      |\n| ⭐ Groovy                     | 🔵 Good                   | 🔵 Good                   | 🟢 Very good            | ⭐ Excellent      |\n\n### Performance\n\n- ⭐ _Excellent_: almost the same or better as native, can be used even for most demanding tasks\n- 🟢 _Very good_: applicable for most of the tasks (expect at least 1/4 of native performance)\n- 🔵 _Good_: fast enough, but requires caution in possible hotspots\n- 🟠 _Fair_: fast enough to be used for basic tasks\n- 🔴 _Poor_: hardly usable in any case\n\n### IDE support\n\n- ⭐ _Excellent_: good typing support, advanced auto-completion, advanced static-analysis\n- 🟢 _Very good_: good typing support, auto-completion, static-analysis\n- 🔵 _Good_: good typing support, may include basic auto-completion and static-analysis\n- 🟠 _Fair_: at least some typing support and usability for target language\n- 🔴 _Poor_: no real integration or cannot map java types\n\n### Interoperability\n\n- ⭐ _Excellent_: integrating feels like Java or better, with almost no disturbances\n- 🟢 _Very good_: just another day in the office with minor disturbances here and there\n- 🔵 _Good_: it is good enough, but may require some patience with minor problems\n- 🟠 _Fair_: it kinda works, but requires some tricks or pesky wrappers, major headache\n- 🔴 _Poor_: almost no interop or really complicated\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokaeripoland%2Fokaeri-poly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fokaeripoland%2Fokaeri-poly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokaeripoland%2Fokaeri-poly/lists"}