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:

  1. The Primary Judging, a fully automatic phase presenting the contestants and earning point based on their condition stats.
  2. The Secondary Judging, where contestants go through 5 rounds of appeal, using moves to score points.
  3. 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:

  1. 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.
  2. Determine the moves that will be played during the round.
    • The player's choice is done with the ContestSkillChoice UI.
    • 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 nil is submitted as the move for that contestant.
  3. 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 :repeatable effect tag: 0.0.
  • Otherwise: counts how many consecutive trailing rounds used this exact move, then applies −(level − 1) × 0.05 per 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.2 if 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.3 if 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.