Chart editing mode
[heading: "Description"]The Editor state is the in-game chart editor where players author and edit songs, from metadata and media files to the notes themselves. It offers a gamepad and mouse driven editing canvas with note placement, selection, area selection, freezes, mines, BPM changes, stops and background changes. Charts can be imported from StepMania packages or exported as zip files.
[heading: "Key Features"] [list] * Full 4-panel chart editor with cursor and snap grid * Place, select, copy, mirror and delete notes * BPM, stop, and background change editing * Metadata editing, playtesting, and SM/zip import or export [/list] [heading: "Properties"] [table header] [ Property | Type | Description ] [ song | Object | The song object currently being edited. ] [ initializedWithSong | boolean | True when starting from a pre-existing song. ] [ currentScreen | string | Current editor screen ('metadata' or 'chartEdit'). ] [ currentDifficultyIndex | number | Index of the difficulty currently being edited. ] [ snapDivision | number | Snap division denominator (e.g. 8 = 1/8 beat). ] [ cursorBeat | number | Cursor position measured in beats. ] [ cursorColumn | number | Cursor column (0 to 3). ] [ selectedNotes | Array | Notes currently selected in the chart. ] [ clipboard | Array | Notes stored for copy and paste operations. ] [ files | Object | Loaded media files keyed by purpose (audio, background, ...). ] [ fileInput | HTMLInputElement | Hidden input element used for picking files. ] [ backgroundLayer | Phaser.Group | Layer containing background visual elements. ] [ backgroundSprite | CanvasBackground | Canvas-drawn background image sprite. ] [ chartRenderer | ChartRenderer | Renders the chart and manages note visuals. ] [ metronome | Metronome | Metronome helper for note timing feedback. ] [ audio | HTMLAudioElement | Audio element used for playback and previews. ] [/table] [heading: "Methods"] [table header] [ Method | Parameters | Description ] [ init | (song) | Initializes the editor with a song and resets all editing state. ] [ create | () | Builds the editor background, chart renderer, overlays, and info HUD. ] [ initalSetup | () | Loads song media into memory and sets up mouse events and the home screen. ] [ setupMouseEvents | () | Registers the editor mouse handlers on the global mouse object. ] [ createNewSong | () | Returns a fresh blank song object with default chart metadata and notes. ] [ showHomeScreen | () | Displays the main editor menu with file, edit, playtest, and export options. ] [ updateBanner | (url) | Draws the song banner image onto the banner sprite canvas. ] [ updateBackground | (url) | Draws the song background image onto the background sprite canvas. ] [ refreshLyrics | () | Re-parses the current LRC lyrics into a synchronizable Lyrics object. ] [ showFileMenu | () | Shows the file menu for loading audio, images, lyrics, and songs. ] [ pickFolder | (accept, onConfirm, onCancel) | Opens a directory picker and routes the chosen files to a callback. ] [ pickFile | (accept, onConfirm, onCancel) | Opens a single-file picker and routes the chosen file to a callback. ] [ showLoadingScreen | (text) | Overlays a full-screen loading mask with dots and progress text. ] [ hideLoadingScreen | () | Removes the full-screen loading overlay if one is present. ] [ loadSong | () | Opens a folder picker to import a song and increments the import stat. ] [ showEditMenu | () | Shows the edit menu with chart and metadata editing options. ] [ showExportMenu | () | Shows the project export menu, including StepMania song export. ] [ showChartsMenu | () | Lists the song's difficulties with options to edit or add each one. ] [ showChartOptions | (difficultyIndex) | Shows the per-difficulty options of edit, retype, rate, or delete. ] [ editChart | (difficultyIndex) | Enters chart editing mode for the given difficulty. ] [ playtest | () | Shows the playtest menu listing each difficulty to test. ] [ startPlaytest | (difficultyIndex) | Launches the Play state with the chosen chart for a test run. ] [ updateInfoText | () | Refreshes the HUD text with cursor, beat, BPM, and note information. ] [ getCurrentBgFileName | () | Returns the background file name that applies at the current cursor beat. ] [ updateCursorPosition | () | Redraws the cursor rectangle at the current column and judge line. ] [ updateSelectionRect | () | Redraws the selection rectangle for the active area selection. ] [ updateFreezePreview | () | Redraws the hold drag preview while the hold key is held. ] [ getDivisionSize | () | Returns the grid division size used for snapping. ] [ getSnappedBeat | (beat) | Snaps a beat value to the current grid division. ] [ getCurrentTime | () | Returns the current time and beat, from playback or the cursor position. ] [ handleChartEditInput | () | Processes gamepad input for editing: selecting, placing, and seeking. ] [ togglePlayback | () | Starts or stops chart playback depending on the current state. ] [ startPlayback | () | Begins playback from the cursor position and starts the audio. ] [ stopPlayback | () | Halts playback and snaps the cursor back to the played position. ] [ abortPreview | () | Cancels an active preview and removes its end handler. ] [ playPreview | (start, length) | Plays a short audio preview window from a start time. ] [ snapCursor | (beat) | Snaps the cursor beat to the nearest grid division. ] [ moveCursor | (deltaX, deltaBeat) | Moves the editing cursor by a column and beat delta, clamped to the grid. ] [ startSingleSelect | () | Clears any active area selection state. ] [ startAreaSelection | () | Begins an area selection anchored at the current cursor position. ] [ endAreaSelection | () | Finishes the selection rectangle and collects the notes inside it. ] [ toggleNoteSelection | () | Toggles selection of the note at the current cursor; clears when none. ] [ previewNote | (note) | Plays an audio preview for the given note and its duration. ] [ placeNote | (column, beat, replace, mine, quick) | Places a tap note at a column and beat, replacing an existing note when set. ] [ placeFreeze | (column, startBeat, duration, type, quick) | Places a hold or roll note spanning a beat duration. ] [ sortNotes | () | Sorts the current difficulty's notes by beat position. ] [ refreshMetronome | () | Re-synchronizes the metronome with the current chart notes. ] [ placeMine | (column, beat, replace, quick) | Places a mine note at the given column and beat. ] [ placeQuickHold | () | Places a quick one-beat hold at the cursor position. ] [ onMouseDown | (button, x, y) | Handles left-button selection and right-button placement drags. ] [ onMouseMove | (x, y) | Updates active selection rectangles and freeze drags while the mouse moves. ] [ onMouseUp | (button, x, y) | Completes selection or note placement when a mouse button is released. ] [ onMouseWheel | (direction) | Seeks the cursor in beat units when the mouse wheel is used. ] [ getNoteAt | (column, beat) | Returns the note at a given column and beat, if one exists. ] [ deleteNoteAt | (column, beat) | Deletes the note at a given column and beat, if one exists. ] [ getColumnAtPosition | (x) | Returns the note column under a given screen X position, or -1. ] [ getBeatAtPosition | (y) | Converts a screen Y position into a beat position on the chart. ] [ getYFromBeat | (targetBeat) | Converts a target beat into its screen Y position. ] [ changeSnapDivision | (direction) | Steps the snap division up or down through the supported denominators. ] [ getAudioOffset | () | Returns the user's audio offset in seconds. ] [ showContextMenu | () | Opens a contextual edit menu for the current selection or cursor position. ] [ copyNotes | (notes) | Stores notes into the clipboard for later pasting. ] [ pasteNotes | () | Pastes the clipboard notes relative to the current cursor beat. ] [ clearClipboard | () | Clears the copying clipboard. ] [ recordStoryEntry | () | Records an undo snapshot of the song and loaded files into the story. ] [ mirrorNotes | () | Mirrors the selected notes horizontally across the note columns. ] [ rearrangeNotes | () | Recalculates all note and timing sec values after BPM or stop changes. ] [ convertNoteType | (newType) | Converts the currently selected notes to a new note type. ] [ convertNotesType | (newType) | Converts all selected notes at once to the new note type. ] [ convertFreezeType | (newType) | Converts the selected freeze note to a different hold or roll type. ] [ convertFreezesType | (newType) | Converts all selected freezes to a different hold or roll type. ] [ alignToBeatDivision | () | Snaps the currently selected notes to the grid division. ] [ alignAllToBeatDivision | () | Snaps all notes in the current chart to the grid division. ] [ refreshSelectedNotes | () | Rebuilds the selected notes array and previews the resulting selection. ] [ deleteSelectedNotes | () | Removes all selected notes from the current chart. ] [ getCurrentChartNotes | () | Returns the note array for the currently edited difficulty. ] [ getSongInfoText | () | Builds the formatted song information summary shown on the home screen. ] [ handleFileSelect | (event) | Handles a file input selection event and forwards the first file. ] [ processFiles | (files) | Imports songs from a folder of files, supporting .sm charts and zips. ] [ loadAudioFile | (file) | Loads an audio file into the song and stores it as a blob. ] [ loadBackgroundFile | (file) | Loads a background image file into the song and stores it as a blob. ] [ loadBannerFile | (file) | Loads a banner image file into the song and stores it as a blob. ] [ loadLyricsFile | (file) | Loads a lyrics file into the song and stores it as a blob. ] [ importFromZip | (file) | Imports a .pmz/.zip package containing a StepMania song. ] [ importStepManiaSong | (zipContent) | Parses the .sm chart from a zip and loads all referenced media. ] [ importSMFile | (file) | Imports a standalone .sm chart file and loads its referenced media. ] [ exportSong | () | Exports the current song as a StepMania .sm package in a zip file. ] [ ensureFilesLoaded | () | Ensures audio, background, banner, and lyrics files are loaded. ] [ fetchFileAsBlob | (url) | Fetches a file at a URL as a Blob. ] [ addSongResourcesToZip | (songData, zip) | Adds the shared song media files to the export zip. ] [ addFileToZip | (zip, filename, data) | Adds a file with the given filename and data to the export zip. ] [ saveFile | (blob, filename) | Saves a blob to the device or downloads it as a file. ] [ saveFileToFilesystem | (blob, filename) | Writes a blob to the filesystem and returns the stored file. ] [ setDifficultyType | (difficultyIndex) | Sets the note type for a difficulty. ] [ setDifficultyRating | (difficultyIndex) | Sets the difficulty level rating for a difficulty. ] [ deleteDifficulty | (difficultyIndex) | Deletes a difficulty from the song chart. ] [ addNewDifficulty | () | Adds a new empty difficulty to the song chart. ] [ showMetadataEdit | () | Opens the metadata editing screen for the current song. ] [ editMetadataField | (field) | Edits a metadata field for the current song via text input. ] [ editSongBpm | () | Opens a text input to change the song BPM. ] [ editSongOffset | () | Opens a text input to change the song offset. ] [ editSampleStart | () | Opens a text input to change the sample start time. ] [ editSampleLength | () | Opens a text input to change the sample length. ] [ editBGChangeFiles | () | Opens file loaders for the currently selected background change. ] [ showBGChangeMenu | (bgIndex) | Opens the background change edit menu for a background entry. ] [ createNewSongAndReload | () | Resets the editor and returns to the home screen. ] [ saveAndExit | () | Saves the current song to the filesystem and leaves the editor. ] [ clearUI | () | Clears leftover editor UI elements and input listeners. ] [ calculateBPM | (beats) | Estimates the BPM from a series of tapped beat times. ] [ detectBPMHere | () | Opens a tap-to-the-beat mode to estimate the BPM at the cursor. ] [ addBPMChange | () | Adds a new BPM change at the current cursor beat. ] [ getBPMChange | () | Returns the BPM change at the current cursor beat, if any. ] [ editBPMChange | (target) | Edits the BPM value of a BPM change entry. ] [ removeBPMChange | () | Removes the BPM change located at the cursor beat. ] [ addStop | () | Adds a new stop duration at the current cursor beat. ] [ getStop | () | Returns the stop at the current cursor beat, if any. ] [ editStop | () | Edits the duration of the stop at the current cursor beat. ] [ removeStop | () | Removes the stop located at the cursor beat. ] [ addBGChange | () | Adds a background change at the cursor from a picked image or video file. ] [ addNoSongBgChange | () | Ensures a background change exists for songs that have no background entry. ] [ getBGChange | () | Returns the background change at the current cursor beat, if any. ] [ editBGChange | (target) | Replaces the media file of an existing background change. ] [ removeBGChange | () | Removes the background change located at the cursor beat. ] [ update | () | Renders the chart and handles per-screen editing input each frame. ] [ playExplosionEffect | (column) | Plays an explosion effect at a column when a mine is hit. ] [ showHitEffects | (now, beat) | Shows hit effects for notes reaching the judge line during playback. ] [ exitEditor | () | Leaves the editor and returns to the main menu. ] [ shutdown | () | Cleans up editor resources and stores the song for later access. ] [/table] [heading: "Example Usage (Modding)"] [codeblock javascript] // Modding usage example // Switch to the chart editor from another state game.state.start("Editor"); // Export or inspect the in-memory chart object const chart = window.editorSongData.chart; window.e.song.chart.difficulties.forEach(d => console.log(d.type, d.rating)); [/codeblock] [footer: "© Retora 2026"]