Guiy

A Minecraft UI library for PaperMC, built on the Jetpack Compose compiler.

Compose is commonly used in Android (and cross-platform) development, so many resources are available online to learn the basics. It makes it much easier to work with changing UI state and has built in support for Kotlin Coroutines.

Note

Guiy is in active development as we continue to try new use-cases in our plugins. We can't promise api stability yet, but try to follow semver for breaking changes.

Examples

See the guiy-example package for a full demonstration of project setup and different features.

Entry

guiy {
    ExampleMenu(player)
}

Chest menu

@Composable
fun ExampleMenu(player: Player) {
    val owner = LocalGuiyOwner.current
    // Guiy will dynamically update players, title, or height if you use a state.
    Chest(setOf(player), title = "Example", height = 4, onClose = { owner.exit() /*owner.reopen()*/ }) {
        ToggleButton()
    }
}

Toggle button

val RED = ItemStack(Material.RED_WOOL)
val GREEN = ItemStack(Material.GREEN_WOOL)

@Composable
fun ToggleButton() {
    var enabled by remember { mutableStateOf(false) }
    val display = if (enabled) GREEN else RED
    Item(display, Modifier.clickable {
        enabled = !enabled
    })
}

Modifiers

We use a similar modifier system to Jetpack Compose.

// Entry to modifiers, though you are encouraged to pass a modifier parameter into your composables.
Modifier
    // Set the width of an element (can use min/max constraints, or .size to set width and height)
    .width(3)
    // Fill based on parent constraints like Jetpack
    .fillmaxHeight()
    // Padding in # of blocks
    .padding(vertical = 1)
    // Place at an offset
    .offset(x = 1, y = 5)
    // Do actions on click
    .clickable { doSomething() }

Alignment

Guiy provides Row, Column, and Box components based on Jetpack's, these come with Arrangement and Alignment too. We also provide our components like Vertical/Horizontal Grids optimized for common Minecraft uses.

// A horizontal row of 10 items, with 1 space between each.
Row(horizontalArrangement = Arrangement.spacedBy(1)) {
    repeat(4) {
        Item(...)
    }
}

// Same but vertical
Column { ... }

// Two rows on top of each other
Column {
    Row { ... }
    Row { ... }
}

// Items aligned left to right, top to bottom, wrapped to be smaller than width, useful for pages of items!
VerticalGrid(Modifier.width(3)) {
    repeat(7) {
        Item(...)
    }
}
/* Result:
    III
    III
    I--   */

Coroutines

LaunchedEffect support, same as in Jetpack Compose:

fun TimedToggle() {
    var enabled by remember { mutableStateOf(false) }
    val display = if (enabled) GREEN else RED
    Item(display)

    LaunchedEffect(Unit) {
        // Button will flash 10 times, with 1 second intervals
        repeat(10) {
            toggled = !toggled
            delay(1000)
        }
    }
}

Real world use

We are using this project internally, so you should be able to find up-to-date usage in our main project.

Usage

Gradle

build.gradle.kts

plugins {
    // Match version in guiy's build.gradle.kts
    id("org.jetbrains.compose") version "1.x.x"
}

repositories {
    maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
    maven("https://repo.mineinabyss.com/releases")
}

dependencies {
    compileOnly("com.mineinabyss:guiy-compose:x.y.z")
}

settings.gradle.kts

pluginManagement {
    repositories {
        google()
        gradlePluginPortal()
        maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
    }
}

Server setup

Guiy does not package the Kotlin runtime, it depends on our helper plugin Idofront using Paper's isolated dependency system.

Download and install Guiy into your plugin folder.
Download Idofront, a required dependency.
Depend on Guiy in a paper-plugin, this will give you access to Guiy and any libraries in Idofront in an isolated manner.

Thanks

Google for creating Jetpack Compose.
JetBrains for making it easy to use the compiler plugin outside of Android.
A lot of the inital code to set up the Jetpack Compose environment comes from https://github.com/JakeWharton/mosaic.

MineInAbyss/guiy-compose