This guide should cover the process of creating new items and recipes for the server. The intent is to provide Professors with a process and commonly used templates to streamline the item creation process.
The server primarily uses Nexo for implementing items, but has other tools at its disposal! Don't be afraid to reach out to Department leadership for more information!
Process
Creating Items
Creating an item in Nexo is primarily split into two parts: creating the item and creating the recipe. Both of these tasks are done in YAML (Yet Another Markup Language), a relatively simple indentation based markup language. It is important that you ensure that each line of your configuration is correctly indented, otherwise it will not work properly.
Generally, you will want to have two separate files when working on an item, one for the recipe(s) and one for the item(s). Multiple items OR recipes of the same type can be placed within the same file.
Creating the Item
Creating the item is where most of the actual work in item creation is done. This is where you can define components, mechanics, and sounds that the item uses. Most parts of an item you might see are:
itemname: This is where you define the name of the item, can use MiniMessage formatting
lore: Where you can define the lore under the name of the item. You can have multiple lines of lore, and supports MiniMessage formatting.
material: The Vanilla item that the custom item is based on. Generally you should pick an item that has minimal uses on its own, such as paper.
Components: This is where you will define most of what the item actually does. The Nexo wiki has a decent description of all of the components, but more will be described below.
Mechanics: These are very specific actions that can be done when an item is used, and you will know when you need to use them. This can be a very powerful tool if you need it.
You can view the full list here
The bare minimum for an item to be functional is an item name and a Material. You should also ensure to add "Pack:" at the end of each of your items as that is where staff will apply the texture information to the item when it is uploaded to the server.
Components
Item Components are primarily what you will be using to create the custom effects players want on their items. This is where we can create custom foods, buffs, armor, and more! A list of the most common ones you will see, along with their uses, are:
Food: This is where you can define a custom item to be edible, and set its nutrition and saturation values.
Consumable: This is where you can define an item to be a consumable and apply potion effects, clear effects, play sounds, etc
Equippable: You can define an item to be equippable as a piece of armor, along with what slot it belongs to. Use Remainder: Replaces the item with a different item after using, such as a bucket of milk becoming a bucket after drinking.
You can view the full list here
Creating the Recipe
Creating a recipe in Nexo will depend on the crafting method that is being used, but the most common method is the crafting table. While a common template is defined in the Templates section, there are important things to consider while defining any recipe. There are three(ish) types of items you can use in a recipe: a minecraft_type, a tag, and a nexo_item.
A minecraft_type will be your most common, and will be from a list of all vanilla items here. Please ensure that you capitalize the name correctly, as it will not work otherwise. A tag will be a list of items already defined by Minecraft or other plugin. You can find a list of vanilla Minecraft tags here. A nexo_item will be any custom item defined by Nexo, including the item you are working on. If you need to know the ID of a specific Nexo item, reach out with Department leadership.
Additionally, when working with patents, the recipe should include a permission for that item to ensure that only the patent holder can create the recipe.
You can view a full list of available recipe types here.
Music Discs
Custom Music in Nexo is typically a bit of a pain, but their formats are shown below:
Sound Definition:
sounds:
- id: nexo:music.songname # Make sure the songname is all lowercase
sound: music:songname.ogg
stream: true
jukebox_playable:
length_in_seconds: 2.5 # How long track is in seconds - check the file
description: Description # Description that will display on the disc lore & the text on the screen when played. Usually Author - Track
Item:
custom_music_disc:
itemname: SongName
material: MUSIC_DISC_CAT
# This is the important bit to enable the item to be playable in a jukebox
Components:
jukebox_playable:
show_in_tooltip: true
song_key: nexo:music.something # Uses the song id
Common Templates
Basic Item Template
[ID of the item]: itemname: [Name of the Item] lore: - [Any Lore] material: [The Vanilla item it is based on] Pack: [Filled out by staff]
Basic Shapeless Recipe Template
[recipe_id]:
result:
nexo_item: [itemid]
amount: [amount]
permission: patent.[itemid]
ingredients:
A:
minecraft_type: [type]
B:
tag: [minecraft:tag]
C:
nexo_item: [nexoitem]
Basic Shaped Recipe Template
[recipe_id]:
result:
nexo_item: [itemid]
amount: [amount]
permission: patent.[itemid]
ingredients:
A:
minecraft_type: [type]
B:
tag: [minecraft:tag]
C:
nexo_item: [nexoitem]
shape:
- 'AAA'
- 'BBB'
- 'CCC'
Simple Custom Food Template
[ID of the item]:
itemname: [Name of the Item]
lore:
- [Any Lore]
material: [The Vanilla item it is based on]
Components:
food:
nutrition: [nutrition]
saturation: [saturation]
can_always_eat: [true/false]
Pack: [Filled out by staff]
Simple Consumable Template
[ID of the item]:
itemname: [Name of the Item]
lore:
- [Any Lore]
material: [The Vanilla item it is based on]
Components:
consumable:
effects:
APPLY_EFFECTS:
[potioneffect]:
duration: 10 # In Seconds
amplifier: 0 # 0 is Potion effect level 1, 1 is level 2, etc
Pack: [Filled out by staff]
Useful Resources
Nexo Documentation: https://docs.nexomc.com/
Minecraft Type List: https://jd.papermc.io/paper/1.21.10/org/bukkit/Material.html
Potion Effect Type List: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionEffectType.html
Minecraft Tags: https://minecraft.wiki/w/Tag_(Java_Edition)
VS Code: https://code.visualstudio.com/ - Has YML formatting for easier writing
YAML Checker: https://yamlchecker.com/ - Check to make sure that your YAML formatting is Valid
Examples
Example Birthday Cake
Item
# ID of the item
birthday_cake_black:
# Display name of the in-game item
itemname: Birthday Cake - Black
# Lore that wil be displayed on the item
# Formatting may make use of Minimessage!
lore:
- '<green>Feed: 1'
- <gold>[<yellow>Happy Birthday!<gold>]
# Components that may be applied to the item
# There is a wide set of components that may be applied that
# will be explained later, for now let's focus on what's here
Components:
# Denotes this is a food item, and you may provide the nutrition and saturation values
food:
nutrition: 1
saturation: 10
# can_always_eat: false
# Denotes that the item is consumable and allows you to apply the effects
consumable:
effects:
APPLY_EFFECTS:
speed:
amplifier: 13
duration: 2
material: PUMPKIN_PIE
# Assign custom model data
# You can leave this for staff to handle
Pack:
# parent_model: ''
# texture: food:item/birthday_cake_black
# custom_model_data: 000
Recipe
# item id
chef_birthday_cake_black:
# Like vanilla items, we can assign permssion to craft Nexo items as well
permission: chef.recipes
# ingredients; this will take a CAKE and BLACK CANDLE
ingredients:
C:
minecraft_type: CAKE
L:
minecraft_type: BLACK_CANDLE
result:
# The resulting item should use `nexo_item`, referring to the above Nexo item id
nexo_item: birthday_cake_black
shape:
- 'CL '
- ' '
- ' '
Example Sapling Recipe
lumberjack_sapling_pale_oak:
# You may leave this for staff to handle
permission: dcrecipes.saplings.pale.oak
# This section is for defining the ingredients found within the recipe
ingredients:
# You can use any character you want for the 'names', this is for use in the shape section below
L:
# The item to represent the 'key' (in this case "L")
minecraft_type: PALE_OAK_LEAVES
W:
minecraft_type: PALE_OAK_LOG
result:
# The item produced when using the recipe
item: PALE_OAK_SAPLING
minecraft_type: PALE_OAK_SAPLING
# the amount to produce
amount: 1
# This defines the shape of the recipe using the letters from ingredients.
shape:
- ' L ' # Blank , Leaves , Blank
- 'LLL' # Leaves , Leaves , Leaves
- ' W ' # Blank , Wood , Blank
Example Potion
potion_of_haste:
customname: Haste Potion
material: POTION
Components:
enchantment_glint_override: true
PotionEffects:
- type: HASTE
duration: 300
amplifier: 1
ambient: true
particles: true
icon: true
effect: haste
use_remainder:
minecraft_type: GLASS_BOTTLE
Example of Use Remainder
full_milk:
itemname: 'Milk Bottle'
Components:
use_remainder:
# Here we return a second Nexo item to represent the used item
nexo_item: half_full_milk_bottle
half_full_milk_bottle:
itemname: 'Milk Bottle'
Components:
use_remainder:
# Here we return a glass bottle because the milk is empty!
minecraft_type: GLASS_BOTTLE