> 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/nucleo/cuxial-interactions/troubleshooting.md).

# Problemas frecuentes

Problemas habituales de Cuxial Interactions, con su causa y su solución.

Los problemas más habituales tras instalar Cuxial Interactions o registrar tus propios NPC, con la causa y la solución de cada uno. Los avisos del recurso en consola empiezan por `[cuxial_interactions]`.

<details>

<summary>El recurso no arranca</summary>

**Causa.** Falta una dependencia o arranca después. Cuxial Interactions necesita OneSync, `ox_lib`, `oxmysql`, `ox_inventory` y `cuxial_bridge`.

**Solución.** Activa OneSync y arranca antes las dependencias:

{% code title="server.cfg" %}

```cfg
ensure ox_lib
ensure oxmysql
ensure ox_inventory
ensure cuxial_bridge
ensure cuxial_interactions
```

{% endcode %}

</details>

<details>

<summary>Un NPC no aparece</summary>

**Causa.** Una de estas:

* Su conjunto está desactivado en `sets`, o el punto tiene `enabled = false`.
* El archivo de datos tiene un error de Lua. La consola muestra un aviso con el nombre del archivo que no se pudo cargar.
* El jugador está más lejos que `spawnDistance` (60 metros por defecto).
* No se pudo crear el ped. La consola del cliente muestra un aviso con el id del punto.

**Solución.** Pon el conjunto a `true` en `shared/config.lua`, corrige el error que señala la consola y reinicia el recurso. Un modelo que no existe se sustituye por `npc.fallbackModel`; si ese también está mal, no se crea ningún ped.

</details>

<details>

<summary>El NPC está, pero no sale la opción de hablar</summary>

**Causa.** Una de estas:

* No hay ningún recurso de target arrancado, o arranca después de Cuxial Interactions.
* El punto tiene una condición `job`, `item` o `canInteract` que el jugador no cumple.
* El punto, o el config, tiene `interaction = 'none'`.
* Ya hay un diálogo o una tienda abiertos.

**Solución.** Arranca `sleepless_interact`, `ox_target` o `qb-target` antes de `cuxial_bridge` y de `cuxial_interactions`. Después revisa las condiciones del punto. Los puntos con `interaction = 'none'` solo se abren con el export `Interact`.

</details>

<details>

<summary>Puse interaction = 'sprite' y se sigue usando el target</summary>

**Causa.** `bl_sprites` no está arrancado. La consola del cliente muestra un aviso una vez. Los puntos sin ped usan siempre el target.

**Solución.** Instala y arranca `bl_sprites` antes de Cuxial Interactions, o vuelve a `interaction = 'target'`.

</details>

<details>

<summary>El NPC flota o se hunde en el suelo</summary>

**Causa.** El ped se crea en la Z de `coords` más `npc.zOffset`, que vale `-1.0`. Eso encaja con coordenadas tomadas de la posición del jugador. Las coordenadas tomadas a ras de suelo dejan el ped un metro por debajo.

**Solución.** Toma las coordenadas de pie en el sitio, o corrige la Z de ese punto. Cambia `npc.zOffset` solo si todas tus coordenadas usan otra referencia.

</details>

<details>

<summary>Los NPC con usePlayerSkin salen todos con el ped por defecto</summary>

**Causa.** Una de estas:

* El recurso de `skins.resource` no está arrancado, así que la apariencia no se puede aplicar.
* No se jugó con ningún personaje en los últimos `skins.activeDays` días. La consola del servidor muestra un aviso y lo vuelve a intentar pasados `skins.retry` segundos.
* El servidor usa ESX. `usePlayerSkin` requiere QBox o QBCore.

**Solución.** Arranca `cuxial_appearance` antes de Cuxial Interactions y sube `skins.activeDays` en un servidor nuevo. En ESX, pon un `model` a esos puntos.

</details>

<details>

<summary>La tienda dice que no está disponible y no se puede vender nada</summary>

**Causa.** La tienda no está registrada en el servidor. O no se llamó a `RegisterShop`, o su id es distinto del `shop.id` del cliente, o el registro se rechazó: un objeto sin `price` válido, una lista vacía, o sin `coords`, `netId` ni `anywhere`. Un registro rechazado deja un aviso en la consola del servidor.

**Solución.** Llama a `RegisterShop` con el mismo id que usa el cliente. En un punto registrado con `Register`, `shop.id` vale por defecto el id del punto. Las tiendas escritas en `data/` se registran solas cuando tienen una lista `items`.

</details>

<details>

<summary>«Estás demasiado lejos del comprador» estando junto al NPC</summary>

**Causa.** El servidor mide la distancia hasta las coordenadas indicadas en `RegisterShop`, no hasta el ped. Están demasiado lejos de donde se coloca el jugador, o la distancia es corta para ese sitio.

**Solución.** Registra la tienda con las coordenadas del NPC, o sube `distance` en las opciones de esa tienda. `shop.maxDistance` cambia el valor por defecto de todas las tiendas.

</details>

<details>

<summary>La venta falla con «No tienes suficiente cantidad de este artículo»</summary>

**Causa.** El servidor cuenta menos unidades que la cantidad pedida. El nombre del objeto en la tienda no coincide con el de `ox_inventory`, o los objetos salieron del inventario con la tienda abierta.

**Solución.** Comprueba que cada `name` de la tienda es el nombre exacto del objeto en tu inventario.

</details>

<details>

<summary>Un botón no hace nada</summary>

**Causa.** Su función `onSelect` falló. La consola del cliente muestra un aviso con el id del botón y el error. En los conjuntos de ejemplo ocurre cuando un botón llama a un recurso que no está en tu servidor. Un `nextDialog` que apunta a una página que no existe, o que está desactivada, también deja un aviso.

**Solución.** Edita el botón en su archivo de `data/`, o desactiva el conjunto en `sets`. Comprueba que `nextDialog` coincide con el `id` de una página del mismo diálogo.

</details>

<details>

<summary>Mis NPC desaparecen al reiniciar cuxial_interactions</summary>

**Causa.** Reiniciar el recurso borra todos los puntos y tiendas registrados por otros recursos.

**Solución.** Regístralos de nuevo cuando arranque, en los dos lados:

```lua
-- cliente
AddEventHandler('onClientResourceStart', function(resource)
    if resource == 'cuxial_interactions' then registerNpc() end
end)

-- servidor
AddEventHandler('onResourceStart', function(resource)
    if resource == 'cuxial_interactions' then registerShop() end
end)
```

</details>

<details>

<summary>Register devuelve false</summary>

**Causa.** Una de estas:

* El id ya está registrado por otro recurso. La consola dice cuál.
* La definición no tiene ninguno de `coords`, `entity` y `netId`.
* La definición tiene `enabled = false`.
* `id` no es un string o está vacío.

**Solución.** Pon de prefijo a tus ids el nombre de tu recurso y da una ubicación al punto.

</details>

<details>

<summary>Un icono muestra un bocadillo en lugar del que escribí</summary>

**Causa.** El nombre no está en la lista de iconos de la interfaz.

**Solución.** Usa uno de los nombres listados en [Exports y eventos](/scripts/es/nucleo/cuxial-interactions/developers.md). La opción de target es distinta: `targetIcon` recibe una clase Font Awesome.

</details>

<details>

<summary>El diálogo tarda un momento en abrirse</summary>

**Causa.** La ventana espera `camera.settle` milisegundos (1500 por defecto) para que la cámara llegue antes al NPC.

**Solución.** Baja `camera.settle` y `camera.transition`, o pon `camera.enabled = false`.

</details>

<details>

<summary>El médico NPC de pago dice que no puede atender al jugador</summary>

**Causa.** El recurso de `maria.revive` no está arrancado, o su export no reanimó al jugador. En el primer caso no se cobra nada; en el segundo se devuelve el dinero. El servicio también se niega cuando el jugador está a más de `maria.maxDistance` de un NPC del conjunto de `maria.set`, o cuando hay `maria.maxOnDuty` médicos de servicio.

**Solución.** Arranca `cuxial_medical`, o apunta `maria.revive` al export de servidor de tu recurso médico; se le llama con el id de servidor del jugador y debe devolver `true`. Mantén activado el conjunto indicado en `maria.set`.

</details>

<details>

<summary>El diálogo no se muestra nunca, o la pantalla se queda con el foco y sin nada</summary>

**Causa.** La interfaz no está cargando. Falta la carpeta `web/dist` o está incompleta, normalmente por una subida parcial.

**Solución.** Comprueba que dentro del recurso existen `web/dist/index.html` y la carpeta `web/dist/assets`. Si no están, vuelve a copiar el recurso desde el paquete original y reinicia el servidor.

</details>


---

# 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/nucleo/cuxial-interactions/troubleshooting.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.