https://github.com/dockyardmc/scroll
Minecraft component library built for DockyardMC
https://github.com/dockyardmc/scroll
Last synced: about 1 year ago
JSON representation
Minecraft component library built for DockyardMC
- Host: GitHub
- URL: https://github.com/dockyardmc/scroll
- Owner: DockyardMC
- Created: 2024-05-12T20:06:44.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-03-30T01:11:54.000Z (about 1 year ago)
- Last Synced: 2025-03-30T02:22:37.913Z (about 1 year ago)
- Language: Kotlin
- Size: 175 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
---
[](https://mvn.devos.one/#/releases/io/github/dockyardmc/dockyard)
[](https://kotlinlang.org/)
[](https://wakatime.com/badge/github/DockyardMC/Scroll)
[](https://discord.gg/SA9nmfMkdc)
[](https://ko-fi.com/LukynkaCZE)
A Minecraft Component library made for the [DockyardMC](https://github.com/DockyardMC/Dockyard) project. It includes easy to use and learn format to represent text components as strings, similiar to minimessage
## Installation
**Kotlin DSL**
```kotlin
repositories {
maven {
name = "devOS"
url = uri("https://mvn.devos.one/releases")
}
}
dependencies {
implementation("io.github.dockyardmc:scroll:2.3")
}
```
**Gradle Groovy**
```groovy
repositories {
maven {
name "devOS"
url "https://mvn.devos.one/releases"
}
}
dependencies {
implementation 'io.github.dockyardmc:scroll:2.3'
}
```
---
## Usage
You can create a different type of components using the following syntax
**_Normal Text Component_**
```kotlin
val textComponent = TextComponent(
text = "woah red bold text",
color = TextColor.RED,
bold = true
// ..other styling
)
```
**_Keybind Component_** (Reads the current keybinds from client)
```kotlin
val keybindComponent = KeybindComponent(
keybind = "key.jump"
// ..other styling
)
```
**_Translatable Component_** (Reads the language file from client)
```kotlin
val translatableComponent = TranslatableComponent(
translate = "advancements.husbandry.safely_harvest_honey.description"
// ..other styling
)
```
---
You can also create component that contains other components
```kotlin
val bigBoiComponent = Components.new(mutableListOf(
TextComponent(text = "Im looking to "),
TextComponent(text = "buy ", color = TextColor.YELLOW, bold = true),
TextComponent(text = "your "),
TextComponent(text = "finest potions ", color = "#9436ff", italics = true)
TextComponent(text = "so I can jump high when I press "),
KeybindComponent(keybind = "key.jump", color = TextColor.YELLOW, underlined = true)
))
```
---
### String to Components
You can also write your components using string format
```kotlin
val component = "HE'S ALLERGIC TO BEANS!".toComponent()
```
The following tags are valid:
- Colors:
- `` for predefined color (ex. red, orange, lime, aqua)
- `<#hex>` for custom hex color (must include the # at the start)
- Format
- ``
- ``
- ``
- ``
- ``
- Events
- `` for hover-able text. Formatting applies to inner text as well
- `` for clickable text. Actions are following
- `open_url` - following text needs to start with "https://"
- `run_command` - following text needs to start with "/"
- `suggest_command` - following text needs to start with "/"
- `copy_to_clipboard`
- Other
- `` to change font
- `` to make the text after rainbow. (Resets when another color is applied or when is reached)
- `` - Color Interpolation, step is float between 0 and 1
- `` to reset formatting
In some cases (format and reset) you can use shortened versions
- `` is short of ``
- `` is short of ``
- `` is short of ``
- `` is short of ``
- `` is short of ``
- `` is short of ``
You also end tags by prefixing the tag with `/`
- `this is bold :D this is not :(`
⚠️ _Currently, there is no support for custom tags_
---
## Sanitization & Escapes
You can escape tag by putting `\\` at the begging of it
`Please login using /login \\` will result to `"Please login using /login "`
You can sanitize string using `String.scrollSanitized()` This is recommended for any player input
`"Player123: omg red color and bold woah".scrollSanitized()` would result to `"Player123: omg \\red color and \\bold woah"`
---
## Serialization
You can convert string **to Component** using `"string".toComponent()` method or using `StringToComponentSerializer().serialize("string")`
---
You can convert component **to NBT** using `Component.toNbt()` or using `ComponentToNbtSerializer.serialize(component)`. This will give you instance of [Hephaistos](https://github.com/Minestom/Hephaistos) NBT Compound
---
You can convert component to Json using `Component.toJson()` or using `ComponentToJsonSerializer.serialize(component)`
---
You can convert Json to component using `JsonToComponentSerializer.serialize(json)`
---
⚠️ _**There is currently no integration with either vanilla minecraft server components or adventure/minimessage**_