# Arsenal Nexora V2 · Fase 3 — Catálogo autoritativo

## Objetivo

Convertir `Item.txt` en la fuente técnica de verdad para la identidad y el tamaño de los ítems de Arsenal, sin cargar el archivo bruto en el frontend público y sin ampliar de forma insegura el encoder DbVersion 3 actual.

## Fuente integrada

- Fuente recibida: `Item.txt` de MuServerPro.
- Entradas normalizadas: **1.839**.
- Compatibles con el encoder actual (`Index 0–255`): **1.594**.
- Entradas con `Index >255`: **245**.
- El catálogo normalizado conserva Section, Index, nombre, Width, Height, Slot, Skill, HaveSerial, HaveOption y DropItem.

El hash SHA-256 de la fuente queda guardado dentro de `includes/plugins/itemshop/data/item-catalog.json` para poder identificar exactamente qué Item.txt originó el catálogo.

## Cambios de AdminCP

En `Arsenal Nexora → Nuevo ítem / Editar ítem` se añadió un selector nativo del catálogo del servidor:

1. Buscar por nombre o por código `Section:Index`.
2. Al seleccionar un ítem compatible se aplican Section, Index, nombre y dimensiones reales de `Item.txt`.
3. El asset visual del template continúa usándose únicamente como verificación visual, no como fuente primaria de dimensiones.
4. Los ítems con Index mayor de 255 siguen visibles en la búsqueda, pero quedan marcados como **bloqueados** y no alteran el código de entrega actual.
5. Si se introduce manualmente un código existente en Item.txt, el formulario muestra su definición oficial.
6. Si Width/Height no coinciden con Item.txt, el formulario y el backend impiden guardar la configuración.

## Seguridad de entrega

No se amplió el encoder de ítems. El esquema SQL y `validateItemInput()` continúan limitando `item_index` a 255.

Esto es intencional: el encoder actual escribe `item_index` en un byte. Los 245 customs con índices superiores necesitan primero una definición confirmada del formato extendido utilizado por el GameServer antes de habilitarlos en compras.

## Runtime y rendimiento

- El `Item.txt` bruto no se analiza en cada request.
- El catálogo se genera una sola vez como JSON compacto.
- `class.itemshop.php` lo mantiene en caché estática durante el request.
- El catálogo técnico se utiliza en AdminCP y como fallback autoritativo de dimensiones al inspeccionar objetos del baúl.
- No se añadieron consultas SQL por ítem.
- No se añadieron frameworks ni servicios externos.
- El frontend público no recibe el catálogo completo.

## Regenerar el catálogo

Cuando cambie Item.txt:

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

El generador es CLI-only y rechaza ejecución web.

## Archivos principales

- `includes/plugins/itemshop/data/item-catalog.json`
- `includes/plugins/itemshop/tools_build_item_catalog.php`
- `includes/plugins/itemshop/classes/class.itemshop.php`
- `admincp/modules/itemshop/form.php`
- `admincp/js/itemshop-admin.js`
- `admincp/css/itemshop-admin.css`

## Siguiente frontera

Para soportar de forma segura los `Index >255` no basta con subir el límite del formulario o de SQL. Primero hay que confirmar cómo codifica el GameServer esos índices dentro del formato de 16 bytes de Warehouse DbVersion 3 (o si usa otra estructura/flags). Hasta entonces se mantienen fuera de la entrega automática.
