Feral Tamer ‐ Documentation - jondevarthur/feraltrainer GitHub Wiki

Installation - Conversion / Research Menu - Evolution Menu
Conversion / Research Troubleshooting - Evolution Troubleshooting
Demonstration Video (Youtube)

Feral Tamer adds two key mechanics - Conversion / Research (an alternative to catching) and Menu-Based Evolution (for handling larger and more branching evolution methods). These are loose adaptations of how these function in the Digimon Story games. This page goes through installation, settings and usage methods.

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

• Icons in Menu List (so you can, for example, use a Pokeball Icon to show the data is ready to convert, instead of the default asterisk (*Raichu) )

• 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 two files:
    1. an example edited Pokemon.txt PBS to show how to implement branching evolutions and demo them in a default Essentials project.
    2. ribbons_feralsuite.txt, which features a single new ribbon as a default handler for Ninjask (as you can go back and forth freely under ideal circumstances and generate infinite Shedinjas, the ribbon method is used by default to designate Pokemon who have previously Shed their Shell).
  • \Graphics contains the various UI elements necessary to handle both methods.
    1. \Icons\ features visual icons used in text, primarily in the Evolution method as the default shorthands for evolution method detail rendering.
    2. \UI\pluginFeralTamer\ features the various visual elements used by both the Conversion and Evolution menus.
    3. \Graphics\UI\pluginFeralCamera\ will install the folders necessary for unique per-menu background graphics. Please see the FeralCamera documentation for more.
  • \Plugins\ [FT06]Feral Tamer\ features the plugin files. Of note while installing:
    1. 01_Setup contains the setup values for both research and evolution. Full Documentation for this file is available.
       • The bottom of this file also contains four additional pieces: the two Party Menu handlers for Evolution and Devolution options, the Pause Menu Conversion Menu handler and a simple 'rewrite' / nullification of pbEvolutionCheck to prevent traditional evolution from occurring after battle etc. Remove any of these elements to not use the associated function.
    2. 02_EvolutionHandler contains a long method that takes each required evolution handler and adds both a simple unified check and a description of the evolution method that can be read by the menu. This is in one long command that has two passes - pass 0 (can this Pokemon evolve?) and pass 1 (the description of the evolution method involved). As a result, once you understand what you're looking at, it's very easy to add new Evolution methods as long as they use the data made available to this method.
    3. 06_optional_convert_battlecode is the function that adds conversion/research checks to battle, which requires rewriting the code for those sections of battle. It has been streamlined as much as possible, but obviously any other code that modifies these sections of combat will be in conflict here. As a result, this file is optional - it contains clearly marked what lines are changed, and where to merge them in compatible code from other plugins. Conversely, if you do not want to use Conversion/Research at all, remove this file to prevent the combat research triggers from firing.
    4. 07_supplmentarycode - this is actually a simplified port of the contents of Feral Terminal to pull out what's necessary to make this work; this file can actually be discarded if you are using Feral Terminal, though any code in here should match what's in FTerminal.
• Once installed, add the following script call to the intro of your game - this initialises the necessary methods and sets them to their defaults. If adding to an existing save, make sure this autoruns on the map you're loading before accessing any menus etc, as uninitialized constants can break things. Yes, if you receive a popup error that says $PokemonGlobal.convertarray is nil, it's because you haven't done this!
  • script: ftInitTamer
  • If using Feral Terminal also, this will also be done in the standard ftGameStart call required for that plugin, you don't have to do both. This specific step is only required if using Feral Tamer as a standalone plugin.

This section will primarily cover the features and settings related to the Conversion/Research function.

Setup is done primarily via the 01_setup file within the plugin folder. Essential settings are described within that file. Important settings are for when to add research data, how to handle Pokeballs, Form handling, Held Item rates and how to handle the Pokemon's level on generation. A full breakdown of the setup file is available here: Setup File Documentation

Use in-game is largely automatic. If you do not see the conversion menu or the in-battle notification, please revisit the installation instructions above and check the troubleshooting section below. Please note the conversion menu, by default, will only show if at least one Pokemon is available to be converted.
Research is obtained at the start of Battle, matching the Digimon Story games. It is not lost when fleeing etc; options are not provided to modify this.

FORMS - forms are handled in two ways:

• Random: recorded form is ignored and the form is assigned manually when the Pokemon is converted from data. The list of possible forms is set in the setup file (i.e. no accidentally giving the player Eternal Flower Floette!).
• Set: each form encountered is recorded individually and appears as a discrete entity in the list.
  

SHINIES - if you encounter a Shiny, your conversion data stays shiny until you convert that Pokemon. I.e. if you encounter a Shiny Pikachu at 20% rate, when you reach 100% your data will still be shiny. After converting that 100% Pikachu, the record is wiped from your data and Pikachus converted will not be shiny again until you encounter another.

• If you do not see the notification in-battle, you likely have a conflict with another plugin that modifies the necessary sections of the battle code. Please see the contents of the file 06_optional_convert_battlecode for more.
• If you do not see the conversion menu option, you either have nothing to convert (working as intended) or your Pause Menu has been heavily modified to use different menu handlers. Please see the documentation for your menu plugin(s) in that instance.
• If you receive a crash that specifies $PokemonGlobal.convertarray.length (or similar) is nil, you have not initialised the plugin. Please run either ftInitTamer (or, if using Feral Terminal, ftGameStart).

ftInitTamer - initialises the Conversion data. Run once at the start of the game (or run the command from Feral Terminal if using that plugin also). Do not run after the player has begun research, as this will wipe all data.
ftFeralTamerConvertMenu_Call - used as part of calling the Conversion Menu. See the Menu Handler in 01_Setup for the safe way to do this.
ftTamerConvertManualAdd(:mon,rate,form,shiny?) - adds a specific combination of Pokemon and Form to the player's data; e.g. (:KIRLIA,200,0,true) will add a fully researched shiny Kirlia to the player's data, (:SHELLOS,80,1,false) will add a non-shiny, 80% researched East Sea Shellos. This is additive, so if the player already has 20 research for East Sea Shellos, (:SHELLOS,80,1,false) will increase it to 100.
ftTamerConvertManualClear(:mon,form) - removes a specific combination of Pokemon and Form from the player's research.
ftTamerDebugClearConvertArray - completely wipes the player's research. Don't use this unless absolutely necessary, it's meant for debug purposes only!
ftTamerDebugPrintConvertArray - prints the player's data into a message box; use only for debug purposes.
ftDebugCheckPokemonLevels - also for debugging; used to quickly check the expected levels after conversion.
ftDebugTamerRateMax - one last debug feature, but only if you encounter a bug I haven't managed to iron out. In the rare event a Pokemon's conversion level somehow ends up greater than 200%, this will check the array and pull them back down to earth.

Setup is largely automatic, using the existing Essentials evolution methods and the default Pokemon.txt PBS file(s). Additional, more elaborate methods than Essentials is default capable of are handled via the 01_setup file within the plugin folder. Additional settings are described within that file. Devolution methods, Trade Method Replacements, Form Changes and Fusions are covered via the setup file. A full breakdown of the setup file is available here: Setup File Documentation

This plugin has it's own evolution handler that uses the default Essentials handlers as a basis. This is one long call present in 01a_evolutionhandler.rb - if you have any custom Evolution methods, you will need to modify this file to include handling for it. Elements of the standard Evolution handler like :level_up_proc do not need to be used. The handler entries look like the following:

elsif method == "FlareonEvo"  		#This is a custom evolution handler called :FlareonEvo
	if pass == 1  				#designates 1 = return how to evolve, 0 = can they evolve right now
		item = GameData::Item.try_get(data).name  
		return (_INTL("Loves heat like <icon=evoItem>{1}s.",item))  	#a simple line of text, formatted appropriately using _INTL()
	elsif $bag.has?(data)  
		outcome = true  		#i.e. can evolve = true; when pass == 0, this code returns the value of outcome
	elsif $game_map.metadata&.has_flag?("IntenseHeat")  
		outcome = true  
	elsif (pkmn.happiness >= (Settings::APPLY_HAPPINESS_SOFT_CAP ? 160 : 220)) && $game_screen.weather_type == :Sun   
		outcome = true 		 #complicated checks are possible; just so long as you successfully can arrive at outcome = true/false
	end  
elsif method == "Shiny" 		#This is a custom evolution handler called :Shiny
	if pass == 1
		return (_INTL("<icon=evoShiny> ",data))
	elsif !pkmn.shiny?
		outcome = false 	#negatives can also be present to deny evolution for some reason
	else
		outcome = true
	end

Additional handler entries require three elements (A, B1 and B2):

• A: A standard evolution handler, so that Pokemon.txt will accept the evolution as valid.
• B: An elsif entry consisting of elsif method == "Method_name". Method name is rendered as a string but is simply the text version of :id => :Method_Name in the default Evolution handlers.
  • B1: A line for "pass == 1" - this is what will be returned when the Evolution screen is checking for a description of the method to display (i.e. "Evolves at level 15". This text should be compatible with most PEssentials text markup. Make sure the line starts with return, and ideally text should be wrapped in _INTL("text") for maximum compatability. This script receives five pieces of information when being called - the 'pass' (1 = description, 0 = actually checking if the evolution is possible), the Pokemon entity being checked, the 'destination' evolution, the method being called, the 'data' portion of the Pokemon.txt PBS (i.e. in this handler's case, the format VAPOREON,Item,WATERSTONE translates to evomon,method,data). All five bits of information are usable in your text description and code as pkmn, method, data, evomon, pass.
  • B2: Nested elsif statement(s) for when pass is 0 that constitute the actual checking as to whether the evolution can be performed at this time. For example, elsif pkmn.level >= data for the standard Level method will compare the chosen Pokemon's level to the level noted in the PBS. If it is higher than or equal to that level, it will return that the evolution is possible. Please look at how other methods work in the call to get an idea of how to add one or more conditions; the default set are quite expansive and cover most expected scenarios. All default Essentials evolution methods have been accounted for - including weirder ones like Ninjask, Silcoon/Cascoon, Region, BattleDealCriticalHit, Event and EventAfterDamageTaken.
    Please note that Pokemon 'consuming' methods are handled in the manner of Kyurem - so if your evolution requires a Remoraid to evolve Mantyke and consumes Remoraid to do so (as an example), that would be defined in the 01_Setup file as a fusion. Method :HasInParty merely checks if the species is present and does not actually touch that Pokemon.
    Please see the Setup File documentation for detailed descriptions of how to handle Fusions, establish Form Changing, set up Direct Form Evolutions (e.g. Pikachu => Alolan Raichu) and designate how to handle Trade Evolution methods.

Use in-game is largely automatic. When selecting the Pokemon on the Party screen, if at least one valid evolution or devolution method is present the appropriate option should appear. These handlers are at the bottom of 01_setup.rb and can be modified at your leisure. Additionally, 01_setup.rb contains a script that overwrites pbEvolutionCheck (the method that performs checks for valid evolutions previously) so that only the menu should handle most evolutions. Stones etc can be converted to normal items; that method has not been touched.

• If your evolution does not appear, either it has not been included in the handler in 01a_evolutionhandler correctly or a similar method has been set up wrong (e.g. mistyped Fusion details).
• If multiple methods are included the devolution style options, the first option will be the description when devolution is not possible. Only the first valid success will be checked and the description shown will reflect that successful method.
• You cannot double fuse - a warning will appear if you try. Fusion in Pokemon Essentials simply takes the second Pokemon and stores it as a line of text within the details of the First Pokemon. In order to facilitate multiple methods forming the same destination correctly (e.g. any combination of Regis forming Regigigas), the second Pokemon will have it's fusion details set to the name of the First Pokemon before fusion begins - i.e. the result will be Regirock.fusion(Regice.fusion(Regirock). That way, when splitting, only the correct pre-evolution will be available. As a result, you can't stack fusions as just the second option either. Regirock + Regice => Regigigas can devolve into Regirock and split off Regice. If you then do Regigigas + Giratina => Arceus, Arceus will be able to split into Regigigas and Giratina but Regigigas will no longer be able to split into Regirock and Regice. This is not a bug, this an unchangeable (without significant default PEssentials Code Modification) limitation and Fusions should be built with this in mind.
• You must designate Pokemon whose forms will be maintained when evolving through non-form related methods, otherwise Forms will reset to 0 on evolution as a fallback to prevent issues.
• Because you can theoretically evolve across gender (0 = male, 1 = female, 2 = genderless in PEssential's default schema), a method has been added to adjust gender to prevent impossible circumstances. This is unavoidable and there is no easy place to store 'long term' gender information when moving like this; for example, you can have a transmasc Gallade if your female Gardevoir evolves into a genderless Deoxys then devolves back into Gardevoir. It's gender will then be selected at the same rates as normal as if it was a new catch - this is interesting flavour, not a bug. If you evolve male Burmy into Wormadam without using e.g. :LevelFemale, your Wormadam will transition to female.
• As of version 1.3, handling has been added to allow inline icon display in Pokemon names, to better quickly indicate e.g. an Evolution is valid. Due to limitations with how Pokemon Essentials v21.1 handles "advanced" text (i.e. inline icons) the following behaviour will be encountered when a Pokemon's name is too wide. This is per-name, not per box.
  • If no 'advanced' characters (icons etc) are present, it will 'shrink' to fit the box.
  • If 'advanced' characters are present, it will trail off with a ... - e.g. - Frost Rot... The expected maximum length is around ~12 characters, excluding the icon. By default, this will mainly affect Forms.