> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/es/ocio/cuxial-danceclass/developers.md).

# Exports y eventos

API pública de Cuxial Dance Class: exports y eventos de servidor para consultar las clases y reaccionar a ellas.

Consulta las clases abiertas, cierra una o reacciona cuando una clase empieza, un alumno se une o un baile termina. Todo lo de esta página corre en el servidor; no hay exports de cliente.

## Exports de servidor

### GetRooms

Devuelve todas las clases abiertas.

```lua
local rooms = exports.cuxial_danceclass:GetRooms()
```

**Devuelve:** `table[]`, ordenada por `id`. Cada entrada es un [resumen de sala](#resumen-de-sala).

```lua
for _, room in ipairs(exports.cuxial_danceclass:GetRooms()) do
    print(room.name, room.studentCount .. '/' .. room.maxStudents)
end
```

### GetPlayerRoom

Devuelve la clase en la que está un jugador y su rol.

```lua
local room, role = exports.cuxial_danceclass:GetPlayerRoom(source)
```

| Parámetro | Tipo   | Descripción                 |
| --------- | ------ | --------------------------- |
| `source`  | number | Id de servidor del jugador. |

**Devuelve:** `table | nil`, `string | nil`. El [resumen de sala](#resumen-de-sala) y el rol, `'instructor'` o `'student'`. `nil` si el jugador no está en ninguna clase.

```lua
local room, role = exports.cuxial_danceclass:GetPlayerRoom(source)
if role == 'instructor' then
    print(('Da la clase %s'):format(room.name))
end
```

### IsInClass

Indica si un jugador está en una clase, como instructor o como alumno.

```lua
local inClass = exports.cuxial_danceclass:IsInClass(source)
```

| Parámetro | Tipo   | Descripción                 |
| --------- | ------ | --------------------------- |
| `source`  | number | Id de servidor del jugador. |

**Devuelve:** `boolean`.

```lua
if exports.cuxial_danceclass:IsInClass(source) then return end
```

### CloseRoom

Cierra una clase desde otro recurso. Si se bailó al menos un baile, la clase termina con su podio y se guarda el historial; si no, simplemente se cierra y las entradas se devuelven según `rooms.refundIfNoRound`.

```lua
local closed = exports.cuxial_danceclass:CloseRoom(id)
```

| Parámetro | Tipo   | Descripción     |
| --------- | ------ | --------------- |
| `id`      | number | Id de la clase. |

**Devuelve:** `boolean`. `false` si no hay ninguna clase con ese id.

```lua
for _, room in ipairs(exports.cuxial_danceclass:GetRooms()) do
    exports.cuxial_danceclass:CloseRoom(room.id)
end
```

### Resumen de sala

| Campo             | Tipo             | Descripción                                                                                             |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| `id`              | number           | Id de la clase.                                                                                         |
| `name`            | string           | Nombre de la clase.                                                                                     |
| `difficulty`      | string           | Id de la dificultad: `easy`, `normal` o `hard`.                                                         |
| `difficultyLabel` | string           | Nombre de la dificultad según el config.                                                                |
| `fee`             | number           | Entrada. `0` = gratis.                                                                                  |
| `maxStudents`     | number           | Cupo.                                                                                                   |
| `instructor`      | table            | `{ id, name, points }`.                                                                                 |
| `students`        | table\[]         | `{ id, name, points, rounds, accuracy, bestAccuracy }`, ordenados por puntos. La precisión va de 0 a 1. |
| `studentCount`    | number           | Alumnos en la clase.                                                                                    |
| `phase`           | string           | `lobby` (sin empezar), `countdown`, `round` o `results` (entre bailes).                                 |
| `roundIndex`      | number           | Bailes hechos hasta ahora.                                                                              |
| `maxRounds`       | number           | Bailes permitidos por clase.                                                                            |
| `playlist`        | string\[] \| nil | Bailes elegidos por el instructor. `nil` = aleatorio.                                                   |
| `currentDance`    | table \| nil     | `{ command, label }` del baile en curso o del último.                                                   |
| `role`            | string \| nil    | Solo con `GetPlayerRoom`: rol de ese jugador.                                                           |

## Eventos de servidor

Cada evento se dispara en el servidor con una tabla. Escúchalos con `AddEventHandler`.

| Evento                            | Datos                            | Cuándo                                                                                              |
| --------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- |
| `cuxial_danceclass:roomCreated`   | `{ id, instructor, difficulty }` | Se abre una clase. `instructor` es un id de servidor.                                               |
| `cuxial_danceclass:roomClosed`    | `{ id, reason }`                 | Se cierra una clase. `reason`: `closed`, `left`, `ended` o `disconnected`.                          |
| `cuxial_danceclass:studentJoined` | `{ id, source }`                 | Se une un alumno.                                                                                   |
| `cuxial_danceclass:studentLeft`   | `{ id, source, reason }`         | Un alumno sale de una clase que sigue abierta. `reason`: `left`, `zone`, `kicked` o `disconnected`. |
| `cuxial_danceclass:roundStarted`  | `{ id, index, dance }`           | Empieza un baile. `dance` es su comando.                                                            |
| `cuxial_danceclass:roundEnded`    | `{ id, index, results }`         | Termina un baile.                                                                                   |
| `cuxial_danceclass:classEnded`    | `{ id, rounds, ranking }`        | Termina una clase con al menos un baile, justo antes de `roomClosed`.                               |

Cada entrada de `results` trae `id`, `name`, `perfect`, `good`, `miss`, `total`, `accuracy`, `maxStreak`, `points` y `totalPoints`. Cada entrada de `ranking` trae `id`, `name`, `points`, `rounds`, `accuracy` y `bestAccuracy`.

{% hint style="info" %}
`studentLeft` no se envía por los alumnos que siguen dentro cuando una clase se cierra. Para ese caso usa `roomClosed`.
{% endhint %}

```lua
AddEventHandler('cuxial_danceclass:roundEnded', function(data)
    for _, result in ipairs(data.results) do
        if result.accuracy >= 0.9 then
            print(('%s clavó el baile %d'):format(result.name, data.index))
        end
    end
end)
```

### on / off

Los mismos eventos como hooks, sin el prefijo. `on` devuelve un identificador y `off` quita el hook.

```lua
local handle = exports.cuxial_danceclass:on(event, fn)
local removed = exports.cuxial_danceclass:off(handle)
```

| Parámetro | Tipo     | Descripción                                                                                               |
| --------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `event`   | string   | `roomCreated`, `roomClosed`, `studentJoined`, `studentLeft`, `roundStarted`, `roundEnded` o `classEnded`. |
| `fn`      | function | Recibe la misma tabla que el evento.                                                                      |
| `handle`  | number   | Valor devuelto por `on`.                                                                                  |

**Devuelve:** `on` devuelve `number`, o `nil` si los argumentos no son válidos. `off` devuelve `boolean`.

```lua
local handle = exports.cuxial_danceclass:on('classEnded', function(data)
    local winner = data.ranking[1]
    if winner then print(('%s ganó la clase'):format(winner.name)) end
end)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/es/ocio/cuxial-danceclass/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.