https://github.com/berberman/emerald-extension
A framework of Minecraft-Spigot Plugin.
https://github.com/berberman/emerald-extension
Last synced: 11 months ago
JSON representation
A framework of Minecraft-Spigot Plugin.
- Host: GitHub
- URL: https://github.com/berberman/emerald-extension
- Owner: berberman
- License: apache-2.0
- Created: 2018-02-02T12:38:03.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-08-30T03:28:45.000Z (almost 8 years ago)
- Last Synced: 2025-03-05T10:50:15.401Z (about 1 year ago)
- Language: Kotlin
- Homepage: http://www.berberman.cn/emerald-extension/
- Size: 366 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README-CN.md
- License: LICENSE
Awesome Lists containing this project
README
# Emerald Extension
[](https://github.com/KotlinBy/awesome-kotlin)
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://www.codacy.com/app/berberman/emerald-extension?utm_source=github.com&utm_medium=referral&utm_content=berberman/emerald-extension&utm_campaign=Badge_Grade)
[](https://github.com/berberman)
[](https://www.spigotmc.org/)
[](https://github.com/berberman/emerald-extension)
[](https://gradle.org/)
[](https://bintray.com/berberman/maven/emerald-extension/_latestVersion)
持续集成构建|构建状态
:---|:---:
Travis CI|[](https://travis-ci.org/berberman/emerald-extension)
CircleCI|[](https://circleci.com/gh/berberman/emerald-extension)
AppVeyor|[](https://ci.appveyor.com/project/berberman/emerald-extension)
Wercker|[](https://app.wercker.com/project/byKey/820a6a6b02261bd3bfe88b9b5a066dce)
Codeship|[ ](https://app.codeship.com/projects/270349)
一个作为 Spigot 插件开发的依赖。
本项目引入了 `spigot-1.12.2` 作为依赖, 理论支持 1.10+ 。
本项目内容：
* 一些顶层成员、函数，可以更便捷访问 Bukkit API
* Kotlin 协程对 Spigot的支持
* DSL 对物品的 NBT 参数修改
* DSL 注册命令
* DSL 注册、取消注册事件监听器
* DSL 注册权限
* `Location`,`Vector` 运算符的重载
* 关于`Player`的扩展函数
## 食用方法
本项目发布于 Bintray，~~Maven签名太麻烦~~ 只是一个依赖，并非前置插件，不能单独加载 / 运行，你需要先将其添加到项目依赖中。
### Gradle
```groovy
repositories {
jcenter()
}
dependencies {
compile "cn.berberman:emerald-extension:1.1"
}
```
### Maven
```xml
jcenter
JCenter
https://jcenter.bintray.com/
cn.berberman
emerald-extension
1.1
pom
```
### 其他
如果你不使用依赖管理系统，
可以直接下载 Jar ([bintray](https://bintray.com/berberman/maven/emerald-extension/_latestVersion) ,
[github](https://github.com/berberman/emerald-extension/releases)) ，放到项目依赖中。
## 一些栗子
### 修改NBT
```kotlin
ItemStack(Material.PAPER).modifyNBT {
addTag {
type = NBTType.AttackDamage
amount = 233.0
}
removeTagByType(NBTType.MovementSpeed)
removeTagByIndex(0)
clearAllTags()
}.operateMeta {
displayName = "Banana"
}
```
`modifyNBT` 提供一个 dsl 修改物品的 NBT 标签。
`addTag` 后面跟一个 dsl ，可以为物品添加基础 NBT 标签。
`removeTagByType` 可以移除某类型全部标签。
`removeTagByIndex` 可以移除根据所有标签的下标移除一个标签。
### Bukkit Scheduler
```kotlin
launch(SchedulerThread) {
Thread.sleep(3000)
runOnServerThread {
player.world.spawnEntity(player.location)
}
}
```
当你执行一些会阻塞线程，并非挂起的任务时，需要使该协程在 `Scheduler` 线程上调度。
这时，如果你想访问 Bukkit API，你就需要使任务运行在服务器线程上。但是，一些同步执行的
简单语句没有开一个在主线程上运行的协程的必要，所以你可以通过`runOnServerThread {}` 函数
使其运行在服务器主线程上。
```kotlin
bukkitAsync {
Thread.sleep(3000)
}
```
有时候没必要开个协程折腾，上面的代码相当于把后面的内容异步执行。
### 注册命令
```kotlin
createAndRegisterCommands {
command("test") {
description = "A test command"
addAlias("t")
permission = "test.test"
permissionMessage = "你没这权限！"
action { sender ->
sender sendMessage "Hi!"
CommandResult.Successful
}
subCommand("player") { sender, args ->
sender.whenSenderIs {
world.spawnEntity(location)
sendMessage(args.joinToString())
CommandResult.Successful
} otherwise {
sendMessage("你不是玩家！")
CommandResult.Failed()
}
}
}
command("xxx"){
//...
}
}
```
`createAndRegisterCommands` 在插件启动时应该被调用。对于每个命令来说，除了名字必须声明外，其他都是可选的，
包括子命令、描述、权限、别名等。子命令可以有许多，但父命令的 `action` 只有在子命令未被调用 (而不是调用失败) 时调用。
~~前面那句话没卵用，请忽略。~~ 在使用 `whenSenderIs` 时后面要加 `otherwise {}`并且声明返回值。
在 `registerCommands {}` 中，你可以使用 `command(name) {}` 注册许多命令。
#### CommandResult
对于命令的返回结果只用一个 `Boolean` 来表示显然不太恰当。我们提供了 `CommandResult` 来代表命令执行的结果。
### 注册事件监听器
```kotlin
createAndRegisterCommands {
command("aaa") {
subCommand("a") { _, _ ->
registerEvent {
event {
player sendMessage ChatColor.AQUA * "Hello,${player.name}!"
}
}
CommandResult.Successful
}
val event = createEvent {
player sendMessage "欢迎上床♂"
}
subCommand("b") { _, _ ->
registerEvent(event)
CommandResult.Successful
}
subCommand("c") { _, _ ->
unregisterEvent(event)
CommandResult.Successful
}
subCommand("d") { _, _ ->
registerEvents {
event { }
event { }
//...
}
CommandResult.Successful
}
}
}
```
一个事件监听器可以被动态地注册和取消注册，上面的栗子就是在调用命令时对事件监听器进行操作。
`registerEvents` 可以一次性注册多个事件监听器，如果想要取消注册的话就要把每个监听器的引用保存下来，
使用 `unregisterEvent()` 取消注册。
### 注册权限
```kotlin
registerPermissions {
permission("test.test") {
defaultValue = PermissionDefault.FALSE
description = "谁都没有！"
childPermission("a") {
defaultValue = PermissionDefault.NOT_OP
childPermission("xxx") {
childPermission("xxx")
}
}
}
}
```
和注册命令相似，`registerPermissions` 需要在插件启用时调用。
对于每一个权限来说，只有名字时必要的，其他都是可选的，你可以给子权限注册子权限注册子权限。
### ComponentChat
对 Spigot#ComponentChat 的扩展。
```kotlin
componentChat("有趣") {
bold(true)
executeCommandOnClick("/say 233")
}.create()
```
`componentChat` 函数会帮助你构建 `BaseChatMessage`。后者可用在聊天消息、书本内容中。
### 玩家的扩展
#### sendComponentChat/ActionBar
```kotlin
Bukkit.getPlayer("").sendComponentChat("测试") {
bold(true)
showTextOnHover(TextComponent("test"))
executeCommandOnClick("/say test")
}
```
正如上部分提到。
#### openBook
```kotlin
Bukkit.getPlayer("").openBook(ItemStack(Material.WRITTEN_BOOK),NmsEnumHand.MAIN_HAND)
```
打开书本界面。
### 书本的扩展
```kotlin
ItemStack(Material.WRITTEN_BOOK).operateBookMeta {
addPage("测试"){
bold(true)
showTextOnHover(TextComponent("test"))
executeCommandOnClick("/say test")
}
}
```
与上面一致。
## 贡献
求星星，欢迎提 Issue、发PR。