# 👋🏻Welcome This website helps you configuring my plugin * ​[Patreon](http://patreon.com/lonedev)​ * ​[YouTube](http://youtube.com/lonedev)​ * ​[SpigotMC](https://www.spigotmc.org/members/lonedev.88296/#resources)​ * ​[Website](https://www.matteodev.it/)​ * ​[Steam developer page](https://store.steampowered.com/developer/LoneDev/)​ * ​[Discord](https://discord.gg/4dfnpUK) # ⚙️First install ## Installing the plugin * Install **ScratchIt** * install [ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/) * install [LoneLibs](https://www.spigotmc.org/resources/lonelibs.75974/) * Start the server {% hint style="warning" %} If you have ViaVersion please: * update it to the [latest version](https://ci.viaversion.com/job/ViaVersion-DEV/). * if you have [ViaBackwards ](https://ci.viaversion.com/view/ViaBackwards/job/ViaBackwards-DEV/)and [ViaRewind ](https://ci.viaversion.com/view/ViaRewind/job/ViaRewind-DEV/)please update them also. {% endhint %} # 📄Online Config Editor ## How to use the online config editor? ### Step 1 Use the command `/scratchit config editconfig NAME` ### Step 2 Click on the link in chat ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZsVFl3KGJOdrZD2vKJ%2F-MZsVWO6Z1Gt9r3pjC5v%2Fimmagine.png?alt=media\&token=d7b028b6-cdb8-4773-86df-5561cf20ae6a) ### Step 3 Edit the item as you wish ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZsVFl3KGJOdrZD2vKJ%2F-MZsVbnidAYQvTohpVvT%2Fimmagine.png?alt=media\&token=df25de11-7ce0-45cb-81f8-29ac432edc63) ### Step 4 Click on **SAVE** ### **Step 5** Press **CTRL+V** in your game **chat** and press **ENTER** ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZsVFl3KGJOdrZD2vKJ%2F-MZsWKkJPcir6rPvieAh%2Fimmagine.png?alt=media\&token=15be8793-c65a-45e5-8751-9c5ac03cc2e1) ### **DONE!** # 📖Configurations # Permissions * `scratchit.card.show_in_list_gui.PERMISSION` * Allows you to show the card in the **/scratchit list** menu. Example: `scratchit.card.show_in_list_gui.default.homework` * `scratchit.card.use.PERMISSION` * Allows you to use the card. Example: `scratchit.card.use.default.homework` * `scratchit.user.list` * Use the /scratchit list command * `scratchit.admin.config` * Use the `/scrachit config` command * `scratchit.admin.config.reload` * Use the `/scratchit config reload` command * `scratchit.admin.config.AutoListAnimationFiles` * Use the `/scratchit config AutoListAnimationFiles` command * `scratchit.admin.config.create` * Use the `/scratchit config create` command * `scratchit.admin.get` * Use the /scratchit get command * `scratchit.admin.give` * Use the `/scratchit give` command # Card ## Introduction This plugin allows you to create custom cards which can be scratched / clicked to reveal images.\ The user will then get actions executed based on the chances you decide. # How to create a card ## Introduction Creating cards is very easy if you're familiar with images editing softwares, you have to know how to edit images or have a friend who can use [Photoshop](https://www.adobe.com/products/photoshop.html), [GIMP ](https://www.gimp.org/)or [Paint.net](https://www.getpaint.net/download.html). ## Creating your first card ### Step 1 To create a card you have to execute the command`/scratchit config create NAME`.\ In this example I will call my card: example, so I execute the command `/scratchit config create example` ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSuIWDlJJypsOl6UZ3%2Fimmagine.png?alt=media\&token=3844dfa9-0e78-4a22-81e0-7d9a185558b7) ### Step 2 A new folder with some files will then be created automatically by the plugin, you can find it here: ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSuRVaxSDXPNLI7E4A%2Fimmagine.png?alt=media\&token=60a4ade0-a958-4087-9eda-f9cce5151d8c) ### Step 4 Now let's edit the card!\ You will notice some files in the new folder, they allow you to customize the minigame based on your needs.\ Open the file example.yml to edit the configurations of the card. ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSy5jwMn2CNG2J8wkz%2Fimmagine.png?alt=media\&token=ff3b53a2-8a47-4538-be40-f37928deb1ad) ### Step 5 Customizing the main properties of the card: ```yaml scratch_card: id: example permissions: show_in_list_gui: new_card.example use: new_card.example name: "example" lore: - '&7EDIT ME!' - '&7(hold right click to scratch)' material: PAPER glow: true needed_to_win: 3 needed_scratch_percentage: 5 win_chance: 30 cursor: speed: 1.2 allow_left_click: false pressed_sound: name: DIG_SAND volume: 3 pitch: 0.9 interval_ticks: 5 ``` Most of the properties are self explanatory, there are some special properties tho: * `scratch_card` : this is the type of the card (more will be added in the future) * `glow`: allows you to me the item glow without enchant * `needed_to_win`: how many "right" symbols are needed to be discovered by the player to win * `needed_scratch_percentage`: it's the minimum scratched percentage to make the plugin show if they lose or win * `win_chance`: it's the chance of the player to find the `needed_to_win` symbols and win * `cursor`: * `speed`: speed of the cursor * `pressed_sound`: sound that the cursor will make while being pressed * `interval_ticks`: it's the interval between each sound play * `allow_left_click`: allows the player to press the cursor using also left click ### Step 6 Customizing the win/lose actions: this plugin allows you to create some actions on win or lose, not only giving items but also a lot of other stuff. For example: ```yaml # this is the list of win actions groups, you can create a any amount you want win_actions: win_effect_levelup_sound: # this is an example group always_execute: true # execute is always, ignoring chance execute_instantly: false # execute it after the win animation, not instantly play_sound_1: # play a sound, you can play as many sounds as you want name: "ENTITY_PLAYER_LEVELUP" volume: 1 pitch: 1 play_sound_another_sound: # play a sound, you can play as many sounds as you want name: "ENTITY_PLAYER_BURP" volume: 1 pitch: 1 first_group: # another actions group chance: 5 # chance of the action to be executed item_1: # this action will give an item name: SPONGE amount: 2 send_message: # send a message to the player when this action is executed message: '&b{player} &awon Sponge x2 using a &bClean It! &ascratchcard!' broadcast: WORLD #type of the broadcast (WORLD, SERVER, PLAYER) play_sound_1: name: ENTITY_ITEM_PICKUP volume: 1 pitch: 1 second_group: chance: 20 item_1: name: GLASS amount: 16 item_2: name: GLASS_PANE amount: 16 play_loop_sound_digging: #plays a sound in loop, 7 times (1 time each 3 ticks) name: "DIG_GRAVEL" volume: 1 pitch: 1 delay: 0 interval: 3 times: 7 send_message: message: '&aYou won Glass x16 and Glass Pane x16 using a &bClean It! &ascratchcard!' command_hello: #supported placeholders: {player} {x} {y} {z} and PlaceholderAPI command: "tell {player} hello" as_console: true delay: 5 ``` ### Step 7 Editing the graphics: you can edit the graphics as you wish! For example I will use [GIMP ](https://www.gimp.org/)to edit the files. **background.png** This is the shape of the card, the background. ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSz1l77blJ2uLDRsYM%2Fimmagine.png?alt=media\&token=4be42f96-4675-468e-af95-70580ba9c42d) #### overlay.png This is the part we are going to erase using the cursor, which will reveal the background. ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSz8Ma19HRIb_x_EFl%2Fimmagine.png?alt=media\&token=18214ffe-dee9-4e5d-a195-180824f7ebc7) #### right.png and wrong.png These are the icons shown behind the **overlay.png** file ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZT-4lLgl5cjPbSl7uZ%2Fimmagine.png?alt=media\&token=825ad69e-8283-476a-b083-1d683d738dcc) ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZT-BIbV1SGpzmAzx2j%2Fimmagine.png?alt=media\&token=35f27662-1e19-45ad-be60-17ae98e3317e) #### eraser.png This is a special file, it's basically the part of the cursor which can delete the **overlay.png**, this is useful if you want the cursor to erase only on the top left part and don't allow the user to remove the **overlay.png** using the whole cursor icon. #### cursor.png It's the cursor icon shown when the player moves the mouse. #### pressed\_cursor.ong It's the cursor icon shown when the player holds down right mouse button. #### background\_lose.png and background\_win.png These are the backgrounds shown when the user wins or loses. #### `lose_anim` and `win_anim` folders These are special folders and they contain the frames of the win/lose animations ### Step 8 Execute the reload command and then get the item ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT2sTVBai_y7FTBtcr%2Fimmagine.png?alt=media\&token=6e617698-ca2b-4a2a-9a57-76f367705900) ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT2zC3IhtlXXJUpZMh%2Fimmagine.png?alt=media\&token=455ced22-8239-4c79-ab26-4a7bdb808f70) ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT31hChFoP6iMoAL8J%2Fimmagine.png?alt=media\&token=c64d36a3-9af1-440c-beff-314cfa87be1a) ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT34WLyU7wIiLo-PEV%2Fimmagine.png?alt=media\&token=b8320524-ccc1-4ed3-aacc-10cc4c5d3f00) # Icons locations If you want to specify where to draw the icons of your card you have to use this special property: ```yaml icons: icon_1: x: 20 y: 20 icon_2: x: 20 y: 40 icon_3: x: 20 y: 60 icon_4: x: 20 y: 80 icon_5: x: 20 y: 100 ``` This example setting tells the plugin to draw the icons on these coords on the card.\ The card coords are shown in this screenshot: ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT3zhr4WI6aEl5Vafo%2Fimmagine.png?alt=media\&token=ffd6f646-b1b2-4a5f-8470-68baae197fc7) # Animations ## Introduction You can create win/lose animations for your cards as you can see in my example cards. The good thing is that you don't have to draw the background on each frame of the animation but you can separate animation from the background, as you can see in my examples. ## Special notes ### Repeating the same frame multiple times If you want to repeat the same frame you can avoid copying and pasting the same .png file, instead you can do that: ```yaml win_anim: frames: - 0|x10 - 1 - 2 - 3 - 4 - 5 ``` As you can see I used this special name `|x10`, this means that the frame named **0.png** will be executed `10 times`. ### Adjusting the animation position This plugin will center the animation automatically, but if you want to move it you can set this special attribute (**shift**): ```yaml win_anim: shift: x: 0 y: 15 frames: - anim_4|x6 - anim_5|x2 - anim_6|x2 - anim_7|x2 - anim_8|x2 - anim_9|x2 ``` ### Specify win/lose background duration If your card doesn't have any animation and you want to show the win/lose background for some seconds you can do that: ```yaml win_anim: static_background_duration: 30 lose_anim: static_background_duration: 30 ``` ### Automatically create list of frames in the .yml config You don't need to manually input all the file names, you can use this command to make the plugin write the files list for you: `/scratchit config AutoListAnimationFiles ` For example: # Cooldowns ## Per-card usage cooldown You can set an usage cooldown separated for each card using the `usage_cooldown_ticks` attribute. ### Example: ```yaml scratch_card: id: example permissions: show_in_list_gui: new_card.example use: new_card.example name: "example" usage_cooldown_ticks: 60 ``` ## Global cards cooldown You can edit this in **config.yml** ```yaml cards: usage_cooldown_ticks: 20 ``` # Cancel usage By default you can cancel card usage pressing Q, F or SHIFT.\ You can customize this in `config.yml` ```yaml cancel_scratching_methods: item_swap_F: true drop: true shift: true ``` # Loots {% hint style="warning" %} ### Warning Loots is not under the scratch\_card YML entry, but it's on its own level, separated from the card info. {% endhint %} ## Dropping cards from blocks, mobs and fishing Loots can be used to specify when to drop a card.\ You can decide to create different loot types: * blocks * mobs * fishing For example this is the loots category of a .yml file I created. ```yaml loots: blocks: nether_quartz_ore: type: NETHER_QUARTZ_ORE drop_only_first: true items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 homework: item: homework min_amount: 1 max_amount: 2 chance: 15 ruby_ore: type: itemsadder:ruby_ore items: clean_it: item: clean_it min_amount: 1 max_amount: 2 chance: 100 ``` This example has two loots in **blocks** category. The first one is a loot from a vanilla **block**. As you imagine it will drop a **defusing\_bomb** card or a **homework** card when the player breaks a **NETHER\_QUARTZ\_ORE**.\ These **drops** are decided by the plugin based on **chance** you set. The second one is an [ItemsAdder ](https://www.spigotmc.org/resources/%E2%9C%85must-have%E2%9C%85-itemsadder%E2%9C%A8textures-3d-models-huds-gui-emojis-ores-blocks-wings-tails-hats.73355/)custom block and is called **ruby\_ore** (you can call them as you prefer), this will drop a **clean\_it** card when you break a custom **block** of type **itemsadder:ruby\_ore** with a minimum **amount** of **1** and **maximum** amount of **2** with **100% chance**. {% hint style="info" %} Special property: **drop\_only\_first**\ This allows you to **stop** the **plugin** from **dropping each** of the **items** that succeed into extracting a **correct** chance to be **dropped**. \ **WARNING**: this would make your items **harder** to be **dropped**. {% endhint %} ## Ignore fortune enchant You can make a loot ignore fortune enchant by adding the **ignore\_fortune** property. ```yaml loots: blocks: nether_quartz_ore: type: NETHER_QUARTZ_ORE drop_only_first: true items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ignore_fortune: true # <----- here ``` ### Other types of loots As I said before there are other types of loots: mobs and fishing.\ These are some examples: #### Fishing ```yaml loots: fishing: loot_blue_parrotfish: items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 loot_green_sunfish: items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 loot_goldfish: items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` #### Mobs ```yaml loots: mobs: villager: type: VILLAGER nbt: profession: path: VillagerData.profession value: minecraft:farmer type: string items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ender_dragon: type: ENDER_DRAGON items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` {% hint style="info" %} ## Custom mobs loots {% endhint %} In order to let ItemsAdder drop an item based on when you kill a custom mob (created with ItemsAdder) you have to use the metadata attribute. Example: ```yaml loots: mobs: soul: type: HUSK metadata: ItemsAdderMob: name: "ItemsAdderMob" value: "creaturesplus:soul" type: "string" items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` As you can see I set **ItemsAdderMob** attribute and specified my custom mob **namespace:id** (in this example I used the **creaturesplus:soul** mob) {% hint style="info" %} ## Villager professions ### (and any other NBT attribute you want to match) {% endhint %} ```yaml loots: mobs: villager: type: VILLAGER nbt: profession: path: VillagerData.profession value: minecraft:farmer type: string items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` As you can see I set **profession** attribute and specified the **NBT attribute** path, which in this case is **VillagerData.profession**.\ Then I set value to **minecraft:farmer**, this tells ItemsAdder to match only **villagers** with attribute **VillagerData.profession** set to **minecraft:farmer**. {% hint style="warning" %} The type attribute of **nbt** and **metadata** are really **important**, don't **forget** them or matches could not occur. {% endhint %} {% hint style="info" %} ## Drop based on spawner entity ### (and any other NBT attribute you want to match) {% endhint %} ```yaml loots: blocks: change_me: enabled: true type: SPAWNER nbt: spawner_type: path: SpawnData.id value: minecraft:zombie type: string items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` # Cards example images {% hint style="info" %} You can get some images templates (**GIMP** project) directly from here: {% endhint %} # Compatibility with other plugins # WorldGuard If you want to disable scratch cards in some regions you can use the flag: ![](https://4216846192-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZTkKXs2_qf6h6kp_tr%2F-MZTkYvUoHD3Ho9D0tPI%2Fimmagine.png?alt=media\&token=179b01ef-4150-4d63-98b8-ff247cd437a4) # Minecraft versions compatibility ## If your server has ViaVersion {% hint style="info" %} ### This is important to optimize the plugin if your server accepts only some Minecraft versions. \ ScratchIt must create different optimized map images because all Minecraft versions have different colors support, you can disable some to speedup the plugin startup process. {% endhint %} If you're using ViaVersion to allow multiple clients to connect to your server you have to make sure to check these options in `config.yml` ```yaml graphics: viaversion: v1_8: true v1_12: true v1_16: true ``` * Set `v1_8` to **true** if your server accepts 1.8 to 1.11 clients * Set `v1_12` to **true** if your server accepts 1.12 to 1.15 clients * Set `v1_16` to **true** if your server accepts 1.16+ clients # 📒Support # 🐞Report a bug ## To report a bug please click here: {% embed url="" %} # 📕Ask for help If you still need help and you **did read all my wiki pages and plugin page** please open a support ticket here: {% embed url="" %} # ☕️Java API ## How to get the API You just have to use **maven** or **gradle**, you can get the **API** here {% embed url="" %} ## Description ItemsAdder includes an easy to use API for Java developers.\ To access it just include **dev.lone.ScratchIt.api** in your code. ## Important! You have to listen to the event **ScratchItCardsLoaded** in order to be sure that the cards are available to be accessed using the api. # Basic API ## Features * show a card to a player * stop showing a card to a player * get current shown card of a player {% embed url="" %} # CustomCardRenderer {% hint style="warning" %} ### This is not for newbie developers. ⚠️Please don't ask for support if you don't know how to use **BufferedImage** and **Color** classes. Keep in mind that you have to handle all the stuff manually and this is limited compared to Spigot API. The only advantage of using this is that it's not laggy like Spigot API as this is only packet based. Use this class only if you really need to. {% endhint %} ## What is a CustomCardRenderer? It's a class that can be used to create a custom renderer. You can use it to show custom images to the player.\ You will have to obtain pixel colors for example using a [BufferedImage](https://docs.oracle.com/javase/7/docs/api/java/awt/image/BufferedImage.html). This class is meant to be used to do simple stuff not advanced layering. To do advanced layering, transparency etc you have to handle that on your own. In the future I may extend this API to fill the gaps. ## Showcase of what you can achieve ![](https://media.giphy.com/media/URRU7u74EZEwyw1gDw/giphy.gif) ## Example code ```java try { BufferedImage img = ImageIO.read(new File(getDataFolder() + File.separator + "test.png")); CustomCardRenderer renderer = new CustomCardRenderer(player, false); renderer.start(); for (int x = 0; x < 128; x++) for (int y = 0; y < 128; y++) renderer.setPixel(x, y, new Color(img.getRGB(x, y))); Bukkit.getScheduler().runTaskLater(this, () -> { renderer.stop(); }, 20L * 5); } catch (IOException e) { //error } ``` # 👋🏻欢迎使用 这个页面将帮助你了解如何配置该插件 * ​[Patreon](http://patreon.com/lonedev)​ * ​[YouTube](http://youtube.com/lonedev)​ * ​[SpigotMC](https://www.spigotmc.org/members/lonedev.88296/#resources)​ * ​[Website](https://www.matteodev.it/)​ * ​[Steam developer page](https://store.steampowered.com/developer/LoneDev/)​ * ​[Discord](https://discord.gg/4dfnpUK) # ⚙️首次安装 ## 如何安装该插件 * 安装 **ScratchIt** * 安装 [ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/) * 安装 [LoneLibs](https://www.spigotmc.org/resources/lonelibs.75974/) * 启动服务器 {% hint style="warning" %} 如果你是跨版本服务器，请: * 更新到 [最新版本](https://ci.viaversion.com/job/ViaVersion-DEV/). * 如果你服务器还有 [ViaBackwards ](https://ci.viaversion.com/view/ViaBackwards/job/ViaBackwards-DEV/)和 [ViaRewind ](https://ci.viaversion.com/view/ViaRewind/job/ViaRewind-DEV/)请也更新至最新版本。 {% endhint %} # 📄在线编辑器 ## 我该如何使用在线编辑器？ ### 第一步 使用 `/scratchit config editconfig NAME` 命令 ### 第二步 打开聊天栏给予你的链接 ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZsVFl3KGJOdrZD2vKJ%2F-MZsVWO6Z1Gt9r3pjC5v%2Fimmagine.png?alt=media\&token=d7b028b6-cdb8-4773-86df-5561cf20ae6a) ### 第三步 编辑你想要的物品 ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZsVFl3KGJOdrZD2vKJ%2F-MZsVbnidAYQvTohpVvT%2Fimmagine.png?alt=media\&token=df25de11-7ce0-45cb-81f8-29ac432edc63) ### 第四步 点击 **SAVE** ### **第五步** 在你的游戏 **聊天栏** 内按下 **CTRL+V** ，然后按下 **ENTER** ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZsVFl3KGJOdrZD2vKJ%2F-MZsWHYGcU4FM7o1n9wl%2Fimmagine.png?alt=media\&token=17ce78d1-52d9-489f-966b-793178a6e4eb) ### **搞定** # 📖配置文件 # 权限 * `scratchit.card.show_in_list_gui.PERMISSION` * 允许在使用 **/scratchit list** 打开的页面查看某个卡片。 示例: `scratchit.card.show_in_list_gui.default.homework` * `scratchit.card.use.PERMISSION` * 允许使用某个卡片。 示例: `scratchit.card.use.default.homework` * `scratchit.user.list` * 允许使用 `/scratchit list` 命令 * `scratchit.admin.config` * 允许使用 `/scrachit config` 命令 * `scratchit.admin.config.reload` * 允许使用 `/scratchit config reload` 命令 * `scratchit.admin.config.AutoListAnimationFiles` * 允许使用 `/scratchit config AutoListAnimationFiles` 命令 * `scratchit.admin.config.create` * 允许使用 `/scratchit config create` 命令 * `scratchit.admin.get` * 允许使用 `/scratchit get` 命令 * `scratchit.admin.give` * 允许使用 `/scratchit give` 命令 # 卡片 ## Introduction This plugin allows you to create custom cards which can be scratched / clicked to reveal images.\ The user will then get actions executed based on the chances you decide. # 如何创建一个新卡片 ## Introduction Creating cards is very easy if you're familiar with images editing softwares, you have to know how to edit images or have a friend who can use [Photoshop](https://www.adobe.com/products/photoshop.html), [GIMP ](https://www.gimp.org/)or [Paint.net](https://www.getpaint.net/download.html). ## Creating your first card ### Step 1 To create a card you have to execute the command`/scratchit config create NAME`.\ In this example I will call my card: example, so I execute the command `/scratchit config create example` ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSuIWDlJJypsOl6UZ3%2Fimmagine.png?alt=media\&token=3844dfa9-0e78-4a22-81e0-7d9a185558b7) ### Step 2 A new folder with some files will then be created automatically by the plugin, you can find it here: ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSuRVaxSDXPNLI7E4A%2Fimmagine.png?alt=media\&token=60a4ade0-a958-4087-9eda-f9cce5151d8c) ### Step 4 Now let's edit the card!\ You will notice some files in the new folder, they allow you to customize the minigame based on your needs.\ Open the file example.yml to edit the configurations of the card. ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSy5jwMn2CNG2J8wkz%2Fimmagine.png?alt=media\&token=ff3b53a2-8a47-4538-be40-f37928deb1ad) ### Step 5 Customizing the main properties of the card: ```yaml scratch_card: id: example permissions: show_in_list_gui: new_card.example use: new_card.example name: "example" lore: - '&7EDIT ME!' - '&7(hold right click to scratch)' material: PAPER glow: true needed_to_win: 3 needed_scratch_percentage: 5 win_chance: 30 cursor: speed: 1.2 allow_left_click: false pressed_sound: name: DIG_SAND volume: 3 pitch: 0.9 interval_ticks: 5 ``` Most of the properties are self explanatory, there are some special properties tho: * `scratch_card` : this is the type of the card (more will be added in the future) * `glow`: allows you to me the item glow without enchant * `needed_to_win`: how many "right" symbols are needed to be discovered by the player to win * `needed_scratch_percentage`: it's the minimum scratched percentage to make the plugin show if they lose or win * `win_chance`: it's the chance of the player to find the `needed_to_win` symbols and win * `cursor`: * `speed`: speed of the cursor * `pressed_sound`: sound that the cursor will make while being pressed * `interval_ticks`: it's the interval between each sound play * `allow_left_click`: allows the player to press the cursor using also left click ### Step 6 Customizing the win/lose actions: this plugin allows you to create some actions on win or lose, not only giving items but also a lot of other stuff. For example: ```yaml # this is the list of win actions groups, you can create a any amount you want win_actions: win_effect_levelup_sound: # this is an example group always_execute: true # execute is always, ignoring chance execute_instantly: false # execute it after the win animation, not instantly play_sound_1: # play a sound, you can play as many sounds as you want name: "ENTITY_PLAYER_LEVELUP" volume: 1 pitch: 1 play_sound_another_sound: # play a sound, you can play as many sounds as you want name: "ENTITY_PLAYER_BURP" volume: 1 pitch: 1 first_group: # another actions group chance: 5 # chance of the action to be executed item_1: # this action will give an item name: SPONGE amount: 2 send_message: # send a message to the player when this action is executed message: '&b{player} &awon Sponge x2 using a &bClean It! &ascratchcard!' broadcast: WORLD #type of the broadcast (WORLD, SERVER, PLAYER) play_sound_1: name: ENTITY_ITEM_PICKUP volume: 1 pitch: 1 second_group: chance: 20 item_1: name: GLASS amount: 16 item_2: name: GLASS_PANE amount: 16 play_loop_sound_digging: #plays a sound in loop, 7 times (1 time each 3 ticks) name: "DIG_GRAVEL" volume: 1 pitch: 1 delay: 0 interval: 3 times: 7 send_message: message: '&aYou won Glass x16 and Glass Pane x16 using a &bClean It! &ascratchcard!' command_hello: #supported placeholders: {player} {x} {y} {z} and PlaceholderAPI command: "tell {player} hello" as_console: true delay: 5 ``` ### Step 7 Editing the graphics: you can edit the graphics as you wish! For example I will use [GIMP ](https://www.gimp.org/)to edit the files. **background.png** This is the shape of the card, the background. ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSz1l77blJ2uLDRsYM%2Fimmagine.png?alt=media\&token=4be42f96-4675-468e-af95-70580ba9c42d) #### overlay.png This is the part we are going to erase using the cursor, which will reveal the background. ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZSz8Ma19HRIb_x_EFl%2Fimmagine.png?alt=media\&token=18214ffe-dee9-4e5d-a195-180824f7ebc7) #### right.png and wrong.png These are the icons shown behind the **overlay.png** file ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZT-4lLgl5cjPbSl7uZ%2Fimmagine.png?alt=media\&token=825ad69e-8283-476a-b083-1d683d738dcc) ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZSsw-dml3Pcrwf5nAS%2F-MZT-BIbV1SGpzmAzx2j%2Fimmagine.png?alt=media\&token=35f27662-1e19-45ad-be60-17ae98e3317e) #### eraser.png This is a special file, it's basically the part of the cursor which can delete the **overlay.png**, this is useful if you want the cursor to erase only on the top left part and don't allow the user to remove the **overlay.png** using the whole cursor icon. #### cursor.png It's the cursor icon shown when the player moves the mouse. #### pressed\_cursor.ong It's the cursor icon shown when the player holds down right mouse button. #### background\_lose.png and background\_win.png These are the backgrounds shown when the user wins or loses. #### `lose_anim` and `win_anim` folders These are special folders and they contain the frames of the win/lose animations ### Step 8 Execute the reload command and then get the item ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT2sTVBai_y7FTBtcr%2Fimmagine.png?alt=media\&token=6e617698-ca2b-4a2a-9a57-76f367705900) ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT2zC3IhtlXXJUpZMh%2Fimmagine.png?alt=media\&token=455ced22-8239-4c79-ab26-4a7bdb808f70) ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT31hChFoP6iMoAL8J%2Fimmagine.png?alt=media\&token=c64d36a3-9af1-440c-beff-314cfa87be1a) ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT34WLyU7wIiLo-PEV%2Fimmagine.png?alt=media\&token=b8320524-ccc1-4ed3-aacc-10cc4c5d3f00) # 图标位置 If you want to specify where to draw the icons of your card you have to use this special property: ```yaml icons: icon_1: x: 20 y: 20 icon_2: x: 20 y: 40 icon_3: x: 20 y: 60 icon_4: x: 20 y: 80 icon_5: x: 20 y: 100 ``` This example setting tells the plugin to draw the icons on these coords on the card.\ The card coords are shown in this screenshot: ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZT2hi7tF5nIKvZ6JZM%2F-MZT3zhr4WI6aEl5Vafo%2Fimmagine.png?alt=media\&token=ffd6f646-b1b2-4a5f-8470-68baae197fc7) # 动作 ## Introduction You can create win/lose animations for your cards as you can see in my example cards. The good thing is that you don't have to draw the background on each frame of the animation but you can separate animation from the background, as you can see in my examples. ## Special notes ### Repeating the same frame multiple times If you want to repeat the same frame you can avoid copying and pasting the same .png file, instead you can do that: ```yaml win_anim: frames: - 0|x10 - 1 - 2 - 3 - 4 - 5 ``` As you can see I used this special name `|x10`, this means that the frame named **0.png** will be executed `10 times`. ### Adjusting the animation position This plugin will center the animation automatically, but if you want to move it you can set this special attribute (**shift**): ```yaml win_anim: shift: x: 0 y: 15 frames: - anim_4|x6 - anim_5|x2 - anim_6|x2 - anim_7|x2 - anim_8|x2 - anim_9|x2 ``` ### Specify win/lose background duration If your card doesn't have any animation and you want to show the win/lose background for some seconds you can do that: ```yaml win_anim: static_background_duration: 30 lose_anim: static_background_duration: 30 ``` ### Automatically create list of frames in the .yml config You don't need to manually input all the file names, you can use this command to make the plugin write the files list for you: `/scratchit config AutoListAnimationFiles ` For example: # 冷却 ## Per-card usage cooldown You can set an usage cooldown separated for each card using the `usage_cooldown_ticks` attribute. ### Example: ```yaml scratch_card: id: example permissions: show_in_list_gui: new_card.example use: new_card.example name: "example" usage_cooldown_ticks: 60 ``` ## Global cards cooldown You can edit this in **config.yml** ```yaml cards: usage_cooldown_ticks: 20 ``` # 取消使用 By default you can cancel card usage pressing Q, F or SHIFT.\ You can customize this in `config.yml` ```yaml cancel_scratching_methods: item_swap_F: true drop: true shift: true ``` # 战利品 {% hint style="warning" %} ### Warning Loots is not under the scratch\_card YML entry, but it's on its own level, separated from the card info. {% endhint %} ## Dropping cards from blocks, mobs and fishing Loots can be used to specify when to drop a card.\ You can decide to create different loot types: * blocks * mobs * fishing For example this is the loots category of a .yml file I created. ```yaml loots: blocks: nether_quartz_ore: type: NETHER_QUARTZ_ORE drop_only_first: true items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 homework: item: homework min_amount: 1 max_amount: 2 chance: 15 ruby_ore: type: itemsadder:ruby_ore items: clean_it: item: clean_it min_amount: 1 max_amount: 2 chance: 100 ``` This example has two loots in **blocks** category. The first one is a loot from a vanilla **block**. As you imagine it will drop a **defusing\_bomb** card or a **homework** card when the player breaks a **NETHER\_QUARTZ\_ORE**.\ These **drops** are decided by the plugin based on **chance** you set. The second one is an [ItemsAdder ](https://www.spigotmc.org/resources/%E2%9C%85must-have%E2%9C%85-itemsadder%E2%9C%A8textures-3d-models-huds-gui-emojis-ores-blocks-wings-tails-hats.73355/)custom block and is called **ruby\_ore** (you can call them as you prefer), this will drop a **clean\_it** card when you break a custom **block** of type **itemsadder:ruby\_ore** with a minimum **amount** of **1** and **maximum** amount of **2** with **100% chance**. {% hint style="info" %} Special property: **drop\_only\_first**\ This allows you to **stop** the **plugin** from **dropping each** of the **items** that succeed into extracting a **correct** chance to be **dropped**. \ **WARNING**: this would make your items **harder** to be **dropped**. {% endhint %} ## Ignore fortune enchant You can make a loot ignore fortune enchant by adding the **ignore\_fortune** property. ```yaml loots: blocks: nether_quartz_ore: type: NETHER_QUARTZ_ORE drop_only_first: true items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ignore_fortune: true # <----- here ``` ### Other types of loots As I said before there are other types of loots: mobs and fishing.\ These are some examples: #### Fishing ```yaml loots: fishing: loot_blue_parrotfish: items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 loot_green_sunfish: items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 loot_goldfish: items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` #### Mobs ```yaml loots: mobs: villager: type: VILLAGER nbt: profession: path: VillagerData.profession value: minecraft:farmer type: string items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ender_dragon: type: ENDER_DRAGON items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` {% hint style="info" %} ## Custom mobs loots {% endhint %} In order to let ItemsAdder drop an item based on when you kill a custom mob (created with ItemsAdder) you have to use the metadata attribute. Example: ```yaml loots: mobs: soul: type: HUSK metadata: ItemsAdderMob: name: "ItemsAdderMob" value: "creaturesplus:soul" type: "string" items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` As you can see I set **ItemsAdderMob** attribute and specified my custom mob **namespace:id** (in this example I used the **creaturesplus:soul** mob) {% hint style="info" %} ## Villager professions ### (and any other NBT attribute you want to match) {% endhint %} ```yaml loots: mobs: villager: type: VILLAGER nbt: profession: path: VillagerData.profession value: minecraft:farmer type: string items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` As you can see I set **profession** attribute and specified the **NBT attribute** path, which in this case is **VillagerData.profession**.\ Then I set value to **minecraft:farmer**, this tells ItemsAdder to match only **villagers** with attribute **VillagerData.profession** set to **minecraft:farmer**. {% hint style="warning" %} The type attribute of **nbt** and **metadata** are really **important**, don't **forget** them or matches could not occur. {% endhint %} {% hint style="info" %} ## Drop based on spawner entity ### (and any other NBT attribute you want to match) {% endhint %} ```yaml loots: blocks: change_me: enabled: true type: SPAWNER nbt: spawner_type: path: SpawnData.id value: minecraft:zombie type: string items: defusing_bomb: item: defusing_bomb min_amount: 1 max_amount: 2 chance: 10 ``` # 卡片示例图片 {% hint style="info" %} You can get some images templates (**GIMP** project) directly from here: {% endhint %} # 兼容的插件 # WorldGuard 如果你想在某些WorldGuard区域禁用ScratchIt的卡片，请在该区域设置以下flag: ![](https://264119651-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZSstxJNDVwFzdZ_-Yg%2F-MZTkKXs2_qf6h6kp_tr%2F-MZTkYvUoHD3Ho9D0tPI%2Fimmagine.png?alt=media\&token=179b01ef-4150-4d63-98b8-ff247cd437a4) # 兼容的Minecraft版本 ## 如果你的服务器是跨版本服务器 {% hint style="info" %} ### 如果你的服务器是单版本服务器，那以下的优化设置十分重要： ScratchIt在使用时针对不同的Minecraft版本会创建不同的地图实例，因为不同版本的地图不同。你可以禁用某些版本的地图来优化插件。 {% endhint %} 如果你使用的是跨版本服务器，则必须检查 `config.yml` 中以下的选项是否打开。 ```yaml graphics: viaversion: v1_8: true v1_12: true v1_16: true ``` * 如果你的服务器支持1.8-1.11的客户端连入，则将 `v1_8` 设为 **true** * 如果你的服务器支持1.12-1.15的客户端连入，则将 `v1_12` 设为 **true** * 如果你的服务器支持1.16的客户端连入，则将 `v1_16` 设为 **true** # 📒获得支持 # 🐞反馈Bug ## 如你想反馈漏洞，请点击以下链接反馈: {% embed url="" %} # 📕获取帮助 如果你在 **完整看完Wiki和插件发布页后** 依然需要帮助，请在以下链接打开一个工单: {% embed url="" %} # ☕️Java API ## How to get the API You just have to use **maven** or **gradle**, you can get the **API** here {% embed url="" %} ## Description ItemsAdder includes an easy to use API for Java developers.\ To access it just include **dev.lone.ScratchIt.api** in your code. ## Important! You have to listen to the event **ScratchItCardsLoaded** in order to be sure that the cards are available to be accessed using the api. # Basic API ## Features * show a card to a player * stop showing a card to a player * get current shown card of a player {% embed url="" %} # 自定义卡片渲染器 {% hint style="warning" %} ### This is not for newbie developers. ⚠️Please don't ask for support if you don't know how to use **BufferedImage** and **Color** classes. Keep in mind that you have to handle all the stuff manually and this is limited compared to Spigot API. The only advantage of using this is that it's not laggy like Spigot API as this is only packet based. Use this class only if you really need to. {% endhint %} ## What is a CustomCardRenderer? It's a class that can be used to create a custom renderer. You can use it to show custom images to the player.\ You will have to obtain pixel colors for example using a [BufferedImage](https://docs.oracle.com/javase/7/docs/api/java/awt/image/BufferedImage.html). This class is meant to be used to do simple stuff not advanced layering. To do advanced layering, transparency etc you have to handle that on your own. In the future I may extend this API to fill the gaps. ## Showcase of what you can achieve ![](https://media.giphy.com/media/URRU7u74EZEwyw1gDw/giphy.gif) ## Example code ```java try { BufferedImage img = ImageIO.read(new File(getDataFolder() + File.separator + "test.png")); CustomCardRenderer renderer = new CustomCardRenderer(player, false); renderer.start(); for (int x = 0; x < 128; x++) for (int y = 0; y < 128; y++) renderer.setPixel(x, y, new Color(img.getRGB(x, y))); Bukkit.getScheduler().runTaskLater(this, () -> { renderer.stop(); }, 20L * 5); } catch (IOException e) { //error } ```