# Plugins

{% content-ref url="/spaces/xCfVOPUXVrM7OymrJ1os" %}
[4.3.3](https://csl.sarhatabaot.net/4.3.3/)
{% endcontent-ref %}

{% content-ref url="/spaces/hQqUXIJ1A8TZFmPWO9r4" %}
[Trading Cards](https://plugins.sarhatabaot.net/trading-cards/)
{% endcontent-ref %}


# README WIP

This wiki is a WIP, you may notice empty or missing content. This is all being updated and worked on in the next following days / week.


# Trading Cards

[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=TreasureIslandMC_TradingCards\&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=TreasureIslandMC_TradingCards) [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=TreasureIslandMC_TradingCards\&metric=bugs)](https://sonarcloud.io/summary/new_code?id=TreasureIslandMC_TradingCards) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=TreasureIslandMC_TradingCards\&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=TreasureIslandMC_TradingCards) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=TreasureIslandMC_TradingCards\&metric=coverage)](https://sonarcloud.io/summary/new_code?id=TreasureIslandMC_TradingCards) [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=TreasureIslandMC_TradingCards\&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=TreasureIslandMC_TradingCards)

[![](https://jitpack.io/v/sarhatabaot/TradingCards.svg)](https://jitpack.io/#sarhatabaot/TradingCards) [![Java CI with Maven](https://github.com/TreasureIslandMC/TradingCards/actions/workflows/maven.yml/badge.svg)](https://github.com/TreasureIslandMC/TradingCards/actions/workflows/maven.yml) [![](https://img.shields.io/discord/881610309637398538?color=%235865F2\&label=support\&logo=Discord\&logoColor=white\&style=for-the-badge)](https://discord.gg/4v9gsBCgg8)

Spigot plugin for Trading Cards. An updated version of TradingCards with improvements and new features.

You can find dev builds on <https://ci.codemc.io/job/sarhatabaot/job/TradingCards/>

## [Coming from version 5.0.x? See how to migrate here.](https://tradingcards.sarhatabaot.net/migration/5.0.4-greater-than-5.7.2+)

## New Features:

* Java 16 - 1.17+
* Custom Drop types
* Custom Materials
* Custom texture support (CustomModelData nbt tag)
* Multiple cards files
* New config system
* New commands:
  * Sell command
  * Worth command
  * Debug commands - Version, Modules, Rarities, exists.

### Improvements:

* Proper use of VaultAPI.
* Improved deck format
* Tab Completions for commands.
* Better pack format. [Old format](https://github.com/sarhatabaot/TradingCards/blob/f24613e8c6238413f89085b9d5030afb7acb3afa/tradingcards-plugin/src/main/resources/settings/packs.yml), [New Format](https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/data/packs.yml)
* Cached cards

### Unimplemented:

* Rewards from completed rarities
* "SCHEDULED" series mode

## Addons:

This version of Trading Cards doesn't support MythicMobs, MobArena & Towny out of the box. For support, you need to install additional addons: [Addons](https://github.com/sarhatabaot/TradingCards/wiki/Tradingcards-Addons)

These are normal plugins, to install just place in your plugins folder.

## Building TradingCards

```
mvn clean package
```

Any class files in the "messages" package are automatically generated from the "internal-messages" folder. To generate them run `messages:generate` & `formatter:format`. You should probably add these as a compound configuration in your ide. See more info about the usage <https://github.com/sarhatabaot/messages-core>


# FAQ

1. **I want to disable card drops:** See [Chances](https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/settings/chances.yml). Omitting the type will prevent the cards from being dropped.
2. **I'm using ItemsAdder or a custom resource pack and my commands are getting replaced with emojis!** See [#182](https://github.com/sarhatabaot/TradingCards/issues/182) for a fix!
3. **Does TradingCards have a pre-made custom resource pack?** We currently don't have one. However isaaclepes from the community has made one! You can find it here <https://github.com/isaaclepes/TradingCardsResource>, it currently required optifine to work.
4. **I want to add a custom texture to my cards!** We support using custom-model-data, use the `/cards edit <cardId> CUSTOM_MODEL_DATA <data>` to edit the data.


# Getting Started

You can use TradingCards out of the box with the configs it comes with.


# Settings

{% hint style="info" %}
Find these under your TradingCards/settings folder
{% endhint %}

{% content-ref url="/pages/URio2crJTfmpw1OFCer1" %}
[General](/trading-cards/customizing/settings/general)
{% endcontent-ref %}

{% content-ref url="/pages/27RgHeR3bgW7kPrQtLEq" %}
[Chances](/trading-cards/customizing/settings/chances)
{% endcontent-ref %}

{% content-ref url="/pages/Q1zptNj1SMB69oULnlCe" %}
[Messages](/trading-cards/customizing/settings/messages)
{% endcontent-ref %}

{% content-ref url="/pages/S1gOhpLu4hnpuuGntPSV" %}
[Storage](/trading-cards/customizing/settings/storage)
{% endcontent-ref %}

{% content-ref url="/pages/pyejbJ8AwSeieY9cmIBt" %}
[Advanced](/trading-cards/customizing/settings/advanced)
{% endcontent-ref %}


# General

{% hint style="info" %}
You can find the default, commented file here: <https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/settings/general.yml>
{% endhint %}

**Debug Mode**: Enable / Disable debug messages. Default: false


# Chances

Chances are calculated when a mob or a player is killed.

{% hint style="info" %}
You can find the default, commented file here: <https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/settings/chances.yml>
{% endhint %}

### How is the drop chance calculated?

First, we determine the mob type from the mob killed. This is done via a predetermined pool of mobs, you can find that pool in the following link: [MobGroupUtil](https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/java/net/tinetwork/tradingcards/tradingcardsplugin/utils/MobGroupUtil.java).

After the mob type is determined, we check the "general drop chance" in `chances.yml` :

```yaml
hostile-chance: 20000
neutral-chance: 5000
passive-chance: 1000
boss-chance: 100000
all-chance: 5000
```

We then generate a random number between 0-100,000 and check if that number is below the chance. If it is, a card is dropped.

#### For example:

**Cards Drops:** \
Player kills a zombie. Type determined is "hostile". Hostile chance is 20,000. Generated number is 12,456. \
12456 < 20000 = drop\
\
**No Drop:**\
Player kills a zombie. Type determined is "hostile". Hostile chance is 20,000. Generated number is 40,000. \
40000 > 20000 = no drop

### How is the card chosen?

We choose the rarity to drop a card from through a "weight" system. The chances you define in chances.yml define the weight. The higher the weight is, the higher the chance that rarity will drop.

```yaml
common:
  hostile: 100000
  neutral: 100000
  passive: 100000
uncommon:
  hostile: 20000
  neutral: 10000
  passive: 5000
rare:
  hostile: 1000
  neutral: 500
very-rare:
  hostile: 10
  boss: 100000
legendary:
  hostile: 1
  boss: 50000
```

We use a CollectionSampler using the weights of all rarities as a sampler. For example, taking the "hostile" drop, we will pass the values to our sampler and then randomly return the rarity id.

If we ommit a type from the section above, it will not get dropped from that type.


# Messages

{% hint style="info" %}
You can find the default file here: <https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/settings/messages.yml>
{% endhint %}


# Storage

{% hint style="info" %}
You can find the default, commented file here: [https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/settings/storage.yml](https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/settings/messages.yml)
{% endhint %}


# Advanced

{% hint style="info" %}
You can find the default commented file here: <https://github.com/sarhatabaot/TradingCards/blob/master/tradingcards-plugin/src/main/resources/settings/advanced.yml>
{% endhint %}


# Customizing

{% hint style="info" %}
It is recommended you use the commands to create/edit/delete anything you make. You can however directly edit the files in YAML mode if that's easier for you. Just don't forget to save your changes and run `/cards reload` when you are done.
{% endhint %}


# Cards


# Rarities


# Series


# Custom Types


# Upgrades


# Drop Pools

## Per-Mob Drop Pools

This page explains how to configure per-mob weighted card drops using `settings/drop-pools.yml`.

### What it does

* Lets you define custom drop pools per entity type (for example `zombie`, `skeleton`, `ender_dragon`).
* Supports optional custom-name matching (`namecheck`) for custom mobs.
* Supports weighted outcomes:
* `card_<cardId>` to drop a specific card id (random active version across rarity/series).
* `rarity_<rarityId>` to drop a random active card from that rarity.
* Supports `dropmin` and `dropmax` to drop multiple cards per kill.
* Supports optional per-pool `dropchance` (out of 100,000).

If no pool matches, the plugin uses the existing default drop logic from `chances.yml`.

### File location

* `plugins/TradingCards/settings/drop-pools.yml`

Default template is shipped at:

* `tradingcards-plugin/src/main/resources/settings/drop-pools.yml`

### Basic format

```yaml
config-version: 1

zombie:
  namecheck: "Jeffrey" # optional
  drops:
    enabled: true
    dropmin: 1
    dropmax: 1
    dropchance: 100000 # optional, 1..100000. If omitted, default mob-group chance is used.
    card_zombie:
      dropchance: 9900
    rarity_common:
      dropchance: 100
```

### Option reference

* Entity key:
* Any Bukkit `EntityType` id, case-insensitive (`zombie`, `skeleton`, `creeper`).
* `namecheck`:
* Optional exact name match for the mob custom name.
* Color codes are supported in matching.
* `drops.enabled`:
* Enables/disables the pool.
* `drops.dropmin`:
* Minimum number of card rolls to drop when this pool triggers.
* `drops.dropmax`:
* Maximum number of card rolls to drop when this pool triggers.
* `drops.dropchance`:
* Optional pool trigger chance out of `100000`.
* If omitted, plugin uses normal hostile/neutral/passive/boss chance from `chances.yml`.
* Entry keys under `drops`:
* `card_<cardId>` with `dropchance` weight.
* `rarity_<rarityId>` with `dropchance` weight.
* Weights are relative, not percentages.

### Weight behavior

* Entries are selected by weight.
* Example:
* `card_zombie: 9900`
* `rarity_common: 100`
* Total is `10000`, so `card_zombie` has 99% weight and `rarity_common` has 1% weight.

### Notes and validation

* Invalid entity keys are ignored with a warning.
* Invalid entry keys are ignored with a warning.
* Non-positive entry weights are ignored.
* If a pool is enabled but has no valid entries, it logs a warning and drops nothing from that pool.
* Rarity ids in `rarity_<id>` are matched case-insensitively.

### Reloading

* After changes, run your plugin reload command so configs are reloaded.
* TradingCards internal reload path reloads `drop-pools.yml`.


# Addons


# Official Addons

<table><thead><tr><th width="219.33333333333331">Addon</th><th width="211">Description</th><th>Link</th></tr></thead><tbody><tr><td>MythicMobs</td><td>Adds support for drops from MythicMobs.</td><td>https://github.com/TreasureIslandMC/TCMythicMobs</td></tr><tr><td>MobArena</td><td>Adds mob arena support.</td><td>https://github.com/TreasureIslandMC/TCMobArena</td></tr><tr><td>Towny (Outdated)</td><td>Adds towny support.</td><td>https://github.com/TreasureIslandMC/TCTowny</td></tr><tr><td>Recipes</td><td>Allows you to create custom recipes from cards.</td><td>https://github.com/sarhatabaot/TCRecipes</td></tr></tbody></table>


# Community Addons

| Addon        | Description                            | Link                                                 |
| ------------ | -------------------------------------- | ---------------------------------------------------- |
| ResourcePack | Resource Pack for Trading Cards Plugin | <https://github.com/isaaclepes/TradingCardsResource> |


# User Commands


# Worth

Display the worth of an item / pack in your inventory.

Use this command to display the sell & buy worth of a pack or card in your inventory.

<div><figure><img src="https://124733191-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhQqUXIJ1A8TZFmPWO9r4%2Fuploads%2FNpGvISl5XZTXjeJ6yg7r%2Fjavaw_CKgt4KN7bB.png?alt=media&amp;token=88544341-2b70-44af-acb6-cad37fdae0ad" alt=""><figcaption></figcaption></figure> <figure><img src="https://124733191-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhQqUXIJ1A8TZFmPWO9r4%2Fuploads%2F4jMcSott9YePjdlVByuJ%2Fjavaw_zHxMiVtmOq.png?alt=media&amp;token=f42bd925-3ec8-47ec-9f30-d2636982a369" alt=""><figcaption><p>Un-tradeable card</p></figcaption></figure></div>


# Deck

Use /deck \<deckNumber> to obtain a deck or open a deck.

### Obtain Item

<figure><img src="https://124733191-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhQqUXIJ1A8TZFmPWO9r4%2Fuploads%2F0uECiyeTrUDV5gHmgyHn%2Fezgif-3-d44470f557.gif?alt=media&amp;token=4524903a-cdc6-4551-aa76-d8cf574576cd" alt=""><figcaption></figcaption></figure>

### Open Directly

To use this feature you must enable it in your general.yml: Set `use-deck-item: false`


# Info


# Upgrade


# List


# Buy


# Sell


# Admin Commands


# Resolve


# Migrate


# Giveaway


# Give


# Debug


# Create


# Edit


# All Commands

## Card Commands:

### Player Commands

| Commands                    | Description                                 |
| --------------------------- | ------------------------------------------- |
| `/cards version`            | Shows the plugin version.                   |
| `/cards reload`             | Reloads the plugin.                         |
| `/cards resolve`            | Allows you to use /cards resolve            |
| `/cards toggle`             | Toggles card drops.                         |
| `/cards give card`          | Gives a card.                               |
| `/cards give card shiny`    | Gives a shiny card.                         |
| `/cards give pack`          | Gives a pack.                               |
| `/cards give random entity` | Allows you to use /cards give random entity |
| `/cards give random rarity` | Allows you to use /cards give random rarity |
| `/cards list`               | Allows you to use /cards list               |
| `/cards list player`        | Allows you to use /cards list player        |
| `/cards list pack`          | Allows you to use /cards list pack          |
| `/cards giveaway rarity`    | Allows you to use /cards giveaway rarity    |
| `/cards giveaway entity`    | Allows you to use /cards giveaway entity    |
| `/cards worth`              | Allows you to use /cards worth              |
| `/cards sell`               | Allows you to use /cards sell               |
| `/cards buy`                | Allows you to use /cards buy                |
| `/cards buy pack`           | Allows you to use /cards buy pack           |
| `/cards buy card`           | Allows you to use /cards buy card           |

### Admin Commands

| Commands                            | Description                                         |
| ----------------------------------- | --------------------------------------------------- |
| `/cards debug showcache all/active` | Allows you to use /cards debug showcache all/active |
| `/cards debug modules`              | Allows you to use /cards debug modules              |
| `/cards debug packs`                | Allows you to use /cards debug packs                |
| `/cards debug rarities`             | Allows you to use /cards debug rarities             |
| `/cards debug exists`               | Allows you to use /cards debug exists               |
| `/cards debug zip`                  | Zips all settings files into a file                 |

## Deck Commands:

| Commands         | Description                         |
| ---------------- | ----------------------------------- |
| `/deck <number>` | Allows you to use the /deck command |


# All Permissions

## Permissions for Commands:

| Permissions                    | Description                                         |
| ------------------------------ | --------------------------------------------------- |
| `cards.version`                | Allows you to use /cards version                    |
| `cards.reload`                 | Allows you to use /cards reload                     |
| `cards.resolve`                | Allows you to use /cards resolve                    |
| `cards.toggle`                 | Allows you to use /cards toggle                     |
| `cards.give.card`              | Allows you to use /cards give card                  |
| `cards.give.card.shiny`        | Allows you to use /cards give card shiny            |
| `cards.give.pack`              | Allows you to use /cards give pack                  |
| `cards.give.random.entity`     | Allows you to use /cards give random entity         |
| `cards.give.random.rarity`     | Allows you to use /cards give random rarity         |
| `cards.list`                   | Allows you to use /cards list                       |
| `cards.list.player`            | Allows you to use /cards list player                |
| `cards.list.pack`              | Allows you to use /cards list pack                  |
| `cards.giveaway.rarity`        | Allows you to use /cards giveaway rarity            |
| `cards.giveaway.entity`        | Allows you to use /cards giveaway entity            |
| `cards.worth`                  | Allows you to use /cards worth                      |
| `cards.sell`                   | Allows you to use /cards sell                       |
| `cards.buy`                    | Allows you to use /cards buy                        |
| `cards.buy.pack`               | Allows you to use /cards buy pack                   |
| `cards.buy.card`               | Allows you to use /cards buy card                   |
| `cards.admin.debug.*`          | Allows you to use all debug commands                |
| `cards.admin.debug.show_cache` | Allows you to use /cards debug showcache all/active |
| `cards.admin.debug.modules`    | Allows you to use /cards debug modules              |
| `cards.admin.debug.packs`      | Allows you to use /cards debug packs                |
| `cards.admin.debug.rarities`   | Allows you to use /cards debug rarities             |
| `cards.admin.debug.exists`     | Allows you to use /cards debug exists               |

## Permissions for Decks:

| Permissions          | Description                         |
| -------------------- | ----------------------------------- |
| `cards.use.deck`     | Allows you to use the /deck command |
| `cards.decks.number` | Allows you to use deck number       |


# Placeholders

## Internal Placeholders

* `%player%` - Player Name
* `%pack%` - Pack Id
* `%card%` - Card Id
* `%name%` - Display Name
* `%uuid%` - Player UUID
* `%rarity%` - Rarity Id
* `%buyamount%`
* `%sellamount%`
* `%prefix%`
* `%color%`
* `%buy_price%`
* `%sell_price%`
* `%shinyprefix%` or `%shiny_prefix%`
* `%amount%`
* `%cards_owned%`
* `%shiny_cards_owned%`
* `%cards_total%`

## PlaceholderAPI

All `{id}` are written as is. Without the brackets. For example: if our type id is "ranks" we would use: `%tc_type_ranks_display-name%`.

* `%tc_version%`
* `%tc_prefix%`
* `%tc_type_{id}_display-name%`
* `%tc_type_{id}_type%`
* `%tc_card_{rarityId.cardId.seriesId}_display-name%`
* `%tc_card_{rarityId.cardId.seriesId}_buy-price%`
* `%tc_card_{rarityId.cardId.seriesId}_sell-price%`
* `%tc_card_{rarityId.cardId.seriesId}_info%`
* `%tc_card_{rarityId.cardId.seriesId}_about%`
* `%tc_card_{rarityId.cardId.seriesId}_type%`
* `%tc_pack_{id}_display-name%`
* `%tc_pack_{id}_buy-price%`
* `%tc_pack_{id}_permission%`
* `%tc_series_{id}_display-name%`
* `%tc_series_{id}_mode%`
* `%tc_rarity_{id}_display-name%`
* `%tc_rarity_{id}_default-color%`
* `%tc_rarity_{id}_buy-price%`
* `%tc_rarity_{id}_sell-price%`


# 5.0.4 -> 5.7.2+

Remember to backup before starting any migration!

It is recommended that you backup your content and start from the beginning.. Starting from version 5.4 there are a lot of changes made. (You can still use your old cards.yml)

#### Migrating

If you still want to move everything over, follow these steps:

1. Backup your XensTradingCards folder.
2. Install TradingCards.
3. Restart your server.
4. Compare your cards.yml with the new cards.yml using vscode, and apply any changes you need.
5. Add your rarities to rarities.yml
6. Add your series to series.yml
7. Modify chances.yml with your own values
8. Compare your messages.yml with the new messages.yml, there a lot of new messages so keep that in mind.
9. That's it!
10. If you want to move to SQL use the guide from [5.6.x YAML -> SQL](/trading-cards/migration/5.6.x-yaml-greater-than-sql)


# 5.0.4 -> 5.4+

Remember to backup before starting any migration!

Version 5.4 brought many config changes to the plugin. **It is recommended to backup all your files before moving to this version.**

Once you have installed version 5.4+ you will that config.yml has been split into 3 different files with 2 new files: `general.yml`, `chances.yml`, `packs.yml` & `rarities.yml`, `series.yml`


# 5.5.x -> 5.6.x YAML

Remember to backup before starting any migration!

1. Move `custom-types.yml`. `rarities.yml`, `series.yml` & `packs.yml` to the data folder.
2. Restart your server.


# 5.6.x YAML -> SQL

Remember to backup before starting any migration!

1. Run `/cards migrate data`
2. Restart your server.


# Java API

We use jitpack for our repository.

{% tabs %}
{% tab title="Maven" %}
{% code title="pom.xml - repository" %}

```xml
<repository>
	<id>jitpack.io</id>
	<url>https://jitpack.io</url>
</repository>
```

{% endcode %}

{% code title="pom.xml - artifact" %}

```xml
<dependency>
	<groupId>com.github.sarhatabaot.TradingCards</groupId>
	<artifactId>tradingcards-api</artifactId>
	<version>5.7.2</version>
</dependency>
```

{% endcode %}
{% endtab %}

{% tab title="Gradle (Groovy)" %}

<pre class="language-groovy" data-title="build.gradle - repository"><code class="lang-groovy">repositories {
<strong>    maven { url 'https://jitpack.io' }
</strong>}
</code></pre>

{% code title="build.gradle - dependency" %}

```groovy
dependencies {
    implementation 'com.github.sarhatabaot.TradingCards:tradingcards-api:5.7.2'
}
```

{% endcode %}
{% endtab %}

{% tab title="Gradle (Kotlin)" %}
{% code title="build.gradle.kts - repository" %}

```kts
repositories {
    maven("https://jitpack.io")
}
```

{% endcode %}

{% code title="build.gradle.kts - dependency" %}

```kts
dependencies {
    compileOnly ("com.github.sarhatabaot.TradingCards:tradingcards-api:5.7.2")
}
```

{% endcode %}
{% endtab %}
{% endtabs %}


# Support

{% content-ref url="/pages/bHZ0932cK7e5vCKREulz" %}
[Discord](/trading-cards/support/discord)
{% endcontent-ref %}

{% content-ref url="/pages/qx6Kt1rnFmnl8ndSI3qy" %}
[Report a Bug](/trading-cards/support/report-a-bug)
{% endcontent-ref %}


# Discord

{% embed url="<https://discord.gg/4v9gsBCgg8>" %}


# Report a Bug

{% embed url="<https://github.com/sarhatabaot/TradingCards/issues>" %}