PSDK Contests
[!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!
This page describes how Creature Contests work in PSDK, how to start them, the phases and rounds flow and their various mechanics.
The Contest system is contained in the Contest:: namespace in pokemonsdk/scripts/6 Contest/. It follows the same pattern as the Battle Engine: a Contest::Scene orchestrates the flow, a Contest::Logic manages the game state and computations, and a Contest::Visual handles UI elements and animations.
Contest Types & Condition Stats
Contests are themed around one of five conditions, which correspond both to the Contest type and to a stat on every PFM::Pokemon:
| Contest Type | Condition Stat | Adjacent Conditions |
|---|---|---|
| Cool | coolness |
Beauty, Tough |
| Beauty | beauty |
Cool, Cute |
| Cute | cuteness |
Beauty, Clever |
| Clever | cleverness |
Cute, Tough |
| Tough | toughness |
Clever, Cool |
Condition stats are defined in 701 Pokemon Conditions.rb.
Condition stats range from 0 to 255 and are raised outside of contests using Pokéblocks. There is also a sixth stat, the Sheen, which contributes to the Primary Judging score but is not tied to any condition. By default, PSDK offers ways to modify and handle the Sheen, but the Pokéblocks implementation will not affect it as they are based on the 6th generation of Pokémon.
Each Contest also has a rank: :normal, :super, :hyper, or :master. By themselves, the ranks' only effect during a Contest is to raise the amount of score needed to show a certain amount of hearts during the Primary Judging. It is the maker's responsibility to design the AI coordinators, their difficulty and the access restrictions (or lack thereof) of each Contest ranks.
Starting a Contest
Contests are launched from an event using the start_contest interpreter method, defined in 130 Interpreter_Sequences.rb:
start_contest(
creature_position, # Party slot of the player's Creature (0–5)
coordinator1_id, # Studio trainer ID of coordinator 1
coordinator2_id, # Studio trainer ID of coordinator 2
coordinator3_id, # Studio trainer ID of coordinator 3
condition: :cool, # Contest's condition: :cool, :beautiful, :cute, :clever, or :tough
rank: :normal, # Contest's rank: :normal, :super, :hyper, or :master
bgm: DEFAULT_CONTEST_BGM
)
# Example:
start_contest(0, 48, 51, 59, condition: :cute, rank: :master)
The condition, rank and bgm parameters are optional, their default values are the ones displayed above if they are not explicitly set in the method call.
The Creature used by an AI coordinator is always the first one in their party. Additionaly, Coordinators need to have a battle sprite set in their Studio resources to be properly displayed during the Contest.
Game Variables
| Yuki::Var Constant | Variable # | Set When | Purpose |
|---|---|---|---|
Contest_Coordinator1_ID |
52 | On start | Studio trainer ID of opponent 1 |
Contest_Coordinator2_ID |
53 | On start | Studio trainer ID of opponent 2 |
Contest_Coordinator3_ID |
54 | On start | Studio trainer ID of opponent 3 |
Last_Contest_Final_Place |
55 | On exit | Player's final placement (1-4) |
Last_Contest_Final_Score |
56 | On exit | Player's final score |
After the Contest ends, Last_Contest_Final_Place and Last_Contest_Final_Score are available to subsequent event commands to award prizes or unlock content.
Contest Phases & Round Flow
Contests are divided into 3 parts:
- The Primary Judging, a fully automatic phase presenting the contestants and earning point based on their condition stats.
- The Secondary Judging, where contestants go through 5 rounds of appeal, using moves to score points.
- The Results, the ending phase where the total score of each contestant is counted and the winner is announced.
Primary Judging
During this phase, each contestant will subsequently earn a score that depends on their conditions' values. The score for this phase is calculated as follows:
score = main condition stat
+ sum of adjacent condition stats / 2
+ sheen / 2
+ 20 when holding the scarf matching the Contest condition
+ 10 when holding a scarf adjacent to the Contest condition
Source: 103 Primary Judging Scoring.rb
Scarves are items that boost the score during Primary Judging only, they have no effect during appeal rounds.
| Contest Type | Matching Scarf | Adjacent Scarves |
|---|---|---|
| Cool | Red Scarf (+20) | Blue Scarf, Yellow Scarf (+10 each) |
| Beauty | Blue Scarf (+20) | Red Scarf, Pink Scarf (+10 each) |
| Cute | Pink Scarf (+20) | Blue Scarf, Green Scarf (+10 each) |
| Clever | Green Scarf (+20) | Pink Scarf, Yellow Scarf (+10 each) |
| Tough | Yellow Scarf (+20) | Green Scarf, Red Scarf (+10 each) |
The Primary Judging's score is then stored in the round history of each contestant with a specific flag to differentiate it.
Secondary Judging
During each of the five rounds of the Secondary Judging, the scene will go through this sequence of steps:
- Determine the play order of the round, usually done by ordering contestants by their previous round's score, highest first. Some moves may affect or completely randomize this order.
- Determine the moves that will be played during the round.
- The player's choice is done with the
ContestSkillChoiceUI. - AIs make their move choice through heuristic computations, this is explained in more details in the AI section.
- If any contestant has an effect making them skip a turn
nilis submitted as the move for that contestant.
- The player's choice is done with the
- Play the moves, earn appeal points, and apply their effects if they have any.
Moves
Every regular move can also be used in a Contest. Each of them is composed of these information:
- An Appeal value, this is the score you will earn when using this move by default. Lots of effects can influence this value.
- A Jam value. This value is optional, it is used when the move has an effect that reduces the score of contestants playing before the user.
- A Condition. Conditions are the counterpart of regular types only used during Contests. Using a move whose condition matches the contests is beneficial, while the contrary will lose you points.
- A list of effects. Unlike in battle, lots of moves have the same effect when used in a Contest. There are 33 possible effects available in PSDK. You can configure a move to have any number of effects at once. This is probably not a good idea for obvious reasons, but more balanced customizations can be made. Effects are referred to as "Effect Tags".
- A list of moves that can complete a combo started by this move. Combo mechanic is explained with more details in Combos
Move procedure
Whenever a move is played during a round, the procedure goes through these steps:
- Show the move use message and play the animation
- Proceed all the effects
- Apply the move's effects
- Give the score (potentially modified by effects) to the user
- Checks for starting or completing a combo
- Apply changes on the Enthusiasm
Sources:
Results
After round 5, the Results phase is called and score banners are shown on screen to summarize the total score of each contestant. Then the player's final placement and score are written in variables for later use.
Source: 102 Scene Score Counting.rb
Mechanics
Enthusiasm
Source: 102 Enthousiasm.rb
Enthusiasm tracks crowd excitement on a 0–5 scale and is displayed on the judge's sprite. After each move is resolved, Logic#change_enthousiasm(move) applies a change and returns a score modification:
| Situation | Effect on Enthusiasm | Score Modification |
|---|---|---|
Move condition matches Contest condition (or has the effect tag :always_exciting) |
+1 | +1 heart |
| Move condition is adjacent to Contest condition | None | None |
| Move condition is opposite (neither match nor adjacent) | −1 | −1 heart |
Move has the effect tag :can_reset_excitement and its condition doesn't match |
Reset to 0 | −1 heart |
| Same move used as last round (repetition penalty) | −1 even if the condition matches | −1 heart |
| Enthusiasm reaches 5 | Resets to 0 | +5 hearts (or +8 with Mega Evolution, see next part) |
A move with the :lock_excitement effect tag was previously played |
Blocks any positive change | None |
Move has the effect tag :very_exciting_first |
+2 if user is first and the initial change is positive | +1 heart |
Move has the effect tag :very_exciting_last |
+2 if user is last and the initial change is positive | +1 heart |
Mega Evolution
When enthusiasm reaches maximum (5), if the contestant holds the correct Mega Stone and its coordinator has any Mega-enabling item in its bag, the maximum enthusiasm bonus becomes +8 hearts instead of +5, and the contestant Mega Evolves.
Mega Evolution in contests is purely a scoring bonus, it does not change anything else besides the visual change.
Combos
Using a move whose list of combo-moves is not empty will start a combo. In this state, the contestant is more likely to become nervous due to a move. Using one of the moves in the list during the next turn will complete the combo, earning 3 bonus points.
If a move with the effect tag :cancel_others_combo is used, contestants playing after the user will be prevented from completing their combo.
Jamming & Jam Protection
Source: 103 Effect Tag Mechanic.rb, 100 EffectBase.rb
Jamming reduces the score of other contestants, and only those that already played their move.
Jam-related effect tags:
| Effect Tag | Behavior |
|---|---|
:prevent_jam_one_turn |
Negates all jam attempts this turn |
:prevent_jam_one_time |
Negates one jam attempt this turn |
:more_nervous |
Doubles the jam amount taken for one turn |
Nervousness
Moves with the :try_make_nervous effect tag targets contestants who have not yet played this round. Each target is considered individually and if the attempt is successful, it will skip its turn.
The success chance calculated as follows:
base_chance = 25%
− 10% per active stack of "raised condition" effect on the target
+ 25% if the target is currently preparing a combo
Condition Level
Condition level is the count of active RaisedCondition effects on a contestant (maximum 3). It acts as a persistent, per-round appeal multiplier. Each stack of this effect adds a bonus point when a move is used. Some moves with the :bonus_raised_condition effect instead receive 2 bonus points per stack.
Contestants with this effect are also less likely to become nervous.
Effect Tags - Full Reference
| Tag | Description |
|---|---|
:play_first_next_turn |
User plays first next round |
:play_last_next_turn |
User plays last next round |
:randomize_next_turn_order |
Next round's play order is fully randomized |
:jam_previous |
Jams the contestant who played immediately before the user |
:jam_all |
Jams all contestants who have already played this round |
:jam_same_condition |
Jams previous contestant if its last move shares the user's condition |
:jam_highest_score |
Jams the contestant(s) with the highest total score |
:prevent_jam_one_turn |
Negates all jam attempts this turn |
:prevent_jam_one_time |
Negates the next jam attempt this turn |
:raise_condition |
Adds a RaisedCondition effect on the user (max 3 stacks) |
:lower_others_condition |
Removes all RaisedCondition effects from previous contestants |
:bonus_raised_condition |
The move receives a bonus of two hearts per RaisedCondition effect instead of one |
:try_make_nervous |
Attempts to make the next contestants nervous |
:more_nervous |
Double the jam amount taken this turn |
:skip_next_turn |
User skips their next turn |
:cant_act_anymore |
User cannot act for the rest of the Contest |
:cancel_others_combo |
Cancels combos of contestants who have not yet played |
:repeatable |
Repeating the move has no negative effect on the enthusiasm |
:bonus_first |
+4 hearts if the user plays first this round |
:bonus_last |
+4 hearts if the user plays last this round |
:bonus_earlier |
first: +5, 2nd: +3, 3rd: +1, 4th: +0 |
:bonus_later |
first: +0, 2nd: +1, 3rd: +3, 4th: +5 |
:bonus_excitement |
+0 if Enthusiasm is 0 or 1, +2 if Enthusiasm is 2, +3 if Enthusiasm is 3, +5 if Enthusiasm is 4 |
:random_appeal |
Random bonus among 0, 1, 3, 5, or 7 |
:copy_previous_appeal |
Bonus equal to the previous contestant's score (if positive) |
:bonus_half_previous_appeals |
Bonus equal to half the score of all previous contestants (each rounded up) |
:compare_previous_appeal |
+3 if the move's appeal is greater than the previous score, −3 if less, no bonus if equal |
:bonus_same_condition_previous |
+4 if this move's condition matches the previous contestant's move condition |
:always_exciting |
Move always grants +1 enthusiasm, regardless of condition match |
:can_reset_excitement |
Resets enthusiasm to 0 if condition doesn't match |
:lock_excitement |
Blocks any further enthusiasm increases this round after this move |
:very_exciting_first |
+1 extra enthusiasm if the user played first this round |
:very_exciting_last |
+1 extra enthusiasm if the user played last this round |
AI
AI levels
Contest AI is divided into 7 levels, configurable from Pokémon Studio using the same component that sets the AI level for battles.
Each AI class is increasingly reliable, gaining access to more heuristics or advanced versions of existing ones. They also have a noise value used at the end of every move heuristic computation to add a random component; this value decreases as the level increases.
| Level | Class name | Description | Noise value |
|---|---|---|---|
| 1 | RandomAI | Fully random AI, only uses a random move every turn | - |
| 2 | NormalRankAI | Sees how much appeal the moves it has access to have and favors the higher ones | 0.3 |
| 3 | SuperRankAI | Sees the condition of the contest and its moves | 0.2 |
| 4 | StrongSuperRankAI | - | 0.15 |
| 5 | HyperRankAI | Has access to more advanced version of heuristics | 0.1 |
| 6 | StrongHyperRankAI | Actively tries to make combos when possible | 0.07 |
| 7 | MasterRankAI | Strongest AI, has access to most advanced heuristics and rarely makes mistakes | 0.05 |
Decision Pipeline
Move heuristics are computed in 101 Move Heuristics Computations.rb:
heuristic = 0.0
+ Sum of all effect tag heuristics of the move
+ Repetition heuristic
+ Appeal heuristic # AI level 2+
+ Condition heuristic # AI level 3+
+ Combo heuristic # AI level 6+
+ Noise
For each effect tag on the move, the AI fetches the highest-registered EffectTagHeuristicBase subclass whose min_level is at or below the AI's own level. If no class is registered, or all registered entries require a higher AI level, the tag contributes 0.0.
When the game is launched in debug mode, AIs' heuristic computation final values are logged in the console.
Heuristics
Effect Tag Heuristics
Each effect tag can have one or more EffectTagHeuristicBase subclasses registered at a given minimum level. At higher levels, "Advanced" variants may replace or add factors to simpler ones. Tags with no registered heuristic silently contribute 0.0.
| Tag | Heuristic class (min level) |
|---|---|
:play_first_next_turn |
PlayFirstNextTurn (≥3), AdvancedPlayFirstNextTurn (≥5) |
:play_last_next_turn |
PlayLastNextTurn (≥3), AdvancedPlayLastNextTurn (≥5) |
:randomize_next_turn_order |
RandomizeNextTurnOrder (≥5) |
:jam_previous |
JamOne (≥3), AdvancedJamOne (≥5) |
:jam_highest_score |
JamOne (≥3), AdvancedJamOne (≥5) |
:jam_same_condition |
JamOne (≥3), AdvancedJamOne (≥5), AdvancedJamSameCondition (≥6) |
:jam_all |
JamAll (≥3), AdvancedJamAll (≥5) |
:prevent_jam_one_time |
PreventJam (≥4), AdvancedPreventJam (≥6) |
:prevent_jam_one_turn |
PreventJam (≥4), AdvancedPreventJam (≥6) |
:more_nervous |
MoreSensitiveToJam (≥4), AdvancedMoreSensitiveToJam (≥6) |
All other effect tags currently have no registered heuristic and contribute 0.0. They will be implemented later.
Repetition Heuristic
This heuristic is always active for non-random AIs, and grows stronger with AI level.
- If the move was not used last round:
0.0. - If the move has the
:repeatableeffect tag:0.0. - Otherwise: counts how many consecutive trailing rounds used this exact move, then applies
−(level − 1) × 0.05per repetition.
At level 2 the multiplier is 0.05, it can often be overshadowed by other heuristic components. At level 7 it reaches −0.30 per consecutive repetition, strongly discouraging higher-level AIs from repeating non-repeatable moves.
Appeal Heuristic
This heuristic is always active for non-random AIs.
Returns move.appeal × 0.025. A move with appeal 4 contributes +0.10; appeal 8 contributes +0.20.
Condition Heuristic
This heuristic is active for AIs at level 3 or higher.
Penalizes moves that will have a negative effect on Enthusiasm:
- Matching condition or has the effect tag
:always_exciting:0.0 - Adjacent condition:
−0.05 - Non-adjacent:
−0.15
Adjacency follows the mapping defined in Contest Types & Condition Stats.
Combo Heuristic
This heuristic is active for AIs at level 6 or higher.
The behaviour depends on whether the contestant is currently preparing a combo:
- Starting a combo (
prepare_combo):+0.2if the move can start a combo and the creature's moveset contains at least one valid follow-up move. No bonus is applied on the last round, to avoid starting a combo that cannot be completed. - Completing a combo (
complete_combo):+0.3if the current move is a valid continuation of last round's combo starter.
Completing is rewarded more than starting, since it yields the actual bonus points.
Noise
def compute_noise(heuristic)
(@logic.rng.rand(-@noise..@noise) + @logic.rng.rand(-@noise..@noise)) / 2.0
end
The RNG is sampled twice and the results are averaged. This produces a non-linear distribution where values near zero are more probable than values at the extremes, a deliberate design choice to avoid extreme noise outliers while still causing the AI to occasionally not pick the most optimal move.