🚀 Instalación

Ruta recomendada para admins: instalar, rellenar lo mínimo, reiniciar y usar /ams appweb.

1. Descargar e instalar el mod

1. Descarga la última versión del mod compatible con tu Vintage Story desde la página oficial de mods (ModDB de VS).
2. Copia el ZIP descargado, sin descomprimir, en la carpeta Mods/ de tu servidor.
3. Arranca el servidor una vez. En ese primer arranque se crea el archivo ModConfig/axinbridge/config.json que vas a editar en el siguiente paso.

2. Crear una clave privada

La clave privada protege el bridge. No la escribas en la app web cuando uses relay; el relay la usará por detrás.

# Windows
scripts\gen-apikey.cmd

# Linux / macOS
openssl rand -hex 32

3. Rellenar la configuración mínima

Edita ModConfig/axinbridge/config.json. Para el camino recomendado con relay, rellena estos campos:

axinbridge/config.json{
  "Port": 42421,
  "ListenAddress": "+",
  "ApiKey": "TU_API_KEY_GENERADA",
  "RelayEnabled": true,
  "RelayUrl": "https://bridgerelay.axin.es",
  "RelaySlug": "mi-servidor",
  "PublicBridgeUrl": "http://TU_IP_PUBLICA:42421",
  "RateLimitPerMinute": 30
}

Si ves en el JSON otros campos relacionados con el relay o una URL final del dashboard, no los rellenes a mano: los escribe el mod automáticamente cuando arranca y se registra.

Reinicia el servidor. En los logs debe aparecer una línea del tipo:

[AxinBridge] Listening on http://+:42421/

Con RelayEnabled=true, el mod intentará registrarse solo en el relay. Puedes comprobar el estado con /ams relay status.

4. Abrir la app

1. Asegúrate de que el puerto configurado está abierto en tu hosting/firewall.
2. Entra al juego como jugador.
3. Ejecuta /ams appweb.
4. Abre el enlace que aparece en el chat.
5. La app debería aparecer con el servidor y el código de vinculación preparados. Si falta la URL, la guía de conexión te dirá qué campo falta.

Página de conexión del dashboard:

⚙ Configuración

Qué campos debe tocar un admin y qué campos escribe el mod automáticamente.

🔧 Bloque recomendado

axinbridge/config.json{
  "Port": 42421,
  "ListenAddress": "+",
  "ApiKey": "TU_API_KEY_GENERADA",
  "RelayEnabled": true,
  "RelayUrl": "https://bridgerelay.axin.es",
  "RelaySlug": "mi-servidor",
  "PublicBridgeUrl": "http://TU_IP_PUBLICA:42421",
  "RateLimitPerMinute": 30
}

El puerto por defecto del mod es 42421. Si tu hosting permite abrirlo, deja ese valor — los ejemplos de la wiki lo usan. Si está ocupado o tu hosting te obliga a otro, elige uno y úsalo igual en Port, en PublicBridgeUrl y en el firewall.

📋 Campos para admins

🤖 Campos que escribe el mod

Estos campos pueden aparecer en el JSON, pero no son tareas normales del admin:

• ServerApiUrl: URL final que debe usar la app. El mod la calcula cuando puede.
• RelayServerId y RelayOwnerToken: identidad interna del servidor en el relay.
• RelayAssignedSlug: nombre confirmado por el relay. Puede coincidir con RelaySlug o cambiar si el solicitado no está disponible.

♻ Recarga en caliente

Usa /ams reload ingame. La config se relee de disco y se aplica sobre la instancia viva sin romper sesiones activas.

📋 Comandos /ams

Comandos ingame del AXINServerBridge. Para la mayoría de jugadores, el importante es /ams appweb.

📐 Sintaxis general

El comando raíz es /ams. Algunos subcomandos son para jugadores y otros requieren permisos de administrador.

🔧 Subcomandos

🚫 Si algo falla

Usa /ams status y /ams relay status. Si el problema está en la URL pública, normalmente será uno de estos tres puntos: puerto cerrado, PublicBridgeUrl con puerto incorrecto o relay todavía sin registro.

🔌 Conexión y login

Distingue dos cosas: conectar la app al servidor y vincular tu jugador dentro de la app.

🌐 Camino recomendado: /ams appweb

1. Entra al servidor de Vintage Story.
2. Ejecuta /ams appweb.
3. Abre el enlace del chat.
4. La app recibe el código de vinculación y, si el mod ya conoce la URL pública, también recibe la URL del servidor.

🔑 Modo directo (solo despliegues controlados)

Si conectas la web directamente al bridge, usa http://host:puerto y proporciona la API key. Ese modo sigue existiendo, pero no es la vía pública normal cuando el relay está activo.

🎟 Vinculación de sesión

1. En el juego, ejecuta /ams link. Recibes un código corto.
2. En el dashboard, introduce el código en el formulario de vinculación.
3. La sesión queda guardada para no tener que repetir el proceso cada vez que se reinicia el servidor.

🔒 Login por contraseña (opcional)

Si el admin deja activadas las contraseñas, un jugador vinculado puede crear una contraseña para volver a entrar sin pedir otro código en el juego.

• La contraseña no sustituye al primer vínculo ingame.
• Si olvidas la contraseña, vuelve a vincular desde el juego.
• Los detalles técnicos de hash y rate-limit quedan en la documentación técnica.

💬 Pestaña Chat

Lee el chat del servidor en tiempo casi-real y envía mensajes bajo tu identidad vinculada.

📖 Lectura

El dashboard hace polling al endpoint de chat. El backend sirve una ventana deslizante de mensajes recientes, filtrando ruido interno.

✍ Envío

Si la sesión está vinculada, los mensajes salen como el jugador real (p.ej. elYandrack). Sin vinculación válida, la identidad degrada a externa (Externo-AxinMovil) y las acciones admin quedan denegadas.

🛡 Pestaña Admin

Acciones operativas seguras para administradores vinculados.

👢 Kick con motivo

Al hacer kick desde el dashboard:

1. El bridge envía un SendMessage al jugador con el motivo normalizado.
2. Tras un breve retardo por callback, se ejecuta player.Disconnect(reason).
3. Así el jugador ve el motivo personalizado antes de ser desconectado.

📣 Mensajería operativa

Broadcast corto a todos los jugadores conectados desde la UI del dashboard. Útil para avisos de reinicio, mantenimiento y eventos.

📊 Métricas

Estado básico del servidor: uptime, jugadores conectados, version, mods cargados. Estas métricas no requieren admin para leer, solo API key y sesión válida (configurable).

🏪 Pestaña Tienda

Interfaz web del Mercado Global de AxinMenuGui: ver ofertas activas, comprar y consultar tus ventas.

🔗 Contrato

La tienda web no toca market.json directamente. Depende del mod axinmenugui, resuelve AxinMenuGuiMod con api.ModLoader.GetModSystem<T>() y opera contra MarketStore / BankService vivos en el hilo principal.

💰 Precio: unidad vs lote

🧯 Errores de dominio

Los fallos del servicio salen como errores específicos con log de alta señal:

• market_query_failed — fallo al enumerar ofertas.
• market_main_thread_timeout — la consulta no volvió al hilo principal a tiempo.

Nunca se degradan a internal_error HTTP genérico.

🎟 Sesiones y autenticación

Dos capas separadas: persistir tokens (siempre) y permitir contraseña (opt-in).

📚 Modelo

1. Tokens persistidos (AuthStore.sessions.json): sobreviven a reinicios del servidor. TTL de inactividad = SessionMaxInactiveDays (default 30 días).
2. Password opt-in: habilitado por AccountsAllowPassword. Permite re-auth sin volver al juego.

🔁 Rehidratación

Al arrancar el bridge, SessionManager.Rehydrate() carga sessions.json, descarta sesiones vencidas y repuebla el diccionario en memoria.

🔒 Password

• Hash: PBKDF2-SHA256, 100.000 iteraciones, salt 16B aleatorio.
• Comparación en tiempo constante (FixedTimeEquals).
• Rate-limit por IP: 3 fallos = 30 s, 5 = 5 min.

🌐 Exposición segura

Cómo publicar el bridge sin obligar a la app web a conectar directamente por HTTP.

🧭 Explicación sin jerga

La app web está en HTTPS. Muchos servidores de Vintage Story solo pueden exponer el mod por HTTP. El relay es una puerta intermedia segura: la app habla con el relay por HTTPS y el relay habla con tu servidor por la dirección que pusiste en PublicBridgeUrl.

🚫 Qué no hacer

• Decir a los usuarios que usen directamente http://ip:puerto como ruta normal de la app pública.
• Dejar ApiKey vacía o derivada de texto corto.
• Compartir la API key en canales no cifrados.
• Confundir PublicBridgeUrl con la URL que debe escribir el usuario en la app.

✅ Qué hacer

• Usar como URL normal de la app https://bridgerelay.axin.es/s/<slug>/api.
• Mantener el puerto del bridge bajo control: por defecto es 42421; si tu hosting tiene reglas estrictas o quieres una capa extra de privacidad, puedes elegir otro puerto TCP alto, siempre coordinándolo con Port, PublicBridgeUrl y el firewall.
• Abrir en el hosting/firewall el puerto real del bridge y hacer que PublicBridgeUrl use exactamente ese mismo puerto.
• Si el hosting/firewall lo permite, restringir el acceso al puerto del bridge solo a la IP del relay (212.227.153.142).
• Reservar la conexión directa al bridge (sin relay) para despliegues controlados o pruebas concretas.

🏪 Integración con el Mercado

El AXINServerBridge se apoya en AxinMenuGui para operar el mercado P2P desde la web.

📐 Principio

El bridge no es dueño del mercado. Actúa como cliente del MarketStore vivo: lee ofertas, prepara transacciones y delega la mutación a la misma API que usa el GUI ingame.

🧵 Hilo principal

Toda operación sobre el MarketStore se ejecuta en el main thread del servidor (api.Event.EnqueueMainThreadTask / equivalente). Si el salto de hilo se demora demasiado, el bridge devuelve market_main_thread_timeout.

💳 Fuentes de pago

Cuando el comprador no tiene saldo suficiente en el inventario, el sistema encadena fuentes — cada una cubre solo lo que puede:

fromInventory = Min(remaining, inventory.CountItem(...))
fromTreasury  = Min(remaining, treasury.CountItem(...))
fromBank      = Min(remaining, bank.CountItem(...))

📦 Enlaces y capturas

Atajos al propio dashboard (configurados en tu instalación) y capturas de referencia.

🔗 Atajos del dashboard

En wiki/Imagenes/AXINMobileServerBridgeImages/ se incluyen accesos directos .url a las vistas reales del dashboard desplegado. Apuntan al servidor concreto — ábrelos desde el explorador, no desde la web:

🖼 Capturas

Pantalla de conexión — introducir la URL del relay, dejar la API key vacía si usas relay y vincular la sesión.

🗺 Roadmap

Hitos previstos. Orden aproximado, sujeto a prioridades operativas.