Refactoring: Move Source (Legality) (#3560)
Rewrites a good amount of legality APIs pertaining to:
* Legal moves that can be learned
* Evolution chains & cross-generation paths
* Memory validation with forgotten moves
In generation 8, there are 3 separate contexts an entity can exist in: SW/SH, BD/SP, and LA. Not every entity can cross between them, and not every entity from generation 7 can exist in generation 8 (Gogoat, etc). By creating class models representing the restrictions to cross each boundary, we are able to better track and validate data.
The old implementation of validating moves was greedy: it would iterate for all generations and evolutions, and build a full list of every move that can be learned, storing it on the heap. Now, we check one game group at a time to see if the entity can learn a move that hasn't yet been validated. End result is an algorithm that requires 0 allocation, and a smaller/quicker search space.
The old implementation of storing move parses was inefficient; for each move that was parsed, a new object is created and adjusted depending on the parse. Now, move parse results are `struct` and store the move parse contiguously in memory. End result is faster parsing and 0 memory allocation.
* `PersonalTable` objects have been improved with new API methods to check if a species+form can exist in the game.
* `IEncounterTemplate` objects have been improved to indicate the `EntityContext` they originate in (similar to `Generation`).
* Some APIs have been extended to accept `Span<T>` instead of Array/IEnumerable
2022-08-03 16:15:27 -07:00
using System ;
2022-05-30 21:43:52 -07:00
using static PKHeX . Core . EntityContext ;
namespace PKHeX.Core ;
/// <summary>
/// "Context" is an existence island; data format restricts the types of changes that can be made (such as evolving).
/// </summary>
/// <remarks>
/// Starting in the 8th generation games, entities can move between games with wildly different evolution rules.
/// Previous implementations of a "Format Generation" were unable to differentiate if a class object was present in one of these different-rule contexts.
/// The "Format Generation" is still a useful generalization to check if certain fields are present in the entity data, or if certain mutations are possible.
/// </remarks>
Refactoring: Move Source (Legality) (#3560)
Rewrites a good amount of legality APIs pertaining to:
* Legal moves that can be learned
* Evolution chains & cross-generation paths
* Memory validation with forgotten moves
In generation 8, there are 3 separate contexts an entity can exist in: SW/SH, BD/SP, and LA. Not every entity can cross between them, and not every entity from generation 7 can exist in generation 8 (Gogoat, etc). By creating class models representing the restrictions to cross each boundary, we are able to better track and validate data.
The old implementation of validating moves was greedy: it would iterate for all generations and evolutions, and build a full list of every move that can be learned, storing it on the heap. Now, we check one game group at a time to see if the entity can learn a move that hasn't yet been validated. End result is an algorithm that requires 0 allocation, and a smaller/quicker search space.
The old implementation of storing move parses was inefficient; for each move that was parsed, a new object is created and adjusted depending on the parse. Now, move parse results are `struct` and store the move parse contiguously in memory. End result is faster parsing and 0 memory allocation.
* `PersonalTable` objects have been improved with new API methods to check if a species+form can exist in the game.
* `IEncounterTemplate` objects have been improved to indicate the `EntityContext` they originate in (similar to `Generation`).
* Some APIs have been extended to accept `Span<T>` instead of Array/IEnumerable
2022-08-03 16:15:27 -07:00
public enum EntityContext : byte
2022-05-30 21:43:52 -07:00
{
2023-11-05 14:20:35 -08:00
// Generation numerically so we can cast to and from int for most cases.
2022-06-07 23:32:57 -07:00
None = 0 ,
2022-05-30 21:43:52 -07:00
Gen1 = 1 ,
Gen2 = 2 ,
Gen3 = 3 ,
Gen4 = 4 ,
Gen5 = 5 ,
Gen6 = 6 ,
Gen7 = 7 ,
Gen8 = 8 ,
2022-11-24 17:42:17 -08:00
Gen9 = 9 ,
2022-05-30 21:43:52 -07:00
2023-11-05 14:20:35 -08:00
/// <summary>
/// Internal separator to pivot between adjacent contexts.
/// </summary>
2022-05-30 21:43:52 -07:00
SplitInvalid ,
2023-11-05 14:20:35 -08:00
/// <summary> Let's Go, Pikachu! & Let's Go, Eevee! </summary>
2022-05-30 21:43:52 -07:00
Gen7b ,
2023-11-05 14:20:35 -08:00
/// <summary> Legends: Arceus </summary>
2022-05-30 21:43:52 -07:00
Gen8a ,
2023-11-05 14:20:35 -08:00
/// <summary> Brilliant Diamond & Shining Pearl </summary>
2022-05-30 21:43:52 -07:00
Gen8b ,
2022-06-07 23:32:57 -07:00
2023-11-05 14:20:35 -08:00
/// <summary>
/// Internal separator to bounds check count.
/// </summary>
2022-06-07 23:32:57 -07:00
MaxInvalid ,
2022-05-30 21:43:52 -07:00
}
public static class EntityContextExtensions
{
2023-11-05 14:20:35 -08:00
/// <summary>
/// Get the generation number of the context.
/// </summary>
2024-02-22 21:20:54 -06:00
public static byte Generation ( this EntityContext value ) = > value < SplitInvalid ? ( byte ) value : value switch
2022-05-30 21:43:52 -07:00
{
2024-02-22 21:20:54 -06:00
Gen7b = > ( byte ) 7 ,
Gen8a = > ( byte ) 8 ,
Gen8b = > ( byte ) 8 ,
2022-05-30 21:43:52 -07:00
_ = > throw new ArgumentOutOfRangeException ( nameof ( value ) , value , null ) ,
} ;
2023-11-05 14:20:35 -08:00
/// <summary>
/// Checks if the context is a defined value assigned to a valid context.
/// </summary>
/// <returns>True if the context is valid.</returns>
2022-06-07 23:32:57 -07:00
public static bool IsValid ( this EntityContext value ) = > value is not ( 0 or SplitInvalid ) and < MaxInvalid ;
2023-11-05 14:20:35 -08:00
/// <summary>
/// Get a pre-defined single game version associated with the context.
/// </summary>
/// <remarks>Game ID choice here is the developer's choice; if multiple game sets exist for a context, one from the most recent was chosen.</remarks>
2022-05-30 21:43:52 -07:00
public static GameVersion GetSingleGameVersion ( this EntityContext value ) = > value switch
{
Gen1 = > GameVersion . RD ,
Gen2 = > GameVersion . C ,
Gen3 = > GameVersion . E ,
Gen4 = > GameVersion . SS ,
Gen5 = > GameVersion . W2 ,
Gen6 = > GameVersion . AS ,
Gen7 = > GameVersion . UM ,
Gen8 = > GameVersion . SH ,
2022-11-27 11:22:53 -08:00
Gen9 = > GameVersion . VL ,
2022-05-30 21:43:52 -07:00
Gen7b = > GameVersion . GP ,
Gen8a = > GameVersion . PLA ,
Gen8b = > GameVersion . BD ,
_ = > throw new ArgumentOutOfRangeException ( nameof ( value ) , value , null ) ,
} ;
Refactoring: Move Source (Legality) (#3560)
Rewrites a good amount of legality APIs pertaining to:
* Legal moves that can be learned
* Evolution chains & cross-generation paths
* Memory validation with forgotten moves
In generation 8, there are 3 separate contexts an entity can exist in: SW/SH, BD/SP, and LA. Not every entity can cross between them, and not every entity from generation 7 can exist in generation 8 (Gogoat, etc). By creating class models representing the restrictions to cross each boundary, we are able to better track and validate data.
The old implementation of validating moves was greedy: it would iterate for all generations and evolutions, and build a full list of every move that can be learned, storing it on the heap. Now, we check one game group at a time to see if the entity can learn a move that hasn't yet been validated. End result is an algorithm that requires 0 allocation, and a smaller/quicker search space.
The old implementation of storing move parses was inefficient; for each move that was parsed, a new object is created and adjusted depending on the parse. Now, move parse results are `struct` and store the move parse contiguously in memory. End result is faster parsing and 0 memory allocation.
* `PersonalTable` objects have been improved with new API methods to check if a species+form can exist in the game.
* `IEncounterTemplate` objects have been improved to indicate the `EntityContext` they originate in (similar to `Generation`).
* Some APIs have been extended to accept `Span<T>` instead of Array/IEnumerable
2022-08-03 16:15:27 -07:00
2023-11-05 14:20:35 -08:00
/// <summary>
/// Get the game console associated with the context.
/// </summary>
2023-10-28 22:01:26 -07:00
public static GameConsole GetConsole ( this EntityContext value ) = > value switch
{
Gen1 or Gen2 = > GameConsole . GB ,
Gen3 = > GameConsole . GBA ,
Gen4 or Gen5 = > GameConsole . NDS ,
Gen6 or Gen7 = > GameConsole . _3DS ,
Gen7b or Gen8 or Gen8a or Gen8b or Gen9 = > GameConsole . NX ,
_ = > throw new ArgumentOutOfRangeException ( nameof ( value ) , value , null ) ,
} ;
2023-11-05 14:20:35 -08:00
/// <summary>
/// Gets all <see cref="GameVersion"/> values that fall within the context.
/// </summary>
2023-09-16 16:53:06 -07:00
public static GameVersion [ ] GetVersionsWithin ( this EntityContext value , GameVersion [ ] source ) = > value . GetVersionLump ( ) . GetVersionsWithinRange ( source ) ;
2023-11-05 14:20:35 -08:00
/// <summary>
/// Gets the corresponding lumped <see cref="GameVersion"/> value for the context.
/// </summary>
/// <remarks>Shouldn't really use this; see <see cref="GetVersionsWithin"/>.</remarks>
2023-09-16 16:53:06 -07:00
public static GameVersion GetVersionLump ( this EntityContext value ) = > value switch
{
Gen1 = > GameVersion . Gen1 ,
Gen2 = > GameVersion . Gen2 ,
Gen3 = > GameVersion . Gen3 ,
Gen4 = > GameVersion . Gen4 ,
Gen5 = > GameVersion . Gen5 ,
Gen6 = > GameVersion . Gen6 ,
Gen7 = > GameVersion . Gen7 ,
Gen8 = > GameVersion . Gen8 ,
Gen9 = > GameVersion . Gen9 ,
Gen7b = > GameVersion . Gen7b ,
Gen8a = > GameVersion . PLA ,
Gen8b = > GameVersion . BDSP ,
_ = > throw new ArgumentOutOfRangeException ( nameof ( value ) , value , null ) ,
} ;
2023-11-05 14:20:35 -08:00
/// <summary>
/// Gets the corresponding <see cref="EntityContext"/> value for the <see cref="GameVersion"/>.
/// </summary>
Refactoring: Move Source (Legality) (#3560)
Rewrites a good amount of legality APIs pertaining to:
* Legal moves that can be learned
* Evolution chains & cross-generation paths
* Memory validation with forgotten moves
In generation 8, there are 3 separate contexts an entity can exist in: SW/SH, BD/SP, and LA. Not every entity can cross between them, and not every entity from generation 7 can exist in generation 8 (Gogoat, etc). By creating class models representing the restrictions to cross each boundary, we are able to better track and validate data.
The old implementation of validating moves was greedy: it would iterate for all generations and evolutions, and build a full list of every move that can be learned, storing it on the heap. Now, we check one game group at a time to see if the entity can learn a move that hasn't yet been validated. End result is an algorithm that requires 0 allocation, and a smaller/quicker search space.
The old implementation of storing move parses was inefficient; for each move that was parsed, a new object is created and adjusted depending on the parse. Now, move parse results are `struct` and store the move parse contiguously in memory. End result is faster parsing and 0 memory allocation.
* `PersonalTable` objects have been improved with new API methods to check if a species+form can exist in the game.
* `IEncounterTemplate` objects have been improved to indicate the `EntityContext` they originate in (similar to `Generation`).
* Some APIs have been extended to accept `Span<T>` instead of Array/IEnumerable
2022-08-03 16:15:27 -07:00
public static EntityContext GetContext ( this GameVersion version ) = > version switch
{
2023-07-21 10:54:44 -07:00
GameVersion . GP or GameVersion . GE or GameVersion . GO = > Gen7b ,
Refactoring: Move Source (Legality) (#3560)
Rewrites a good amount of legality APIs pertaining to:
* Legal moves that can be learned
* Evolution chains & cross-generation paths
* Memory validation with forgotten moves
In generation 8, there are 3 separate contexts an entity can exist in: SW/SH, BD/SP, and LA. Not every entity can cross between them, and not every entity from generation 7 can exist in generation 8 (Gogoat, etc). By creating class models representing the restrictions to cross each boundary, we are able to better track and validate data.
The old implementation of validating moves was greedy: it would iterate for all generations and evolutions, and build a full list of every move that can be learned, storing it on the heap. Now, we check one game group at a time to see if the entity can learn a move that hasn't yet been validated. End result is an algorithm that requires 0 allocation, and a smaller/quicker search space.
The old implementation of storing move parses was inefficient; for each move that was parsed, a new object is created and adjusted depending on the parse. Now, move parse results are `struct` and store the move parse contiguously in memory. End result is faster parsing and 0 memory allocation.
* `PersonalTable` objects have been improved with new API methods to check if a species+form can exist in the game.
* `IEncounterTemplate` objects have been improved to indicate the `EntityContext` they originate in (similar to `Generation`).
* Some APIs have been extended to accept `Span<T>` instead of Array/IEnumerable
2022-08-03 16:15:27 -07:00
GameVersion . PLA = > Gen8a ,
GameVersion . BD or GameVersion . SP = > Gen8b ,
_ = > ( EntityContext ) version . GetGeneration ( ) ,
} ;
2022-05-30 21:43:52 -07:00
}