Using the AI simulation tool
[!NOTE]
To read this file the intended way, open this file using Visual Studio Code (VSCode) and type CTRL+K, then V.
It will open the preview of this file.
You can also read it on the official GitLab repository of PSDK.
Enjoy your reading!
In this tutorial, we will explain how to use the AI simulation tool to get summarized results on its behaviour in different configurable scenarii.
Configuration
To use the AI simulation tool, you have to define the scenarii that will be used in a configuration file. You can have as many configuration files as you want, they must be located in the Data/PSDK/Tests folder of the project. You may need to create the folder Tests if it is not already in your project.
Configuration files are json formatted files, they must follow this structure:
{
"scenarii": [
{
"title": "Scenario example",
"creatures": [
{
"creature": {
"specie": "bulbasaur",
"form": 0,
"shinySetup": {
"kind": "automatic",
"rate": -1
},
"levelSetup": {
"kind": "fixed",
"level": 50
},
"randomEncounterChance": 1,
"expandPokemonSetup": []
},
"side": "player",
"hp_ratio": 0.75,
"stat_stages": {
"atk": 1,
"dfe": 0,
"spd": -5,
"ats": -6,
"dfs": 3,
"eva": 0,
"acc": 0
},
"status": "poison",
"effects": [
{
"type": "Battle::Effects::CantSwitch",
"args": [
[
"battler",
0,
0
],
[
"battler",
1,
0
],
[
"move",
"mean_look"
]
]
}
]
},
{
"creature": {
"specie": "charmander",
"form": 0,
"shinySetup": {
"kind": "automatic",
"rate": -1
},
"levelSetup": {
"kind": "fixed",
"level": 50
},
"randomEncounterChance": 1,
"expandPokemonSetup": []
},
"side": "enemy",
"hp_ratio": 0.75,
"status": "burn"
}
],
"vs_type": 1,
"weather": "rain",
"terrain": "electric",
"terrain_effects": [
{
"type": "Battle::Effects::TrickRoom",
"args": []
}
],
"bank_effects": {
"player": [
{
"type": "Battle::Effects::StealthRock",
"args": [
"bank",
[
"move",
"stealth_rock"
]
]
}
],
"enemy": [
{
"type": "Battle::Effects::Spikes",
"args": [
"bank"
],
"ivars": {
"power": 3
}
}
]
},
"position_effects": {
"player": {
"0": [
{
"type": "Battle::Effects::FutureSight",
"args": [
"bank",
"position",
[
"battler",
1,
0
],
3,
[
"move",
"future_sight"
]
]
}
],
"1": [],
"2": []
},
"enemy": {
"0": [],
"1": [],
"2": []
}
},
"items": [
{
"dbSymbol": "full_heal",
"amount": 2
},
{
"dbSymbol": "master_ball",
"amount": 1
}
],
"ai_level": 0,
"simulation_times": 100
},
{
//...other scenarii
}
]
}
A configuration file can have multiple scenarii at once, they will each be simulated one after the other. They are independent and do not affect one another.
How to define a scenario
To define your scenario and use it with the tool, you can copy the example above and add it in your configuration file. Here are the customization options available:
- To set a title to the scenario, modify the
titlefield - To change creatures used in the scenario and their state, you can fill the
creaturesfield of the scenario, each object contained in this array represents a creature and is structured as following:- The
creaturefield describes the creature itself, you must use theEncounterobject structure here. Examples of such objects can be found in group or trainer json files of any Pokémon Studio project. If you feel confident in manipulating this kind of object, you can do it manually, otherwise you can define the creatures you want to use in a dedicated trainer on Pokémon Studio, then open its file and copy the creatures to the configuration. - The
sidefield tells on which side of the battle the creature will be. Possible values are "player" or "enemy". - The
hp_ratiofield tells what the creature's hp ratio will be. Accepts float values between 0 and 1. - The
stat_stagesobjects describes the stat modifications to set to the creature. Each stat can be set between -6 and 6. Stat changes will only be applied on creatures that are effectively on the field when initializing the simulated battle. - The
statusfield allows you to set a non-volatile status the the creature. Possible values are "poison", "paralysis", "burn", "sleep", "freeze" and "toxic". - The
effectlists allows setting effects to the creature. More information on how to describe an effect below.
- The
- To change the type of battle to use (1v1, 2v2 or 3v3) modify the
vs_typefield to 1, 2 or 3. - To set a weather for the scenario, modify the
weatherfield. Possible values are "none", "rain", "sunny", "sandstorm", "hail", "fog", "hardsun", "hardrain", "strong_winds" and "snow". - To set a terrain for the scenario, modify the
terrainfield. Possible values are "none", "electric", "grassy", "misty" and "psychic". - To add terrain effects (E.g. Trick Room, not to be confused with actual terrains which are a specific family of effects, see above) to the simulation, use the
terrain_effectslist. More information on how to describe an effect below. - To add bank effects (E.g. Entry hazards, screens) to the simulation, use the
bank_effectslists. More information on how to describe an effect below. - To add position effects (E.g. Future Sight) to the simulation, use the
position_effectslists. Each of the sub-lists named by a number refer to the in-battle position, any effect set to a position that cannot exist with the currentvs_typechosen will be ignored. More information on how to describe an effect below. - To give items for the AI to potentially use, fill the
itemslist. - To change the AI level to use, modify the
ai_levelfield. Default AI levels are included between -1 to 7. You can use custom levels (8+) if you created some in your project. - To change the amount of time the tool will simulate the scenario, modify the
simulation_timesfield.
How to define an effect in the config
Effects to add to the simulation must follow this structure:
{
"type": "Battle::Effects::FutureSight",
"args": [
"bank",
"position",
[
"battler",
1,
0
], // Target
3, // Turn counter
[
"move",
"future_sight"
] // Source move
]
}
Effects are defined using two fields, type where you have to set the full name of the effect, and args where you have to set the arguments in the same order as in the initialize method of the effect.
For the exact arguments of an effect and their type, you have to see how it is defined in PSDK's code. Since the logic argument is always used, and always first, you don't need to add it to the list in the config.
Depending on the kind of argument an effect is looking for to be initialized, follow these instructions:
- When the argument must be a Battler, use an array like this: ["battler", X, Y], where "battler" is a mandatory constant, X is a bank number and Y is a position number.
- When the argument must be a Move, use an array like this: ["move", "db_symbol"], where "move" is a mandatory constant and "db_symbol" is the Symbol of the Move.
- When the argument must be a Type, use an array like this: ["type", "db_symbol"], where "type" is a mandatory constant and "db_symbol" is the Symbol of the Type.
- Only in the
bank_effectsandposition_effectsfields, when the argument must be a bank number, you can use the constant "bank" to automatically compute it depending on the effect's location in the config. E.g. in the "player" sub-list ofbank_effects, "bank" will be replaced by 0. - Only in the
position_effectsfield, when the argument must be a position number, you can use the constant "position" to automatically compute it depending on the effect's location in the config. E.g. in the "2" sub-list of the "enemy" sub-list ofposition_effects, "position" will be replaced by 0. - When the argument in something else (int, boolean), set the value directly in the config.
Special case
For stackable effects, such as Spikes, Toxic Spikes or Stockpile that are empowered through a method different from "initialize", you can set multiple stacks of these at the same time by adding an ivars object to the effect like this:
{
"type": "Battle::Effects::Spikes",
"args": [/* args */],
"ivars": {
"power": 3
}
}
In the example above, the attribute "power" of the "Spikes" effect will be set to 3 when created. As a reference, for the Stockpile effect you'll need to set the effect like this:
{
"type": "Battle::Effects::Stockpile",
"args": [/* args */],
"ivars": {
"stockpile": 3
}
}
Starting the tool
To launch the simulation(s), open a terminal located at the root of your project (you can execute the cmd.bat file for that) and use the command psdk.bat ai_sim --config=ConfigFileName[.json]. Change ConfigFileName by the name of the configuration file you want to use. The .json part is optional, the tool will find the file even if you don't include it in the command.
The tool will run the scenarii it finds in the configuration file provided, and print out the results of the simulation in a format like this:
=== Scenario 1 (1v1, no weather, AI level 0) simulation results ===
- Charmander used Ember on Bulbasaur 1 time(s) (10.0%)
- Charmander used Smokescreen on Bulbasaur 3 time(s) (30.0%)
- Charmander used Fire Fang on Bulbasaur 3 time(s) (30.0%)
- Charmander used Dragon Breath on Bulbasaur 1 time(s) (10.0%)
- Used Item Potion on Charmander 1 time(s) (10.0%)
- Switched Charmander with Squirtle 1 time(s) (10.0%)
=== End of scenario 1 simulation ===
=== Scenario 2 (second title) simulation results ===
...
=== End of scenario 2 simulation ===
...Other scenarii...