🚀 Inicio rápido

Instala AxinMenuGUI y crea tu primer menú en minutos.

📥 Instalación

1. Copia AxinMenuGUI_v0.9.5.zip en la carpeta Mods/ del servidor.
2. Reinicia el servidor. Se generan los ficheros de configuración y menús de ejemplo.
3. Verifica en los logs: [AxinMenuGUI] Alias registrado: /menu → 'ejemplo'
4. Entra al juego y escribe /menu para ver el menú de ejemplo.

📂 Ficheros generados

ModConfig/AxinMenuGUI/
├── config.json             # Configuración global (idioma, killPoints, ranking, RTP, market)
├── adminteleports.json     # Puntos ATP guardados con /atp set (auto-generado)
├── menus/                  # Tus ficheros JSON de menú
│   ├── ejemplo.json        # Menú índice con submenús (/menu)
│   ├── ejemplo_jugador.json
│   ├── ejemplo_stats.json
│   ├── ejemplo_temas.json  # 13 escenas, un tema por pestaña (/temas)
│   ├── ejemplo_tp.json     # Panel de teleport admin (ATP, RTP, waypoints)
│   └── ...
├── playerdata/             # Stats por jugador (auto-generado)
│   └── {uid}.json
├── bank/                   # Snapshots de Banks por jugador (auto-generado)
│   └── {uid}.json
├── missions/               # Configuración de misiones (auto-generado)
│   └── killranking.json
└── marketlog/              # Log persistente de transacciones de mercado (auto-generado)
    └── market_log_{fecha}.json

🎯 Tu primer menú

hola.json{
  "id": "hola",
  "title": "Mi primer menú",
  "theme": "dark-red",
  "rows": 3,
  "commandAlias": "hola",
  "scenes": {
    "0": {
      "items": {
        "saludo": {
          "slot": 13,
          "item": "axinmenugui:menuicon-star",
          "name": "Hola, {player}!",
          "lore": ["Clic para saludar"],
          "clickEvents": {
            "msg": { "type": "message", "message": "¡Bienvenido, {player}!" }
          }
        }
      }
    }
  }
}

Guarda el fichero en ModConfig/AxinMenuGUI/menus/ y ejecuta /amenu reload. Luego /hola para abrir el menú.

📋 Comandos y permisos

Todos los comandos disponibles en AxinMenuGUI.

🏪 Mercado global (/market)

El mercado P2P permite a los jugadores publicar y comprar ofertas. Todos los subcomandos requieren privilegio chat.

⚡ Teleport administrativo (ATP)

Gestiona puntos de teletransporte guardados en el servidor. Todos requieren privilegio controlserver.

🌀 Teletransporte aleatorio (RTP)

Teletransporta al jugador a una posición aleatoria segura. Requiere privilegio controlserver.

Output de /amenu player

[AxinMenuGUI] Stats: elYandrack
  timeRealSeconds:       77  (1m 17s)
  timeGameDays:          0.00
  deaths:                0
  mobKillsAll:           4
  mobKillsHostile:       3
  mobKillsHostilePoints: 22.5
  playerKills:           0
  ranking.position:      #1

⚙ Configuración global

El fichero config.json se genera automáticamente al primer inicio.

ModConfig/AxinMenuGUI/config.json{
  "language": "en",
  "rankingSize": 10,
  "rankingField": "mobKillsHostilePoints",
  "killPoints": {
    "drifter-normal":        0.5,
    "drifter-deep":          2.0,
    "drifter-tainted":       4.0,
    "drifter-corrupt":       8.0,
    "drifter-nightmare":     14.0,
    "drifter-double-headed": 20.0
    // ... 29 mobs en total
  },
  "randomTeleport": {
    "defaultMin":          5000,
    "defaultMax":          10000,
    "maxAttempts":         40,
    "claimMargin":         128,
    "storyZoneMargin":     256,
    "forbidWater":         true,
    "requireTwoAirBlocks": true
  },
  "saveIntervalSeconds":            30,
  "rankingCacheSeconds":            60,
  "marketLogRetentionDays":         30,
  "marketLogFlushSeconds":          30,
  "marketSellWizardTimeoutSeconds":  60
}

🏪 Bloque market

🌀 Bloque randomTeleport

Configuración del teletransporte aleatorio (/artp y click event randomTeleport).

🖼 Estructura del GUI

Anatomía completa de un menú JSON.

mi_menu.json{
  "id": "mi_menu",
  "title": "Mi Menú",
  "theme": "dark-red",
  "rows": 3,
  "commandAlias": "menu",
  "commandAliasTarget": "OPTIONAL",
  "permission": "",
  "openTriggers": [],
  "scenes": {
    "0": {
      "delay": 0,
      "theme": "parchment",
      "items": {
        "boton1": {
          "slot": 13,
          "item": "axinmenugui:menuicon-star",
          "amount": 1,
          "name": "Hola, {player}!",
          "lore": ["Primera línea", "Segunda línea"],
          "hideOnFail": false,
          "clickEvents": {
            "ev1": { "type": "message", "message": "¡Hola!" }
          },
          "conditions": {},
          "conditionFailMessage": ""
        }
      }
    }
  }
}

📄 Escenas y navegación

Un menú puede tener múltiples escenas (páginas). Cada escena puede tener su propio tema visual.

🗂 Múltiples escenas

"scenes": {
  "0": { "theme": "dark-red",  "items": { ... } },
  "1": { "theme": "dark-blue", "items": { ... } },
  "2": { /* sin theme → hereda el del menú */ "items": { ... } }
}

🧭 Click events de navegación

🔗 Patrón submenús con back

// En el menú índice:
"sub_stats": {
  "slot": 13,
  "item": "axinmenugui:menuicon-trophy",
  "name": "Estadísticas",
  "clickEvents": {
    "open": { "type": "openGui", "guiId": "ejemplo_stats" }
  }
}

// En ejemplo_stats.json:
"volver": {
  "slot": 17,
  "item": "axinmenugui:menuicon-back",
  "name": "← Volver",
  "clickEvents": {
    "back": { "type": "back" }
  }
}

🎨 Temas visuales

14 temas Cairo para personalizar completamente el aspecto de tus menús.

🖼 Cómo aplicar un tema

Añade el campo "theme" al menú y/o a cada escena:

{
  "id": "mi_menu",
  "theme": "dark-red",    // tema por defecto del menú
  "scenes": {
    "0": { "theme": "parchment", "items": { ... } },  // sobreescribe el del menú
    "1": { "items": { ... } }                         // hereda "dark-red"
  }
}

🎨 Temas disponibles (14)

📐 Diferencias entre variantes

🖱 Click Events

Acciones que se ejecutan al hacer clic en un botón del menú.

Ejemplos de uso

// message
"ev": { "type": "message", "message": "Hola {player}, estás en {pos}" }

// openGui (submenú)
"ev": { "type": "openGui", "guiId": "mi_submenu" }

// back
"ev": { "type": "back" }

// consoleCommand
"ev": { "type": "consoleCommand", "commands": ["/tp {player} 0 150 0"] }

// giveItem
"ev": { "type": "giveItem", "itemCode": "game:ingot-iron", "quantity": 5 }

// setVariable
"ev": { "type": "setVariable", "field": "puntos", "op": "add", "value": 10 }

// teleport — coordenadas fijas separadas por coma
"ev": { "type": "teleport", "location": "0,150,0" }

// teleportSaved — usa un punto ATP guardado con /atp set
"ev": { "type": "teleportSaved", "target": "spawn" }

// randomTeleport — radios explícitos (0,0 usa defaults de config.json)
"ev": { "type": "randomTeleport", "radiusMin": 1000, "radiusMax": 5000 }

✅ Condiciones

Muestra u oculta botones según el estado del jugador.

"conditions": {
  "es-admin": { "type": "hasPrivilege", "privilege": "controlserver", "inverted": false }
},
"hideOnFail": true,
"conditionFailMessage": "Solo administradores."

🖼 Iconos del mod

58 iconos pixel art 32×32 incluidos en AxinMenuGUI. Úsalos en cualquier botón de tus menús.

🧭 Navegación

ℹ UI / Información

🛒 Tienda / Economía

👤 Social / Admin / Roles

✨ Decorativos / Misc

💡 Cómo añadir iconos propios

Puedes añadir tus propios iconos al mod creando los ficheros necesarios:

1. Coloca el PNG (32×32, fondo transparente, estilo pixel art) en:
   assets/axinmenugui/textures/item/menuicon-MINOMBRE.png
2. Crea el fichero de itemtype en:
   assets/axinmenugui/itemtypes/menuicon-MINOMBRE.json
3. El contenido del JSON del itemtype es:

menuicon-MINOMBRE.json{
  "code": "menuicon-MINOMBRE",
  "class": "Item",
  "maxStackSize": 1,
  "texture": { "base": "axinmenugui:item/menuicon-MINOMBRE" }
}

4. Reinicia el servidor. Usa el icono con: "item": "axinmenugui:menuicon-MINOMBRE"

💾 Player Data y Stats

Variables persistentes por jugador: stats automáticos, campos personalizados, cooldowns.

📊 Stats automáticos

El mod trackea automáticamente al entrar, morir y matar entidades:

🎯 Puntos por mob

Los puntos se calculan con lookup progresivo: wolf-male-adult → prueba wolf-male → prueba wolf. Configúralos en config.json.

📋 Ranking

El ranking se calcula automáticamente sobre el campo rankingField (por defecto mobKillsHostilePoints). Se refresca con caché de 30 segundos.

🔗 Tokens / Placeholders

Variables dinámicas que puedes usar en cualquier campo de texto del menú.

💬 Chat Fetcher

Solicita input al jugador vía chat. Fase 3

⚡ Modos de apertura

Formas de abrir un menú en AxinMenuGUI.

📦 Menús de ejemplo incluidos

8 menús se generan automáticamente al instalar el mod.

Navegación del menú principal

/menu → ejemplo.json (índice)
    ├── Sobre ti     → ejemplo_jugador.json  [← Volver]
    ├── Estadísticas → ejemplo_stats.json    [← Volver]
    ├── Tienda       → ejemplo_tienda.json
    ├── Panel Admin  → ejemplo_admin.json    (oculto si no es admin)
    └── Teleport TP  → ejemplo_tp.json       (oculto si no es admin)

🗺 Roadmap

Plan de desarrollo por fases del mod.

⚔ AxinMenuGUI vs GUIPlus

Diferencias y equivalencias entre los dos sistemas.

🏪 Mercado Global P2P

Permite a los jugadores publicar ofertas de venta y comprar ítems de otros jugadores. Las transacciones usan escrow automático.

🚀 Cómo acceder

Usa el comando /market o /amenu market para abrir el menú principal. No requiere permisos especiales.

🛒 Flujo de compra

1. Abre el mercado con /market.
2. Selecciona Comprar para ver ítems disponibles agrupados por tipo.
3. Selecciona un ítem para ver los vendedores, precio y cantidad disponible.
4. Haz clic en la oferta que quieras comprar. El sistema verificará que puedes pagar (inventario + Treasury + Bank cerrados).
5. Si la compra prospera, los ítems aparecen en tu inventario y el vendedor recibe una notificación.

💰 Flujo de venta — venta rápida

Para publicar una oferta directamente sin GUI:

/amenu market sell <itemCode> <cantidad> <precioItem> <precioCantidad>

Ejemplo: vender 10 lingotes de hierro a 2 engranajes oxidados cada uno
/amenu market sell game:ingot-iron 10 game:gear-rusty 2

Los ítems se retiran inmediatamente del inventario y quedan en escrow hasta ser comprados o cancelados.

🧙 Flujo de venta — asistente personalizado

Para iniciar el wizard interactivo, ejecuta /amenu market sell sin argumentos. Se abre la GUI de tu inventario y el proceso es guiado por chat:

1. Haz clic en el ítem de tu inventario que quieres vender.
2. Si tienes más de 1 unidad, escribe por chat la cantidad a vender.
3. Selecciona en la GUI (o escribe por chat en formato dominio:codigo) el ítem que pides como precio.
4. Escribe por chat la cantidad de ese ítem que pides por cada unidad vendida.
5. La oferta se publica y los ítems pasan a escrow.

📋 Gestión de ofertas

📦 Estado de una oferta

📝 Log de transacciones

Todas las transacciones quedan registradas en ModConfig/AxinMenuGUI/marketlog/. Los archivos se rotan diariamente y se purgan automáticamente pasados marketLogRetentionDays días (default 30).

🏦 Bank (bloque)

Cofre especial crafteable que actúa como fuente de pago secundaria en el Mercado Global.

📐 Qué es el Bank

El Bank es un bloque de almacenamiento similar a un cofre. La diferencia clave es que el Mercado Global usa automáticamente los ítems del Bank como fuente de pago cuando el inventario del jugador no es suficiente, siempre que el Bank esté cerrado en el momento de la transacción.

🔨 Crafteo

El Bank se craftea con planchas de madera (cualquier tipo), clavos metálicos y piedra tallada. La receta exacta está disponible en el Handbook del juego buscando "Bank".

🏗 Colocación y uso

1. Coloca el Bank en el mundo como cualquier cofre.
2. Ábrelo con clic derecho para guardar ítems.
3. Al cerrarlo, el servidor sincroniza el contenido en ModConfig/AxinMenuGUI/bank/{uid}.json.
4. Cuando realices una compra en el mercado, el sistema sumará automáticamente el saldo de todos tus Banks cerrados al calcular si puedes pagar.

📊 Múltiples Banks

Un jugador puede tener varios Banks colocados. El servicio los identifica por su posición en el mundo. Todos los Banks cerrados de un mismo jugador contribuyen al saldo total disponible para el mercado.

🗂 Persistencia

Los snapshots se guardan en ModConfig/AxinMenuGUI/bank/{uid}.json, uno por jugador, con la lista de Banks y su contenido en el momento del último cierre.

🎯 KillRanking Missions

Recompensa automática y única cuando un jugador cruza un umbral de puntos de ranking de kills hostiles.

📄 Fichero de configuración

Se genera automáticamente en ModConfig/AxinMenuGUI/missions/killranking.json con valores de ejemplo. Se recarga con /amenu reload.

missions/killranking.json{
  "DocVersion": "0.1",
  "RankingBonus": {
    "10": {
      "message":     "¡Has alcanzado 10 puntos de ranking!",
      "all_message": "{player} ha alcanzado 10 puntos de ranking.",
      "give": { "type": "item", "code": "game:gear-rusty", "amount": 1 },
      "command":     "/amenu ranking"
    },
    "50": {
      "message":     "¡Leyenda! 50 puntos de ranking.",
      "all_message": "{player} ha alcanzado 50 puntos de ranking.",
      "give": { "type": "item", "code": "game:ingot-iron", "amount": 5 },
      "command":     null
    }
  }
}

📋 Campos de un hito

⚙ Comportamiento

• Cada hito se concede exactamente una vez por jugador, aunque los puntos bajen y vuelvan a subir.
• La verificación ocurre en el momento del kill, sin I/O adicional (todo en memoria).
• Los umbrales se evalúan de menor a mayor; si un jugador sube varios umbrales de golpe, recibe todos.
• Las recompensas no concedidas (give: null) se omiten sin error.
• El estado "ya concedido" persiste en playerdata/{uid}.json y sobrevive a reloads y reinicios.