Configuration - Simplix-Softworks/Cirrus GitHub Wiki

Menu configurations

In this section I will cover the usage of the MenuConfiguration class. There are currently two types of MenuConfigurations:

  • MenuConfiguration
  • MultiPageMenuConfiguration

Those menu configurations will be loaded from json serialized files when a menu get's opened. There is no caching.

LocalizedString

A localized string in the sense of menu configuration is a map of strings in which a language ISO 639 code is mapped to an according translation in that given language. For example:

"someLocalizedString": {
  "de": "Hallo!",
  "en": "Hello!",
  "fr": "Bonjour!"
}

If the application requests a translation, that is not implemented in the configuration, it will return the first translation. If even that fails, the translation returned is missigno..

This is used for storing localized inventory titles and item names.

LocalizedStringList

A localized string list is a map in which a language ISO 639 key is mapped to a string array. For example:

"giveMeMoreTranslations": {
  "de": [
    "Eine Zeile genügt mir nicht",
    "Ich will einfach mehr"
  ],
  "en": [
    "One line is not enough for me"
    "I need more"
  ]
}

If the application requests a translation, that is not implemented in the configuration, it will return the first translation. If even that fails, the translation returned is empty.

This is used for storing localized item lores.

ItemStackModel

The item stack model class (dev.simplix.cirrus.api.model.ItemStackModel) is representing an item stack in the json configuration file. It contains the following information:

  • The display name of the item stack as LocalizedString
  • The item description (lore) as LocalizedStringList
  • The item type as Protocolize ItemType enum name
  • The quantity of items in that stack (default set to 1)
  • The durability of the item stack or -1 if the item has no durability (default set to -1)
  • The action handler id of the item stack (default set to noAction)
  • An optional array of strings used as arguments for an action handler call
  • An optional int array for slots
  • An optional NBT tag stored as JSON object

Skeleton

This how it looks in json:

{  
  "itemType": "PLAYER_HEAD",  
  "displayName": {  
    "en": "§6Example Item",  
    "de": "§6Beispielitem"  
  },  
  "lore": {  
    "en": [  
      "§7Hello §6{viewer}§7,",  
      "§7this is an example item to show",  
      "§7how Cirrus menus and items are configured."  
    ],  
    "de": [  
      "§7Hallo §6{viewer}§7,",  
      "§7das ist ein Beispiel, um zu zeigen",  
      "§7wie man Cirrus Menüs und Items konfiguriert."  
    ]  
  },
  "amount": 1,
  "durability": -1, 
  "actionHandler": "noAction",  
  "actionArguments": [],  
  "slots": [13],  
  "nbt": {  
    "SkullOwner": "Exceptionflug"  
  }  
}

LocalizedItemStackModel

There is a business model out there which is sometimes referenced by the API. If you have to convert an ItemStackModel to a LocalizedItemStackModel you can do this by using the Localizer class.

LocalizedItemStackModel localizedModel = Localizer.localize(itemStackModel, Locale.ENGLISH /** or whatever locale you want **/);
// You can additionally pass your replacements to the method

MenuConfiguration

The class dev.simplix.cirrus.api.model.MenuConfiguration contains the basic information to be shown in any menu subtype of dev.simplix.cirrus.common.menu.AbstractConfigurableMenu<MenuConfiguration>.

A configuration of this type contains the following information:

  • The inventory title as LocalizedString
  • The type of the inventory
  • An item stack model for placeholder items
  • An int array for reserved slots. Reserved slots are excluded from beeing filled with items using the add() method.
  • An array of item stack models. All items that are actually shown in the inventory.
  • A map of item stack models mapped to an identifier string. Used to be accessed from code. Those items will not be automatically shown in the inventory, you have to set them by code. This feature is called "business items" (because you have to set them in business logic).

Skeleton

This is the default configuration file for MenuConfigurations which is shipped with Cirrus. This file will automatically generated if no configuration file exists for your inventory.

{  
  "title": {  
    "en": "§bCirrus Menu",  
    "de": "§bCirrus Menü"  
  },  
  "type": "GENERIC_9X4",  
  "placeholderItem": {  
    "itemType": "GRAY_STAINED_GLASS_PANE",  
    "displayName": {  
      "en": "§0",  
      "de": "§0"  
    },  
    "lore": {  
      "en": [],  
      "de": []  
    },
    "amount": 1,  
    "slots": [0, 1, 2, 3, 4, 5, 6, 7, 8, 27, 28, 29, 30, 31, 32, 33, 34, 35]  
  },  
  "reservedSlots": [],  
  "items": [  
    {
      "itemType": "PLAYER_HEAD",  
      "displayName": {  
        "en": "§6Example Item",  
        "de": "§6Beispielitem"  
      },  
      "lore": {  
        "en": [  
          "§7Hello §6{viewer}§7,",  
          "§7this is an example item to show",  
          "§7how Cirrus menus and items are configured."  
        ],  
        "de": [  
          "§7Hallo §6{viewer}§7,",  
          "§7das ist ein Beispiel, um zu zeigen",  
          "§7wie man Cirrus Menüs und Items konfiguriert."  
        ]  
      },
      "amount": 1,  
      "actionHandler": "noAction",  
      "actionArguments": [],  
      "slots": [13],  
      "nbt": {  
        "SkullOwner": "Exceptionflug"  
      }  
    }
  ]
}

MultiPageMenuConfiguration

The configuration class for multi page inventories (dev.simplix.cirrus.api.model.MultiPageMenuConfiguration) is extending the base class MenuConfiguration. This means a MultiPageMenuConfiguration automatically contains all properties from the base MenuConfiguration (see above).

Additionally the multi page configuration adds the following properties:

  • An item stack model that is shown as a "next page item"
  • An item stack model that is shown as a "previous page item"

Skeleton

This is the default configuration file for MultiPageMenuConfigurations which is shipped with Cirrus. This file will be automatically generated if no configuration file exists for your inventory.

{  
  "title": {  
    "en": "§bCirrus Menu {page} / {pageCount}",  
    "de": "§bCirrus Menü {page} / {pageCount}"  
  },  
  "type": "GENERIC_9X6",  
  "placeholderItem": {  
    "itemType": "GRAY_STAINED_GLASS_PANE",  
    "displayName": {  
      "en": "§0",  
      "de": "§0"  
    },  
    "lore": {  
      "en": [],  
      "de": []  
    },
    "amount": 1,  
    "slots": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 17, 18, 26, 27, 35, 36, 44, 45, 46, 47, 48, 49, 50,  
  51, 52, 53]  
  },
  "reservedSlots": [],  
  "nextPageItem": {  
    "itemType": "LIME_STAINED_GLASS_PANE",  
    "displayName": {  
      "en": "§aNext page",  
      "de": "§aNächste Seite"  
    },  
    "lore": {  
      "en": [],  
      "de": []  
    },
    "amount": 1,  
    "slots": [17, 26, 35, 44]  
  },
  "previousPageItem": {  
    "itemType": "LIME_STAINED_GLASS_PANE",  
    "displayName": {  
      "en": "§cPrevious page",  
      "de": "§cVorherige Seite"  
    },  
    "lore": {  
      "en": [],  
      "de": []  
    },
    "amount": 1,  
    "slots": [9, 18, 27, 36]  
  },
  "items": []  
}

Configuration utility

There is a plugin available for JetBrains IDEs which will show you the resulting inventory while you are editing the configuration file in your IDE.

Download the Cirrus Tooling plugin here.

Example image for Cirrus Tooling After installation just open any configuration file and select Cirrus Menu in the lower bar under the editor.