Okaeri Poly

Enterprise grade Minecraft scripting adapter for Groovy (formerly also JavaScript, and Python). Created with okaeri-platform.

Requirements

Java 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.

Supported platforms

• Bukkit: Spigot/Paper minecraft server plugin (disclaimer: requires version 1.13 or newer)
• Velocity: Velocity minecraft proxy plugin (incoming)

Installation

Grab latest release jar for your platform and install it like any other plugin, e.g. put in plugins/ for Spigot/Paper and Velocity servers.

Put your script files inside plugins/Poly/scripts/ directory. File extension will determine backend to be used (groovy, js, py).

Development

Command support, event listeners, and scheduler can be accessed through script object/variable helper. This ensures script unloading unregisters commands, listeners, and cancels pending tasks.

@BaseScript BukkitGroovyScript script

import eu.okaeri.poly.api.bukkit.BukkitGroovyScript
import groovy.transform.BaseScript
import org.bukkit.event.player.PlayerJoinEvent

// groovy example (with @BaseScript)
listen(PlayerJoinEvent) { event ->
    logger.info("${event.player.name} joined the game!")
}

import org.bukkit.event.player.PlayerJoinEvent

// groovy example (dynamic properties)
script.listen(PlayerJoinEvent) { event ->
    logger.info("${event.player.name} joined the game!")
}

Bukkit

Backend	Helper	Note
Groovy	BukkitGroovyHelper	Exposes additional closure based methods for even better typing support. Use is optional and BukkitScriptHelper should work too.

Additional global variables:

• plugin: instance of eu.okaeri.poly.bukkit.PolyPlugin
• logger: instance of java.util.logging.Logger
• server: instance of org.bukkit.Server

Demo project: bukkit-example-groovy, bukkit-example-javascript

Velocity

Backend	Helper	Note
Groovy	VelocityGroovyHelper	Exposes additional closure based methods for even better typing support. Use is optional and VelocityScriptHelper should work too.

Additional global variables:

• plugin: instance of eu.okaeri.poly.velocity.PolyPlugin
• logger: instance of org.slf4j.Logger
• proxy: instance of com.velocitypowered.api.proxy.ProxyServer

Demo project: velocity-example

Dependency

Maven

Add repository to the repositories section:

<repository>
    <id>okaeri-repo</id>
    <url>https://storehouse.okaeri.eu/repository/maven-public/</url>
</repository>

Add dependency to the dependencies section:

<dependency>
    <groupId>eu.okaeri</groupId>
    <artifactId>okaeri-poly-[platform]-api</artifactId>
    <version>1.3.0</version>
    <scope>provided</scope>
</dependency>

Gradle

Add repository to the repositories section:

maven { url "https://storehouse.okaeri.eu/repository/maven-public/" }

Add dependency to the maven section:

compileOnly 'eu.okaeri:okaeri-poly-[platform]-api:1.3.0'

IDE

IntelliJ (Groovy)

my-poly-project/
    src/
        main/
            groovy/
                script1.groovy
                script2.groovy
    pom.xml

• Using @BaseScript (recommended):
  • Create new (maven/gradle) project or use existing project of your choice.
  • Add poly-[platform]-api as a provided dependency.
  • Add platform provided dependencies (e.g. spigot-api).
  • Use BaseScript annotation in your scripts:

  @BaseScript BukkitGroovyScript script
  
  import eu.okaeri.poly.api.bukkit.BukkitGroovyScript
  import groovy.transform.BaseScript

• Using dynamic properties:
  • Create new (maven/gradle) project or use existing project of your choice.
  • Add poly-[platform]-api as a provided dependency.
  • Add platform provided dependencies (e.g. spigot-api).
  • Open any .groovy script with Groovy support enabled.
  • Point your cursor on the script variable.
  • Press Alt + Enter and choose Add dynamic property 'script'.
  • Set property type to matching helper type (see sections above).
  • Optionally add additional variables that are specified.

Details

Otherwise, standard implementation practices/limitations apply. This software is intended for advanced users that are not afraid to explore. See provider repos for more details:

• Groovy: apache/groovy, docs: groovy-lang.org

Backend comparison

Backend	Performance (OpenJDK 11)	Performance (GraalVM 11)	IDE Support (IntelliJ)	Interoperability
⭐ Groovy (w. @CompileStatic)	⭐ Excellent	⭐ Excellent	⭐ Excellent	⭐ Excellent
⭐ Groovy	🔵 Good	🔵 Good	🟢 Very good	⭐ Excellent

Performance

• ⭐ Excellent: almost the same or better as native, can be used even for most demanding tasks
• 🟢 Very good: applicable for most of the tasks (expect at least 1/4 of native performance)
• 🔵 Good: fast enough, but requires caution in possible hotspots
• 🟠 Fair: fast enough to be used for basic tasks
• 🔴 Poor: hardly usable in any case

IDE support

• ⭐ Excellent: good typing support, advanced auto-completion, advanced static-analysis
• 🟢 Very good: good typing support, auto-completion, static-analysis
• 🔵 Good: good typing support, may include basic auto-completion and static-analysis
• 🟠 Fair: at least some typing support and usability for target language
• 🔴 Poor: no real integration or cannot map java types

Interoperability

• ⭐ Excellent: integrating feels like Java or better, with almost no disturbances
• 🟢 Very good: just another day in the office with minor disturbances here and there
• 🔵 Good: it is good enough, but may require some patience with minor problems
• 🟠 Fair: it kinda works, but requires some tricks or pesky wrappers, major headache
• 🔴 Poor: almost no interop or really complicated