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 v2.2.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 (08/08/2024) this plugin is supporting EXILED >= v8.9.4

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 CustomInfo { get; set; }
        public abstract string BadgeName { get; set; }
        public abstract string BadgeColor { get; set; }
        public abstract int MaxPlayers { get; set; }
        public abstract int MinPlayers { get; set; }
        public abstract int SpawnChance { get; set; }
        public abstract RoleTypeId Role { get; set; }
        public abstract RoleTypeId RoleAppearance { get; set; }
        public abstract List<RoleTypeId> CanReplaceRoles { get; set; }
        public abstract float Health { get; set; }
        public abstract float MaxHealth { get; set; }
        public abstract float Ahp { get; set; }
        public abstract float HumeShield { get; set; }
        public abstract List<UCREffect>? Effects { get; set; }
        public abstract bool InfiniteStamina { 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 SpawnLocationType Spawn { get; set; }
        public abstract List<ZoneType> SpawnZones { get; set; }
        public abstract List<RoomType> SpawnRooms { get; set; }
        public abstract Vector3 SpawnPosition { get; set; }
        public abstract Vector3 SpawnOffset { get; set; }
        public abstract float DamageMultiplier { get; set; }
        public abstract string? RequiredPermission { get; set; }
        public abstract bool IgnoreSpawnSystem { get; set; }

YAML

Ok you should understand this

custom_roles:
- id: 1
  name: 'Janitor'
  custom_info: 'Clean the Light Containment Zone.'
  badge_name: ''
  badge_color: ''
  max_players: 5
  min_players: 1
  spawn_chance: 60
  role: ClassD
  role_appearance: ClassD
  can_replace_roles:
  - ClassD
  health: 100
  max_health: 100
  ahp: 0
  hume_shield: 0
  effects:
  -
  # The effect EffectType found on the EXILED discord server
    effect_type: MovementBoost
    # The duration of the effect, -1 if you want to have an infinite effect
    duration: -1
    # The intensity of the effect from 1 to 255
    intensity: 1
    # Can the effect be removed with SCP-500?
    removable: false
  infinite_stamina: false
  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
  spawn: RoomsSpawn
  spawn_zones: []
  spawn_rooms:
  - LczToilets
  spawn_position:
    x: 0
    y: 0
    z: 0
  spawn_offset:
    x: 0
    y: 0
    z: 0
  damage_multiplier: 1
  required_permission: ""
  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 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

int max_players

The max number of players that can be spawned with this role

int min_players

The minimum number of players in the server to allow the spawn of this role

int spawn_chance

Defines the spawn chance for this role in percentage, 0 is never and 100 is always

[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

List<[enum]RoleTypeId> can_replace_roles

Defines the roles that can be replaced by this custom role.
For example if the list contains only NtfPrivate a NtfCaptain won't never be this role

float healt

The healt of the player

float max_healt

The max healt, equals to healt by default

float ahp

The artificial hp (AHP) that will be given to the player when spawned

float hume_shield

Set the max hume shield that the custom role can have

List<UCREffect> effects

Add effects to a role, read more here

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 if you want the game to choose, otherwise see this page for more examples.

bool infinite_stamina

Choose if the role will use or not the stamina.

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

[enum]SpawnLocationType spawn

Define the spawn location type, read more here

List<[enum]ZoneType> spawn_zones

Define a list of zones that will be the spawnpoint for the role if spawn is ZoneSpawn. The choice is randomic.

List<[enum]RoomTypeId> spawn_rooms

Define a list of rooms that will be the spawnpoint for the role if spawn is RoomsSpawn. The choice is randomic.

Vector3 spawn_position

Define the spawn position by x, y and z if spawn is PositionSpawn. - [Note]

Vector3 spawn_offset

Change the spawn coordinates by adding or removing.
Available only for these SpawnSettings: RoomsSpawn. [Note]

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.

string required_permission

If not null or empty impose that only players with that permission can spawn as this role.

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!