Section 3

Documentación de "Ren'Py RhythmBeats!"

Sección 3: Documentación para programadores.

En esta sección encontrarás todo lo necesario para comenzar a escribir código en tu juego, utilizando el sistema de acción rítmica de Ren'Py RhythmBeats!

Aquí encontrarás los elementos que puedes utilizar del módulo en tu juego. Como la lógica más "compleja" del sistema rítmico es manejada por el módulo, no necesitas hacer demasiadas maniobras para implementarlo.

[¡NUEVO!]: Ahora el sistema rítmico posee un apartado para obtener puntajes por tocar una nota, y también puede mostrar el juicio actual (Perfect, Great y Miss). Pon atención a los cambios aplicados en esta sección.

En fin, vamos a ver las clases y métodos que posee el módulo rbs_plugin.rpymc.

---

1. Clase RhythmPlayground(fn, displayable, song_file, **kwargs).

Esta clase se encarga de gestionar la carga y procesamiento de los beatmaps, seguido de la interpretación de los toques del jugador, los cálculos de precisión al momento de tocar las notas en el juego, y la representación gráfica de la partida.

Recibe 3 parámetros obligatorios en el momento que se crea la instancia de la clase.

Estos parámetros son los siguientes:

• fn (str):

  Este parámetro es obligatorio, y recibe una cadena con la ruta del archivo .beat relativa a la carpeta /game de tu juego. Por ejemplo, si tu archivo de beatmap está en esta ruta:

  /game
  |   /my_beatmap.beat <- [Tu archivo de beatmap]
  

  Deberías escribirlo como:

  fn = "my_beatmap.beat"

  Este archivo puede ser leído incluso dentro de un paquete RPA.

  ---

• displayable (str o displayable):

  Este parámetro es obligatorio, y recibe como argumento un elemento displayable que será utilizado para mostrar cada nota en la pantalla. Puedes pasar como argumento una ruta de una imagen, o algún displayable de Ren'Py como Image() o Transform().

  ---

• song_file (str o list):

  Este parámetro es obligatorio, y recibe como argumento una cadena de texto con la ruta del archivo de audio que contiene la canción a reproducir durante la partida. También puedes pasar una lista para crear una cola de reproducción, por ejemplo, en el caso de que quieras agregar un breve silencio antes de que inicie la canción real de la partida.

  Todas las rutas de archivos de audio deben ser relativas a la carpeta /game, y estos archivos pueden ser leídos incluso dentro de un paquete RPA.

  Más detalles en la Documentación de Ren'Py (Audio) .

  ---

  Con el fin de configurar el comportamiento del sistema rítmico, el constructor de esta clase puede aceptar los siguientes campos adicionales:

• [Nuevo!] preload_size(int):

  Este campo recibe el tamaño (cantidad de notas) que el juego debe precargar antes de renderizar en la pantalla, y durante la partida. Un número bajo puede asegurar fluidez de FPS en la cascada de notas.

  El rango permitido es de 30 a 200 notas precargadas.

  Por defecto: 30 (mejor rendimiento).

  ---

• miss_sound (str):

  Este campo recibe una cadena con la ruta de un archivo de audio relativa a la carpeta /game, que se reproduce cuando el jugador pierde una nota.

  Por defecto: None.

  ---

• offset_map (int):

  Este campo recibe como argumento un número entero que representa el tiempo (en milisegundos) que el beatmap debe compensar respecto de la pista musical, en caso de que exista un desfase entre ambas.

  Valores positivos retrasan al beatmap respecto de la pista musical, mientras que valores negativos lo adelantan.

  Por defecto: 0 (milisegundos).

  ---

• offset_game (int):

  Si no es 0, este parámetro recibe como argumento un número entero que representa el tiempo (en milisegundos) que se agrega como una compensación personalizable por el jugador, cumpliendo un rol similar al calibrador de Timing que tienen algunos juegos de ritmo.

  [Tip:] Almacena ese número en una variable persistent para que el jugador no tenga que calibrar una y otra vez cada vez que inicia el juego. Luego pasa esa variable como argumento de este parámetro.

  Por defecto: 0 (milisegundos).

  ---

• threshold (int):

  Este campo recibe como argumento un número entero, que representa el umbral de tiempo base (en milisegundos) para detectar si el jugador ha acertado una nota.

  Por defecto el umbral ha sido fijado en 100ms (0.1 segundos), lo que da un total de 200ms para acertar una nota (100ms antes de la nota y 100ms después).

  Por defecto: 100 (milisegundos).

  ---

• [Nuevo!] perfect_thr (int):

  Este campo recibe como argumento un número entero, que representa el umbral de tiempo límite para considerar una nota tocada como "Perfect". Debe ser un valor menor al establecido en el campo threshold.

  Por defecto: 60 (milisegundos).

  ---

• max_score (int):

  El sistema rítmico de Ren'Py RhythmBeats! ahora posee una funcionalidad básica para computar puntajes durante la partida, en función de la precisión con la que se toquen las notas de una canción.

  Este parámetro recibe como argumento un número entero que representa un máximo 'hipotético' de puntos que se podría recibir por nota.

  Por defecto: 1000 (puntos).

  ---

• [Nuevo!] font (str):

  Este campo recibe como argumento la ruta de un archivo de fuente (TTF u OTF) relativa a la carpeta /game del juego, el cual se usa para estilizar el texto de juicio (Perfect, Great, BRUH). Si desea usar la fuente por defecto del juego, este campo no es requerido.

  Por defecto: gui.interface_text_font

  ---

• failsafe (bool):

  Si es True, la canción de la partida se ejecuta en "Modo Seguro", de lo contrario, las partidas se ejecutan normalmente como en cualquier juego de ritmo.

  El modo seguro permite reproducir el beatmap sin perder el combo durante la partida. Es útil en caso de querer ajustar visualmente o sincronizar la cascada de notas respecto de la música (mediante offset_map).

  Por defecto: False.

  ---

• [Nuevo!] left_key, right_key (Constantes de Pygame):

  Para tocar las notas, por defecto el sistema rítmico utiliza las teclas C y M.

  Si no se te acomoda esta configuración de teclas, puedes pasar como argumento las constantes de teclas de Pygame.

  Todas las constantes de Pygame: (Ver documentación)

  Por defecto: pygame.K_c, pygame.K_m.

---

2. Atributos útiles de la clase.

Al instanciar la clase RhythmPlayground(), puedes tener acceso a los valores de algunos atributos que pueden ser útiles para ejecutar la partida, renderizar las notas, mostrar datos de la partida en un HUD, o para depurar la actividad de juego, ya que al jugar, son atributos que se actualizan constantemente.

[IMPORTANTE]: Estos atributos, por ningún motivo deberían ser modificados, pues el alterarlos, podría producir comportamientos inesperados y errores no deseados para el módulo.

Estos atributos son los siguientes:

---

2.1. Atributos de gráficos (displayables).

Los "atributos de gráficos", son aquellos que en su defecto, tienen la misión de ser utilizados para renderizar ciertos gráficos en la pantalla. Te explicaré todo sobre este grupo de atributos a continuación:

• Atributo map_mgr:

  Este atributo es, en teoría un displayable SpriteManager(), pero su función real es ejecutar la lectura de las interacciones del jugador, calcular la precisión de los pulsos y decidir el tipo de juicio de las notas tocadas. En una screen, debe ser llamada igual que como si fuera un displayable (usando add), pero en realidad no renderiza nada en la pantalla.

  ---

• Atributo waterfall_mgr:

  A diferencia del atributo anterior, este se encarga de entregar una instancia de SpriteManager(), utilizado para renderizar la cascada de notas en la pantalla durante la partida.

  Para utilizar el displayable, debe ser llamada en una screen usando add.

  ---

• Atributo judgement_dsp:

  Este atributo es un DynamicDisplayable() que se encarga de mostrar en tiempo real el juicio de una nota. Entiéndase como "juicio" a los niveles de precisión con los que tocas una nota, es decir: "Perfect!", "Great!" o "Miss".

  Para utilizar el displayable, debe ser llamada en una screen usando add.

---

2.2. Atributos de datos de la partida.

Los "Atributos de datos" se utilizan generalmente para recopilar datos importantes de la partida en curso. Estos atributos son los siguientes:

• Atributo combo (int):

  Este atributo entrega el conteo de Combo de la partida, es decir, las notas que el jugador ha acertado consecutivamente sin fallar. Si el jugador falla una nota, este conteo regresa a cero.

  ---

• Atributo perfect (int):

  Este atributo entrega el conteo actual de notas acertadas con mayor precisión por el jugador.

  ---

• Atributo great (int):

  Este atributo entrega el conteo actual de notas acertadas con menor precisión por el jugador, sin perder el Combo.

  ---

• Atributo miss (int):

  A diferencia de perfect o great, este atributo entrega el conteo actual de notas fallidas del jugador.

  ---

• Atributo stage_score (int):

  Durante la partida el jugador irá acumulando puntaje según su precisión. Este atributo entrega la cantidad total de puntos generado en la partida.

  ---

• Atributo note_score (int):

  Este atributo entrega la cantidad de puntos obtenida en la última nota tocada. Esto se calcula en función de la precisión del jugador por cada nota.

  ---

• Atributo epoch (float):

  Si es que lo necesitas, este atributo entrega el tiempo Epoch actual de la partida, en segundos.

  ---

• Atributo map_progress (tuple):

  Este atributo entrega una tupla con el progreso del mapa actual, en el orden:

  (Nota actual, Notas totales).

[IMPORTANTE]: Recuerda que puedes acceder a los atributos de la clase, siempre y cuando hayas instanciado a la clase en alguna variable.

---

3. Métodos de la clase que puedes utilizar.

Ahora, los métodos que puedes ocupar de la clase RhythmPlayground() son los siguientes:

3.1. Método accuracy_ms().

Este método retorna un float, indicando la precisión media del jugador, en milisegundos.

---

3.2. Método result_flag().

Este método retorna una cadena expresando el status de finalización de la partida.

• AP (All Perfect): La partida ha finalizado con todas las notas en juicio 'Perfect'.
• FC (Full Combo): La suma de notas 'Great' y 'Perfect' es igual a la cantidad total de notas del beatmap.
• SC (Show Clear): El jugador ha fallado algunas notas en la partida.

---

3.3. Método is_running().

Este método retorna True si el mapa aún se está ejecutando. En el caso contrario, retorna False si se recorrieron todas las notas del Beatmap.

---

4. Lista de excepciones posibles que podría emitir el módulo.

• Excepción Beatmap read error: <Error>:

  Esta excepción se dispara en caso de que haya ocurrido un error inesperado en el proceso de lectura y procesamiento del beatmap. Este error podría ser reportable en la sección Issues del repositorio.

  ---

• Excepción Preload size must be in range 30-200 (Got: <value>):

  Esta excepción se dispara cuando ajustas en preload_size un valor inferior a 30 o mayor a 200.

  ---

• Excepción: Perfect threshold must be less than the base threshold (Got: <perfect_threshold> > <threshold>):

  Esta excepción se dispara cuando ajustas el perfect_threshold de la partida, a un valor mayor que threshold. Esto ha sido especificado en la documentación.

---

Y eso es todo lo que conforma al módulo rbs_plugin.rpymc. Ahora solo te falta ver los ejemplos para implementarlo en tu juego. Sigue navegando para ver un tutorial detallado para integrar Ren'Py RhythmBeats! en una novela visual.

---

¡Navega por la documentación!

Ir a la Sección 2 | Ir a la Sección 4