Package com.pixelmonmod.pixelmon.battles.controller.random

Interface BattleRandomness

All Known Implementing Classes:
EvaluationBattleRandomness, StandardBattleRandomness
public interface BattleRandomness
Central randomness gateway for battle mechanics.

Battle mechanics should prefer the semantic methods on this interface over direct access to the underlying BattleRandomSource. This allows different battle contexts, such as normal battles, tests, simulations, and AI evaluation, to resolve random events differently without scattering special-case logic throughout individual mechanics.

For example, a normal battle may roll a 30% secondary effect normally, while an AI evaluation context may intentionally treat that same random upside as failing. The battle mechanic should only describe the kind of random event being resolved, such as rollSecondaryEffect(double) or rollAbilityEffect(double).

Chance values used by this interface are probabilities in the range 0.0 to 1.0, unless a method explicitly documents otherwise.

  • Method Details

    • raw

      BattleRandomSource raw()
      Gets the raw battle randomness source.

      This should almost never be used directly by internal battle mechanics. Prefer adding or using a semantic method on this interface instead.

      Direct raw access is appropriate for:

      • Implementing methods inside a BattleRandomness implementation.
      • External/non-battle-mechanic randomness where AI evaluation is irrelevant.
      • Old AI implementations (such as Advanced/Tactical AIs)
      • Temporary migration code where no semantic method exists yet.

      If a random result can affect battle state, turn order, damage, status, targeting, move success, or any decision an AI may need to evaluate, add a semantic method instead of using this directly.

      Returns:
      The raw battle random source.

    • rollAccuracy

      boolean rollAccuracy(double accuracy)
      Rolls whether a move passes its accuracy check.
      Parameters:
      accuracy - The move accuracy as a probability from 0.0 to 1.0.
      Returns:
      Whether the move hits.

    • rollOHKOAccuracy

      boolean rollOHKOAccuracy(double accuracy)
      Rolls whether an OHKO move passes its special accuracy check.

      OHKO moves are separated from normal accuracy because they have unusually high impact and may need to be treated more conservatively by AI evaluation.

      Parameters:
      accuracy - The OHKO accuracy as a probability from 0.0 to 1.0.
      Returns:
      Whether the OHKO move hits.

    • rollSecondaryEffect

      boolean rollSecondaryEffect(double chance)
      Rolls whether a move's secondary effect occurs.

      This should be used for additional effects caused by a move, such as secondary status, stat drops, or similar effects that are not the primary purpose of the move.

      Parameters:
      chance - The secondary effect chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the secondary effect occurs.

    • rollAbilityEffect

      boolean rollAbilityEffect(double chance)
      Rolls whether an ability-based random effect occurs.
      Parameters:
      chance - The ability effect chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the ability effect occurs.

    • rollCrit

      boolean rollCrit(double chance)
      Rolls whether an attack is a critical hit.
      Parameters:
      chance - The critical hit chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the attack crits.

    • rollConsecutiveMoveSuccess

      boolean rollConsecutiveMoveSuccess(double chance)
      Rolls whether a consecutively-used move succeeds.

      This is intended for Protect-like effects, Ally Switch repeat failure, and similar mechanics where repeated use lowers the success chance.

      Parameters:
      chance - The success chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the consecutive-use move succeeds.

    • rollStatusEffect

      boolean rollStatusEffect(double chance)
      Rolls whether a status-inflicting effect occurs.

      This is intended for random status application when the status effect itself is the thing being rolled.

      Parameters:
      chance - The status effect chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the status effect occurs.

    • rollStatusPrevention

      boolean rollStatusPrevention(double chance)
      Rolls whether a status prevents the affected Pokémon from acting.

      Examples include full paralysis, immobilization from infatuation, drowsy action failure, and similar status-based turn denial.

      Parameters:
      chance - The prevention chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the status prevents action this turn.

    • rollHeldItemEffect

      boolean rollHeldItemEffect(double chance)
      Rolls whether a held item random effect occurs.
      Parameters:
      chance - The held item effect chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the held item effect occurs.

    • chooseMultiHitCount

      int chooseMultiHitCount(int minHits, int maxHits)
      Chooses the number of hits for a multi-hit move.

      Implementations should preserve any special distributions for common multi-hit moves, such as the standard weighted 2-5 hit distribution, rather than assuming uniform selection.

      Parameters:
      minHits - The minimum possible number of hits.
      maxHits - The maximum possible number of hits.
      Returns:
      The selected number of hits.

    • rollUserWinsSpeedTie

      boolean rollUserWinsSpeedTie(PixelmonWrapper user, PixelmonWrapper target)
      Rolls whether the user wins a speed tie against the target.
      Parameters:
      user - The Pokémon whose move order is being checked.
      target - The opposing Pokémon in the speed tie.
      Returns:
      Whether user wins the speed tie.

    • rollStatusRecovery

      boolean rollStatusRecovery(double chance)
      Rolls whether a status randomly recovers or ends.

      Examples include random thawing from freeze or similar status recovery mechanics.

      Parameters:
      chance - The recovery chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the status recovers.

    • rollMovePowerBoost

      boolean rollMovePowerBoost(double chance)
      Rolls whether a move receives a random power boost.

      This is intended for moves where the primary damage profile changes due to a random effect, rather than for secondary effects.

      Parameters:
      chance - The power boost chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the move receives the power boost.

    • chooseBefuddleStatus

      StatusType chooseBefuddleStatus(PixelmonWrapper user, PixelmonWrapper target)
      Chooses the status applied by Befuddle.
      Parameters:
      user - The Pokémon using Befuddle.
      target - The Pokémon receiving the status.
      Returns:
      The selected status type.

    • chooseDireClawStatus

      StatusType chooseDireClawStatus(PixelmonWrapper user, PixelmonWrapper target)
      Chooses the status applied by Dire Claw.
      Parameters:
      user - The Pokémon using Dire Claw.
      target - The Pokémon receiving the status.
      Returns:
      The selected status type.

    • chooseTriAttackStatus

      StatusType chooseTriAttackStatus(PixelmonWrapper user, PixelmonWrapper target)
      Chooses the status applied by Tri Attack.
      Parameters:
      user - The Pokémon using Tri Attack.
      target - The Pokémon receiving the status.
      Returns:
      The selected status type.

    • chooseStunShockStatus

      StatusType chooseStunShockStatus(PixelmonWrapper user, PixelmonWrapper target)
      Chooses the status applied by Stun Shock.
      Parameters:
      user - The Pokémon using Stun Shock.
      target - The Pokémon receiving the status.
      Returns:
      The selected status type.

    • rollStatusTurns

      int rollStatusTurns(int min, int max)
      Rolls the number of turns a status will last.
      Parameters:
      min - The minimum number of turns.
      max - The maximum number of turns.
      Returns:
      The selected duration.

    • chooseFixedDamageMultiplier

      float chooseFixedDamageMultiplier(float min, float max)
      Chooses a fixed-damage multiplier.

      This is intended for fixed-damage moves with random damage ranges, such as Psywave-style effects. Normal attack damage variance should generally be handled by the attack damage calculator instead.

      Parameters:
      min - The minimum multiplier.
      max - The maximum multiplier.
      Returns:
      The selected multiplier.

    • rollCheerChance

      boolean rollCheerChance(double chance)
      Rolls whether a raid cheer attempt succeeds.
      Parameters:
      chance - The cheer success chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the cheer succeeds.

    • rollShockwaveChance

      boolean rollShockwaveChance(double chance)
      Rolls whether a shockwave-style random raid effect occurs.
      Parameters:
      chance - The shockwave chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the shockwave effect occurs.

    • chooseRaidCheerEffect

      int chooseRaidCheerEffect(int effectCount)
      Chooses which raid cheer effect occurs.
      Parameters:
      effectCount - The number of possible cheer effects.
      Returns:
      The selected cheer effect index.

    • chooseRaidCheerBoost

      RaidCheerBoost chooseRaidCheerBoost()
      Chooses the stat boost or special boost applied by a raid cheer effect.
      Returns:
      The selected raid cheer boost.

    • copy

      BattleRandomness copy(BattleRandomContext newController, BattleRandomSource newSource)
      Creates a copy of this randomness context for another battle controller and random source.

      This is primarily intended for battle state copying, simulation, and AI lookahead.

      Parameters:
      newController - The battle controller the copied randomness should belong to.
      newSource - The random source the copied randomness should use.
      Returns:
      The copied randomness context.

    • getRandomStatIncrease

      BattleStatsType getRandomStatIncrease(it.unimi.dsi.fastutil.ints.IntList possibleStats)
      Chooses a random stat from the possible stat list to increase.
      Parameters:
      possibleStats - The possible stat indexes.
      Returns:
      The selected battle stat type.

    • rollMoveEffect

      boolean rollMoveEffect(double chance)
      Rolls whether a move's main random effect occurs.

      This is intended for moves whose primary effect has a random activation chance, rather than for secondary effects, ability effects, or held item effects.

      Parameters:
      chance - The move effect chance as a probability from 0.0 to 1.0.
      Returns:
      Whether the move effect occurs.

    • rollMagnitude

      MagnitudeRoll rollMagnitude()
      Rolls Magnitude's magnitude and power.
      Returns:
      The selected Magnitude roll.

    • getRandomTarget

      PixelmonWrapper getRandomTarget(PixelmonWrapper user, PixelmonWrapper[] possibleTargets)
      Chooses a random target from the possible targets.
      Parameters:
      user - The Pokémon choosing the target.
      possibleTargets - The possible targets.
      Returns:
      The selected target.

    • getRandomAttack

      Attack getRandomAttack(List<Attack> possibleAttacks)
      Chooses a random attack from the possible attacks.
      Parameters:
      possibleAttacks - The possible attacks.
      Returns:
      The selected attack.

    • getRandomType

      net.minecraft.core.Holder<Type> getRandomType(List<net.minecraft.core.Holder<Type>> possibleTypes)
      Chooses a random type from the possible types.
      Parameters:
      possibleTypes - The possible types.
      Returns:
      The selected type.

    • rollPresentPower

      int rollPresentPower(int maxPower)
      Rolls Present's random base power.
      Parameters:
      maxPower - The maximum power value available to the roll.
      Returns:
      The selected Present power.

    • standard

      static BattleRandomness standard(BattleRandomContext controller, BattleRandomSource source)
      Creates standard battle randomness.

      Standard randomness resolves random events normally and may respect battle-level overrides such as force-chance testing behavior.

      Parameters:
      controller - The owning battle controller.
      source - The raw battle random source.
      Returns:
      A standard battle randomness context.

    • evaluation

      static BattleRandomness evaluation(BattleRandomSource source)
      Creates evaluation battle randomness.

      Evaluation randomness is intended for AI evaluation and should avoid granting unreliable random upside as though it were guaranteed.

      Parameters:
      source - The raw battle random source.
      Returns:
      An evaluation battle randomness context.