Documentación de Tiendas y negocios con NPC

Otra Vida Negocios (ov_negocios)

Que hace

ov_negocios convierte las tiendas de tu servidor FiveM (qb-core) en negocios con un NPC vivo detras del mostrador, una rejilla de productos por categorias y compra con efectivo o banco. Los administradores crean y editan negocios desde un menu dentro del juego, sin tocar archivos, y pueden asignar un dueno a cada uno.

Lo mas importante:

• NPC con vida: el dependiente cambia de postura, camina un poco dentro de un radio y saluda al atender. Se puede desactivar el movimiento por negocio.
• Rejilla de productos por categorias, con imagen del item, precio y, si el negocio tiene dueno, existencias.
• Compra validada en el servidor: distancia al mostrador, precio real, existencias, espacio en el inventario y saldo. Si algo falla, no se cobra.
• Catalogos incluidos (18 en Config.Catalogos): tienda 24/7, gasolinera, licoreria, tienda de armas blancas y mejoras, municiones, maquina expendedora, tienda de gang, farmacia y otros. Todos editables.
• Negocios con dueno: existencias limitadas, precio fijado por el dueno dentro de un rango, y caja propia donde cae el dinero de las ventas.
• Registro de ventas, retiros, depositos y reposiciones por negocio.
• Menu de administracion /negocios para crear, abrir o cerrar, mover, renombrar, cambiar catalogo o NPC, asignar dueno y eliminar.
• Marcas en el mapa opcionales por negocio.

Alcance actual: la gestion del dueno (retirar dinero de la caja, depositar, reponer existencias y cambiar precios) existe como callbacks y exports del servidor, pero el recurso no incluye una pantalla para el dueno. Si quieres que los jugadores gestionen su negocio, necesitas conectar esas funciones a tu propia interfaz (ver Comandos y permisos).

Requisitos

Todos los items de los catalogos deben existir en ox_inventory. Los catalogos de ejemplo usan items como water_bottle, sandwich, bandage o phone, que debes tener definidos o sustituir por los tuyos.

Instalacion

1. Descarga el recurso desde el Portal de Cfx.re (seccion de assets comprados) con la cuenta Cfx.re con la que hiciste la compra. El recurso viene protegido con Asset Escrow de Cfx.re: solo funciona en servidores cuya clave de licencia pertenece a tu cuenta.
2. Copia la carpeta ov_negocios dentro de resources.
3. Revisa los catalogos de shared/config.lua y ajusta los items a los que existan en tu ox_inventory.
4. Agrega en server.cfg, despues de ox_lib, oxmysql, qb-core y ox_inventory:

   ensure ov_negocios

1. Da el permiso de administracion:

   add_ace group.admin ov_negocios.admin allow

1. Inicia el servidor. No hay archivo .sql: al arrancar se crean solas las tablas ov_negocios, ov_negocios_stock y ov_negocios_log (CREATE TABLE IF NOT EXISTS).
2. Entra al juego y crea tus negocios con /negocios (ver Para administradores). El paquete no trae negocios precargados: se crean en la posicion donde esta parado el administrador.

El codigo no lee convars de server.cfg.

Archivos editables: en el fxmanifest.lua, escrow_ignore deja sin cifrar web/** (interfaz) y shared/config.lua. El resto (client/ y server/) va cifrado por Asset Escrow.

Configuracion

Todo esta en shared/config.lua. Opciones principales:

Estructura de un catalogo:

Config.Catalogos.mi_tienda = {
    etiqueta = [[Mi tienda]],
    categorias = {
        { id = 'bebidas', nombre = 'Bebidas', items = {
            { item = 'water_bottle', precio = 150, max = 60 },
        } },
    },
}

max es el maximo de existencias que el dueno puede reponer de ese producto. Los catalogos de ejemplo incluyen nombres comerciales de tiendas y precios de muestra: ajustalos a tu servidor.

Comandos y permisos

Exports del servidor (para conectar una interfaz de gestion del dueno)

Callbacks de ox_lib (uso interno y para integraciones): ov_negocios:abrir, ov_negocios:comprar, ov_negocios:mis, ov_negocios:panel, ov_negocios:retirar, ov_negocios:depositar, ov_negocios:reponer, ov_negocios:precio. Todas validan en el servidor que quien llama es el dueno del negocio.

Como se usa

Comprar

1. Acercate al NPC del mostrador. Aparece [E] <nombre del negocio>.
2. Pulsa E. Se abre la rejilla y el NPC se gira hacia ti.
3. Elige productos y cantidades (hasta el maximo de lineas y unidades configurado).
4. Elige pagar con efectivo o banco y confirma.
5. Recibes los items en el inventario. Si no tienes saldo, el producto ya no esta disponible, no te cabe en el inventario o estas lejos del mostrador, el servidor lo rechaza con un aviso.

Negocios con dueno: solo se vende lo que hay en existencias, al precio que fijo el dueno, y el dinero va a la caja del negocio. En negocios sin dueno las existencias son ilimitadas, al precio del catalogo.

Para administradores

1. Escribe /negocios (con el permiso asignado).
2. Crear negocio aqui: coloca el NPC donde estas parado. Eliges nombre, catalogo y modelo de NPC. El servidor impide crear dos negocios a menos de 2 metros.
3. Al abrir un negocio de la lista puedes:
4. Abrirlo o cerrarlo.
5. Moverlo a tu posicion actual.
6. Activar o desactivar el movimiento del NPC.
7. Cambiar nombre, catalogo o NPC.
8. Asignar o quitar dueno (por ID de jugador conectado).
9. Eliminarlo. Si la caja tiene dinero, no se puede eliminar hasta retirarlo.
10. Los cambios se guardan en la base de datos y se difunden a los jugadores conectados.
11. Para anadir productos o catalogos nuevos, edita Config.Catalogos y reinicia el recurso.
12. El historial de cada negocio queda en ov_negocios_log.

Preguntas frecuentes

No veo el aviso para comprar. Debes estar cerca del NPC, y el negocio debe estar abierto. La distancia sale de Config.DistanciaInteraccion.

La imagen de un producto no aparece. La interfaz usa las imagenes de ox_inventory. Comprueba que existe <item>.png en la carpeta de imagenes de ox_inventory.

Por que mi compra dice "No tienes espacio en el inventario"? El pedido completo no cabe. Reduce las cantidades.

Puedo cambiar los precios? Si, en Config.Catalogos. Un dueno puede variar el precio entre Config.MultiplicadorPrecioMin y Config.MultiplicadorPrecioMax veces el precio de catalogo, a traves de las funciones del servidor.

Los jugadores pueden gestionar su negocio desde el juego? El recurso incluye la logica del servidor, no una pantalla. Puedes conectar los callbacks y exports a tu propia interfaz.

Donde veo los errores? En la consola del servidor (mensajes [ov_negocios]) y en F8.

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re (en tus recursos comprados) y en la tienda. Descargalas con la misma cuenta Cfx.re de la compra y reemplaza la carpeta, conservando tus cambios en shared/config.lua. Para soporte, abre un ticket en el Discord de la tienda: [enlace de soporte]. Indica la version del recurso, el error de consola y los pasos para reproducirlo.