diff --git a/PkmnLib.Dynamic/ScriptHandling/PokeballScript.cs b/PkmnLib.Dynamic/ScriptHandling/PokeballScript.cs index 7ed9b6a..3412fd2 100644 --- a/PkmnLib.Dynamic/ScriptHandling/PokeballScript.cs +++ b/PkmnLib.Dynamic/ScriptHandling/PokeballScript.cs @@ -25,6 +25,11 @@ public abstract class PokeballScript : ItemScript // Override this method in derived classes to add custom behavior after a successful capture. } + /// + /// Whether the pokeball has a perfect capture rate, for example the master ball. + /// + public virtual bool IsAlwaysSuccessful(IBattlePokemon target) => false; + /// public override bool IsItemUsable => true; diff --git a/Plugins/PkmnLib.Plugin.Gen7.Tests/Scripts/Items/Pokeballs/MasterBallTests.cs b/Plugins/PkmnLib.Plugin.Gen7.Tests/Scripts/Items/Pokeballs/MasterBallTests.cs new file mode 100644 index 0000000..600323c --- /dev/null +++ b/Plugins/PkmnLib.Plugin.Gen7.Tests/Scripts/Items/Pokeballs/MasterBallTests.cs @@ -0,0 +1,361 @@ +using PkmnLib.Dynamic.Libraries; +using PkmnLib.Dynamic.Models; +using PkmnLib.Dynamic.ScriptHandling; +using PkmnLib.Plugin.Gen7.Libraries.Battling; +using PkmnLib.Plugin.Gen7.Scripts.Items.Pokeballs; +using PkmnLib.Static; +using PkmnLib.Static.Species; + +namespace PkmnLib.Plugin.Gen7.Tests.Scripts.Items.Pokeballs; + +/// +/// Tests for the item script. +/// Bulbapedia: "When used from the Bag in a wild encounter, it catches the wild Pokémon without fail (with some +/// exceptions mentioned below). Despite the common misconception that the Master Ball has a low chance to fail in +/// certain generations, it functions by simply overriding the catch formula entirely, skipping any calculations +/// based on chance." +/// +public class MasterBallTests +{ + /// + /// Looks up a real item from the loaded Gen7 library. + /// + private static IItem GetItem(IDynamicLibrary library, string name) + { + if (!library.StaticLibrary.Items.TryGet(name, out var item)) + throw new InvalidOperationException($"Failed to load item {name}."); + return item; + } + + /// + /// Creates a real level 50 Pokémon of the given species from the loaded Gen7 library. + /// + private static IPokemon CreatePokemon(IDynamicLibrary library, string speciesName) + { + if (!library.StaticLibrary.Species.TryGet(speciesName, out var species)) + throw new InvalidOperationException($"Failed to load species {speciesName}."); + return new PokemonImpl(library, species, species.GetDefaultForm(), new AbilityIndex + { + Index = 0, + IsHidden = false, + }, 50, 0, Gender.Genderless, 0, "hardy"); + } + + /// + /// Creates a mocked wild Pokémon at full health with the given species catch rate. The default is 3, the lowest + /// catch rate in the games. is the real Gen7 library, so thrown items resolve to + /// their real scripts. + /// + private static IBattlePokemon CreateFullHealthTarget(IDynamicLibrary library, byte captureRate = 3) + { + var species = Substitute.For(); + species.CaptureRate.Returns(captureRate); + + var target = Substitute.For(); + target.Library.Returns(library); + target.Species.Returns(species); + target.BoostedStats.Returns(new StatisticSet(100, 0, 0, 0, 0, 0)); + target.CurrentHealth.Returns(100u); + target.GetScripts().Returns(new ScriptIterator([])); + return target; + } + + /// + /// Creates a random source that always rolls the highest possible value, so every shake check of the regular + /// capture formula fails and a critical capture never triggers. + /// + private static IBattleRandom CreateWorstRolls() + { + var random = Substitute.For(); + random.GetInt(Arg.Any(), Arg.Any()).Returns(call => call.ArgAt(1) - 1); + return random; + } + + /// + /// Creates a random source that always rolls the lowest possible value, so every shake check of the regular + /// capture formula succeeds and a critical capture triggers whenever it is possible. + /// + private static IBattleRandom CreateBestRolls() + { + var random = Substitute.For(); + random.GetInt(Arg.Any(), Arg.Any()).Returns(0); + return random; + } + + /// + /// Bulbapedia: "it catches the wild Pokémon without fail". The script reports a perfect capture rate to the + /// capture library through . + /// + [Test] + public async Task IsAlwaysSuccessful_AnyTarget_ReturnsTrue() + { + // Arrange + var masterBall = new MasterBall(Substitute.For()); + var target = Substitute.For(); + + // Act + var result = masterBall.IsAlwaysSuccessful(target); + + // Assert + await Assert.That(result).IsTrue(); + } + + /// + /// Bulbapedia: "it functions by simply overriding the catch formula entirely". The Master Ball has no catch rate + /// multiplier of its own, so leaves the rate untouched. + /// + [Test, Arguments((byte)0), Arguments((byte)3), Arguments((byte)45), Arguments((byte)255)] + public async Task ChangeCatchRate_AnyCatchRate_LeavesCatchRateUnchanged(byte initialCatchRate) + { + // Arrange + var masterBall = new MasterBall(Substitute.For()); + var target = Substitute.For(); + var catchRate = initialCatchRate; + + // Act + masterBall.ChangeCatchRate(target, ref catchRate); + + // Assert + await Assert.That(catchRate).IsEqualTo(initialCatchRate); + } + + /// + /// Bulbapedia: "When used from the Bag in a wild encounter, it catches the wild Pokémon". A Pokémon in a wild + /// battle is a valid target for . + /// + [Test] + public async Task IsTargetValid_PokemonInWildBattle_ReturnsTrue() + { + // Arrange + var masterBall = new MasterBall(Substitute.For()); + var battle = Substitute.For(); + battle.IsWildBattle.Returns(true); + var target = Substitute.For(); + target.Battle.Returns(battle); + + // Act + var result = masterBall.IsTargetValid(target); + + // Assert + await Assert.That(result).IsTrue(); + } + + /// + /// Bulbapedia: "If used in a Trainer battle (except if used as a Snag Ball on a Shadow Pokémon), the opposing + /// Trainer will deflect it". A Pokémon in a trainer battle is not a valid target. + /// + [Test] + public async Task IsTargetValid_PokemonInTrainerBattle_ReturnsFalse() + { + // Arrange + var masterBall = new MasterBall(Substitute.For()); + var battle = Substitute.For(); + battle.IsWildBattle.Returns(false); + var target = Substitute.For(); + target.Battle.Returns(battle); + + // Act + var result = masterBall.IsTargetValid(target); + + // Assert + await Assert.That(result).IsFalse(); + } + + /// + /// Bulbapedia: the Master Ball is used "in a wild encounter". A Pokémon that is not in a battle at all is not a + /// valid target. + /// + [Test] + public async Task IsTargetValid_PokemonOutsideBattle_ReturnsFalse() + { + // Arrange + var masterBall = new MasterBall(Substitute.For()); + var target = Substitute.For(); + + // Act + var result = masterBall.IsTargetValid(target); + + // Assert + await Assert.That(result).IsFalse(); + } + + /// + /// The master_ball item in the Gen7 data resolves to the script, so the capture + /// library picks up the guaranteed capture when the real item is thrown. + /// + [Test] + public async Task ScriptResolver_MasterBallItem_ResolvesToMasterBallScript() + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var item = GetItem(library, "master_ball"); + + // Act + var resolved = library.ScriptResolver.TryResolveBattleItemScript(item, out var script); + + // Assert + await Assert.That(resolved).IsTrue(); + await Assert.That(script).IsTypeOf(); + } + + /// + /// Bulbapedia: "it catches the wild Pokémon without fail". Even the hardest possible target, a catch rate 3 + /// species at full health, with every shake check failing, is caught by . + /// + [Test] + public async Task TryCapture_MasterBallOnHardestTargetWithWorstRolls_IsCaught() + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var captureLibrary = new Gen7CaptureLibrary(new Gen7PluginConfiguration()); + var target = CreateFullHealthTarget(library); + + // Act + var result = captureLibrary.TryCapture(target, GetItem(library, "master_ball"), CreateWorstRolls()); + + // Assert + await Assert.That(result.IsCaught).IsTrue(); + } + + /// + /// Sanity check for the setup of : + /// under the same conditions an ordinary Poké Ball fails, so the guaranteed capture really comes from the + /// Master Ball and not from the test setup. + /// + [Test] + public async Task TryCapture_PokeBallOnHardestTargetWithWorstRolls_IsNotCaught() + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var captureLibrary = new Gen7CaptureLibrary(new Gen7PluginConfiguration()); + var target = CreateFullHealthTarget(library); + + // Act + var result = captureLibrary.TryCapture(target, GetItem(library, "poke_ball"), CreateWorstRolls()); + + // Assert + await Assert.That(result.IsCaught).IsFalse(); + } + + /// + /// Bulbapedia: "it functions by simply overriding the catch formula entirely, skipping any calculations based on + /// chance." No random number is rolled when a Master Ball is thrown. + /// + [Test] + public async Task TryCapture_MasterBall_DoesNotRollRandom() + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var captureLibrary = new Gen7CaptureLibrary(new Gen7PluginConfiguration()); + var target = CreateFullHealthTarget(library); + var random = CreateWorstRolls(); + + // Act + captureLibrary.TryCapture(target, GetItem(library, "master_ball"), random); + + // Assert + await Assert.That(random.ReceivedCalls()).IsEmpty(); + } + + /// + /// Bulbapedia: "skipping any calculations based on chance". The critical capture roll is part of the formula the + /// Master Ball skips, so a species caught hundreds of times still reports a regular capture through + /// , even with rolls that would otherwise guarantee a critical capture. + /// + [Test] + public async Task TryCapture_MasterBallOnSpeciesCaughtManyTimesWithBestRolls_IsNotCriticalCapture() + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var captureLibrary = new Gen7CaptureLibrary(new Gen7PluginConfiguration + { + TimesSpeciesCaught = _ => 1000, + }); + var target = CreateFullHealthTarget(library, 200); + + // Act + var result = captureLibrary.TryCapture(target, GetItem(library, "master_ball"), CreateBestRolls()); + + // Assert + await Assert.That(result.IsCaught).IsTrue(); + await Assert.That(result.CriticalCapture).IsFalse(); + } + + /// + /// Sanity check for the setup of + /// : under the same + /// conditions an ordinary Poké Ball does trigger a critical capture, so the Master Ball really skips that roll. + /// + [Test] + public async Task TryCapture_PokeBallOnSpeciesCaughtManyTimesWithBestRolls_IsCriticalCapture() + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var captureLibrary = new Gen7CaptureLibrary(new Gen7PluginConfiguration + { + TimesSpeciesCaught = _ => 1000, + }); + var target = CreateFullHealthTarget(library, 200); + + // Act + var result = captureLibrary.TryCapture(target, GetItem(library, "poke_ball"), CreateBestRolls()); + + // Assert + await Assert.That(result.CriticalCapture).IsTrue(); + } + + /// + /// Bulbapedia (Catch rate): "If a Master Ball is used, the amount of successful shake checks is set to four." + /// A Master Ball capture therefore reports the full four shakes in , the same + /// as any other guaranteed capture. + /// + [Test] + public async Task TryCapture_MasterBall_ReportsFourShakes() + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var captureLibrary = new Gen7CaptureLibrary(new Gen7PluginConfiguration()); + var target = CreateFullHealthTarget(library); + + // Act + var result = captureLibrary.TryCapture(target, GetItem(library, "master_ball"), CreateWorstRolls()); + + // Assert + await Assert.That(result.Shakes).IsEqualTo(4); + } + + /// + /// Bulbapedia: "it catches the wild Pokémon without fail". Using the real Master Ball item through + /// in a real wild battle against a full-health Beldum (catch rate 3) + /// captures it on the first attempt, whatever the battle's random seed is. + /// + [Test, Arguments(0), Arguments(1), Arguments(7), Arguments(1234)] + public async Task OnUseWithTarget_RealWildBattle_CapturesTargetOnFirstAttempt(int seed) + { + // Arrange + var library = LibraryHelpers.LoadLibrary(); + var own = CreatePokemon(library, "bulbasaur"); + var wildPokemon = CreatePokemon(library, "beldum"); + var party = new PokemonPartyImpl(1); + party.SwapInto(own, 0); + var wildParty = new PokemonPartyImpl(1); + wildParty.SwapInto(wildPokemon, 0); + using var battle = new BattleImpl(library, [ + new BattlePartyImpl(party, [new ResponsibleIndex(0, 0)]), + new BattlePartyImpl(wildParty, [new ResponsibleIndex(1, 0)]), + ], false, 2, 1, true, "grass", seed); + battle.Sides[0].SendOut(0, own); + battle.Sides[1].SendOut(0, wildPokemon); + var wildBattlePokemon = battle.GetPokemon(1, 0)!; + var masterBallItem = GetItem(library, "master_ball"); + if (!library.ScriptResolver.TryResolveBattleItemScript(masterBallItem, out var masterBall)) + throw new InvalidOperationException("Failed to resolve the master ball script."); + + // Act + masterBall.OnUseWithTarget(wildBattlePokemon, battle.EventHook); + + // Assert + await Assert.That(wildBattlePokemon.IsCaught).IsTrue(); + await Assert.That(battle.Result!.Value.CapturedPokemon).Contains(wildPokemon); + } +} \ No newline at end of file diff --git a/Plugins/PkmnLib.Plugin.Gen7/Data/Items.json b/Plugins/PkmnLib.Plugin.Gen7/Data/Items.json index d6825df..80b240d 100755 --- a/Plugins/PkmnLib.Plugin.Gen7/Data/Items.json +++ b/Plugins/PkmnLib.Plugin.Gen7/Data/Items.json @@ -3514,10 +3514,7 @@ "flingPower": 0 }, "battleEffect": { - "name": "pokeball_flat_modifier", - "parameters": { - "catchRate": 255 - } + "name": "master_ball" } }, { diff --git a/Plugins/PkmnLib.Plugin.Gen7/Libraries/Battling/Gen7CaptureLibrary.cs b/Plugins/PkmnLib.Plugin.Gen7/Libraries/Battling/Gen7CaptureLibrary.cs index c3db343..30f4684 100644 --- a/Plugins/PkmnLib.Plugin.Gen7/Libraries/Battling/Gen7CaptureLibrary.cs +++ b/Plugins/PkmnLib.Plugin.Gen7/Libraries/Battling/Gen7CaptureLibrary.cs @@ -24,6 +24,9 @@ public class Gen7CaptureLibrary : ICaptureLibrary if (target.Library.ScriptResolver.TryResolveBattleItemScript(captureItem, out var script) && script is PokeballScript pokeballScript) { + if (pokeballScript.IsAlwaysSuccessful(target)) + return new CaptureResult(true, 4, false); + pokeballScript.ChangeCatchRate(target, ref catchRate); } diff --git a/Plugins/PkmnLib.Plugin.Gen7/Scripts/Items/Pokeballs/MasterBall.cs b/Plugins/PkmnLib.Plugin.Gen7/Scripts/Items/Pokeballs/MasterBall.cs new file mode 100644 index 0000000..d428728 --- /dev/null +++ b/Plugins/PkmnLib.Plugin.Gen7/Scripts/Items/Pokeballs/MasterBall.cs @@ -0,0 +1,11 @@ +namespace PkmnLib.Plugin.Gen7.Scripts.Items.Pokeballs; + +[ItemScript("master_ball")] +public class MasterBall(IItem item) : PokeballScript(item) +{ + public override bool IsAlwaysSuccessful(IBattlePokemon target) => true; + + public override void ChangeCatchRate(IBattlePokemon target, ref byte catchRate) + { + } +} \ No newline at end of file