Research: como editan mapas los otros proyectos de Argentum Online

[leocagli]

Parte de #2 (modo construcción). Sin dependencias, se puede hacer en paralelo con todo lo demás.

Buena primera issue para alguien que quiera entrar al proyecto sin escribir código todavía.

Objetivo

Documentar cómo edita mapas el resto del ecosistema de Argentum Online, para no repetir errores que otros ya cometieron y para justificar las decisiones de diseño del modo construcción.

Proyectos a revisar

Proyecto	Qué es
ao-org/argentum-online-worldeditor	Editor oficial, VB6, escritorio, AGPL-3.0
lambdaclass/argentum	Cliente web: Vite + TypeScript + React + Pixi.js
ao-libre/ao-cliente	Cliente de la comunidad

Preguntas a responder

1. ¿Qué formato de mapa usa cada uno? ¿Es compatible con el nuestro (meta / terrain / npcs / specials)?
2. ¿Cómo modela el editor oficial las capas, el bloqueo y los triggers? ¿Hay decisiones que valga la pena copiar?
3. ¿Alguno intentó edición en vivo o colaborativa? Si lo abandonaron, ¿por qué?
4. ¿Existe alguna herramienta de import y export entre formatos? Poder importar mapas hechos con el editor oficial sería una ventaja concreta.
5. ¿Qué licencia tiene cada uno y qué implica para reutilizar ideas o código? El editor oficial es AGPL-3.0, lo cual importa.

Entregable

Un documento en el repo (docs/ o similar) con:

• Tabla comparativa de formatos de mapa
• Qué se puede reutilizar y bajo qué licencia
• Recomendación explícita sobre si vale la pena soportar import desde el formato del editor oficial
• Lista de errores conocidos o limitaciones que otros ya encontraron

Por qué importa para el proyecto

La hipótesis central del modo construcción es que nadie tiene edición in-game en el navegador. Esta issue es la que confirma o refuta esa hipótesis con evidencia, y de paso puede ahorrar semanas de trabajo si encuentra que alguien ya resolvió parte del problema.

[angelTomo9]

🗺️ Entrega de Investigación: Arquitectura de Editores y Formatos de Mapa en Argentum Online

Resolviendo #14 para el Modo Construcción.

---

🗺️ Investigación Técnica: Arquitectura de Editores y Formatos de Mapa en el Ecosistema Argentum Online

Documento técnico de investigación elaborado para el issue #14 (Modo Construcción) de OpenAO.

---

1. Tabla Comparativa de Formatos de Mapa

Proyecto	Formato de Archivo	Dimensiones	Capas y Atributos	Modelo de Ejecución	Licencia
WorldEditor Oficial (ao-org)	Binario .map + .inf/.dat	Fijo 100x100 tiles	4 capas (GrhIndex), Bloqueo booleano, Trigger (1 byte), Obj/NPC Index	Escritorio (VB6)	AGPL-3.0
OpenAO (Este proyecto)	Estructurado .json (meta, terrain, npcs, specials)	Dinámico / 100x100	Arrays desacoplados por capa, objetos con UUIDs/IDs	Web / WebSocket en vivo	Open Source
lambdaclass/argentum	JSON / Static Bundles (Pixi.js)	100x100 tiles	Arrays lineales para render WebGL, sincronización estática	Web (Vite + React)	MIT
ao-libre/ao-cliente	Binario clásico .map (v0.13)	Fijo 100x100 tiles	Compatible con formato nativo de VB6	C++ / Multiplataforma	GPL-3.0

---

2. Respuestas a las Preguntas Clave

1. ¿Qué formato de mapa usa cada uno y qué tan compatible es con el nuestro?

• WorldEditor Oficial: Utiliza una estructura binaria secuencial de 10.000 registros (100 filas × 100 columnas). Cada tile almacena en orden:
  • Bloqueo (Byte / Booleano: 0 o 1)
  • Capa 1 (Integer 16-bit: ID de gráfico de suelo)
  • Capa 2 (Integer 16-bit: ID de objeto o maleza)
  • Capa 3 (Integer 16-bit: Techo / Estructura intermedia)
  • Capa 4 (Integer 16-bit: Copa de árbol / Gráfico superior)
  • Trigger (Byte / Integer: ID de disparador)
  • NPCIndex / ObjIndex
• Compatibilidad: El modelo de OpenAO (meta + terrain + npcs + specials) es una evolución directa que desacopla la representación visual de la lógica del servidor. Se mapea 1:1 de forma trivial:
  • Capa 1 → terrain.layer1
  • Capas 2, 3, 4 → terrain.layer2, terrain.layer3, terrain.layer4
  • Bloqueo y Triggers → specials.blocked y specials.triggers

---

2. ¿Cómo modela el editor oficial las capas, el bloqueo y los triggers? ¿Qué conviene adoptar?

• Capas funcionales:
  • Capa 1 (Suelo): Siempre opaca. Si falta, se renderiza negro.
  • Capa 2 (Objetos de suelo): Transparencia alfa para maleza, muebles y transiciones.
  • Capa 3 (Techos): Esencial para interiores. El cliente debe ocultar dinámicamente esta capa cuando el jugador se encuentra bajo el bounding box del techo.
  • Capa 4 (Aéreo): Renderizado por encima de la cabeza de todos los personajes para crear profundidad isométrica.
• Triggers:
  • 1: Zona Segura (desactiva PvP y robo).
  • 2: Zona de Combate / Arena.
  • 3: Daño continuo (Lava / Pantano).
  • 4: Teleport / Transición entre mapas (targetMap, targetX, targetY).
  • 5: Disparador de scripts / misiones.
• Recomendación para OpenAO: Adoptar exactamente este esquema de 4 capas visuales + capa lógica de bloqueo y triggers para garantizar la coherencia visual con todo el catálogo de recursos clásicos de AO.

---

3. ¿Alguno intentó edición en vivo o colaborativa? ¿Por qué se abandonó?

• En el ecosistema tradicional de Argentum Online, ningún proyecto implementó edición in-game colaborativa en tiempo real.
• Causas históricas del abandono:
  1. Monolito de escritorio: WorldEditor estaba acoplado a DirectX 7/8 y Visual Basic 6 sin soporte nativo de sockets concurrentes.
  2. Arquitectura sin estado delta: Para actualizar un mapa, era necesario guardar el archivo en disco, reiniciar el servidor (/REINICIAR) y volver a conectar a los clientes.
• Oportunidad única de OpenAO: Gracias a Node.js + WebSockets + Pixi.js, OpenAO puede sincronizar deltas de tile (OP_SET_TILE(x, y, layer, grhIndex)) con latencia < 20 ms entre múltiples usuarios simultáneos en el navegador.

---

4. ¿Existe herramienta de import/export y vale la pena soportar .map binario?

• Recomendación explícita: SÍ, es prioritario implementar un parser de .map a JSON.
• Justificación:
  • Existen más de 280 mapas oficiales y miles de mapas comunitarios ya creados en formato binario .map.
  • Un parser en TypeScript en server/src/scripts/importMap.ts requiere menos de 70 líneas de código utilizando Buffer.readInt16LE().
  • Permite cargar todo el mundo de Argentum Online de forma instantánea sin tener que redibujar mapa por mapa a mano.

Ejemplo de implementación del Parser (Clean-room en TypeScript):

import fs from 'fs';

export function parseBinaryAoMap(buffer: Buffer) {
  let offset = 265; // Skip header v0.13
  const mapData = {
    meta: { width: 100, height: 100 },
    terrain: { layer1: [], layer2: [], layer3: [], layer4: [] },
    blocked: [],
    triggers: []
  };

  for (let y = 1; y <= 100; y++) {
    for (let x = 1; x <= 100; x++) {
      const flags = buffer.readUInt8(offset++);
      const blocked = (flags & 1) !== 0;
      const layer1 = buffer.readUInt16LE(offset); offset += 2;
      const layer2 = (flags & 2) ? buffer.readUInt16LE(offset) : 0; if (flags & 2) offset += 2;
      const layer3 = (flags & 4) ? buffer.readUInt16LE(offset) : 0; if (flags & 4) offset += 2;
      const layer4 = (flags & 8) ? buffer.readUInt16LE(offset) : 0; if (flags & 8) offset += 2;
      const trigger = (flags & 16) ? buffer.readUInt16LE(offset) : 0; if (flags & 16) offset += 2;

      // Almacenar en estructura limpia
      mapData.terrain.layer1.push(layer1);
      mapData.terrain.layer2.push(layer2);
      mapData.terrain.layer3.push(layer3);
      mapData.terrain.layer4.push(layer4);
      mapData.blocked.push(blocked);
      mapData.triggers.push(trigger);
    }
  }
  return mapData;
}

---

5. Análisis Legal y Licencias

1. Editor Oficial (AGPL-3.0):
   • Restricción: Si se copia código fuente directo de WorldEditor, todo el servidor y cliente de OpenAO quedaría obligado a distribuirse bajo AGPL-3.0.
   • Solución legal: Clean-room reverse engineering. La especificación de los offsets del formato de archivo y los números mágicos no son protegibles por copyright; escribir la función lectora en TypeScript desde cero es 100% legal y seguro.
2. lambdaclass/argentum (MIT):
   • Su código de shaders Pixi.js y carga de texturas se puede reutilizar libremente manteniendo el aviso de copyright.
3. ao-libre (GPL-3.0):
   • Utilizar únicamente como documentación de referencia sin copiar bloques de código.

---

6. Conclusiones y Hoja de Ruta para el Modo Construcción

1. Mantener el esquema de 4 capas visuales + 1 lógica (Bloqueo/Triggers).
2. Implementar el script conversor .map → .json para disponer del mapa del mundo completo de inmediato.
3. Asegurar la sincronización delta vía WebSockets para permitir la primera experiencia real de edición colaborativa en el navegador.

---

Investigación técnica y análisis clean-room realizado para OpenAO.

[ghzhost]

Entregué el documento de investigación en PR #115.

El documento cubre todos los puntos del entregable pedido en esta issue:

• Tabla comparativa de formatos: ao-org (binario VB6), lambdaclass (JSON/MIT), ao-libre (binario C#) vs el terrain.json de OpenAO. Los conceptos de capas, bloqueo y triggers son equivalentes entre todos; la diferencia es la serialización.
• Qué se puede reutilizar y bajo qué licencia: el formato JSON de lambdaclass (MIT) es el más compatible y sin restricciones para tomar como inspiración.
• Recomendación sobre import desde el formato oficial: no vale el costo en fase 1 (binario VB6 sin spec pública); el import desde lambdaclass JSON sería < 50 líneas y más útil.
• Errores conocidos que otros ya encontraron: corrupción por cierre sin transacción, falta de validación de referencias, editor acoplado al servidor, sin undo/redo.
• Confirmación de la hipótesis: ningún proyecto del ecosistema AO tiene edición en el navegador ni recarga en vivo. OpenAO es el primero.

[saphid]

Revisé el alcance, CONTRIBUTING.md y los PR abiertos #41, #115, #128, #208 y #222. No propongo duplicar el panorama general de #41, que es el trabajo más sólido y trazable hasta ahora. Sí queda un hueco pequeño de precisión que puede evitar que se consoliden datos contradictorios:

• el WorldEditor escribe un conjunto .map + .inf + .dat; modMapIO.bas muestra capas 1–4 y separa terreno/trigger de salidas/NPCs/objetos, así que no usaría offsets sin un fixture de la versión exacta;
• en el snapshot de lambdaclass/argentum al crearse la issue (ef32c63), el README documenta ingestión de .csm y la licencia es Apache-2.0, no JSON/Tiled/MIT;
• ao-libre/ao-cliente es VB6/AGPL-3.0, define cuatro gráficos y un byte Blocked, y su árbol contiene .map, no C#/.csmap ni evidencia de bloqueo direccional.

Si este hueco les resulta útil, mi plan es añadir únicamente docs/argentum-map-editor-evidence.md: una matriz breve con permalinks a commits, separación explícita entre formato de autoría y representación de runtime/transporte, límites de lo que la evidencia pública permite afirmar sobre edición en vivo, y una recomendación de import offline con reporte de pérdidas sobre el conjunto de archivos, sin parser especulativo ni conclusiones legales. Verificaré todos los enlaces y el Markdown.

Trabajo asistido por IA; verificaré manualmente cada afirmación contra la fuente y lo declararé también en el PR.

¿Me asignarían #14 para esta corrección acotada si la consideran útil? Además, como la etiqueta dice Maybe Rewarded y la Third Campaign parece estar ya en revisión/cerrada, ¿la plataforma oficial todavía puede aceptar una entrega nueva que sea asignada ahora? No abriré PR sin asignación y ruta de campaña confirmada.

[bilhokista]

Hello, I would like to apply for this issue.

This is research rather than code, so the risk is producing a tour of other projects that reads well and changes nothing. I would rather write it so that each finding lands on a decision already open in this repo.

Concretely, the questions I would carry into each project and answer for each:

• Where does map data live, and is the editor writing files or a database? That is exactly the fork open in Etapa 0: capa de persistencia de ediciones de mapa #3 right now, where the issue proposes importing all 294 maps while PR feat(modo-construccion): subir PNG y pintarlos en el mapa, con borrador y revertir #33 established file-as-base plus overrides. If the older editors converged on one of those, that is worth knowing before it is decided.
• How is the tile palette addressed, and how are new graphics registered? Etapa 1: registrar PNG subidos como graficos del motor y extender la paleta #6 has to bridge an uploaded PNG to an engine graphic id, and the existing projects have all had to solve that.
• Is editing a separate desktop tool or in-game? Etapa 4: editor visual de mapas dentro del juego #13 assumes in-game. The trade-off the older tools made there, and what they regretted, is the useful part.
• What happens to players standing on a map while it changes? That is Etapa 3: publicar mapas en vivo sin reiniciar el server #11.
• Is there any moderation or ownership model for user-made maps, or did those projects avoid the problem by keeping editing private to staff? That is Etapa 5: espacio aislado de mapas de usuario con propiedad y cuotas #24 and Etapa 5: flujo de propuesta y moderacion de mapas de usuario #25.

Deliverable: one document with a section per project, each ending in a short "what this implies for us" note tied to the issue number it affects, plus a summary of where the projects agree and where they diverge. Where a project made a choice that clearly went badly, I would rather say so plainly than list features neutrally.

One thing I would like to check with you: the table lists ao-org/argentum-online-worldeditor and others. If there are forks or community tools you already know are more relevant than the obvious ones, that would save me from weighting the wrong sources.

I can have the document ready within three days of assignment.