Handlers y puntos de extensión
Un handler registra una función para que un sistema existente la invoque en un momento concreto. Para personalizar un juego, suele ser más seguro que reemplazar un método del motor.
Handlers existentes y nuevos
Antes de crear uno, busca si ya existe un handler que cubra el momento que necesitas. Los sistemas de handlers disponibles están implementados en los scripts del motor; registra tus callbacks desde un plugin propio.
También puedes definir un handler propio para organizar código de un plugin. Pero un registro nuevo solo almacena callbacks: no se ejecutará hasta que tu código lo invoque. Para que varios plugins o makers puedan usarlo de forma general, el motor necesita un punto de llamada estable; eso implica proponer una extensión de la base, no solo declarar un HandlerHash nuevo.
EventHandlers
Los eventos globales permiten reaccionar a momentos del juego, como nueva partida, carga, cambio de mapa, pasos del jugador o inicio y fin de combate. La lista y el momento exacto de cada evento están en Data/Scripts/009_Game processing/006_Event_Handlers.rb.
EventHandlers.add(:on_new_game, :MIPREFIJO_mi_plugin, proc {
MiPlugin.al_iniciar_partida
})Usa una clave única por evento. En bloques proc, usa next para salir del bloque, no return.
MenuHandlers y PageHandlers
MenuHandlers permite registrar comandos en menús que ya consultan este sistema; PageHandlers registra páginas para pantallas que ya soportan pestañas. La existencia de un handler no significa que cualquier menú o pantalla lo consuma: revisa los registros y llamadas de la pantalla objetivo.
Para opciones configurables, consulta también Opciones por páginas. Para páginas de resumen o Pokédex, consulta MUI.
Handlers de objetos
La base ofrece varios contextos de uso. Entre ellos: UseFromBag, UseInField, UseOnPokemon, CanUseInBattle y UseInBattle. Están definidos en Data/Scripts/041_Items/002_Item_Utilities.rb; hay handlers adicionales para objetos de batalla en Data/Scripts/034_Other battle code/010_Battle_ItemEffects.rb.
ItemHandlers::UseInField.add(:MI_OBJETO, proc { |item|
next MiPlugin.usar_en_campo(item)
})El contexto determina los argumentos y el valor de retorno; comprueba el handler correspondiente y un ejemplo vecino antes de registrar el tuyo.
Handlers de habilidades en combate
Battle::AbilityEffects agrupa triggers para cálculos de estadísticas, inmunidades, cambios de estado, entrada/salida del campo, efectos de fin de ronda y otros momentos. La lista está en Data/Scripts/034_Other battle code/009_Battle_AbilityEffects.rb.
Elige el trigger según el momento exacto del efecto. Sus argumentos, valor de retorno y reglas de ignorabilidad dependen del trigger; consulta su método trigger... y los registros de habilidades similares. No copies una firma de otro trigger sin verificarla.
UIHandlers (MUI)
UIHandlers permite registrar opciones/páginas modulares de las pantallas que usan MUI. Se implementa en Data/Scripts/069_MUI/002_MUI Modular UI Scenes/002_UI Module.rb. Para detalles sobre páginas y personalización, consulta MUI - Interfaz Modular.
Si no existe un punto de extensión
Si un cambio necesita modificar un método, revisa primero sus llamadores y otros parches. Usa alias_method con un nombre exclusivo para tu plugin y conserva el original cuando sea posible. El nombre de alias debe ser único dentro de la clase o módulo parcheado, incluso si el otro plugin pretendía aliasar otro método. Si se repite, un plugin puede reemplazar el destino del alias de otro y causar recursión o saltarse parte del parche.
Guía paso a paso: Crear un plugin.