Skip to content

Commit 15a8f5c

Browse files
OliverSchlueterOliverSchlueter
committed
fancynpcs: Action scripting and Citizens converter
1 parent 0280c13 commit 15a8f5c

6 files changed

Lines changed: 121 additions & 2 deletions

File tree

‎content/docs/minecraft-plugins/fancydialogs/tutorials/json-schema.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,11 @@ In this tutorial, we will explore the JSON schema used by FancyDialogs to define
77
This schema provides a structured way to create fancy dialogs.
88

99
<Callout>
10-
The Community has created an experimental web editor for FancyDialogs. Feel free to check it out at [https://fd-web-editor.vercel.app/](https://fd-web-editor.vercel.app/) and give feedback!
10+
The community has created an web editor for FancyDialogs.
11+
12+
Feel free to check it out: [https://fd-web-editor.vercel.app](https://fd-web-editor.vercel.app/)
13+
14+
It's made by [TSERATO](https://github.com/TSERATO) and [tolnayeu](https://github.com/tolnayeu)
1115
</Callout>
1216

1317
## Example Dialog

‎content/docs/minecraft-plugins/fancynpcs/api/action-scripting.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Action scripting
3+
description: Learn how to create custom actions for FancyNpcs using Kite.
4+
---
5+
6+
FancyNpcs' action system offers some basic actions, but if you need more advanced functionality, you can use [Kite](https://echonine.dev/kite/getting-started/) to create custom action in Kotlin.
7+
8+
With Kite, you can write scripts that define new actions, which can then be registered with FancyNpcs and used in your NPCs.
9+
10+
Here's a simple example of how to create and register a custom action using Kite:
11+
12+
```kotlin
13+
import de.oliver.fancynpcs.api.FancyNpcsPlugin
14+
import de.oliver.fancynpcs.api.actions.NpcAction
15+
import de.oliver.fancynpcs.api.actions.executor.ActionExecutionContext
16+
import java.lang.Thread.sleep
17+
18+
val action = object : NpcAction("helloworld", false) {
19+
20+
override fun execute(context: ActionExecutionContext, value: String?) {
21+
context.getPlayer()!!.sendMessage("Custom action executed with value: $value")
22+
}
23+
}
24+
25+
onLoad {
26+
Thread {
27+
sleep(20 * 1000) // Wait for 20 seconds to ensure that FancyNpcs is fully loaded before registering the action
28+
registerAction()
29+
}.start()
30+
}
31+
32+
fun registerAction() {
33+
FancyNpcsPlugin.get().getActionManager().registerAction(action)
34+
println("Registered custom action: ${action.name}")
35+
}
36+
```
37+
38+
*(As you may see, I'm not a Kotlin developer. Feel free to send me some better examples over!)*
39+
40+
Put the code in `plugins/Kite/scripts/my_custom_actions.kite.kts`, and restart your server.
41+
You can then use the custom action `custom_action_name` in your NPCs, passing a string value that will be displayed to the player when the action is executed.
42+
43+
Now you can extend the script to add more complex logic. The [ActionExecutionContext](https://fancyspaces.net/javadoc/fn/fi-releases/de.oliver:FancyNpcs/latest/de/oliver/fancynpcs/api/actions/executor/ActionExecutionContext.html) provides various methods to interact with the NPC and the player, allowing you to create a wide range of custom actions.

‎content/docs/minecraft-plugins/fancynpcs/api/meta.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"title": "API Reference",
3+
"icon": "",
4+
"defaultOpen": false,
5+
"pages": ["getting-started", "action-scripting"]
6+
}

‎content/docs/minecraft-plugins/fancynpcs/tutorials/action-system.mdx‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,33 @@ Example: `/npc action (npc) (trigger) add need_permission my.cool.permission`
125125
If you add the `!` prefix to the permission, the action will be inverted. This means that the action list will be canceled if the player has the permission.
126126
</Callout>
127127

128+
### need_item
129+
130+
Checks if the player has a specific item in their inventory.
131+
If the player does not have the item, the action list will be canceled.
132+
This action is useful for creating item-based interactions with NPCs.
133+
You can also specify the amount of the item required.
134+
135+
Syntax: `need_item (item) [amount]`
136+
137+
Example: `/npc action (npc) (trigger) add need_item diamond 5` (checks if the player has at least 5 diamonds in their inventory)
138+
139+
<Callout>
140+
If you add the `!` prefix to the item, the action will be inverted. This means that the action list will be canceled if the player has the item.
141+
</Callout>
142+
128143
### play_sound
129144

130145
Plays a sound to the player. This action is useful for creating audio feedback for the player when interacting with the NPC.
131146

132147
Syntax: `play_sound (sound)`
133148

134-
Example: `/npc action (npc) (trigger) add play_sound entity.experience_orb.pickup`
149+
Example: `/npc action (npc) (trigger) add play_sound entity.experience_orb.pickup`
150+
151+
## Custom actions
152+
153+
The NPC Action System is designed to be extensible, allowing developers to create custom actions that can be registered and used in NPCs.
154+
If you're a developer and want to create custom actions, you can check out the [JavaDoc](https://fancyspaces.net/javadoc/fn/fi-releases/de.oliver:FancyNpcs/latest/de/oliver/fancynpcs/api/actions/package-summary.html) to learn how to create and register custom actions using the API.
155+
156+
You can also use [Kite](https://echonine.dev/kite/getting-started/) to create custom actions using Kotlin scripts.
157+
Check out the [action scripting tutorial](../api/action-scripting) for more information on how to create custom actions with Kite.

‎content/docs/minecraft-plugins/fancynpcs/tutorials/citizens-converter.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Citizens Converter
3+
description: How to convert your Citizens NPCs to FancyNpcs
4+
---
5+
## How to use
6+
7+
FancyNpcs provides a simple converter that allows you to convert your existing Citizens NPCs to FancyNpcs.
8+
This is a great way to migrate your NPCs without having to recreate them from scratch.
9+
10+
1. Have Citizens installed (tested with version `2.0.41-b4129`)
11+
2. Have the latest version of [FancyNpcs](https://modrinth.com/plugin/fancynpcs/versions?c=release) installed
12+
3. Run the `/npcconvert citizens` command
13+
4. Check the result (`/fancynpcs:npc list`)
14+
5. You can now delete the Citizens npcs and/or the Citizens plugin
15+
16+
The following properties get converted:
17+
* Npc owner
18+
* Npc name (white spaces will be replaced with underscores)
19+
* Mob type
20+
* Skin (only tested with usernames so far)
21+
* Look close (turn_to_player in fancynpcs)
22+
* Glowing & glowing color
23+
* Equipment
24+
* Text -> `message` action with ANY_CLICK trigger
25+
* Command -> `console_command` action with trigger defined as Hand
26+
27+
The converter does not convert mob type specific attributes yet (e.g. variants or poses).
28+
29+
Please leave feedback, bugs and issues about the converter in the Discord server or as an issue on GitHub.
30+
If there is any important property that is not being converted, please let us know so we can add support for it!

‎content/docs/minecraft-plugins/fancynpcs/tutorials/meta.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"title": "Tutorials",
3+
"icon": "",
4+
"defaultOpen": false,
5+
"pages": [
6+
"citizens-converter",
7+
"action-system",
8+
"multiple-lines",
9+
"sitting-npcs",
10+
"mineskin-api-key",
11+
"using-minimessages"
12+
]
13+
}

0 commit comments

Comments
 (0)