Feral Tank ‐ Documentation - jondevarthur/feraltrainer GitHub Wiki

Download - Installation - Setup File
Equipment Setup - Readme

Feral Tank introduces simple new properties to the behind-the-scenes definitions of Pokemon to allow storage of 'equipment'. To make life simple, it also lets you handle Held Items!

All items listed are pending the practicalities of implementation and are noted purely for reference.

• Trainer equipment support (this would change too much and increase the incompatibility of plugins dramatically, from my current perspective).
• Items.txt PBS effect and short description support (this would change too much and increase the incompatibility of plugins dramatically, from my current perspective).
• Default Essentials Item_Effect and Move integration (this affects a lot and would have big, echoing effects to other plugins - it's unlikely).

• Add the Plugin to your Essentials install in the traditional method, merging the relevant folders. The Plugin consists of three Folders, \Graphics, \Plugins and \PBS. \Graphics and \Plugins are required, \PBS is optional.
  • \PBS consists of one file:
    • Items_feraltankdemo.txt, which contains the definitions of the 'default' items as examples. This is a valid Pokemon Essentials v21.1 items file and will be compiled if present.
  • \Graphics contains the various UI elements necessary.
    • \Items\ features the optional item icons used for the 'default', example items.
    • \UI\pluginFeralTank\ features the default menu elements for the Equipment screen.
    • \Graphics\UI\pluginFeralCamera\ will install the folders necessary for unique menus. Please see the FeralCamera documentation for more.
  • \Plugins\ [FT07]Feral Tank\ features the plugin files. Of note while installing:
    • 00_readme is the readme file - it includes a local list of valid functions and flags. Content is similar to the Online Readme.
    • 01_setup is the setup file. It will work fine from a full, 'default' installation as all references to items etc are present in the installation file.
    • 02_main contains the majority of the potentially 'incompatible' code that overwrites how stats are calculated.
    • 03_menu is the code for the equipment menu; at the top of this file are also a handful of menu and event handlers that may be in conflict with other plugins.
• No code is necessary to run at the start of your game - all menus etc feature in-built redundancies should elements not be missing. It should work out of the box, but your own settings and items will be needed to make it your own.

Setting up your equipment system is easy. The majority of work will be in defining items, icons etc. Before beginning work on this, however, you should handle the setup file side of things. This is 01_setup in the \plugins[FT07]Feral Tank\ folder.

• EQUIP_SLOTS - an array of arrays that defines your valid equipment slots. The format is ["itemflag","menu icon filename",game switch id] - e.g. ["eqrighthand","icon_sword",69].
  • "itemflag" is any valid string that can be placed against e.g. Flags = itemflag in the Items.txt PBS file. You do not need to predefine these somewhere else, as long as a word here matches a word in the PBS file's flags, it'll be valid. The item flag for held items is "helditem".
  • "menu icon filename" is a valid image in \pluginFeralTank\. Variants can also be present in the Feral Camera folders. The menu_icon for Held Items is "icon_held" - this is hardcoded and not defined here.
  • Game Switch ID is the id of an in-game switch - if set to 0, it won't be used. When an actual Switch ID value is given, that slot will only be usable when that switch is turned on. Items can still be equipped to that slot behind the scenes, the player just can't add or remove anything themselves. No switch toggle is offered for Held Items.
    • Note that default spacing allows for 6 slots, including the Held Item if enabled. You can fit more with narrower slots, but Icon display will be affected. Current spacing is to accomodate the 48px item icons of default essentials - if your item icons are smaller, you may well fit more rows neatly!
• INCLUDE_HELDITEMS - if true, your final slot will be the Pokemon's Held Item.

• COLLAPSE_UNUSABLE - if true, locked / unusable slots will not be visible to the player. Items may still be placed in these by game code, even when not visible.
• CAMERA_USESUBFOLDER - an integer of value 0, 1 or 2.
  • If 2, will check \UI\pluginFeralCamera\FeralTank\ first and then \UI\pluginFeralCamera\ if no valid image can be found (as per the below, the theme background will show if neither find a valid background).
  • If 1, will check \UI\pluginFeralCamera\FeralTank.
  • If 0, will check \UI\pluginFeralCamera\
• SHOW_POKEMON - if true, shows the Pokemon's sprite beneath their name.
• DEXART_USECUSTOMPOKEMON - Format is [state, "folder"]. If using my plugin DexArt, you can use custom art instead of the Pokemon graphics. It will check this folder, and use the standard Pokemon Front Sprites if nothing is found. Only checked if SHOW_POKEMON is true.
• DEXART_USECUSTOMICONS - Format is [state, "folder"]. If using my plugin DexArt, you can use custom art instead of the Pokemon icons. It will check this folder, and use the standard Pokemon icons if nothing is found.
  • Do not switch on either DEXART setting if not using my DexArt plugin!
• EQUIPMENTSLOTS_X, EQUIPMENTSLOTS_ICON_X, EQUIPMENTSLOTS_MENUICON_WIDTH, EQUIPMENTSLOTS_Y, EQUIPMENTSLOTS_HEIGHT, EQUIPMENTSLOTS_TEXT_X, EQUIPMENTSLOTS_TEXT_Y, TEXT_COLOR, TEXT_SHADOW - adjusts the visual design of the equipment slots.
  • EQUIPMENTSLOTS_ICON_X sets where the equipped item's icon displays on the X axis; the Y value is set relative to the box itself.
  • EQUIPMENTSLOTS_MENUICON_WIDTH - the Category icon that renders will be rendered at EQUIPMENTSLOTS_X minus this value.
  • EQUIPMENTSLOTS_HEIGHT - this is the vertical spacing of the boxes.
  • TEXT_COLOR and _SHADOW are R,G,B colors.
• NAME_X, NAME_Y, NAME_TEXT_COLOR, NAME_TEXT_SHADOW - adjusts the appearance of the Pokemon's name section.
• STATS_X, STATS_Y, STATS_SPACING, STATS_COLUMN_SPACING, STATS_TEXT_COLOR, STATS_TEXT_SHADOW, STATS_ORDER - adjusts the visual appearance of the stat box.
  • STATS_SPACING is the vertical spacing between lines. STATS_COLUMN_SPACING is the horizontal spacing between columns.
  • ORDER is the order in which stats will be drawn, 2 per column in this order (i.e. 1,2,new line,3,4). Valid values are "hp", "speed", "attack", "defense", "spattack", "spdefense".
• DESCRIPTIONLINES - if set to 1, renders a single line of text at the bottom of the screen. 2 or higher, displays a fullsize message window of that many lines instead.
• DESCRIPTION_SHOWWINDOW - if true and DESCRIPTIONLINES is set to 2 or higher, the window skin of the message box will be shown. If false, it will be hidden.
• DESCRIPTION_EMPTYTEXT, DESCRIPTION_BANTEXT,DESCRIPTION_LOCKTEXT - Text to display when no valid item description is available (i.e. the item slot is empty) when hovering over Empty, per-Pokemon/Form banned and Locked slots respectively.

• BUTTONS - Allows you to change the mapping of the non confirm/cancel buttons in the format [Unequip, AutoEquip Toggle, Help, Unequip All]. Valid buttons are "SPECIAL", "ACTION", "AUX1", "AUX2", "JUMPUP", "JUMPDOWN". Use, Back and the Arrows are reserved for their usual functions.
• HELP_COMMONEVENT - An array of the format [state, Common Event Id]. If state is true, you will run the common event of the given id when pushing the "help" button. Use this to call a message with your help text (etc) - I am using this method to make it as easy as possible by using the standard essentials editor text markup rather than setting this in a text box.

• BAN_SLOTS - an array of arrays in where the sub-arrays are in the format [:SPECIES,form_id]. With these combinations, you can block certain Pokemon from using specific slots entirely (e.g. since Rotom does not have legs, it shouldn't have leg armor). It is an array of arrays in the same order as the EQUIP_SLOTS array. If form_id is -1, any form will be counted. For example, [ [ [:TYNAMO,-1],[:ROTOM,1]],[:KYUREM,1],[:MAGIKARP,-1],[:GYARADOS,-1] ] ] would mean Tynamo (any form) and Rotom (form 1) will not be able to use the first slot, and Kyurem (form 1), Magikarp (any form) and Gyarados (any form) cannot use the second slot.
• BAN_SLOTS_SHOWLOCKED - If true, will use the different slot graphics for banned slots. Set to false if you want to give a Pokemon a unique item to compensate, for example - otherwise your player won't ever know it's possible! Unlike locked slots when _COLLAPSE is false, these slots can still be interacted with - this is just aesthetic.
  • Uses the _banned variant of the selectbox graphics.

• HOLDITEM_ADDITIONALBANS - an array of item flags that are banned from being used as held items. It is recommended you put the item flags from your equip slots here. This will be overridden by the presence of a valid helditem_flag and should be used to eliminate anything not in the default ban list (HM/TM, Key Items) and/or that belongs only in other slots.
• ALLOW_PARTYMENU_HELDITEMS - if false, disables the Party Menu held items management option. If true, operates as normal. Adjustments have been made to the Party Menu item functions to accommodate; these updated handlers are in the 03_menu file. Using the Party Menu Give/Take item functions will automatically disable Auto-Equip (to avoid bugs); it is recommended you give your players a single point of contact.

• ENABLE_AUTOEQUIP - if true, every Pokemon will always be able to use Auto-Equip as long as they have a valid held item.
• TOGGLESWITCH_AUTOEQUIP - Auto-Equip can only be used when this switch is turned on. Set to 0 to not use, otherwise set to a Game Switch ID.
• RIBBON_AUTOEQUIP - As a final option, you can toggle Auto-Equip availability per Pokemon via ribbons. Set to RIBBON_AUTOEQUIP = nil if you don't want to use.

• UNIVERSALMOVES - if true, any move learnable from a piece of equipment can be learned by any Pokemon. If false, it must still be traditionally compatible (listed as a tutor move or egg move etc).
• FORGETMOVES - if true, any moves taught by equipment items will be forgotten when the item is unequipped.
• FORGETMESSAGE_SHOW - if true, show the message below.
• FORGETMESSAGE - An array of three parts of a message - displays in the format (part1)(pokemon name)(part2)(move name)(part3) without spaces.
  • For example, "Oh! Pikachu forgot how to use Thunderbolt..." would be ["Oh! "," forgot how to use ","..."]. You can leave a portion blank by just using "".
• LEARNONCE - if true, a Pokemon can only learn a move from a piece of equipment once. This is a per-individual-Pokemon block; that item will still teach the same move to other Pokemon once.
  • Note, move learning plays by the same rules as applying a TM/HM - you will only get a confirmation check if you have to overwrite a move. If you equip an item to a Pokemon with empty slots, it will learn the move and will not be able to again in the future if this is true.
  • If an item teaches multiple moves, a Pokemon can learn one (or multiple) and not all of them. If this happens, the next time the item is equipped, only moves previously learned will be skipped; any that have not been learned before from that item will have an opportunity to be learned.

The file 01_setup_equipment contains the lengthy checks necessary to make your equipment have an effect. This is handled via script to avoid rendering Items.txt potentially incompatible with other plugins, and in doing so enables more than simple additions. It breaks down as follows:

Simple stat boosts are defined in ftEquipmentBoosts. It goes in sections: HP, Attack, Defense, Special Attack, Special Defense and Speed, in that order.

• Each stat also has the 5 types of boost possible: "base" (base stats), "iv" (IVs), "ev" (EVs), "level" (bonuses based on level) and "flat" (a flat rate number added at the end on top of all other bonuses). It is under these headings that you should place your code. You only need to fill out the sections used; a blank section will just return +0.
• Note that the calculations are as follows, and the values used are that Pokemon's value + all boosts from items to that value.
  • HP: (base HP stat x 2) + IVs + (EVs/4) * (level/100) + level + 10 + flat rate
  • All others: (base HP stat x 2) + IVs + (EVs/4) * ((level/100) + 5 * nature bonus / 100) + flat rate
• Values may be negative - redundancies are added to return a minimum stat of 1.
• Values may also be calculations - ($player.party.length - 1 ) * 2 will add + 2 for every Pokemon in the party other than the wearer, for example.
• The suggested format is an array of items, in the format [:WOODENCROWN,:MYTHRILCROWN,:KINGSCROWN].include?(i)
  • i is the current equipment item being assessed *.include? means that it is checking if the item is listed in the [array] - if it is there, it adds the number. If it isn't, it doesn't!
    • Everything must be valid ruby language:

if [check] - the starting check, you can only add this once at the very beginning.
elsif [check] - 'else if', for if there's more than one thing to check; you can add as many of these as you want.
else - only if you want something to happen whenever none of the other checks, and should just be the word else with no other conditions; you can only add this once as the final check.
end - must be present to say 'stop checking please'!

• The value used for the calculation is boost - so your increase should be boost += 10 or boost -= 25, for example.

You can override natures also - only for the purposes of calculating stats! This does not change the Pokemon's actual definition in any other way, and moves or items that require specific natures will not be affected.

• This is just a simple list of items and then, per item, what nature to use instead.

In a similar setup to nature, sets an array of moves based on the item. Moves must be an [array], even if there is only one move inside. Multiple moves are allowed.

Item descriptions are often far too long for the small amount of space at the bottom of the screen available for text. As a result, you can override that text here. Be aware that you have 44 characters' worth of space before it cuts off.

• This is a simple list of if this, description = that. You can also use elsif [:WOODENBOOTS,:MYTHRILBOOTS,:KINGSBOOTS].include?(item) etc for multiple items with the same description.
• Please note this description is simple text and does not support markup, special characters like \n or \v[1], icons or images.
  • If you are using the message window version of the description instead of the single line version, markup should be supported but is currently untested. For obvious reasons, interruptive markup (wait for x, close window, sound effects etc) should not be used.