Evolution System

MCE supports 37 evolution types through a polymorphic command pattern. Each evolution type is a concrete class that inherits from EvolutionData and defines its own trigger conditions. This guide covers all built-in evolution types and how to configure them.

Every form carries a LIST of evolutions, and each one is asked whether its condition holds. The first that says yes wins, which is how a single species can branch.

How Evolution Works

Evolution is managed by the EvolutionManager, which checks for evolution conditions at key moments:

• After leveling up (in battle or via rare candy).
• After using an item on a monster.
• After a trade completes.
• At specific game events (friendship threshold reached, location entered, etc.).

When conditions are met, the EvolutionAnimation plays and the MonsterInstance transforms into the target species, keeping its nickname, IVs, EVs, friendship, and other personal data.

Configuring Evolution

On a MonsterEntry ScriptableObject, each per-form entry (DataByFormEntry) holds an Evolutions list of EvolutionData entries (serialized polymorphically via [SerializeReference]). Each entry specifies:

1. The evolution type (which concrete class to use).
2. The target species (TargetSpecies, a MonsterEntry reference).
3. The target form (TargetForm, for form-specific evolutions).
4. Type-specific parameters (level threshold, item to use, etc.).

Built-In Evolution Types

Level-Based

Type	Description	Parameters
EvolveByLevel	Evolves at a specific level	TargetLevel
EvolveByLevelAtSpecificTime	Evolves at a level during a time of day	TargetLevel, EvolvingTimes
EvolveByLevelWhenAttackIsHigherThanDefense	Evolves at a level when Attack > Defense	TargetLevel
EvolveByLevelWhenDefenseIsHigherThanAttack	Evolves at a level when Defense > Attack	TargetLevel
EvolveByLevelWhenAttackEqualsDefense	Evolves at a level when Attack = Defense	TargetLevel
EvolveByLevelWhenSpecificGender	Evolves at a level if specific gender	TargetLevel, Gender
EvolveByLevelWithSceneTag	Evolves at a level in a specific location	TargetLevel, CompatibleTags
EvolveByLevelWithSceneTagAtSpecificTime	Level + location + time	TargetLevel, CompatibleTags, EvolvingTimes
EvolveToRandomSpeciesByLevel	Evolves into the target or a second species (random) at a level	TargetLevel, OtherSpecies

Friendship-Based

Type	Description	Parameters
EvolveByFriendship	Evolves when friendship reaches threshold	TargetFriendship
EvolveByFriendshipAtSpecificTime	Friendship + time of day	TargetFriendship, EvolvingTimes
EvolveByFriendshipWithMoveOfType	Friendship + knows a move of a specific type	TargetFriendship, Type

Item-Based

Type	Description	Parameters
EvolveOnItemUse	Evolves when a specific item is used on it	ItemToUse
EvolveOnItemUseAtSpecificTime	Item + time of day	ItemToUse, EvolvingTimes
EvolveOnItemUseOnSpecificGender	Item + specific gender	ItemToUse, Gender
EvolveOnItemUseWithSceneTag	Item + specific location	ItemToUse, CompatibleTags
EvolveOnLevelUpHoldingItem	Any level up while holding an item	ItemToHold
EvolveOnLevelUpHoldingItemAtSpecificTime	Level up + held item + time	ItemToHold, EvolvingTimes

Trade-Based

Type	Description	Parameters
EvolveWhenTraded	Evolves upon being traded	(none)
EvolveWhenTradedHoldingItem	Evolves when traded while holding an item	ItemToHold
EvolveWhenTradedWithMonster	Evolves when traded for a specific species	OtherMonster

Move-Based

Type	Description	Parameters
EvolveOnLevelUpWhenAMoveHasBeenLearnt	Level up if knows a specific move	Move
EvolveOnLevelUpWhenAMoveHasBeenLearntWithSceneTag	Move + location	Move, CompatibleTags
EvolveToRandomFormOnLevelUpWhenAMoveHasBeenLearnt	Move known, personality-based form result	Move, OtherForm, PersonalityThreshold
EvolveByUsingMoveXTimes	Evolves after using a specific move X times	Move, TargetCounter

Condition-Based

Type	Description	Parameters
EvolveOnLevelUpWithOtherMonInParty	Level up with a specific species in the party	OtherSpecies, OtherForm
EvolveOnLevelUpWhenConditionHasLevel	Level up when monster conditions reach set levels	Conditions
EvolveByEvolutionCounter	Evolves when its evolution counter reaches a target	TargetCounter

Battle Condition-Based

Type	Description	Parameters
EvolveByCriticalHitCounter	Evolves after landing X critical hits in a single battle	TargetCounter
EvolveByDefeatingRivals	Evolves after defeating enough rivals (counter-based)	TargetCounter, Item
EvolveByRecoilDamageBasedOnGender	Evolves after taking recoil damage, gender-specific target	TargetDamage (+ per-gender species/form)

Special

Type	Description	Parameters
SplitEvolutionByLevel	Split evolution: the evolving monster also spawns a second monster into an empty party slot (requires a compatible ball)	TargetLevel, OtherSpecies, OtherForm, CompatibleBalls

Setting Up an Evolution Chain

Here is a complete example of a three-stage evolution chain:

Stage 1: Flameleon (Dex #152)

On the Flameleon MonsterEntry, add one evolution:

• Type: EvolveByLevel
• Target Species: Blazeking
• Target Level: 16

Stage 2: Blazeking (Dex #153)

On the Blazeking MonsterEntry, add two evolutions (branching):

• Evolution 1:
  • Type: EvolveByLevel
  • Target Species: Infernarch
  • Target Level: 36
• Evolution 2:
  • Type: EvolveOnItemUse
  • Target Species: Infernarch (Mega Form)
  • Item To Use: Fire Stone

Stage 3: Infernarch (Dex #154)

No evolutions (final stage). Leave the Evolutions array empty.

Form Changes vs Evolution

Not all transformations are evolutions. MCE distinguishes between:

Mechanism	Permanent?	Creates New Instance?	Example
Evolution	Yes	No (same instance, new species)	Flameleon evolving into Blazeking
Form Change	Depends	No (same instance, same species)	Seasonal form, battle-only form
Item-Based Form	Reversible	No	ChangeFormOnItemUse, ChangeBetweenMultipleFormsOnItemUse

Form changes use ChangeFormOnItemUse or ChangeBetweenMultipleFormsOnItemUse instead of evolution data. These toggle the active DataByFormEntry index without changing the species.

Creating Custom Evolution Types (Source and Studio Editions)

If you have the Source or Studio edition, you can create new evolution types:

1. Create a new class that inherits from TargetSpeciesAndFormEvolutionData:

[Serializable]
public class EvolveWhenLowHP : TargetSpeciesAndFormEvolutionData
{
    [Range(0f, 1f)]
    public float HPThreshold = 0.5f;

    public override bool CanEvolveAfterLevelUp(MonsterInstance monster,
                                                DayMoment currentTime,
                                                PlayerCharacter playerCharacter,
                                                out bool consumeHeldItem)
    {
        consumeHeldItem = false;
        uint maxHP = MonsterMathHelper.CalculateStat(monster, Stat.Hp, null);
        float hpRatio = (float)monster.CurrentHP / maxHP;
        return monster.AllowEvolution(this) && hpRatio <= HPThreshold;
    }

    public override bool CanEvolveAfterBattleThroughExtraData(MonsterInstance m,
        DayMoment t, out bool c) { c = false; return false; }
    public override bool CanEvolveWhenUsingItem(MonsterInstance m, DayMoment t,
        Item i, PlayerCharacter p, out bool c) { c = false; return false; }
    public override bool CanEvolveWhenTrading(MonsterInstance m, DayMoment t,
        MonsterInstance o, PlayerCharacter p, out bool c) { c = false; return false; }
}

2. Because the Evolutions list is [SerializeReference], your subclass appears automatically in the Inspector's polymorphic type picker — no registration step is needed.
3. Add it to the species' per-form Evolutions list and configure the parameters.

Serialization

Custom evolution types must be [Serializable] and use [SerializeField] for their parameters. MCE uses Unity's polymorphic serialization ([SerializeReference]) for the evolution array, so your custom types will serialize and deserialize correctly.

Triggering Evolution Manually

In some cases, you may want to trigger an evolution check programmatically (e.g., from a CommandGraph node or a custom script):

// Source and Studio editions only — manually trigger level-up evolution check.
// EvolutionManager is a ScriptableObject bound through Zenject
// (MCE > Dependency Injection > Evolution Manager installer) — inject it.
[Inject] private EvolutionManager evolutionManager;

monster.ExtraData.NeedsLevelUpEvolutionCheck = true;
StartCoroutine(evolutionManager.TriggerEvolutionsAfterLevelUp(
    new[] { monster }, playerCharacter, false));

The EvolutionManager will check all applicable evolution data entries on the monster's species and trigger the first one whose conditions are met.

Best Practices

1. Test evolution chains end-to-end. Walk through every possible evolution path.
2. Avoid circular evolution chains. A evolving into B evolving into A creates infinite loops.
3. Set appropriate level thresholds. Early monsters should evolve around level 16-20, later ones around 30-40.
4. Use branching evolutions sparingly. They add gameplay depth but can confuse players if there are too many branches.
5. Validate the database. Open the OpenMon Hub → Database tab → Validate Database to ensure all evolution target species exist in the database.