This website provides detailed information about all core classes in PadManiacs. Use this reference when creating addons to understand available APIs and modification points.
[heading: "Introduction"]PadManiacs is a lightweight rhythm game that brings the StepMania experience to web and mobile devices with a retro pixel art aesthetic. The game features core rhythm gameplay mechanics of StepMania, a popular open source rhythm game.
PadManiacs supports community-created modifications through an add-on system. Add-ons can:
[list] * Replace game assets (arrows, backgrounds, UI elements) * Add new behaviors and gameplay mechanics * Extend the game with new features [/list] [heading: "How addons work"]An addon is a folder that contains data that the game loads at startup, overwriting the assets and default game behavior.
In order for an addon to be considered valid, it must include the [code: "manifest.json"] file, a file that defines metadata, which parts of the game must be modified or extended, as well as the data and the code that must be loaded.
Add-ons are stored at a subfolder [code: "Addons/"] under local storage folder. All Addons you develop must be inside this folder so you can test them in the game.
You can download working sample add-ons to load in the game from itch.io.
[heading: "Tutorials"]Learn how to create and modify PadManiaX with these step-by-step tutorials.
[list] * Getting Started with Modding - Learn the basics of creating your first addon * Understanding the Manifest Format - Complete guide to manifest.json structure * Asset Replacement Tutorial - How to replace game graphics and sounds * Creating Behavior Scripts - Adding custom gameplay logic * UI Modification Guide - Customizing menus and interfaces * Character System Guide - Understanding characters, skills, and leveling * Achievements System Guide - Working with achievements and stats [/list] [heading: "Global Scope"]The following global variables and constants are available throughout the game and can be used in addons:
[subheading: "Constants"] [table header] [ Name | Type | Value | Description ] [ COPYRIGHT | string | "(C) RETORA 2026" | Copyright notice ] [ VERSION | string | "v0.9.0" | Current game version ] [ window.DEBUG | boolean | false | Global debug flag, can be enabled for development ] [ FONTS | object | {...} | Predefined font configurations for text rendering ] [ DEFAULT_SONG_FOLDERS | array | 16 songs | Default built-in song folders ] [ WINDOW_PANELS | array | ["1"] | Available UI window panels ] [ JUDGE_WINDOWS | object | {marvelous:55, perfect:75, great:99, good:140, boo:180} | Delta limits in milliseconds for different judgments ] [ SCORE_VALUES | object | {...} | Score values for different judgments ] [ COMMUNITY_HOMEPAGE_URL | string | https://retora.itch.io/padmaniacs/community | Community website home page URL ] [ FEEDBACK_REVIEW_URL | string | https://retora.itch.io/padmaniacs/rate | Rating survey URL ] [ FEEDBACK_FEATURE_REQUEST_URL | string | https://itch.io/t/5585472/feature-requests | Feature requests forum URL ] [ FEEDBACK_BUG_REPORT_URL | string | https://itch.io/t/5585499/bug-reports | Bug reports forum URL ] [ COMMUNITY_PROMPT_MIN_PLAYTIME | number | 3600 | Seconds to wait before displaying start-up community popup prompt ] [ RATING_PROMPT_MIN_PLAYTIME | number | 900 | Seconds to wait before displaying feedback dialog ] [ FEATURE_REQUEST_MIN_PLAYTIME | number | 1800 | Seconds to wait before displaying feature request dialog ] [ CHARACTER_SYSTEM | object | {...} | Character system constants (max level, name length, etc.) ] [ CHARACTER_SKILLS | array | 50+ skills | Skill definitions for characters ] [ CHARACTER_ITEMS | object | {...} | Clothing and accessory definitions ] [ ACHIEVEMENTS | object | {...} | Achievements system constants ] [ ACHIEVEMENT_CATEGORIES | object | {...} | Achievement categories (Gameplay, Character, Progression, etc.) ] [ ACHIEVEMENT_DEFINITIONS | array | 150+ achievements | Achievement definitions ] [ KEYBOARD_KEY_NAMES | object | {...} | Keyboard key name map for UI ] [ GAMEPAD_KEY_NAMES | object | {...} | Gamepad key name map for UI ] [ DEFAULT_KEYBOARD_MAPPING | object | {...} | Default key mappings for keyboard controls ] [ DEFAULT_GAMEPAD_MAPPING | object | {...} | Default key mappings for gamepad controls ] [ ENVIRONMENT | object | {...} | Environment type definitions (UNKNOWN, NWJS, CORDOVA, WEB) ] [ CURRENT_ENVIRONMENT | string | (platform-specific) | Current runtime environment ] [ CORDOVA_EXTERNAL_DIRECTORY | string | "PadManiacs/" | External directory path for Cordova ] [ NWJS_EXTERNAL_DIRECTORY | string | "data/" | External directory path for NW.js ] [ EXTERNAL_DIRECTORY | string | (environment-specific) | Current external directory path ] [ ADDONS_DIRECTORY | string | "Addons" | Addons directory name ] [ SCREENSHOTS_DIRECTORY | string | "Screenshots" | Screenshots directory name ] [ SONGS_DIRECTORY | string | "Songs" | Songs directory name ] [ EDITOR_OUTPUT_DIRECTORY | string | "Edits" | Editor output directory name ] [ ENABLE_PARALLEL_LOADING | boolean | true | Enable parallel asset loading ] [ MAX_PARALLEL_DOWNLOADS | number | 128 | Maximum parallel downloads ] [ MAX_PARALLEL_ADDON_LOADS | number | 3 | Maximum parallel addon loads ] [ ENABLE_ADDON_SAFE_MODE | boolean | true | Enable addon safe mode for error protection ] [ ENABLE_UI_SFX | boolean | false | Enable UI sound effects ] [ ENABLE_EXP_SFX | boolean | true | Enable experience sound effects ] [ REGULAR_VIBRATION_INTENSITY | number | 75 | Vibration duration in MS for regular hits ] [ WEAK_VIBRATION_INTENSITY | number | 50 | Vibration duration in MS for weak hits ] [ STRONG_VIBRATION_INTENSITY | number | 50 | Vibration duration in MS for strong hits ] [ DEFAULT_ACCOUNT | object | {...} | Default settings and user data including characters and achievements ] [/table] [subheading: "Global Variables"] [table header] [ Name | Type | Description ] [ game | Phaser.Game | Main Phaser game instance ] [ gamepad | Gamepad | Unified input system instance ] [ backgroundMusic | BackgroundMusic | Background music controller ] [ notifications | NotificationSystem | Global notification system instance ] [ addonManager | AddonManager | Addon management system ] [ achievementsManager | AchievementsManager | Achievements system instance ] [ Account | Object | User data with settings, characters, achievements, and progress ] [ Audio | Object | Audio pool for Phaser Audio objects ] [/table] [subheading: "Global Functions"] [table header] [ Name | Parameters | Description ] [ saveAccount | () | Saves account data to localStorage ] [ bootGame | () | Initializes and starts the Phaser game ] [ addFpsText | () | Adds an FPS counter ] [ openExternalUrl | (url) | Opens URL in default browser ] [/table] [heading: "API"]PadManiaX was built using Phaser CE, with Cordova for mobile file access and NW.js for desktop builds. See the documentation: Cordova Docs, NW.js Docs, and Phaser CE Docs.
The game code is divided into different classes. All classes are accessible in the scope of addon file. Each of them plays a role, some more important than others. For example game screens visual or abstract elements, data managers, etc.
[subheading: "Game States"] [table header] [ Name | Description ] [ Boot | Load critical assets, initialize input system, then start loading the game ] [ Load | Dynamic asset loading with progress tracking ] [ LoadCordova | Initialize Cordova on mobile devices, initialize file system ] [ LoadAddons | Initializes the addon manager and loads addon resources ] [ LoadLocalSongs | Loads built-in default songs ] [ LoadExternalSongs | Loads user-added songs from external storage ] [ LoadSongFolder | Loads a single song via file input ] [ Title | Title Screen with animated logo ] [ MainMenu | Main Menu screen with navigation to all features ] [ CharacterSelect | Character selection, creation, and customization ] [ SongSelect | Song selection with previews and difficulty selection ] [ Play | Main gameplay state ] [ Results | Displays gameplay results and high scores ] [ Settings | Settings user interface ] [ Keybindings | Gamepad and keyboard keybindings UI ] [ Addons | Addon Manager user interface ] [ AchievementsMenu | Achievements viewing interface ] [ StatsMenu | Player statistics display ] [ Editor | Chart editing mode ] [ Jukebox | Music player mode with visualizers ] [ Credits | Credits screen ] [ ErrorScreen | Error display screen shown when game crashes ] [/table] [subheading: "Core Game Classes"] [table header] [ Name | Description ] [ Player | Handles all gameplay logic including note processing and scoring ] [ ChartRenderer | Renders notes, receptors, and chart elements ] [ Gamepad | Unified input system for keyboard, touchscreen, and gamepad ] [ Metronome | Audio metronome system for timing assistance ] [ OffsetAssistant | Audio-video synchronization calibration tool ] [ ScreenRecorder | Video recording and screenshot functionality ] [ Visualizer | Base class for gameplay visualizers ] [ AccuracyVisualizer | Displays timing accuracy history graph ] [ AudioVisualizer | Shows audio frequency spectrum ] [ BPMVisualizer | Displays BPM changes and beat timing ] [ FullScreenAudioVisualizer | Advanced audio visualization for Jukebox ] [ Lyrics | LRC lyrics synchronization system with color support ] [ BackgroundMusic | Manages background music playback with caching ] [/table] [subheading: "UI Classes"] [table header] [ Name | Description ] [ Text | Retro pixel text with typewriter and scrolling effects ] [ Window | Customizable UI window with menu items and scrollbar ] [ WindowManager | Manages UI windows, focus, and navigation ] [ CarouselMenu | Vertical scrolling menu with animations and scrollbar ] [ DialogWindow | Modal dialog windows for confirmations ] [ TextInput | Text input dialog for character naming ] [ ValueInput | Numeric value input dialog ] [ NotificationSystem | Global notification manager with achievement/exp support ] [ NavigationHint | Displays input prompts in menus (0-7 frames) ] [ ProgressText | Progress text for loading screens ] [ LoadingDots | Animated loading indicator ] [ BackgroundGradient | Animated gradient background ] [ FuturisticLines | Animated futuristic line effects ] [ Logo | Animated logo for title screen ] [ ExperienceBar | Visual experience progress bar ] [ SkillBar | Visual skill level indicator (1-5 segments) ] [ Background | Generic background sprite with alpha tween ] [ CanvasBackground | Canvas-based background rendering for dynamic content ] [/table] [subheading: "Character System Classes"] [table header] [ Name | Description ] [ Character | Character data model with leveling and experience ] [ CharacterManager | Manages multiple characters and persistence ] [ CharacterDisplay | Visual character sprite with layered rendering ] [ CharacterCroppedDisplay | Character display with cropping support ] [ CharacterPortrait | Cropped character portrait display (15x15) ] [ CharacterCloseShot | Close-up character display for skill effects (36x7) ] [ CharacterSkillSystem | Skill activation and effect management ] [/table] [subheading: "Achievements and Stats Classes"] [table header] [ Name | Description ] [ AchievementsManager | Achievement tracking, unlocking, and stats management ] [/table] [subheading: "File System Classes"] [table header] [ Name | Description ] [ FileSystemTools | Platform-agnostic file system access wrapper ] [ CordovaFileSystem | File system for Apache Cordova mobile apps ] [ NodeFileSystem | File system for NW.js desktop apps ] [ FallbackFileSystem | Stub for web environments without file access ] [ NodeDirectoryEntry | Cordova DirectoryEntry equivalent for Node.js ] [ NodeFileEntry | Cordova FileEntry equivalent for Node.js ] [ FileTools | File utilities for Base64 conversion and export ] [/table] [subheading: "Parser Classes"] [table header] [ Name | Description ] [ LocalSMParser | Parses StepMania .SM files for built-in songs ] [ ExternalSMParser | Parses .SM and .SSC files for external songs ] [ SMFile | StepMania file generation for chart export ] [/table] [subheading: "Addon System Classes"] [table header] [ Name | Description ] [ AddonManager | Manages addon loading, execution, hibernation, and safe mode ] [/table] [footer: "© Retora 2026"]