Getting Started with Modding

This guide will help you create your first mod for Remixed Dungeon. We'll start with simple modifications and work up to more complex ones.

Before starting, make sure you have:

• A copy of Remixed Dungeon installed
• A text editor or IDE for editing files
• Basic understanding of JSON format
• Basic understanding of file organization

• Navigate to your game's files directory: Android/data/com.nyrds.pixeldungeon.ml/files/ (on Android)
• Create a new folder for your mod (e.g., “MyFirstMod”)

• Inside your mod folder, create a version.json file
• Add this basic content to the file:

    {
      "version": 1,
      "name": "My First Mod"
    }
 

• Download a simple image (e.g., a PNG file) that could replace an item sprite
• In your mod folder, create the directory structure to match the original game: items/weapon/
• Place your image file in this directory with the same name as the original sprite you want to replace (e.g., dagger.png to replace the dagger sprite)

• Launch Remixed Dungeon
• Go to the Mods menu and enable your mod
• Start a new game to see your changes

• Locate the JSON configuration for the item you want to modify in the game's assets
• For example, weapon properties might be in items/weapon/ in files like short_sword.json

• Copy the JSON file to your mod folder in the same directory structure
• Modify the properties you want to change (e.g., damage, level requirements)

Example modification:

{
  "class": "com.watabou.pixeldungeon.items.weapon.melee.ShortSword",
  "name:en": "Modified Short Sword",
  "name:ru": "Модифицированный короткий меч",
  "damageMin": 3,  // Original value might be 4
  "damageMax": 8,  // Original value might be 8
  "ac": "ATTACK",
  "imageIndex": 0
}

• Make sure your mod is enabled
• Start a new game to see the modified item properties

The game's assets follow a specific organization:

• actors/ - Mobs, NPCs, and other entities
  • actors/mobs/ - Monster definitions
  • actors/buffs/ - Status effects
• items/ - All items in the game
  • items/weapon/ - Weapons
  • items/armor/ - Armor
  • items/rings/ - Rings
  • items/potions/ - Potions
  • items/scrolls/ - Scrolls
• levelsDesc/ - Level definitions and dungeon structure
• res/ - Text strings and localization
  • res/values/ - English texts
  • res/values-ru/ - Russian texts
• sounds/ - Sound effects
• music/ - Background music
• sprites/ - Game graphics

To modify in-game text, create a res/values/strings.json file in your mod:

{
  "DungeonTitle": "My Custom Dungeon",
  "WelcomeMsg": "Welcome to my modded version!"
}

To change a mob's properties, copy the mob's JSON file to your mod:

{
  "class": "com.watabou.pixeldungeon.actors.mobs.Rat",
  "name:en": "Giant Rat",
  "HP": 15,           // Higher HP
  "damageMin": 3,     // Higher damage
  "damageMax": 6,     // Higher damage
  "exp": 3,          // More experience
  "loot": "gold",    // Additional loot
  "lootChance": 0.5  // Higher chance for loot
}

For more complex modifications, you can use Lua scripts. The correct approach uses specialized libraries:

Example: items/custom_item.lua

local RPD = require "scripts/lib/commonClasses"
local item = require "scripts/lib/item"
 
return item.init{
    desc = function()
        return {
            image         = 0,
            imageFile     = "items.png",
            name          = "Explosive Item",
            info          = "An explosive item that damages enemies when thrown.",
            stackable     = true,
            upgradable    = false,
            isFlies       = true,
            defaultAction = "THROW"
        }
    end,
 
    onThrow = function(self, cell, user)
        -- Custom behavior when item is thrown
        RPD.glog("Custom item thrown at " .. cell.x .. ", " .. cell.y)
        -- Add explosion effect
        -- Blast functionality would need to be implemented using specific game mechanics
        RPD.topEffect(RPD.Dungeon.level():cell(cell.x, cell.y), "blast")
    end
}

Reference the script in your item's JSON using the correct format:

{
  "class": "com.watabou.pixeldungeon.items.Item",
  "name:en": "Explosive Item"
}

Note: Modern Remixed Dungeon uses the library-based approach that's defined entirely in the Lua file rather than through JSON script references.

• Mod not loading: Check that your version.json file exists and is properly formatted
• Changes not showing: Make sure the file paths exactly match the original game structure
• JSON errors: Use a JSON validator to check for syntax errors
• Game crashes: Check for missing or incorrectly formatted properties

• Start with simple changes before moving to complex modifications
• Use the game's existing files as examples
• Test frequently to isolate problems
• Keep backups of working configurations

When your mod is complete and tested:

• Package all your mod files in a ZIP archive
• Include clear instructions and documentation
• Test on multiple devices if possible
• Share on the Remixed Dungeon Discord server
• Consider uploading to mod distribution platforms

Once you're comfortable with basic modding:

• Explore more complex JSON configurations
• Learn Lua scripting for dynamic behavior
• Create custom levels using Tiled
• Join the modding community for tips and feedback
• Look at existing mods like Maze to understand advanced techniques

Remember to always backup your save files before testing new mods!