Esta librería es el corazón de la manipulación de tags en Kara Effector. Permite crear, modificar, animar y procesar tags 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.
tag.redefine( String )Descripción: Es una de las funciones de pre-procesamiento más importantes. Se ejecuta internamente para "traducir" la sintaxis avanzada de KE (como \t(500, \blur5), \blur~, etc.) a tags de ASS que el motor puede entender. Expande atajos, evalúa variables y prepara el terreno para otras funciones.
Argumentos:
String (string): La cadena de texto con los tags a procesar.Uso: Generalmente se usa de forma interna, pero puedes llamarla si estás construyendo una cadena de tags manualmente y necesitas que se procese.
tag.dark( String )Descripción: Similar a redefine, esta función expande "tags compuestos" o "tags oscuros" 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.
Argumentos:
String (string): La cadena de texto con los tags a expandir.Uso: Interno, pero fundamental para poder escribir tags de forma abreviada en la interfaz.
tag.modify( String )Descripción: Realiza modificaciones específicas sobre ciertos tags, principalmente \clip. Por ejemplo, si pasas un \clip con una shape y un modificador de posición, esta función calcula la posición final de la shape y la inserta en el tag.
Argumentos:
String (string): La cadena de texto con los tags a modificar.Ejemplo de Uso: Procesa \clip(shape.circle, "center") para desplazar la shape al centro del objeto.
tag.default( String ) y tag.default2( String )Descripción: Devuelve el valor por defecto de un tag de ASS. Por ejemplo, para \blur5, devolvería \blur0. default2 maneja la sintaxis con ~ (ej. \blur~ se convierte en \blur0).
Argumentos:
String (string): El tag (o conjunto de tags) cuyo valor por defecto se quiere obtener.Ejemplo de Uso: return "\\blur5\\t(" .. tag.default("\\blur5") .. ")" // Crea una animación de \blur5 a \blur0.
tag.inverse( String )Descripción: Devuelve el valor "inverso" de un tag. Para la mayoría de los tags numéricos, esto significa cambiar su signo (\frx20 -> \frx-20). Para colores, devuelve el color complementario. Para alphas, el valor por defecto del estilo.
Argumentos:
String (string): El tag o conjunto de tags a invertir.Ejemplo de Uso: return "\\frx20\\t(" .. tag.inverse("\\frx20") .. ")" // Crea una animación de \frx20 a \frx-20.
tag.natsu( String )Descripción: Procesa la sintaxis de interpolación "Natsu". Esta sintaxis permite interpolar valores de un tag 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.Argumentos:
String (string): La cadena con la sintaxis Natsu.Ejemplo de Uso: \\fscy{100, 150} hará que la primera sílaba tenga \fscy100, la última \fscy150, y las intermedias valores interpolados.
tag.do_alpha( String )Descripción: Convierte valores de alpha escritos como números decimales (0-255) a su formato hexadecimal de ASS (&HFF&). También procesa atajos como TA1 (alpha primario del texto).
Argumentos:
String (string): La cadena con tags de alpha.Ejemplo de Uso: Procesa \1a(128) y lo convierte en \1a&H80&.
tag.HTML_to_ass( String )Descripción: Convierte formatos de color y alpha de estilo web (HTML, ej. #FF0000) al formato de ASS (&H0000FF&).
Argumentos:
String (string): La cadena que contiene los colores o alphas en formato HTML.tag.tonumber( String )Descripción: 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.
Argumentos:
String (string): La cadena con los atajos.Uso: Se aplica internamente para que puedas usar estos atajos en las casillas numéricas.
tag.filter( String, Tag, Filter )Descripción: Aplica una función de filtro a todas las ocurrencias de un tag específico dentro de una cadena de texto.
Argumentos:
String (string): El texto que contiene los tags.Tag (string): El tag a modificar (ej. \\blur, \\pos).Filter (function): La función que se aplicará al valor del tag. La función recibe el valor actual y debe devolver el nuevo valor.Ejemplo de Uso:
-- 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"
tag.oscill( dur, delay, ... )Descripción: Crea un efecto de oscilación o parpadeo. Genera una secuencia de transformaciones \t que alternan entre un estado activo (los tags que proporcionas) y un estado inactivo (el valor por defecto de esos tags).
Argumentos:
dur (number): La duración total de la oscilación en milisegundos.delay (number | table): La duración de cada ciclo (activo + inactivo). Puede ser un número para una duración fija o una tabla para configuraciones avanzadas.
{dur_ciclo, accel}: Permite especificar una aceleración.{{dur_activo, dur_inactivo}}: Permite especificar duraciones diferentes para el estado activo y el inactivo.... (string): Uno o más strings de tags que se aplicarán durante el estado activo.Ejemplo de Uso:
-- 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")
tag.oscill2( Times, ... )Descripción: 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 de "glitch" o destellos aleatorios complejos sin tener que definir cada tag manualmente.
Argumentos:
Times (table): Una tabla que define los intervalos de tiempo. Puede ser una tabla de tablas {{t1, t2, dur_trans}, {t3, t4, dur_trans}, ...} o {"random", dur_ciclo, dur_trans} para generar intervalos aleatorios.... (string | table, opcional): Los tags a usar. Si se omite, la función elige combinaciones aleatorias de un catálogo interno.Ejemplo de Uso:
-- Genera destellos aleatorios durante la sílaba
tag.oscill2({syl.start_time, syl.end_time, 1.5 * frame_dur})
tag.glitter( dur, ExtraTags_i, ExtraTags_f )Descripción: 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.
Argumentos:
dur (number | table, opcional): La duración total del efecto. Puede ser un número o una tabla {t_inicio, t_final}. Por defecto es fx.dur.ExtraTags_i (string, opcional): Tags adicionales que se aplicarán al inicio del brillo.ExtraTags_f (string, opcional): Tags adicionales que se aplicarán al final del brillo.Ejemplo de Uso: tag.glitter(syl.dur, "\\1c&HFFFF00&", "\\1c" .. l.color1)
tag.cyclic( Dur, Dur_tr, Delay, Fad_i, Fad_f, tags_ini, tags_fin )Descripción: 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.
Argumentos:
Dur (number | table): Duración total del efecto.Dur_tr (number): Duración de cada ciclo de aparición/desaparición.Delay (number): Retardo entre cada ciclo.Fad_i, Fad_f (number): Duración de los fundidos de entrada y salida del \alpha.tags_ini, tags_fin (string): Tags adicionales para la transición de entrada y salida, respectivamente.Ejemplo de Uso:
-- Un pulso de visibilidad cada 500ms durante toda la línea
tag.cyclic(line.dur, 500, 0, 250, 250)
tag.sec( Dur, Dur_tr, tags_ini, tags_fin )Descripción: Crea una secuencia de transformaciones. Es similar a cyclic pero más general, ya que en lugar de animar \alpha, aplica dos conjuntos de tags (tags_ini y tags_fin) en intervalos de tiempo definidos.
Argumentos:
Dur (number | table): Duración total de la secuencia.Dur_tr (number | table): Tiempos de la transición.
dur_transicion.{dur_trans_1, dur_off, dur_trans_2}.tags_ini (string): Los tags que se aplicarán en la primera transición.tags_fin (string): Los tags que se aplicarán en la segunda transición.Ejemplo de Uso:
-- Alterna entre dos colores cada 400ms
tag.sec(line.dur, {200, 200, 200}, "\\1c&HFF0000&", "\\1c&H0000FF&")
tag.ipol( Ipol_i, ... )Descripción: 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.
Argumentos:
Ipol_i (number): El porcentaje de interpolación (de 0 a 1)....: La lista de valores entre los que se interpolará (ej. 100, 200, 150). Puede manejar números, colores y alphas.Ejemplo de Uso:
-- 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)
tag.clip( left_cx, top_cy, width_clip, height_clip, Mode, clip_move )Descripción: 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".
Argumentos:
left_cx, top_cy (number): Coordenadas de la esquina superior izquierda del área total a dividir.width_clip, height_clip (number): Ancho y alto del área total a dividir.Mode (number): Un número de 1 a 9 que define el orden en que se procesan los recortes (desde qué esquina o lado). Por defecto es 79 (no es un error, es un código interno).clip_move (string | table, opcional): Permite animar el clip usando una trayectoria definida por una shape o una tabla de coordenadas.Ejemplo de Uso:
-- 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)
tag.clip2( left_cx, top_cy, width_clip, height_clip, clip_move )Descripción: 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.
Argumentos: Los mismos que tag.clip, pero sin el argumento Mode.
Ejemplo de Uso:
-- Crea un clip que cubre exactamente la sílaba.
return tag.clip2(syl.left, syl.top, syl.width, syl.height)
tag.Rclip( left_cx, top_cy, width_clip, height_clip, Mode )Descripción: 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.
Argumentos: Los mismos que tag.clip, pero sin clip_move.
Ejemplo de Uso:
-- 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)
tag.Pclip( size_clip, left_cx, top_cy, width_clip, height_clip )Descripción: 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.
Argumentos:
size_clip (number | table): El tamaño de cada "baldosa" del perímetro. Puede ser {ancho} o {ancho, alto}.left_cx, top_cy, width_clip, height_clip (number): El área rectangular cuyo perímetro se recorrerá.Ejemplo de Uso: return tag.Pclip({20, 20}, syl.left, syl.top, syl.width, syl.height)
tag.clip_shape( Shapes, Center_x, Center_y )Descripción: Divide una shape compuesta (una shape que contiene múltiples figuras m ...) en sus componentes individuales y aplica un \clip vectorial para cada una.
Argumentos:
Shapes (string): La shape compuesta a dividir.Center_x, Center_y (number, opcional): Coordenadas para centrar el conjunto de shapes.Ejemplo de Uso:
-- 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.
tag.setclip( Clips, Tags, Index )Descripción: Un efecto avanzado que aplica diferentes conjuntos de tags (Tags) a los objetos que se encuentren dentro de diferentes áreas de recorte (Clips).
Argumentos:
Clips (table): Una tabla de \clip strings.Tags (table): Una tabla de tags, uno por cada clip.Index (table, opcional): Índices de las líneas a las que se aplica el efecto.tag.only( Conditions, ... )Descripción: 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.
Argumentos:
Conditions (booleano): La condición a evaluar. Generalmente es una expresión como syl.i % 2 == 1....: Los valores a devolver. El primer valor es para true, el segundo para false. Si el segundo se omite, devuelve un valor neutro (0 o "").Ejemplo de Uso:
-- 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")
tag.set( Times, Events )Descripción: Crea una serie de eventos (aplicación de tags) en momentos específicos y no necesariamente periódicos. Genera una cadena de tags \t que se activan en los tiempos indicados en la tabla Times.
Argumentos:
Times (table): Una tabla con los milisegundos en los que se debe activar cada evento.Events (string | table): Un tag o una tabla de tags que se aplicarán en cada uno de los tiempos. Si es una tabla, se aplica cíclicamente.Ejemplo de Uso: tag.set({500, 1200, 1350}, {"\\blur2", "\\blur4", "\\blur0"}) // Aplica \blur2 en 500ms, \blur4 en 1200ms, y \blur0 en 1350ms.
tag.timefx( String )Descripción: 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).
Argumentos:
String (string): La cadena de texto con los atajos de tiempo.Uso: Es principalmente una función interna que permite usar estos atajos en la interfaz.
tag.do_tag( String )Descripción: Permite ejecutar funciones de la librería tag o shape escribiéndolas como si fueran un tag 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.
Argumentos:
String (string): La cadena que contiene las llamadas a funciones en formato de tag.Ejemplo de Uso:
-- En la casilla "Add Tags [fx]:"
-- Esto ejecutará tag.oscill(500, 100, "\\frz10")
return tag.do_tag("\\tag.oscill(500, 100, '\\\\frz10')")
tag.to_Auto4( String )Descripción: 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.
Argumentos:
String (string): La cadena de texto a convertir.Uso: Es una función interna del macro y no está pensada para ser llamada directamente por el usuario.
tag.to_temp( String )Descripción: 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.
Argumentos:
String (string): La cadena de plantilla a evaluar.Uso: Interno, se activa cuando se utiliza un Template.
tag.temp2( my_temp )Descripción: Es el motor principal detrás de los "Templates" (plantillas). 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.
Argumentos:
my_temp (string): La cadena de plantilla a procesar.Uso: 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.
tag.v_dollar( String )Descripció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.
Argumentos:
String (string): La cadena que contiene las variables.Uso: Es interna, pero es lo que te permite usar atajos como $syl_dur en lugar de tener que escribir syl.duration.
tag.coupling( String )Descripción: Una función de utilidad para asegurar que ciertos tags que definen una posición o estado (como \pos, \move, \an) aparezcan solo una vez en un bloque de tags. Si detecta duplicados, elimina los anteriores y conserva solo el último.
Argumentos:
String (string): La cadena de tags a "limpiar".Uso: Interno, para evitar conflictos como tener dos \pos en la misma línea de efecto.
tag.operation( String )Descripción: 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).
Argumentos:
String (string): La cadena a escapar.tag.to_vsf( String )Descripción: Convierte formatos de color y alpha 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.
Argumentos:
String (string): La cadena con tags en formato VSFilterMod.tag.delete_in_return( return_fx )Descripción: Una función de seguridad interna. Si tienes el mismo tipo de tag 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.
Argumentos:
return_fx (string): El contenido de la casilla "Return [fx]:".