Plugin Configuration

This page explains the main config.yml file.

File location

/plugins/SkinEngine/config.yml

Main sections

settings - basic SkinEngine settings
storage - storage configuration
economy - economy integrations
resource-pack - resource pack builder, hosting and merger
update - update checks and file updating

`settings`

`settings.license-key`

Used for SkinEngine licensed features.

Default value:

settings:
  license-key: ""

What it does:

Periodically verifies your license key to verify your legitimate purchase
This has no effect on your server's performance
The expected license format is AAAA-BBBB-CCCC-DDDD

`settings.language.type`

Sets the default language folder from translations/.

Default value:

settings:
  language:
    type: "default"

What it does:

Type default loads a language located in translations/default/
Custom values like serbian or german load translations/<name>/. In other words, the folder name becomes your language type
This is the default plugin language before any per-player override is applied
Your players can choose a different language if it exists, by running /se language <name> (see below)

`settings.language.switch.enabled`

Sets whether players can change their own language with /se language <name>.

Default value:

settings:
  language:
    switch:
      enabled: true

`settings.language.switch.auto-detect-client-language`

Lets SkinEngine match the Minecraft client locale using language.yml.

Default value:

settings:
  language:
    switch:
      auto-detect-client-language: true

What it does:

If enabled, SkinEngine tries to match the player's client locale to a translation folder
If no match is found, it falls back to settings.language.type (your plugin's default language)
See Translations for how to configure client locale codes for your languages

`settings.command-aliases`

Optionally registers extra root command aliases for SkinEngine.

Default value:

settings:
  command-aliases: []

What it does:

Lets you define extra aliases in addition to the built-in /skinengine and /se

Rules:

Aliases must be defined as a YAML list of strings
Aliases may only contain lowercase letters, numbers, underscores, or hyphens
Spaces and other invalid characters are not allowed

Example:

settings:
  command-aliases:
    - "skins"
    - "mycoolskins"
    - "customskins"

Important behavior:

After changing this option, restart the server, a plugin reload is not enough for alias registration changes to take effect!
If another plugin or command already uses the same alias, SkinEngine skips that alias

`settings.prevent-custom-item-merging`

Protects custom SkinEngine items in vanilla repair (anvil) and other blocks that merge or modify items.

Default value:

settings:
  prevent-custom-item-merging: true

What it does:

Normal items continue to use Minecraft's usual repair and combining behavior
When one SkinEngine item is combined with one normal item, SkinEngine keeps the custom look on the result
Minecraft still decides the result's durability, enchantments, name, repair cost, and other normal item data.
If your both items are custom (for example, two SkinEngine skins or SkinEngine with any other custom item), we block the merging event to prevent either of them getting lost.

[!INFO] This applies to: anvils, grindstones, and crafting tables (for simple repair crafting).

SkinEngine recognizes its own skinned items here, but also treats items with minecraft:item_model or Custom Model Data as custom. This helps avoid accidentally overwriting items made by another custom-item plugin, like ItemsAdder, Nexo, Oraxen, CraftEngine or other custom items that are not handled by SkinEngine.

[!TIP] Players with the skinengine.bypass.custom-merge permission can bypass only the custom + custom restriction. The normal visual-preservation behavior stays enabled. See Permissions.

`settings.prevent-skins.custom-model-data`

Blocks items that already use legacy Custom Model Data.

Default value:

settings:
  prevent-skins:
    custom-model-data: true

Keep this enabled if your server has custom items that use Custom Model Data. SkinEngine does not use Custom Model Data for its own skins, so these items can be safely kept out of the skin menu.

`settings.prevent-skins.temporarily-hide-skin`

Temporarily hides skins from players who do not own them.

[!TIP] If you sell your skins to donors, or you don't want to allow your players to share their custom items with each other, we recommend enabling this option!

Default value:

settings:
  prevent-skins:
    temporarily-hide-skin: false

When this option is enabled, all skinned items will only work when they're used by their owner. If the item is taken by someone else, its skin and effects will temporarily stop showing up until its given back to the owner.

`settings.prevent-skins.integrations`

Prevents SkinEngine skins from being applied to custom items made by supported item plugins.

Default value:

settings:
  prevent-skins:
    integrations:
      itemsadder:
        enabled: true
      oraxen:
        enabled: true
      nexo:
        enabled: true
      craftengine:
        enabled: true

When an integration is enabled, SkinEngine asks that plugin whether the selected item is one of its custom items. If it is, the item cannot enter the skin selection flow and its existing custom appearance stays protected.

Each integration only does anything when its plugin is installed and enabled. You can turn off an individual check by setting its enabled value to false.

Option	Custom items detected
`settings.prevent-skins.integrations.itemsadder.enabled`	ItemsAdder
`settings.prevent-skins.integrations.oraxen.enabled`	Oraxen
`settings.prevent-skins.integrations.nexo.enabled`	Nexo
`settings.prevent-skins.integrations.craftengine.enabled`	CraftEngine

[!INFO] These options protect custom items. They do not control resource pack merging. Use resource-pack.merge when another plugin should deliver SkinEngine's resource pack.

`settings.prevent-skins.blocked-nbt`

Blocks items whose saved item data contains one of your configured patterns.

What this means:

matching items cannot have a SkinEngine skin applied or changed
clearing an existing SkinEngine skin remains available
this is useful for custom items from plugins without a built-in integration, or for items marked by your own plugin

Default value:

settings:
  prevent-skins:
    blocked-nbt:
      - "se:noskin"

How to add a rule:

Hold the item in your main hand.
Run /se nbt to view its saved item data.
Find a short, unique value that identifies the custom item or plugin.
Add that value to blocked-nbt and run /se reload.

Plain entries are case-insensitive text matches. For example:

blocked-nbt:
  - "myplugin:custom_item"

For a broader match, start the entry with {$regex}:

blocked-nbt:
  - "{$regex}myplugin:(weapon|tool)_.*"

[!TIP] Keep rules as specific as possible. A common word or a broad regex can also block normal items that happen to contain the same text.

`settings.particles.enabled`

Turns on the skin particle system.

Default value:

settings:
  particles:
    enabled: true

[!WARNING] If this is set to false, all visual particle effects will stop rendering! You can disable particles per-skin by removing the particle option from their config.

`settings.particles.viewer-range`

Sets how far away players can see SkinEngine particles.

Default value:

settings:
  particles:
    viewer-range: 32

[!INFO] Avoid setting this value too high as it can affect performance.

`settings.particles.armor.interval-ticks`

Sets how often armor particle effects are updated.

Default value:

settings:
  particles:
    armor:
      interval-ticks: 10

[!INFO] Lower values update more often. Higher values are lighter on performance.

`storage`

`storage.type`

Sets the active storage backend.

Default value:

storage:
  type: "sqlite"

Supported values:

sqlite
mysql
mariadb

`storage.remote.host`

Remote database host for MySQL or MariaDB.

Default value:

storage:
  remote:
    host: "127.0.0.1"

`storage.remote.port`

Remote database port.

Default value:

storage:
  remote:
    port: 3306

`storage.remote.database`

Database name used by SkinEngine.

Default value:

storage:
  remote:
    database: "skinengine"

`storage.remote.username`

Username used for remote database login.

Default value:

storage:
  remote:
    username: "root"

`storage.remote.password`

Password used for remote database login.

Default value:

storage:
  remote:
    password: ""

`storage.remote.table-prefix`

Prefix added to SkinEngine tables.

Default value:

storage:
  remote:
    table-prefix: "skinengine_"

Change this only if you know exactly why you need it.

`storage.remote.ssl`

Enables SSL for the remote database connection.

Default value:

storage:
  remote:
    ssl: false

`storage.remote.connect-timeout-ms`

Connection timeout in milliseconds.

Default value:

storage:
  remote:
    connect-timeout-ms: 5000

`storage.remote.read-timeout-ms`

Read timeout in milliseconds.

Default value:

storage:
  remote:
    read-timeout-ms: 10000

`economy`

`economy.provider`

Chooses the economy backend SkinEngine should use.

Default value:

economy:
  provider: "vault"

Supported values:

vault
playerpoints

`economy.currency`

Display currency name used in translated text.

Default value:

economy:
  currency: "coins"

`resource-pack`

`resource-pack.display.namespace`

[!ERROR] Changing this value in production will break all existing SkinEngine items on your server! If you accidentally changed it, revert the change as fast as possible to the value before updating (it's skinengine by default).

Namespace used in generated resource-pack paths and model keys.

This is only how the resource pack is internally organized, your players can't see this in-game.

Default value:

resource-pack:
  display:
    namespace: "skinengine"

`resource-pack.display.description`

Pack description shown by Minecraft.

Default value:

resource-pack:
  display:
    description: "&bSkin&3Engine &fResource Pack"

The plugin treats this as plain text content for the pack description field.

We recommend using legacy color codes &<code> or §<code>. No MiniMessage here due to Minecraft limitations!

`resource-pack.display.prompt`

Prompt text shown when the server sends the resource pack.

Default value:

resource-pack:
  display:
    prompt: |-
      <#fda130>Accept the pack to view SkinEngine skins!</#fda130>
      <#bcff47>Press <bold>Yes</bold> below to start.</#bcff47>

This supports MiniMessage formatting.

`resource-pack.pack-format-override`

Optional explicit pack format override.

[!INFO] In most cases, this should be kept commented out. If you know what you're doing, you can manually set the override for the resource pack format here.

SkinEngine by default generates pack overrides starting from the lowest supported version, to the latest supported version. However, you can use this option to manually "update" the pack before we do. Don't ask for support if you change this option!

Default state:

resource-pack:
  # pack-format-override: 75

This is commented out by default, so no override is active.

`resource-pack.supported-formats-override`

Optional supported formats override.

[!INFO] In most cases, this should be kept commented out. If you know what you're doing, you can manually set the override for the resource pack supported formats here.

Default state:

resource-pack:
  # supported-formats-override: [46, 75]

This is also inactive by default unless you uncomment it.

`resource-pack.images.range.min`

Lower bound for managed image codepoint allocation.

[!WARNING] This is a SPUA-A starting value. Don't modify unless you get conflicts with third-party plugins.

Default value:

resource-pack:
  images:
    range:
      min: "0xF0000"

`resource-pack.images.range.max`

Upper bound for managed image codepoint allocation.

[!WARNING] This is a SPUA-A ending value. Don't modify unless you get conflicts with third-party plugins.

Default value:

resource-pack:
  images:
    range:
      max: "0xF17FF"

These values are used by the image/font asset system documented on Images and Font Assets.

`resource-pack.host`

`resource-pack.host.send-on-join`

Sends the current pack to players when they join.

Default value:

resource-pack:
  host:
    send-on-join: true

`resource-pack.host.send-on-zip`

Sends the pack after /se zip finishes.

Default value:

resource-pack:
  host:
    send-on-zip: true

`resource-pack.host.required`

Marks the resource pack as required.

Default value:

resource-pack:
  host:
    required: true

If a player refuses the pack, Minecraft itself will kick them from your server until they manually accept the pack.

`resource-pack.host.self-host.enabled`

Enables SkinEngine's built-in pack host. This will allow connections to your server so that your players can download the pack automatically on join.

Default value:

resource-pack:
  host:
    self-host:
      enabled: false

`resource-pack.host.self-host.host`

Bind address for the built-in host.

What IP address should you use here?

In most cases, 0.0.0.0 will work fine
You can also try other local IP addresses, such as 127.0.0.1
If that doesn't work, try using a direct IP of your server
Domain names (with valid DNS records pointing to the IP) should also work
If everything above fails, please contact your server hosting for support. We can't help you with this!

Default value:

resource-pack:
  host:
    self-host:
      host: "0.0.0.0"

`resource-pack.host.self-host.port`

Port for the built-in host.

You must create a new, unused additional port for your server and set it here.

Default value:

resource-pack:
  host:
    self-host:
      port: 8080

`resource-pack.host.self-host.url`

Optional public URL override used when the bind address itself is not the real public address.

Good to know:

If you don't use SSL, it should begin with http://
If you use SSL, it should begin with https://
Accepts both domain names and direct (public) IP addresses
If your service is behind a valid reverse proxy (Apache, nginx), the port is not required

[!WARNING] If you don't know what this is, please do the following:

Set it to http://DIRECT_IP_OF_YOUR_SERVER:PORT
Example: http://123.45.255.255:8080
Please see the two options above, you can use the IP set in resource-pack.host.self-host.host and the port from resource-pack.host.self-host.port

Default value:

resource-pack:
  host:
    self-host:
      url: "http://example.com:8080"

`resource-pack.merge`

`resource-pack.merge.enabled`

Enables merge/export mode for external pack workflows.

[!INFO] Enable this if you use ItemsAdder, Nexo, Oraxen and similar plugins, and you want to let them handle the pack!

Default value:

resource-pack:
  merge:
    enabled: false

`resource-pack.merge.paths`

Defines where SkinEngine should export the generated pack when merge mode is enabled.

By default, SkinEngine is configured to work with ItemsAdder, Nexo or Oraxen. No need to change anything here.

Default value:

resource-pack:
  merge:
    paths:
      - "{$extract:/resourcepack/}ItemsAdder/contents"
      - "{$zip}Nexo/pack/external_packs"
      - "Oraxen/pack/uploads"

[!INFO] Even if you don't use all three plugins on your server, you can leave them configured. SkinEngine will only merge with installed plugins.

Supported path modes:

{$zip} writes a zip file
{$extract} writes extracted output
{$extract:/subfolder/} writes extracted output inside an extra subfolder (we added this mainly because of ItemsAdder's weird structure)

All paths are plugin-relative output locations. So we assume all folders are located in your server's /plugins/ folder!

`update`

`update.check`

Should SkinEngine periodically check on Github if there's a new update available to download?

Default value:

update:
  check: true

`update.version`

[!ERROR] Do not change this manually! It can break your configuration files.

Internal managed YAML version - used to automatically update your files with new stuff once the new update is out!

Default value:

update:
  version: 3 # Don't change!