Home

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

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 (21/12/2023) this plugin is supporting EXILED >= v8.4.3

How to configure UCR

You can create and configure as many roles as you like with UCR in various manienre, here explained:

• You can create all the roles in the main configuration file, keep in mind that an error would lead to a complete reset of the plugin configuration
• 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 DisplayNickname { 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 CanEscape { 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 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.'
    display_nickname: 'D-%name%'
    max_players: 5
    min_players: 1
    spawn_chance: 100
    role: NtfSergeant
    role_appearance: ChaosRifleman
    can_replace_roles:
    - ClassD
    health: 150
    max_health: 150
    ahp: 20
    hume_shield: 0
    effects: []
    can_escape: true
    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: KeepRoleSpawn
    spawn_zones: []
    spawn_rooms:
    - LczToilets
    spawn_position:
      x: 0
      y: 0
      z: 0
    spawn_offset:
      x: 0
      y: 0
      z: 0
    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? display_nickname

If not null this nickname will be shown, some extra features are avaiable and listed here (like placeholders!)

int max_players

The max number of players that can be spawned with 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.

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]

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 outside the <port>-config.yml

The latest version of UncomplicatedCustomRoles brought an innovative feature that will make you stop cursing when you make a YAML error and EXILED would reset your configuration. Now 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
    ....

Any problem or question?

Then we can help you!

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!