Mod templates

Five starter mods covering the common patterns. Copy any of them and edit.

The templates ship under Mods/Mod Template/ in the Mod Loader repo. Each is a self-contained, working mod - copy it into BLACK SOULS II/Mods/<new_name>/ to use, or read it as a reference.

01 - Simple Ruby

The minimum viable mod: alias a vanilla method, call the original, add behavior.

What it does: awards 5 souls per step on the map by hooking Game_Player#increase_steps.

class Game_Player
  alias_method :_my_orig_increase_steps, :increase_steps
  def increase_steps
    _my_orig_increase_steps
    if $game_party
      $game_party.gain_gold(5) rescue nil
    end
  end
end

ModLoader.log("[01_simple_ruby] hooked Game_Player#increase_steps") rescue nil

When to use this pattern: any time you want to add behavior to an existing game class without breaking what's already there.

02 - Asset override

A pure asset mod - no Ruby logic, just files in assets/.

Mods/<your_mod>/
├── main.rb                    can be empty (or just an info log)
└── assets/
    ├── Graphics/
    │   └── Faces/Alice.png    replaces the original
    └── Audio/
        └── BGM/title.ogg      replaces the original

See the Asset overrides page for the full list of supported folders.

03 - Data tweak

Mutate the database arrays at runtime. The change applies for the rest of the session and goes away when the game closes - no save corruption.

What it does: makes every consumable cost 1 soul and heal full HP.

($data_items || []).each do |item|
  next unless item && item.id != 0
  next unless item.itype_id == 1   # 1 = Regular item, 2 = Key item
  item.price = 1
  item.effects = [RPG::UsableItem::Effect.new(11, 0, 1.0, 0)]
end

ModLoader.log("[03_data_tweak] juiced consumables") rescue nil

When to use this pattern: balance changes, stat overhauls, removing restrictions, debug cheats. Anything where you want a numeric or behavior tweak that applies for the play session.

04 - Custom scene

Add a brand-new in-game screen with its own command window. The template binds it to F3 on the map.

class Window_HelloHello < Window_Command
  def window_width;  280 end
  def make_command_list
    add_command("Hello, mod world", :hello)
    add_command("Close",            :cancel)
  end
end

class Scene_HelloHello < Scene_MenuBase
  def start
    super
    @window = Window_HelloHello.new
    @window.x = (Graphics.width  - @window.width)  / 2
    @window.y = (Graphics.height - @window.height) / 2
    @window.set_handler(:hello,  method(:on_hello))
    @window.set_handler(:cancel, method(:return_scene))
    @window.activate
    @window.select(0)
  end

  def on_hello
    ModLoader.log("[04_custom_scene] hello pressed") rescue nil
    @window.activate
  end
end

When to use this pattern: any standalone tool that needs its own UI - stat editors, item spawners, debug menus. The bundled creative_mode mod is a large-scale example of this pattern.

05 - Scene hook

Hook into an existing scene's lifecycle (start / update / terminate) to add overlays, intercept input, or react to scene transitions.

What it does: draws the player's coordinates and current map ID in the top-left corner of the map.

class Scene_Map
  alias_method :_my_orig_start,    :start
  alias_method :_my_orig_update,   :update
  alias_method :_my_orig_terminate, :terminate

  def start
    _my_orig_start
    create_coord_overlay
  end

  def update
    _my_orig_update
    refresh_coord_overlay
  end

  def terminate
    _my_orig_terminate
    if @_my_coord_sprite
      @_my_coord_sprite.bitmap.dispose if @_my_coord_sprite.bitmap
      @_my_coord_sprite.dispose
      @_my_coord_sprite = nil
    end
  end

  def create_coord_overlay
    @_my_coord_sprite = Sprite.new
    @_my_coord_sprite.bitmap = Bitmap.new(220, 28)
    @_my_coord_sprite.bitmap.font.size = 18
    @_my_coord_sprite.x = 8; @_my_coord_sprite.y = 8; @_my_coord_sprite.z = 9999
  end

  def refresh_coord_overlay
    return unless @_my_coord_sprite && @_my_coord_sprite.bitmap && $game_player
    bmp = @_my_coord_sprite.bitmap
    bmp.clear
    bmp.draw_text(0, 0, bmp.width, bmp.height,
      "Map #{$game_map.map_id}  (#{$game_player.x},#{$game_player.y})")
  end
end

When to use this pattern: HUDs, debug overlays, custom hotkeys, anything that needs to react to per-frame scene activity. Always include the terminate hook to dispose of any Sprites/Bitmaps you allocated, otherwise they leak on every scene transition.

The full reference example

For a much larger working mod combining many of these patterns, see Mods/creative_mode/main.rb in the source repo. It builds an F2 admin menu with stat editors, item / skill pickers, teleport, toggles (god mode, no-clip, infinite souls, etc.), all using the patterns above.