[title: "Getting Started with Modding"] ← Back to index

Learn how to create your first PadManiaX addon from scratch.

[heading: "Prerequisites"]

Before you begin modding PadManiaX, you should have:

[list] * Basic understanding of JavaScript * Text editor or code editor * PadManiaX installed on your device * File manager app (for mobile development) [/list] [heading: "Development Tools"] [subheading: "Mobile Development with Acode"]

If you're developing on mobile, we recommend using Acode - a powerful mobile code editor.

[subheading: "Desktop Development"]

For desktop development, any code editor works: Visual Studio Code (recommended), Sublime Text, or Atom.

[heading: "Your First Addon"] [subheading: "Step 1: Create Addon Directory"]

Navigate to your PadManiaX data directory and create a new folder in the "Addons" folder:

[list] * Path on desktop: [code: "[Game Folder]/data/Addons/MyFirstAddon/"] * Path on mobile: [code: "/storage/emulated/0/PadManiacs/Addons/MyFirstAddon/"] [/list] [subheading: "Step 2: Create Manifest File"]

Create a manifest.json file with basic information:

[codeblock json] { "id": "my-first-addon", "name": "My First Addon", "version": "1.0.0", "author": "Your Name", "description": "My very first PadManiaX addon!" } [/codeblock] [subheading: "Step 3: Test Your Addon"]

Launch PadManiaX and check if your addon appears in the Addon Manager:

[list] * Go to Main Menu → Extras → Addon Manager * Your addon should appear in the list * Enable it if it's disabled [/list] [heading: "Understanding the Basics"] [subheading: "Addon Structure"] [codeblock] MyFirstAddon/ ├── manifest.json # Required: Addon metadata ├── icon.png # Optional: Addon icon ├── assets/ # Optional: Game assets to replace └── behaviors/ # Optional: JavaScript code files ├── global.js # Runs when addon loads └── menu.js # Runs in MainMenu state [/codeblock] [subheading: "Required JavaScript Knowledge"]

You'll need basic JavaScript knowledge for modding:

[list] * Variables and functions * Objects and arrays * Event handling * Basic DOM manipulation (for web concepts) [/list]

Recommended JavaScript learning resources:

[list] * MDN JavaScript Guide * The Modern JavaScript Tutorial * W3Schools JavaScript Tutorial [/list] [heading: "Development Tips"] [subheading: "Enable Debug Console"]

PadManiaX has a hidden developer console using Eruda. To enable it:

[codeblock js] // Add this in any file of your addon eruda.init(); [/codeblock]

Eruda is a mobile web debugger that provides console, elements inspection, and network monitoring. Learn more about Eruda.

[subheading: "Restart the Game"]

You can restart the game programmatically:

[codeblock js] bootGame(); // Restarts the entire game [/codeblock] [heading: "Examples"] [subheading: "Hello World"] [codeblock js] eruda.init(); // To initialize the console this.helloWorldText = new Text(2, 2, "Hello World"); console.log("Hello World"); [/codeblock] [subheading: "Simple Character Mod"] [codeblock js] // behaviors/global.js console.log("My character mod loaded!"); // Add a custom skill CHARACTER_SKILLS.push({ id: "mod_skill", name: "Modder's Touch", description: "A custom skill from an addon", activationCondition: "on_combo", effect: "modify_score_gain", effectParams: { multiplier: 1.2, judgement: "marvelous", threshold: 50 }, duration: 10000, cooldown: 45000 }); // Add a custom achievement ACHIEVEMENT_DEFINITIONS.push({ id: "mod_achievement", name: "Mod User", category: ACHIEVEMENT_CATEGORIES.MISC, description: { unachieved: "Use a modded skill", achieved: "You used a modded skill!" }, expReward: ACHIEVEMENTS.EXPERIENCE_VALUES.COMMON, condition: (stats, lastSong) => lastSong.skillsUsed > 0, hidden: false }); [/codeblock]

You can download working sample add-ons to load in the game from itch.io.

[heading: "Next Steps"]

Now that you've created your first addon, check out these tutorials:

[list] * Understanding the Manifest Format * Asset Replacement Tutorial * Creating Behavior Scripts [/list] [footer: "© Retora 2026"]