Skip to content
FoxWorn3365 edited this page Aug 23, 2024 · 22 revisions

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 v4.0.0 of UncomplicatedCustomRoles

How to install UCR

UncomplicatedCustomRole is really easy to install: download the .dll file from the latest release and put it inside the EXILED/Plugins folder.
You should use the latest version of EXILED.
You have also to download the file Newtonsoft.Json.dll from the latest release and put it inside the EXILED/Plugins/dependencies folder if yuou don't have it.

At this time (23/08/2024) this plugin is supporting EXILED >= v8.11.0

How to configure UCR

You can put the custom role in any file inside the EXILED/Configs/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 bool OverrideRoleName { 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 Team? Team { get; set; }
        public abstract RoleTypeId RoleAppearance { get; set; }
        public abstract List<Team> IsFriendOf { get; set; }
        public abstract HealthBehaviour Health { get; set; }
        public abstract AhpBehaviour Ahp { get; set; }
        public abstract List<Effect>? Effects { get; set; }
        public abstract StaminaBehaviour Stamina { get; set; }
        public abstract int MaxScp330Candies { get; set; }
        public abstract bool CanEscape { get; set; }
        public abstract Dictionary<string, 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 Dictionary<ItemCategory, sbyte> CustomInventoryLimits { 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 CustomFlags? CustomFlags { get; set; }
        public abstract bool IgnoreSpawnSystem { get; set; }

YAML

Ok you should understand this

id: 1
name: 'Janitor'
override_role_name: false
nickname: 'D-%dnumber%'
custom_info: 'Janitor'
badge_name: 'Janitor'
badge_color: 'pumpkin'
role: ClassD
team: 
role_appearance: ClassD
is_friend_of: []
health:
  amount: 100
  maximum: 100
  hume_shield: 0
  hume_shield_regeneration_amout: 2
  hume_shield_regeneration_delay: 7.5
ahp:
  amount: 0
  limit: 75
  decay: 1.20000005
  efficacy: 0.699999988
  sustain: 0
  persistant: false
effects: []
stamina:
  regen_multiplier: 1
  usage_multiplier: 1
  infinite: false
max_scp330_candies: 2
can_escape: true
role_after_escape:
  default: InternalRole Spectator
  cuffed by InternalTeam ChaosInsurgency: InternalRole ClassD
scale:
  x: 1
  y: 1
  z: 1
spawn_broadcast: |-
  You are a <color=orange><b>Janitor</b></color>!
  Clean the Light Containment Zone!
spawn_broadcast_duration: 5
spawn_hint: 'This hint will be shown when you will spawn as a Janitor!'
spawn_hint_duration: 5
custom_inventory_limits:
  Medical: 2
inventory:
- Flashlight
- KeycardJanitor
custom_items_inventory: []
ammo:
  Nato9: 10
damage_multiplier: 1
spawn_settings:
  can_replace_roles:
  - ClassD
  max_players: 10
  min_players: 1
  spawn_chance: 60
  spawn: RoomsSpawn
  spawn_zones: []
  spawn_rooms:
  - LczClassDSpawn
  spawn_points: []
  required_permission: ''
custom_flags: 
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 won't appear anywhere on the player as it's just a way for server owners to distinguish a Custom Role unless override_role_name is not false.

bool override_role_name

If true the vanilla name of the role will be hidden and the name will be shown instead.\

Warning

You can't use tags such as <color=>, <size=>, <b> etc in the name is this option is true!

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.
See more in the specifics at this link

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]Team? team

If not null you can override the vanilla team of the given role.
This will work also if the role class is a human while the team is SCPs and vice-versa!

[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]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!

Note

If the team param is NOT null it will bypass this system! (for example if the team is SCPs, is_friend_of: [] and role: ClassD the role won't be damaged by SCPs)

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 Custom Role can escape or not.

Dictionary<string, string> role_after_escape

Choose the role that this player should get after escaped.\

Note

Please see this page of the wiki related to this topic: UncomplicatedCustomServer/UncomplicatedCustomRoles/wiki/Specifics!
Set it to {} if you want the game to choose, otherwise see this page for more examples.

Vector3 scale

Set the player scale.\

Tip

y is for the height!

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

Dictionary<[enum]ItemCategory, sbyte> custom_inventory_limits

Change the inventory limits for this Custom Role for each ItemCategory.

Important

You can only REDUCE inventory limits and not increase them!

List<[enum]ItemTypeId> inventory

A list of all of the items that will be given to the player when spawn as this Custom Role,

List<int> custom_items_inventory

A list of all CustomItems IDs that will be given to the player when spawn as this Custom Role.

Dictionary<[enum]AmmoType, int> ammo

A list of all ammos that will be given to the player when spawn as this Custom Role.

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

CustomFlag custom_flags

You can add custom behaviour of your Custom Role by adding one or more CustomFlag.

bool ignore_spawn_system

If true the internal spawn system of UCR won't consider this Custom 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:

id: 1
name: ...
...

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.

Note

Every single file can contain only and only one CustomRole!

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!

Clone this wiki locally