How to add a Personal Item into the Umbra Server

Personal Items 101:

Introduction:

The Umbra Sector offers characters the opportunity to bring special and personalised items and clothing to the station. These items can have personal sprites, icons or just be a renamed item with slightly different properties. There are a few limits to these items that this page will go over but any questions can be forwarded to Maintainers if necessary!

This guide assumes basic knowledge of setting up a development environment and the creation of prototypes with possible new textures, if you have any questions contact someone with the @maintainer role or ask in ⁠#development.

Limitations of Personal Items:

There are a set of guidelines regarding what personal items can be on the Umbra Sector. If you have any specific questions regarding the functionality or look to a personal item, you can ask in #questions-to-gms or @maintainers for any functionality questions.

How to add Personal Items:

There are three locations for files that you will be working with for adding personal items. They are:

1. Resources/Textures/_Umbra/PersonalItems/[...]/name/name.rsi
   
2. Resources/Prototypes/_Umbra/PersonalItems/[...]/name/name.yml
3. Resources/Prototypes/_Umbra/Loadouts/loadout_groups.yml

It is recommended you peruse though other made personal items but there are a set of coding guidelines for Personal Items. Personal Items should be a max of three words. One word for the characters name, and a max of two words regarding the item itself. This will be used to create the ID of the item, as well as the lowercase name for the folder and file. Personal Item IDs all start with "PersonalItem". All names for items should only be capitalised if there is a name for a character owning an item, not if the item is of the character. For example: 

• John's winter coat
  • The name "John" is capitalised as they own the winter coat
    
  • The name "winter coat" is lowercase as it is the name of the item
  • This would become johnwintercoat.rsi and johnwintercoat.yml
  • The Personal Item ID would be PersonalItemJohnWinterCoat
• john plushie
  • The name "john" is lowercase as it isn't the owner rather an item about the owner
  • the name "plushie" is lowercase as it is the name of the item
  • This would become johnplushie.rsi and johnplushie.yml
  • The Personal Item ID would be PersonalItemJohnPlushie

To add the item to the Personal Item section in game, you must add two sections. One within name.yml and loadout_groups.yml. 

- type: loadout
  id: PersonalItemJohnWinterCoat
  storage:
    back:
    - PersonalItemJohnWinterCoat
  effects:
  - !type:PersonalItemLoadoutEffect
    character:
    - John
    jobs:
    - JobCaptain

This section adds the Personal Item to be able to be given to any character listed in the Character category. This can also have an optional specified role in the Jobs category to whitelist the item if required. This example locks the item to only the captain role. These can be found in Resources/Locale/en-US/job/job-names.ftl and Resources/Locale/en-US/_CD/job/job-names.ftl

- type: loadoutGroup
  id: PersonalItemsJobAgnostic
  name: loadout-group-personal-items
  minLimit: 0
  maxLimit: 2
  loadouts:
  - [...]
  - PersonalItemJohnWinterCoat

This section adds the Personal Item into the personal item loadout within the games character creator. Add the new item to the very bottom of this section.