Main gameplay state
[heading: "Description"]The Play state runs a single song from start to finish. It clones the chart, loads the audio and backgrounds, spawns the player renderer and advances the rhythm gameplay loop producing judgement counts, combo, accuracy and a final score. When the song ends it collates the results and hands them to the Results state.
[heading: "Key Features"] [list] * Full playthrough flow from audio setup through judgement and results * HUD with score, combo, lifebar, accuracy, visualizers and character closeups * Background pipeline supporting images, videos, fades and animated effects * Chart modifiers, character skills, lyrics, metronome and pause menu support [/list] [heading: "Properties"] [table header] [ Property | Type | Description ] [ originalSong | Object | The unmodified song object passed into the state ] [ song | Object | A deep clone of the chart used for gameplay ] [ difficultyIndex | number | Index of the selected difficulty ] [ player | Object|null | The player renderer and judgement objects ] [ backgroundQueue | Array | Queue of background preload tasks ] [ preloadedBackgroundElements | Object | Cache of preloaded background elements by file name ] [ currentBackground | ?Object | The background element currently on screen ] [ isPaused | boolean | Whether gameplay is currently paused ] [ pauseStartTime | number | Timestamp when the current pause started ] [ totalPausedDuration | number | Total accumulated pause duration in milliseconds ] [ pendingSongStart | boolean | Whether the song start is held until audio is ready ] [ audioEndListener | ?Function | Handler notified when the audio element ends ] [ started | boolean | Whether the song has started playing ] [ startTime | number | Audio timeline offset used to sync the chart ] [ autoplay | boolean | Whether the note roadmap is being played by the computer ] [ playlistKey | string | Optional playlist key the current song belongs to ] [ userOffset | number | The user's global timing offset in milliseconds ] [ lastVideoUpdateTime | number | Timestamp of the last video sync update ] [ lyrics | ?Lyrics | Lyrics renderer for the current song ] [ hasLyricsFile | boolean | Whether the chart includes a lyrics file ] [ visualizerType | string | Active visualizer type from account settings ] [ lastVisualizerUpdateTime | number | Timestamp of the last visualizer redraw ] [ metronome | ?Metronome | Beats-per-minute metronome display ] [ gameRecorder | ?ScreenRecorder | Recorder capturing the playthrough ] [ playtestMode | boolean | Whether this is an editor playtest run ] [ fullComboAnimationStarted | boolean | Whether the full combo overlay animation has started ] [ fullComboAnimationEnded | boolean | Whether the full combo overlay animation has finished ] [ shootingDown | boolean | Whether the shots are currently flying on screen ] [ characterManager | CharacterManager | Manages the player's characters and persistence ] [ currentCharacter | Object|null | The character active for this playthrough ] [ skillSystem | CharacterSkillSystem | Tracks character skills used during the playthrough ] [ JUDGE_WINDOWS | Object | Timing windows used to judge each note ] [ SCORE_VALUES | Object | Score values awarded for each judgement ] [ FIXED_DELAY | number | Fixed playback delay in milliseconds ] [ backgroundLayer | Phaser.Group | Layer holding the background elements ] [ backgroundSprite | CanvasBackground | The chart background rendered as a canvas ] [ visibilityChangeListener | Function | Handler pausing or resuming the game on tab visibility changes ] [ audio | HTMLAudioElement | Audio element used for the song playback ] [ backgroundGradient | BackgroundGradient | Animated gradient behind the HUD ] [ hud | Phaser.Sprite | Root sprite of the HUD ] [ hudFlashShape | Phaser.Sprite | Full-screen flash shape keyed by the temperature meter ] [ hudTop | Phaser.Sprite | Top HUD strip ] [ hudBottom | Phaser.Sprite | Bottom HUD strip ] [ overHud | Phaser.Sprite | Overlay sprite sitting above the HUD ] [ difficultyBanner | Phaser.Sprite | Banner showing the difficulty name ] [ difficultyTypeText | Text | Label of the current difficulty ] [ songTitleText | Text | Scrolling song title label ] [ playerName | Text | Name of the active character ] [ skillBar | SkillBar | Bar showing the character's skill usage ] [ scoreText | Text | Numeric score label ] [ lifebarStart | Phaser.Sprite | Left segment of the lifebar ] [ lifebarMiddle | Phaser.Sprite | Stretching middle segment of the lifebar ] [ lifebarEnd | Phaser.Sprite | Right segment of the lifebar ] [ autoplayText | Text | Label shown while autoplay is enabled ] [ healthText | Text | Numeric health label ] [ judgementText | Phaser.Sprite | Sprite showing the last judgement result ] [ accuracyBar | Phaser.Sprite | Accuracy bar sprite ] [ comboText | Text | Current combo count label ] [ visualizer | ?Object | The active visualizer instance, or null when none is shown ] [ temperature | AudioTemperatureMeter | Meter tracking the song's audio temperature ] [ lyricsText | ?Text | On-screen label rendering the current lyrics line ] [ fullComboOverlay | Phaser.Sprite | Full combo celebration overlay ] [ fullComboGradient | Phaser.Sprite | Gradient layer over the full combo background ] [ fullComboBg | Phaser.Graphics | Bordered bar behind the full combo message ] [ fullComboText | Text | "FULL COMBO!!" or "FLAWLESS!!" message ] [ video | HTMLVideoElement | Video element currently used as the background ] [ _bgFadeTween | ?Phaser.Tween | Tween animating the current background fade-in ] [ _pendingFadeOut | ?Object | Pending fade-out parameters for the current background ] [ _bgEffectTimer | ?number | Interval id driving the active background effect ] [ pauseBg | Phaser.Graphics | Dark overlay dimming the gameplay behind the pause menu ] [ pauseStatsText | Text | Label listing the current judgement counts ] [ pauseCarousel | CarouselMenu | Pause menu options (continue, autoplay, restart, quit) ] [ lastStart | boolean | Start button state from the previous frame ] [/table] [heading: "Methods"] [table header] [ Method | Parameters | Description ] [ init | (song, difficultyIndex, playtestMode, autoplay, playlistKey) | Phaser state hook that clones the chart, initializes the gameplay objects and saves the last played song to the account. ] [ create | () | Phaser state hook that builds the HUD, applies chart modifiers and starts the asynchronous background and audio setup. ] [ initialSetup | () | Preloads all chart backgrounds, sets up the audio and starts the song. ] [ applyChartModifiers | () | Applies the enabled chart modifiers (mines, freezes, jumps, mirror, randomize) to a working copy of the current difficulty's notes. ] [ setupAudio | () | Creates and loads the audio element, then builds the audio visualizer. ] [ preloadBackground | (background) | Loads a single background image or video element for later drawing. ] [ createHud | () | Builds the heads-up display with lifebar, score, combo, accuracy and text. ] [ createVisualizer | (visualizerX, visualizerY, visualizerWidth, visualizerHeight) | Recreates the visualizer matching the current setting, or removes it. ] [ setupSongTemperature | () | Wires the audio temperature meter to the HUD flash effects. ] [ setupPlayer | () | Instantiates the center-lane Player used for gameplay. ] [ setupLyrics | () | Creates the lyrics text element and controller when a lyrics file exists. ] [ setInitialBackground | () | Sets the initial chart background or clears it when none is present. ] [ songStart | () | Begins playback: shows the song info, schedules the audio start and HUD reveal. ] [ checkModifiersScreenButton | () | Opens the Chart Modifiers state while the start button is held at kickoff. ] [ showSongInfo | () | Animates an intro banner with the song's title, subtitle, artist and credit. ] [ startHudFlash | () | Starts the pulsing HUD flash effect synced to the song's beat. ] [ stopHudFlash | () | Stops the HUD flash effect and fades the flash shape away. ] [ showHud | (duration, backgroundAlpha, receptorsAlpha) | Slides the HUD panels, background and receptors into view. ] [ hideHud | (duration, backgroundAlpha, receptorsAlpha) | Slides the HUD panels and background out of view. ] [ showCharacterCloseShot | (duration) | Plays the character close shot sequence with a countdown timer. ] [ showGlitchAnimation | (duration) | Plays a full-screen glitch animation layered over the HUD. ] [ showFullCombo | () | Plays the full combo (or flawless) celebration overlay when reached. ] [ drawBackground | (element) | Draws a background element onto the background canvas, handling errors. ] [ drawFallbackBackground | () | Draws the default chart background as a fallback when one fails to load. ] [ clearBackground | () | Clears the background canvas to black and reveals the gradient overlay. ] [ loadBackgroundImage | (filename, url) | Loads or reuses a background image and draws it onto the canvas. ] [ loadBackgroundVideo | (filename, url, onloadCallback, onerrorCallback) | Loads or reuses a background video and begins playback. ] [ playVideo | (video) | Starts playback of the given video and hides the gradient overlay. ] [ applyBackground | (bg) | Applies a chart background at its scheduled beat, honoring fade options. ] [ applyBgEffects | (bg) | Handles fade-in, scheduled fade-out and opacity for a background. ] [ applyBgEffect | (bg) | Applies the StepMania-style background effect loop (stretch, scroll or pulse). ] [ handlePreviousBgFadeOut | () | Fades out the previous background when a fade-out was scheduled for it. ] [ getGameResults | (player) | Collects the game results from a player into a plain result object. ] [ restartSong | () | Restarts the current song with the same settings. ] [ songEnd | () | Finalizes the run: updates stats, experience and records, then opens Results. ] [ updateUserStats | (gameResults) | Accumulates the account statistics from the completed game. ] [ togglePause | () | Toggles between the paused and running states of the song. ] [ pause | () | Pauses gameplay and playback, then shows the pause menu. ] [ resume | () | Resumes gameplay and playback, then hides the pause menu. ] [ getStatsContent | () | Builds a text block listing the current judgement counts. ] [ showPauseMenu | () | Shows the pause menu with continue, autoplay, restart, retry and quit options. ] [ hidePauseMenu | () | Removes the pause menu objects from the scene. ] [ getCurrentTime | () | Returns the current play time in seconds and beats, accounting for pauses. ] [ secToBeat | (sec) | Converts a time in seconds to beats using the player's timing. ] [ updateBackgrounds | () | Enqueues and applies chart backgrounds as their beats arrive, then updates video. ] [ updateVideo | () | Redraws the current video frame at the configured frame rate. ] [ update | () | Phaser lifecycle hook called every frame; drives the main gameplay loop. ] [ render | () | Phaser render hook that renders the player's note objects. ] [ shutdown | () | Phaser lifecycle hook called when leaving the state; tears down playback. ] [/table] [heading: "Example Usage (Modding)"] [codeblock javascript] // Start a normal playthrough for a song and difficulty game.state.start("Play", true, false, { chart: song, difficultyIndex: 2 }); // Launch in playtest mode with autoplay from the editor game.state.start("Play", true, false, song, 0, true, true); [/codeblock] [footer: "© Retora 2026"]