# Arsenal Nexora — instalación

Este parche agrega Arsenal Nexora 1.6.1, una tienda modular de ítems para WebEngine 1.2.6 y server files X-Team Season 6 con baúl `DbVersion 3`. La economía utiliza la estructura confirmada en ambos reinos: `CashShopData.AccountID` con `WCoinC`, `WCoinP` y `GoblinPoint`.

## Instalación

1. Haz un respaldo de los archivos de la web y de las bases de datos.
2. Copia el contenido del parche sobre la raíz de WebEngine conservando las rutas.
3. En `AdminCP → Plugin Manager → Import`, importa `plugin_itemshop_nexora.xml`.
4. Habilita `Arsenal Nexora — Item Shop`.
5. Entra en `AdminCP → Arsenal Nexora → Configuración`.
6. Selecciona primero **Seasonal** y pulsa `Instalar / validar tablas`. Repite en **Legacy** si también venderás allí.
7. Configura la moneda y el `GameServer Number` que corresponda a la fila de `GameServerInfo` usada por el reino.
8. Confirma que todos los diagnósticos aparezcan en verde.
9. Pulsa `Agregar al menú`.
10. Crea un ítem de prueba, déjalo oculto hasta validar Section, Index, dimensiones y opciones.
11. Activa la tienda solamente después de completar una compra de prueba con una cuenta desconectada.

La carpeta `templates/nexoraves6custom/img/itemshop/` debe tener permiso de escritura para que AdminCP pueda guardar imágenes promocionales. La ruta ya está declarada en `includes/config/writable.paths.json`. No le otorgues permisos de ejecución.

El parche fija el registro global de plugins en el reino principal de cuentas. De esta forma, cambiar el selector de AdminCP a Seasonal no reemplaza la caché global con el registro local de ese reino.

## Recuperación si sólo aparece Arsenal

Los plugins anteriores no fueron eliminados del disco. Aplica la versión 1.0.1 del parche y vuelve a importar `plugin_itemshop_nexora.xml`, incluso si Arsenal ya figura activo. La importación usará el registro canónico de Legado, agregará o actualizará Arsenal y reconstruirá la caché con todos los plugins anteriores.

## Reglas de entrega

- La cuenta debe estar desconectada del juego.
- El saldo, stock, serial, baúl y registro de entrega se actualizan dentro de una sola transacción SQL.
- El saldo se bloquea y descuenta directamente en `CashShopData`; el módulo no crea billeteras alternativas ni duplica monedas.
- Si no existe espacio contiguo suficiente en el baúl, la compra se rechaza sin descontar moneda.
- Si el baúl contiene un ítem cuya dimensión no puede determinarse con certeza, la compra se bloquea para no superponer ítems. Desde Arsenal 1.1.0 no se redondean dimensiones inferidas desde imágenes: el fallback sólo acepta assets con ancho y alto múltiplos exactos de 32.
- Las dimensiones cargadas en AdminCP deben coincidir con el catálogo técnico validado; desde Fase 4, `Items.xml` del Warehouse Editor es la autoridad X/Y y `Item.txt` queda como contraste.
- Cada reino mantiene configuración y catálogo separados.

## Catálogo V2

Desde la versión 1.1.0 se utiliza un token de intención por carga del catálogo en vez de crear un token por cada card. El token se consume una sola vez, expira a los 15 minutos y queda ligado al reino activo. La interfaz añade filtros por categoría, búsqueda local y una confirmación previa de entrega sin agregar frameworks ni consultas SQL por producto.

El JavaScript de Arsenal se carga únicamente en `/shop/` desde `templates/nexoraves6custom/js/itemshop.js`. La compra sigue siendo validada completamente en backend; el bloqueo visual por saldo insuficiente es sólo una optimización de experiencia.

## SQL manual

Si el usuario SQL de la web no puede crear tablas, ejecuta `includes/plugins/itemshop/sql/INSTALL_ITEMSHOP.sql` en la base `Me_MuOnline` de cada reino. Después vuelve a Configuración y verifica los diagnósticos.

## Prueba recomendada

Usa un ítem simple de 1×1 y precio bajo. Verifica el saldo anterior, desconecta la cuenta, compra una vez, abre el baúl desde el cliente y confirma:

- nombre/código y opciones;
- posición sin superposición;
- descuento correcto;
- saldo final;
- fila nueva en `Arsenal Nexora → Entregas`.


## AdminCP asistido V2 · Fase 2

Arsenal 1.2.0 reorganizó la administración sin añadir carga al frontend público:

- `Section` usa etiquetas por familia. Desde Arsenal 1.3.0, `Index` admite 0–511 conforme al formato DbVersion 3 confirmado con el Warehouse Editor.
- El formulario verifica el asset instalado y muestra una previsualización del código seleccionado.
- La medida del baúl solo puede aplicarse automáticamente cuando el asset de referencia tiene ancho y alto múltiplos exactos de 32 y el resultado cabe en la cuadrícula 8×15. No se redondean imágenes ambiguas.
- Si un código Section:Index ya existe en Arsenal, su nombre, categoría y dimensiones quedan disponibles como referencia para altas nuevas.
- Ancient y Harmony se mantienen disponibles, pero separados como opciones avanzadas.
- El catálogo administrativo incorpora búsqueda y filtros locales, sin consultas SQL por fila.
- Se puede duplicar una configuración existente para crear variantes; la copia nace oculta y no duplica la imagen promocional.
- Los POST de Arsenal utilizan la protección CSRF central ya aplicada por `NexoraSecurity`; no se mantiene un segundo token paralelo.
- Publicar u ocultar un ítem queda registrado en `NexoraAudit`.

El JavaScript y CSS de esta fase viven únicamente en `admincp/js/itemshop-admin.js` y `admincp/css/itemshop-admin.css`; no se cargan en `/shop/`.

## Arsenal V2 Fase 3 · Item.txt

La Fase 3 incluye `includes/plugins/itemshop/data/item-catalog.json`, generado desde el Item.txt del servidor. No requiere importación SQL.

Si el Item.txt cambia, reconstruye el catálogo con:

```bash
php includes/plugins/itemshop/tools_build_item_catalog.php /ruta/al/Item.txt
```

La Fase 4 valida el encoder extendido y habilita Index 0–511. Después de actualizar, ejecuta `Instalar / validar tablas` en cada reino para migrar el constraint SQL.

## Arsenal V2 Fase 4 · Index extendido y Items.xml

DbVersion 3 fue contrastado contra HEX reales del Warehouse Editor. El bit alto de Index (`0x100`) se guarda en `byte 7 / 0x80`, por lo que Arsenal admite de forma comprobada índices `0–511`.

Después de instalar esta versión, en **Seasonal y Legacy** pulsa `Instalar / validar tablas`. El diagnóstico `Índices extendidos 0–511` debe aparecer en verde.

Para regenerar el catálogo técnico usa preferiblemente ambas fuentes:

```bash
php includes/plugins/itemshop/tools_build_item_catalog.php /ruta/Items.xml /ruta/Item.txt
```

`Items.xml` es la autoridad de ocupación física X/Y porque es la definición consumida por el Warehouse Editor. `Item.txt` se conserva como contraste. Si discrepan, AdminCP lo señala y Arsenal usa X/Y de `Items.xml` para evitar superposiciones.


## Arsenal V2 Fase 5 · Opciones inteligentes

Arsenal 1.4.0 incluye `includes/plugins/itemshop/data/item-options.json`. El archivo ya viene generado y no se procesa ningun XML en cada visita.

Despues de actualizar, entra en **Seasonal** y **Legacy** y pulsa `Instalar / validar tablas`. Ademas de `Indices extendidos 0-511`, el diagnostico `Motor de opciones inteligentes` debe quedar en verde.

El editor utiliza las fuentes tecnicas para limitar Excellent, Skill/Luck/opcion adicional, Ancient, Harmony, Socket y Level380. Los valores raw quedan encapsulados en backend. Los perfiles Excellent especiales 3/4/5 se mantienen bloqueados si las fuentes no aportan un mapa de bits verificable; Arsenal no inventa opciones. Los cinco slots Socket se almacenan de forma explicita y `socket_count` se mantiene solo como resumen compatible.

Si cambian los XML del Warehouse Editor, regenera el catalogo con:

```bash
php includes/plugins/itemshop/tools_build_option_catalog.php \
  /ruta/Ancient_Items.xml /ruta/Ancient_Type.xml \
  /ruta/Harmony_Attack.xml /ruta/Harmony_Defensive.xml \
  /ruta/Harmony_Staffs.xml /ruta/Socket_Options.xml
```

Antes de publicar en masa opciones 380, Ancient, Harmony o Socket, realiza al menos una entrega controlada de cada familia y comprueba el HEX/resultado con el Warehouse Editor. Las muestras proporcionadas confirmaron exactamente el formato de Index extendido; no incluian cada opcion especial activada.

## Fase 6 - Navegacion Comercial

Si vienes de Arsenal V2 Fase 5, copia el PATCH Fase 6 sobre la raiz de WebEngine y reemplaza los archivos indicados.

No requiere cambios SQL ni volver a instalar tablas.

Validacion visual recomendada:

1. En desktop (>960 px), confirmar que `Arsenal` aparece como acceso directo en el topbar.
2. Abrir la flecha contigua y comprobar Economia Nexora: Arsenal, Beneficios, WCoinC y, con sesion, VIP.
3. En movil (<=960 px), abrir el menu hamburguesa y confirmar que Economia Nexora aparece antes del menu general.
4. En Home, confirmar la tarjeta Arsenal y accesos secundarios Beneficios/WCoinC.
5. Abrir `/shop/` y confirmar que Arsenal queda marcado como activo.


## Fase 7 - Armory Experience

Si vienes de Arsenal V2 Fase 6, copia el PATCH Fase 7 sobre la raiz de WebEngine. No requiere cambios SQL ni volver a instalar tablas.

Validacion visual recomendada:

1. Abrir `/shop/` en 1440p/1080p y comprobar cabecera compacta, saldo y estado del reino.
2. Verificar que la barra de categorias permanece disponible al hacer scroll y que `Todo`, categorias, `Seleccion` y `Ofertas` filtran sin recargar la pagina.
3. Probar busqueda y orden por precio/nombre/recientes.
4. Con 1, 2 y 3 productos visibles, confirmar que el grid no deja columnas fantasma.
5. Revisar un item con render tecnico y otro con imagen promocional: el primero usa `contain`; el segundo usa composicion `artwork`.
6. Abrir una adquisicion y confirmar imagen, traits, reino, precio, saldo actual/posterior, stock y destino.
7. Probar <=640 px y <=430 px; las cards tienen composicion movil propia.
8. Hacer una compra controlada con la cuenta offline para confirmar que el rediseño no altera entrega, saldo o Warehouse.


## Fase 7.1 - Dirección de arte

Si vienes de Arsenal V2 Fase 7, copia el PATCH Fase 7.1 sobre la raíz de WebEngine. No requiere SQL, reinstalar tablas ni reconfigurar el plugin.

Validación visual recomendada:

1. En 1080p/1440p, confirmar que el destacado completo muestra imagen, nombre, traits, precio y CTA sin ocupar todo el viewport.
2. Comprobar que un render técnico pequeño conserva su tamaño natural y no se pixela por upscale agresivo.
3. Confirmar que una imagen promocional sigue usando composición `cover`.
4. Verificar que el inicio del catálogo normal aparece inmediatamente después de la Selección.
5. Revisar tablet, <=640 px y <=430 px.
6. Abrir la Orden de adquisición y hacer una compra controlada para confirmar que backend y Warehouse permanecen sin cambios.

## Fase 7.3 - Render cache

La Fase 7.3 no requiere SQL. El paquete ya incluye el cache `templates/nexoraves6custom/img/itemshop-renders-v1/` para el pack de imágenes entregado.

Si en el futuro reemplazas o amplías `templates/nexoraves6custom/img/item_images/`, reconstruye el cache desde consola con:

`php includes/plugins/itemshop/tools_build_render_cache.php`

El comando requiere PHP GD con soporte WebP y nunca debe ejecutarse desde una petición web.

## Fase 7.3.1 - estándar de imagen promocional

No requiere SQL. Para las imágenes personalizadas de Arsenal utiliza preferiblemente **WEBP de 1600 × 900 px (16:9)**, con un peso objetivo de **250–600 KB**. Mantén el foco principal dentro del **70% central** para protegerlo de recortes en desktop, tablet y móvil. El máximo técnico de carga continúa siendo 2 MB.
