DOE:Making New Items

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