> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SkyFangames/La-Base-de-Sky/llms.txt
> Use this file to discover all available pages before exploring further.

# Luka's Scripting Utilities

> Conjunto completo de utilidades de scripting y extensiones para desarrollo avanzado en Pokémon Essentials

## Descripción

**Luka's Scripting Utilities** (LUTS) es una biblioteca completa de utilidades y extensiones para Ruby que facilita el desarrollo de scripts avanzados en Pokémon Essentials. Proporciona clases, módulos y extensiones que simplifican tareas comunes de programación.

<Note>
  **Versión:** 4.1.0\
  **Requisitos:** Pokémon Essentials v21.1\
  **Dependencia opcional:** Marin's Scripting Utilities v1.7\
  **Autor:** Luka S.J.\
  **Enlace:** [luka-sj.com/res/luts](https://luka-sj.com/res/luts)
</Note>

<Warning>
  **Importante:** Este plugin debe cargarse primero. Tiene configurado `First = True` y `Priority = 3` para asegurar que sus utilidades estén disponibles para otros plugins.
</Warning>

## Módulos Principales

### 1. Sistema de Animaciones (Animatable)

Permite animar propiedades de objetos de forma automática y fluida.

```ruby theme={null}
# Incluir el módulo en tu clase
class MiSprite < Sprite
  include LUTS::Concerns::Animatable
end

# Animar propiedades
sprite = MiSprite.new(viewport)
sprite.animate(x: 200, y: 150, opacity: 255)

# Durante el update
sprite.play_target_animation(duration) # duration en frames

# Verificar si está animando
if sprite.animating?
  puts "Animación en curso"
end

# Limpiar animaciones
sprite.clear_anim_target
```

#### Ejemplo Práctico: Fade In/Out

```ruby theme={null}
class FadeSprite < Sprite
  include LUTS::Concerns::Animatable
  
  def fade_in(duration = 30)
    self.opacity = 0
    animate(opacity: 255)
    duration.times do
      play_target_animation(duration)
      Graphics.update
    end
  end
  
  def fade_out(duration = 30)
    animate(opacity: 0)
    duration.times do
      play_target_animation(duration)
      Graphics.update
    end
  end
end
```

### 2. Sprites Extendidos

Clase base mejorada para sprites con funcionalidades adicionales.

```ruby theme={null}
# Crear sprite con bloque de configuración
sprite = Sprites::Base.new(viewport) do |s|
  s.x = 100
  s.y = 100
  s.bitmap = Bitmap.new(50, 50)
end

# Propiedades adicionales
sprite.direction  # Dirección del sprite
sprite.speed      # Velocidad de movimiento
sprite.toggle     # Toggle para animaciones
sprite.param      # Parámetro personalizado
sprite.finished   # Flag de finalización
```

#### Métodos de Dimensiones

```ruby theme={null}
# Ancho y alto del sprite
sprite.width = 100
sprite.height = 50

# Zoom uniforme
sprite.zoom = 2.0  # Aplica a zoom_x y zoom_y

# Obtener centro
center_x, center_y = sprite.center

# Centrar sprite
sprite.center!        # Centra el origen
sprite.center!(snap: true)  # Centra en el viewport

# Anclar al fondo
sprite.bottom!

# Anclar en cualquier posición
sprite.anchor(:middle)
sprite.anchor(:top_left)
sprite.anchor(:bottom_right)
```

#### Manipulación de Bitmaps

```ruby theme={null}
# Crear rectángulo de color
sprite.create_rect(100, 50, Color.new(255, 0, 0))

# Llenar pantalla con color
sprite.full_rect(Color.new(0, 0, 0, 128))

# Bitmap en blanco del tamaño del viewport
sprite.blank_screen

# Captura de pantalla
sprite.snap_screen

# Estirar imagen a pantalla completa
sprite.stretch_screen("Graphics/Pictures/background")
```

#### Efectos de Color

```ruby theme={null}
# Obtener color promedio del bitmap
avg = sprite.avg_color(freq: 2)  # freq = frecuencia de muestreo

# Aplicar color a píxeles sólidos
sprite.colorize(Color.new(255, 0, 0), amount: 128)

# Difuminar sprite
sprite.blur

# Crear contorno
sprite.outline(Color.new(0, 0, 0))

# Aplicar brillo/resplandor
sprite.glow(Color.new(255, 255, 0), keep: true)

# Transparencia de color
sprite.alpha = 128
```

### 3. Extensiones de Core

Extiende clases base de Ruby y RGSS con nuevos métodos.

#### String

```ruby theme={null}
# Métodos adicionales para cadenas
string = "hola mundo"
string.titleize  # "Hola Mundo"
string.snake_case  # "hola_mundo"
string.camel_case  # "HolaMundo"
```

#### Numeric

```ruby theme={null}
# Interpolación linear
value = 0.5.lerp  # Para animaciones suaves

# Clamp (limitar valor)
number = 150
number.clamp(0, 100)  # Retorna 100

# Conversión de grados/radianes
angulo = 45
angulo.to_rad  # Convertir a radianes
```

#### Array

```ruby theme={null}
# Métodos de array mejorados
array = [1, 2, 3, 4, 5]
array.random  # Elemento aleatorio
array.shuffle!  # Mezclar in-place
```

#### Hash

```ruby theme={null}
# Acceso con símbolos o strings
hash = { nombre: "Pikachu", nivel: 50 }
hash[:nombre]  # "Pikachu"
hash["nombre"] # "Pikachu"
```

#### Color

```ruby theme={null}
# Crear color desde hexadecimal
color = Color.from_hex("#FF0000")  # Rojo

# Conversión a hexadecimal
color.to_hex  # "#FF0000"

# Interpolación de colores
color1 = Color.new(255, 0, 0)
color2 = Color.new(0, 0, 255)
color_intermedio = color1.lerp(color2, 0.5)  # Púrpura
```

### 4. Utilidades de UI

#### Ventanas Mejoradas

```ruby theme={null}
class UI::Window
  # Métodos para gestión de ventanas
  def smooth_open(frames = 20)
    # Abre la ventana suavemente
  end
  
  def smooth_close(frames = 20)
    # Cierra la ventana suavemente
  end
end
```

#### Cursores Personalizados

```ruby theme={null}
class UI::Cursor
  # Gestión de cursores de menú
  def initialize(viewport, options)
    # Crear cursor personalizado
  end
end
```

### 5. SpriteHash

Sistema de gestión de sprites con hash para mejor organización.

```ruby theme={null}
# Crear hash de sprites
sprites = SpriteHash.new

# Añadir sprites
sprites["background"] = Sprites::Base.new(viewport)
sprites["player"] = Sprites::Base.new(viewport)

# Acceder y manipular
sprites["background"].x = 100

# Actualizar todos
sprites.update

# Disponer todos
sprites.dispose
```

### 6. Tipos de Sprites Especializados

#### Sprite de Hoja (Sheet)

```ruby theme={null}
# Para animaciones de sprite sheets
sheet_sprite = Sprites::Sheet.new(viewport) do |s|
  s.bitmap = "Graphics/Characters/player"
  s.frames = 4
  s.frame_width = 32
  s.frame_height = 32
end

sheet_sprite.update  # Avanza el frame automáticamente
```

#### Sprite de Desplazamiento (Scrolling)

```ruby theme={null}
# Sprite con scroll automático
scroll_sprite = Sprites::Scrolling.new(viewport) do |s|
  s.bitmap = "Graphics/Pictures/background"
  s.speed_x = 2  # Velocidad horizontal
  s.speed_y = 1  # Velocidad vertical
end

scroll_sprite.update  # Se desplaza automáticamente
```

#### Sprite Arcoíris (Rainbow)

```ruby theme={null}
# Sprite con efecto de color arcoíris
rainbow = Sprites::Rainbow.new(viewport) do |s|
  s.bitmap = "Graphics/Pictures/logo"
  s.speed = 5  # Velocidad del cambio de color
end

rainbow.update  # Cambia de color automáticamente
```

#### Sprite con Estela (Trailing)

```ruby theme={null}
# Sprite que deja estela de movimiento
trailing = Sprites::Trailing.new(viewport) do |s|
  s.bitmap = "Graphics/Pictures/star"
  s.trail_length = 10  # Longitud de la estela
end
```

### 7. Sistema de Entrada de Mouse

Extensión del sistema de mouse con funcionalidades adicionales.

```ruby theme={null}
# Obtener posición del mouse
mouse_x = Mouse.x
mouse_y = Mouse.y

# Verificar clics
if Mouse.click?
  puts "Clic izquierdo"
end

if Mouse.right_click?
  puts "Clic derecho"
end

# Verificar si está sobre un área
if Mouse.in_rect?(x, y, width, height)
  puts "Mouse sobre el área"
end
```

### 8. Sistema de Logging

Sistema mejorado para registrar mensajes y errores.

```ruby theme={null}
# Diferentes niveles de log
LUTS::Logger.debug("Mensaje de debug")
LUTS::Logger.info("Información")
LUTS::Logger.warn("Advertencia")
LUTS::Logger.error("Error")

# Log con contexto
LUTS::Logger.info("Pokémon capturado", pokemon: pokemon.name, nivel: pokemon.level)
```

### 9. Utilidades Matemáticas

```ruby theme={null}
# Generar puntos de polígono
points = getPolygonPoints(
  n: 6,          # Número de lados
  rx: 50,        # Radio X
  ry: 50,        # Radio Y
  a: 0,          # Ángulo inicial
  tx: 200,       # Centro X
  ty: 200        # Centro Y
)

# Coordenadas aleatorias en circunferencia
x, y = randCircleCord(radius: 100)
```

### 10. Plugin Manager Extendido

```ruby theme={null}
# Alias automático de métodos
PluginManager::Aliaser.alias_method(
  klass: PokemonParty_Scene,
  method: :pbStartScene,
  new_name: :custom_start_scene
)

# Tu nuevo método
def pbStartScene(*args)
  custom_start_scene(*args)  # Llama al original
  # Tu código adicional
end
```

## Concerns (Módulos Mixins)

### BlockConstructor

Permite inicializar objetos con bloques de configuración.

```ruby theme={null}
class MiClase
  include LUTS::Concerns::BlockConstructor
  
  attr_accessor :x, :y, :name
end

# Usar con bloque
obj = MiClase.new do |o|
  o.x = 100
  o.y = 200
  o.name = "Objeto"
end
```

### Floatable

Añade efecto de flotación a sprites.

```ruby theme={null}
class FloatingSprite < Sprite
  include LUTS::Concerns::Floatable
  
  def initialize(viewport)
    super
    start_float(
      amplitude: 10,  # Amplitud del movimiento
      speed: 2        # Velocidad
    )
  end
end
```

### QuickAnimatable

Animaciones rápidas con menos configuración.

```ruby theme={null}
class QuickSprite < Sprite
  include LUTS::Concerns::QuickAnimatable
  
  def show
    quick_animate(opacity: 255, duration: 20)
  end
end
```

## Ejemplos Avanzados

### Ejemplo 1: Menú Personalizado Animado

```ruby theme={null}
class CustomMenu
  def initialize
    @viewport = Viewport.new(0, 0, Graphics.width, Graphics.height)
    @sprites = SpriteHash.new
    
    # Fondo
    @sprites["bg"] = Sprites::Base.new(@viewport) do |s|
      s.create_rect(Graphics.width, Graphics.height, Color.new(0, 0, 0, 128))
      s.opacity = 0
    end
    @sprites["bg"].animate(opacity: 255)
    
    # Ventana
    @sprites["window"] = Sprites::Base.new(@viewport) do |s|
      s.bitmap = "Graphics/Pictures/menu_window"
      s.center!(snap: true)
      s.zoom = 0
    end
    @sprites["window"].animate(zoom: 1.0)
    
    # Animar entrada
    30.times do
      @sprites.update
      @sprites["bg"].play_target_animation(30)
      @sprites["window"].play_target_animation(30)
      Graphics.update
    end
  end
  
  def update
    @sprites.update
  end
  
  def dispose
    @sprites.dispose
    @viewport.dispose
  end
end
```

### Ejemplo 2: Sistema de Partículas

```ruby theme={null}
class ParticleSystem
  def initialize(viewport)
    @viewport = viewport
    @particles = []
  end
  
  def create_particle(x, y)
    particle = Sprites::Trailing.new(@viewport) do |s|
      s.create_rect(4, 4, Color.new(255, 255, 0))
      s.x = x
      s.y = y
      s.center!
      s.trail_length = 5
    end
    
    # Animar partícula
    angle = rand(360)
    distance = 50
    end_x = x + Math.cos(angle * Math::PI / 180) * distance
    end_y = y + Math.sin(angle * Math::PI / 180) * distance
    
    particle.animate(x: end_x, y: end_y, opacity: 0)
    @particles << particle
  end
  
  def update
    @particles.each do |p|
      p.play_target_animation(60)
      @particles.delete(p) if p.opacity <= 0
    end
  end
end
```

### Ejemplo 3: Transición Personalizada

```ruby theme={null}
class CustomTransition
  def self.execute(duration = 40)
    viewport = Viewport.new(0, 0, Graphics.width, Graphics.height)
    
    # Captura de pantalla
    snapshot = Sprites::Base.new(viewport)
    snapshot.snap_screen
    
    # Efecto de pixelación
    pixelation = 1
    max_pixel = 20
    
    duration.times do |i|
      progress = i.to_f / duration
      pixelation = 1 + (max_pixel * progress).to_i
      
      # Aplicar pixelación (simulada con zoom)
      snapshot.zoom = 1.0 / pixelation
      snapshot.center!(snap: true)
      snapshot.opacity = 255 - (255 * progress)
      
      Graphics.update
    end
    
    snapshot.dispose
    viewport.dispose
  end
end
```

## Optimización y Mejores Prácticas

<CardGroup cols={2}>
  <Card title="Gestión de Memoria" icon="memory">
    Siempre dispón sprites y bitmaps cuando no los uses
  </Card>

  <Card title="Animaciones" icon="play">
    Usa `play_target_animation` en el bucle update
  </Card>

  <Card title="SpriteHash" icon="hashtag">
    Organiza sprites complejos con SpriteHash
  </Card>

  <Card title="Logging" icon="file-text">
    Usa el Logger para debugging efectivo
  </Card>
</CardGroup>

<Warning>
  **Importante para Rendimiento:**

  * No crees bitmaps grandes innecesarios
  * Reutiliza bitmaps cuando sea posible
  * Dispón objetos que ya no uses
  * Limita el número de sprites animados simultáneos
</Warning>

## Compatibilidad

<Note>
  **Luka's Scripting Utilities** es compatible con:

  * Pokémon Essentials v21.1
  * Marin's Scripting Utilities (opcional)
  * Todos los plugins de la serie MUI
  * La mayoría de plugins de terceros
</Note>

## Recursos y Enlaces

**Autor:** Luka S.J.\
**Versión:** 4.1.0\
**Documentación oficial:** [luka-sj.com/res/luts](https://luka-sj.com/res/luts)\
**Soporte:** Comunidad de Pokémon Essentials

## Páginas Relacionadas

<CardGroup cols={2}>
  <Card title="Modular UI Scenes" icon="window" href="/plugins/modular-ui">
    Sistema MUI que usa estas utilidades
  </Card>

  <Card title="Enhanced Pokemon UI" icon="palette" href="/plugins/enhanced-ui">
    Plugin que aprovecha LUTS
  </Card>

  <Card title="Descripción General" icon="list" href="/plugins/descripcion-general">
    Volver al catálogo de plugins
  </Card>
</CardGroup>