Skip to content

Latest commit

 

History

History
189 lines (136 loc) · 8.53 KB

README.md

File metadata and controls

189 lines (136 loc) · 8.53 KB
Raw

Okaeri Poly

License Total lines Repo size Contributors Discord

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:

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