Home

Welcome to the UncomplicatedCustomRoles or UCR official wiki!
Here you'll find tutorials to configure our plugin for a perfect experience!

Note

This documentation is for the v3.0.0 of UncomplicatedCustomRoles

How to install UCR

UncomplicatedCustomRole is really easy to install: download the .dll file from the latest realese and put it inside the EXILED/Plugins folder.
You should use the latest version of EXILED.

At this time (13/07/2024) this plugin is supporting EXILED >= v8.9.6

How to configure UCR

You can put the custom role in any file inside the UncomplicatedCustomRoles folder, it will be loaded anyway.

Configuration

This is the actual code of the configuration of a custom role of UCR.

C#

No, you won't have to understand this one.
We put the YAML one underneath :D

        public abstract int Id { get; set; }
        public abstract string Name { get; set; }
        public abstract string? Nickname { get; set; }
        public abstract string CustomInfo { get; set; }
        public abstract string BadgeName { get; set; }
        public abstract string BadgeColor { get; set; }
        public abstract RoleTypeId Role { get; set; }
        public abstract RoleTypeId RoleAppearance { get; set; }
        public abstract Team? IsFriendOf { get; set; }
        public abstract HealthBehaviour Health { get; set; }
        public abstract AhpBehaviour Ahp { get; set; }
        public abstract List<UCREffect>? Effects { get; set; }
        public abstract StaminaBehaviour Stamina { get; set; }
        public abstract int MaxScp330Candies { get; set; }
        public abstract bool CanEscape { get; set; }
        public abstract string? RoleAfterEscape { get; set; }
        public abstract Vector3 Scale { get; set; }
        public abstract string SpawnBroadcast { get; set; }
        public abstract ushort SpawnBroadcastDuration { get; set; }
        public abstract string SpawnHint { get; set; }
        public abstract float SpawnHintDuration { get; set; }
        public abstract List<ItemType> Inventory { get; set; }
        public abstract List<uint> CustomItemsInventory { get; set; }
        public abstract Dictionary<AmmoType, ushort> Ammo { get; set; }
        public abstract float DamageMultiplier { get; set; }
        public abstract SpawnBehaviour? SpawnSettings { get; set; }
        public abstract bool IgnoreSpawnSystem { get; set; }

YAML

Ok you should understand this

custom_roles:
- id: 1
  name: Janitor
  nickname: 
  custom_info: Clean the Light Containment Zone.
  badge_name: ""
  badge_color: ""
  role: ClassD
  role_appearance: ClassD
  is_friend_of: 
  health:
    amount: 100
    maximum: 100
    hume_shield: 0
  ahp:
    amount: 0
    limit: 75
    decay: 1.2
    efficacy: 0.7
    sustain: 0
    persistant: false
  effects:
  - effect_type: MovementBoost
    duration: -1
    intensity: 1
    removable: false
  stamina:
    regen_multiplier: 1
    usage_multiplier: 1
    infinite: false
  max_scp_330_candies: 2
  can_escape: true
  role_after_escape: ""
  scale:
    x: 0
    y: 0
    z: 0
  spawn_broadcast: |-
    You are a <color=orange><b>Janitor</b></color>!
    Clean the Light Containment Zone!
  spawn_broadcast_duration: 5
  spawn_hint: This is an hint shown when you spawn as a Janitor!
  spawn_hint_duration: 3
  inventory:
  - Flashlight
  - KeycardJanitor
  custom_items_inventory: []
  ammo:
    Nato9: 5
  damage_multiplier: 1
  spawn_settings:
    max_players: 5
    min_players: 1
    spawn_chance: 60
    can_replace_roles:
    - ClassD
    spawn: RoomsSpawn
    spawn_zones: []
    spawn_rooms:
    - LczToilets
    spawn_position:
      x: 0
      y: 0
      z: 0
    spawn_offset:
      x: 0
      y: 0
      z: 0
  ignore_spawn_system: false

Tip

If you read [enum] and is not in this docs you probably should go see here!

Let's analyze together every single option here:

int id

The Id to indentify the role, the plugin will refer to the custom role with this Id so it must be unique.

string name

The name of the custom role, it will appear under the player name

string nickname

The nickname(s) that will be given to the custom role, divided by a comma (,).
See more in the specifics at this link

string custom_info

Custom info, will be shown under the role name

string badge_name

The name that will appear on the badge, leave it empty to disable the badge function

string badge_color

The color of the badge, leave it empty to disable the badge function

[enum]RoleTypeId role

Defines the role that this custom role will be spawned as

[enum]RoleTypeId role_appearance

You will be visible as this role to others but for the game you will be the first role defined.
Set equal to the role to disable

[enum]Team is_friend_of

With this value you can decide which teams can't damage (and be damaged) by this custom role.
Read more in the specifics at this link!

HealthBehaviour health

The health settings contained inside a specific class.
Read more in the specifics at this link!

AhpBehaviour ahp

The ahp (artificial health) settings contained inside a specific class.
Read more in the specifics at this link!

List<UCREffect> effects

Add effects to a role, read more here

StaminaBehaviour stamina

The stamina settings contained inside a specific class.
Read more in the specifics at this link!

bool can_escape

Choose if the role can escape or not.

string? role_after_escape

Choose the role that this player should get after escaped.
-> ⚠️ Please see this page of the wiki related to this topic: UncomplicatedCustomServer/UncomplicatedCustomRoles/wiki/Specifics!
Set it to null (so leave it empty) if you want the game to choose, otherwise see this page for more examples.

Vector3 scale

Set the player scale. y is the height - [Note]

string spawn_broadcast

This broadcast will be showed to the player when spawn as this custom role

ushort spawn_broadcast_duration

Defines for how long the broadcast will be shown

string spawn_hint

This hint will be showed to the player when spawn as this custom role

float spawn_hint_duration

Defines for how long the hint will be shown

List<[enum]ItemTypeId> inventory

A list of all of the items that will be given to the player when spawn as this custom class

List<int> custom_items_inventory

A list of all CustomItems IDs that will be given to the player when spawn as this custom class

Dictionary<[enum]AmmoType, int> ammo

A list of all ammos that will be given to the player when spawn as this custom class

float damage_multiplier

This value will be multiplied to the damage when this role hurts something.
If it's 1 then nothing will change.
If for example the damage_miltiplier is 2 and the damage is 20 the real damage will be 40.

SpawnBehaviour spawn_settings

The spawn options contained in a specific class.
Read more in the specifics at this link

bool ignore_spawn_system

If true the internal spawn system of UCR won't consider this role.

Create custom roles

In fact you can create configurations of independent custom roles in as many files as you want, as long as they are in the UncomplicatedCustomRoles folder will be loaded. The files will have to have this format:

custom_roles:
  - id: 1
    name: Zio pera
    ....
  - id: 2
    name: Thunder
    ....

Instead, if the role is put in a folder inside the UncomplicatedCustomRoles folder then will be loaded only when the current server port will be equal to the folder name.
So, if you put a janitor.yaml inside the UncomplicatedCustomRoles/1234 folder the role will be loaded only when the port will be 1234.

Any problem or question?

Then we can help you!
Join our Discord

You've found a bug or you want to suggest a new feature?

So open a new issue here!

You want to ask us a question?

@foxworn / @dr.agenda on discord!