Librería (tag)

Autortrotacalles

¿Para qué sirve?

Esta librería es el corazón de la manipulación de etiquetas en Kara Effector. Permite crear, modificar, animar y procesar etiquetas de ASS de manera programática y dinámica. Las funciones de este primer grupo se centran en la interpretación y transformación de la sintaxis especial de Kara Effector.

Funciones

Funciones de Procesamiento y Manipulación Fundamental

Es una de las funciones de pre-procesamiento más importantes. Se ejecuta internamente para “traducir” la sintaxis avanzada de Kara Effector (p.e. \t(500, \blur5), \blur~, etc.) a etiquetas de ASS que el motor puede entender. Expande atajos, evalúa variables y prepara el terreno para otras funciones.

Generalmente se usa de forma interna, pero puedes llamarla si estás construyendo una cadena de etiquetas manualmente y necesitas que se procese.

Similar a redefine, esta función expande “etiquetas compuestas” o “etiquetas oscuras” en sus componentes básicos. Por ejemplo, convierte \fscxy150 en \fscx150\fscy150. También maneja atajos de tiempo como \frx20~500, que se convierte en una transformación \t con un valor inicial y uno final.

Interno, pero fundamental para poder escribir etiquetas de forma abreviada en la interfaz.

Realiza modificaciones específicas sobre ciertas etiquetas, principalmente \clip. Por ejemplo, si pasas un \clip con un shape y un modificador de posición, esta función calcula la posición final del shape y lo inserta en la etiqueta.

Procesa el modificador para desplazar el shape al centro del objeto.

Ejemplo

"\\clip(shape.circle, \"center\")"

Devuelve el valor por defecto de una etiqueta de ASS. Por ejemplo, para \blur5, devolvería \blur0. default2 maneja la sintaxis con ~ (p.e. \blur~ se convierte en \blur0).

Ejemplo

return "\\blur5\\t(" .. tag.default("\\blur5") .. ")" -- Crea una animación de \blur5 a \blur0.

Devuelve el valor “inverso” de una etiqueta. Para la mayoría de las etiquetas numéricas, esto significa cambiar su signo (\frx20 -> \frx-20). Para colores, devuelve el color complementario. Para alfas, el valor por defecto del estilo.

Ejemplo

return "\\frx20\\t(" .. tag.inverse("\\frx20") .. ")" -- Crea una animación de \frx20 a \frx-20.

Procesa la sintaxis de interpolación “Natsu”. Esta sintaxis permite interpolar valores de una etiqueta a lo largo de un bucle o de las sílabas.

\tag{valor1, valor2}: Interpola entre valor1 y valor2 a lo largo de las sílabas (val_i).
\tag-{valor1, valor2}: Interpola a lo largo del bucle (j).
\tag>valor_final: Interpola desde el valor actual del tag hasta valor_final a lo largo del bucle.

Hará que la primera sílaba tenga \fscy100, la última \fscy150, y las intermedias valores interpolados.

Ejemplo

"\\fscy{100, 150}"

Convierte valores alfa escritos como números decimales (0-255) a su formato hexadecimal de ASS (&HFF&). También procesa atajos como TA1 (alfa primario del texto).

Procesa la etiqueta y la convierte en \1a&H80&.

Ejemplo

"\\1a(128)"

Convierte formatos de color y alfa de estilo web (HTML, ej. #FF0000) al formato de ASS (&H0000FF&).

Convierte atajos de texto en valores numéricos. Por ejemplo, 50r se convierte en 50 * ratio, 10f se convierte en 10 * frame_dur. También procesa los atajos de tiempo como 30li o 50mid1.

Se aplica internamente para que puedas usar estos atajos en las casillas numéricas.

Aplica una función de filtro a todas las ocurrencias de una etiqueta específica dentro de una cadena de texto.

Ejemplo

-- En "Variables [fx]:":
mi_filtro = function(valor) return tonumber(valor) * 2 end
-- En "Return [fx]:":
return tag.filter("\\blur5 \\frx10", "\\blur", var.mi_filtro) -- Devuelve "\blur10 \frx10"

Funciones de animación basada en tiempo

Crea un efecto de oscilación o parpadeo. Genera una secuencia de transformaciones \t que alternan entre un estado activo (las etiquetas que proporcionas) y un estado inactivo (el valor por defecto de esas etiquetas).

Ejemplo

-- Parpadeo de color durante toda la sílaba, cada 200ms
tag.oscill(syl.dur, 200, "\\1c&HFFFFFF&")

-- Oscilación de rotación con un ciclo de 400ms (200ms activo, 200ms inactivo)
tag.oscill(syl.dur, { {200, 200} }, "\\frz45")

Una versión preconfigurada de tag.oscill que genera combinaciones aleatorias de efectos (como \shad, \bord, \fr, colores, etc.) dentro de intervalos de tiempo específicos. Es ideal para crear efectos glitch o destellos aleatorios complejos sin tener que definir cada etiqueta manualmente.

Ejemplo

-- Genera destellos aleatorios durante la sílaba
tag.oscill2({syl.start_time, syl.end_time, 1.5 * frame_dur})

Crea un efecto de “brillos” o destellos aleatorios. Genera \t con \fscx y \fscy en momentos y con tamaños aleatorios para simular destellos que aparecen y desaparecen rápidamente.

Ejemplo

tag.glitter(syl.dur, "\\1c&HFFFF00&", "\\1c" .. l.color1)

Genera un efecto de aparición y desaparición cíclica usando \alpha. Es perfecto para crear efectos de “respiración” o pulsos de visibilidad.

Ejemplo

-- Un pulso de visibilidad cada 500ms durante toda la línea
tag.cyclic(line.dur, 500, 0, 250, 250)

Crea una secuencia de transformaciones. Es similar a cyclic pero más general, ya que en lugar de animar \alpha, aplica dos conjuntos de etiquetas (tags_ini y tags_fin) en intervalos de tiempo definidos.

Ejemplo

-- Alterna entre dos colores cada 400ms
tag.sec(line.dur, {200, 200, 200}, "\\1c&HFF0000&", "\\1c&H0000FF&")

Interpola un valor único. A diferencia de table.ipol que genera una tabla de valores, esta función devuelve un solo valor interpolado basado en un porcentaje. Es una función de utilidad muy versátil.

Ejemplo

-- En la casilla "Scale x":
-- La escala irá de 100 a 150 a lo largo de la duración de la sílaba.
tag.ipol(syl.progress, 100, 150)

Funciones de recorte (clipping)

Genera un \clip rectangular para un solo objeto de un bucle (loop). Su función principal es dividir un área rectangular en una matriz (definida por fx.loop_h y fx.loop_v) y devolver el \clip que corresponde al objeto j actual. Es la base para efectos de tipo “mosaico” o “persianas”.

Ejemplo

-- En un Template [Syl] con loop = {10, 1}
-- Esto divide la sílaba en 10 barras verticales y aplica el clip correspondiente a cada una.
return tag.clip(syl.left, syl.top, syl.width, syl.height, 79)

Genera un \clip rectangular para un área completa, sin dividirla. Es una versión simplificada de tag.clip para cuando no se necesita un efecto de matriz. También soporta animación.

Ejemplo

-- Crea un clip que cubre exactamente la sílaba.
return tag.clip2(syl.left, syl.top, syl.width, syl.height)

Random clip. Similar a tag.clip, pero las divisiones de la matriz no son uniformes, sino de tamaños aleatorios. Esto crea un efecto de mosaico irregular.

Ejemplo

-- En un Template [Syl] con loop = {5, 5}
-- Divide la sílaba en una cuadrícula de 5x5 con celdas de tamaño irregular.
return tag.Rclip(syl.left, syl.top, syl.width, syl.height, 79)

Perimeter clip. Genera \clip rectangulares que recorren el perímetro de un área. El bucle loop se ajusta automáticamente para coincidir con el número de recortes en el perímetro.

Ejemplo

return tag.Pclip({20, 20}, syl.left, syl.top, syl.width, syl.height)

Divide un shape compuesto (un shape que contiene múltiples figuras m ...) en sus componentes individuales y aplica un \clip vectorial para cada uno.

Ejemplo

-- Si 'mis_figuras' es una shape con 5 estrellas...
-- loop = 5
return tag.clip_shape(mis_figuras)
-- Cada objeto del bucle será recortado por una de las 5 estrellas.

Funciones de utilidad y conversión

Un efecto avanzado que aplica diferentes conjuntos de etiquetas (Tags) a los objetos que se encuentren dentro de diferentes áreas de recorte (Clips).

Una de las funciones lógicas más útiles. Actúa como un operador condicional (ternario). Evalúa una condición y, dependiendo de si es verdadera o falsa, devuelve uno de los dos valores proporcionados. Es fundamental para crear efectos que cambian de comportamiento dinámicamente.

Ejemplo

-- En la casilla "Add Tags [fx]:"
-- Rota las sílabas impares 45 grados y las pares -45 grados.
return tag.only(syl.i % 2 == 1, "\\frz45", "\\frz-45")

Crea una serie de eventos (aplicación de etiquetas) en momentos específicos y no necesariamente periódicos. Genera una cadena de etiquetas \t que se activan en los tiempos indicados en la tabla Times.

Ejemplo

tag.set({500, 1200, 1350}, {"\\blur2", "\\blur4", "\\blur0"}) -- Aplica \blur2 en 500ms, \blur4 en 1200ms, y \blur0 en 1350ms.

Función de pre-procesamiento interno que expande los atajos de tiempo como \ts, \tc, \td, \ti. Por ejemplo, convierte \ts(...) en un \t(...) cuyos tiempos de inicio y fin se basan en los tiempos de la sílaba actual (syl.start_time y syl.end_time).

Es principalmente una función interna que permite usar estos atajos en la interfaz.

Permite ejecutar funciones de la librería tag o shape escribiéndolas como si fueran etiquetas dentro de una cadena de texto. La función busca patrones como \tag.oscill(...) o \shape.lmove(...), los ejecuta con los parámetros dados y reemplaza el texto por el resultado de la función.

Ejemplo

-- En la casilla "Add Tags [fx]:"
-- Esto ejecutará tag.oscill(500, 100, "\frz10")
return tag.do_tag("\\tag.oscill(500, 100, '\\\\frz10')")

Es una función de conversión interna para el motor de macros. Su propósito es tomar una cadena de texto procesada por Kara Effector y convertirla a una sintaxis que el motor de Automation 4 de Aegisub pueda ejecutar correctamente. Se encarga principalmente de procesar las expresiones dentro de !...! y de preparar el returnfx.

Es una función interna del macro y no está pensada para ser llamada directamente por el usuario.

Similar a la anterior, esta función se especializa en evaluar el contenido de las plantillas (templates). Procesa el código dentro de !...! llamando a string.toval para ejecutar el código Lua que contienen.

Interno, se activa cuando se utiliza un Template.

Es el motor principal detrás de las plantillas (Templates). Procesa una cadena de texto que contiene variables dólar ($syl_i, $l_width, etc.) y la expande para toda la línea, sustituyendo las variables por sus valores correspondientes para cada sílaba, caracter o palabra.

Esta función es la que se ejecuta cuando usas los Templates Template Line [Word], Template Line [Syl], y Template Line [Char]. El contenido de la casilla “Add Tags [fx]:” se pasa como argumento a esta función.

La función responsable de reemplazar las “variables dólar” (ej. $syl_i, $l_width) por sus valores numéricos correspondientes en el momento de la ejecución. Es uno de los primeros pasos en el procesamiento de cualquier cadena de texto en las casillas.

Es interna, pero es lo que te permite usar atajos como $syl_dur en lugar de tener que escribir syl.duration.

Una función de utilidad para asegurar que ciertas etiquetas que definen una posición o estado (como \pos, \move, \an) aparezcan solo una vez en un bloque de etiquetas. Si detecta duplicados, elimina los anteriores y conserva solo el último.

Interno, para evitar conflictos como tener dos \pos en la misma línea de efecto.

Una función de utilidad muy simple que “escapa” los caracteres especiales de Lua en una cadena de texto para que puedan ser usados de forma segura dentro de patrones de búsqueda (string.gsub, string.match).

Convierte formatos de color y alfa específicos del mod VSFilter (como \1vc(...)) al formato estándar de xy-vsfilter (\1c&H...&). Calcula el color o alpha resultante de la interpolación de los 4 valores que admite el mod.

Una función de seguridad interna. Si tienes el mismo tipo de etiqueta en la casilla “Return [fx]:” y en la casilla “Add Tags [fx]:” (por ejemplo, un \bord en ambos), esta función elimina el de “Return [fx]:” para evitar conflictos y asegurar que el de “Add Tags” tenga prioridad.

InicioVolver a la biblioteca de funciones