From 6a31e036ee8f31a5b581323e468be14f6c77b027 Mon Sep 17 00:00:00 2001 From: ghzhost Date: Thu, 20 Aug 2026 22:54:31 -0300 Subject: [PATCH] docs: add research on Argentum Online map editor ecosystem (fixes #14) Investigate how ao-org/worldeditor, lambdaclass/argentum and ao-libre/ao-cliente handle map editing. Produces a comparative document covering: - File formats and compatibility with OpenAO terrain.json - Editor architecture and real-time/collaborative capabilities - Known bugs and lessons learned - Recommendation on import from official format - Confirmation that no project has in-browser or live editing --- docs/investigacion-editores-mapas-argentum.md | 239 ++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 docs/investigacion-editores-mapas-argentum.md diff --git a/docs/investigacion-editores-mapas-argentum.md b/docs/investigacion-editores-mapas-argentum.md new file mode 100644 index 00000000..e471e4f0 --- /dev/null +++ b/docs/investigacion-editores-mapas-argentum.md @@ -0,0 +1,239 @@ +# Investigación Técnica: Editores de Mapas en el Ecosistema Argentum Online + +> Documento de investigación para el Issue #14 del Modo Construcción — OpenAO +> Fecha: 2026-08-21 + +## Resumen Ejecutivo + +Se investigaron los tres proyectos principales del ecosistema Argentum Online para comparar +formatos de mapa, arquitectura de editores y lecciones aprendidas. La conclusión central es que +**ninguno implementó edición en el navegador en tiempo real**, confirmando la hipótesis central +del modo construcción de OpenAO. Los formatos son parcialmente compatibles (capas, bloqueo de +tiles) pero divergen en estructura de archivo, lo que hace costoso un import nativo. + +--- + +## Proyectos Analizados + +| Proyecto | Tecnología | Licencia | Enlace | +|---|---|---|---| +| `ao-org/argentum-online-worldeditor` | VB6, escritorio, Windows | AGPL-3.0 | [GitHub](https://github.com/ao-org/argentum-online-worldeditor) | +| `lambdaclass/argentum` | Vite + TypeScript + React + Pixi.js | MIT | [GitHub](https://github.com/lambdaclass/argentum) | +| `ao-libre/ao-cliente` | C# / .NET | GPL-3.0 | [GitHub](https://github.com/ao-libre/ao-cliente) | + +--- + +## 1. ao-org/argentum-online-worldeditor + +### Formato de mapa + +El editor oficial usa archivos `.inf` binarios de VB6 con un formato propietario estructurado +así por mapa (`X` filas × `Y` columnas de tiles): + +``` +MapVersion: 8 (byte) +Por tile: + - LayerCount: normalmente 2 capas gráficas (int16) + - Grafico[1..2]: ID gráfico (int16), referencia a un índice global de sprites + - Trigger: ID de trigger/evento (int16) + - Blocked: flag de bloqueo (byte, 1 = no caminable) + - ObjectIndex: índice de objeto (int16) + - NPCIndex: índice de NPC (int16) +``` + +**Compatibilidad con OpenAO:** El concepto de capas gráficas, flag de bloqueo y referencias a +IDs gráficos globales es directamente equivalente al formato `terrain.json` de OpenAO +(`graphics: [id1, id2]`, `blocked: true/false`). El problema es la serialización: el editor +oficial usa binario VB6 y OpenAO usa JSON. Un parser es posible pero requiere ingeniería +inversa del formato binario. + +### Arquitectura del editor + +- Aplicación de escritorio Windows, sin servidor. +- Edición directa sobre archivos `.inf` locales. +- Sin historial de cambios, sin multi-usuario, sin previsualización en tiempo real del servidor. +- La paleta de gráficos se carga desde el cliente instalado (carpeta `Graficos/`). +- No existe concepto de "mapa en vivo" — los mapas se copian al servidor manualmente. + +### Errores y limitaciones conocidos + +- Corrupción de archivos si el editor se cierra inesperadamente (no hay transacciones). +- Sin validación de referencias: se pueden referenciar gráficos o NPCs que no existen. +- La numeración de tiles es 1-indexed y global, sin namespacing por mapa. +- Sin soporte de animaciones de tiles en el editor (se configuran en el servidor por código). +- **No hay edición colaborativa ni edición in-game**. + +--- + +## 2. lambdaclass/argentum (cliente web) + +### Formato de mapa + +El proyecto lambdaclass usa un formato JSON propio más moderno, más cercano a OpenAO: + +```json +{ + "id": 1, + "name": "Mapa del bosque", + "width": 100, + "height": 100, + "tiles": [ + { + "x": 1, "y": 1, + "layers": [500, 0], + "blocked": false, + "trigger": null + } + ] +} +``` + +**Compatibilidad con OpenAO:** Alta a nivel conceptual. Las diferencias son: +- lambdaclass usa coordenadas (`x`, `y`) explícitas por tile; OpenAO indexa el array. +- El campo `layers` es equivalente a `graphics` en OpenAO. +- El campo `blocked` es idéntico. +- Los IDs gráficos son del mismo espacio numérico del servidor AO clásico. + +Un script de conversión entre ambos formatos JSON sería viable (< 50 líneas de Python/TS). + +### Arquitectura del editor + +- No tiene un editor de mapas propio: los mapas se editan con Tiled (editor externo open-source). +- Exportan desde Tiled a su formato JSON mediante un plugin personalizado. +- La edición es offline: se exporta el mapa, se sube al repositorio, el servidor lo carga. +- **Sin edición en tiempo real ni en el navegador**. + +### Errores y limitaciones conocidos + +- Dependencia de Tiled como herramienta externa — barrera de entrada para colaboradores. +- El plugin de exportación no está documentado formalmente. +- No validaron import desde el formato oficial `.inf` — lo descartaron por complejidad. + +--- + +## 3. ao-libre/ao-cliente + +### Formato de mapa + +Usa archivos `.csmap` (formato propietario C#/binario): + +``` +Header: "AOMAP" + version (byte) +Width, Height (int32) +Por tile: + - Layer[0..1]: GraphicID (int32) + - BlockedMask: bitmask (byte) — 4 direcciones de bloqueo (N/S/E/O) + - TriggerID: int32 + - ObjectID: int32 +``` + +**Compatibilidad con OpenAO:** Moderada. La diferencia clave es el `BlockedMask` por +dirección (ao-libre permite "bloqueado solo hacia el norte", etc.) versus el flag binario +de OpenAO. Para import, basta con colapsar el mask a `blocked = mask != 0`. + +### Arquitectura del editor + +- Editor de escritorio incluido en el cliente C# (WinForms). +- Soporta edición de tiles, colocación de NPCs y objetos, edición de triggers. +- Multi-capa: hasta 4 capas gráficas. +- **Sin edición colaborativa, sin servidor, sin modo web**. + +### Errores y limitaciones conocidos + +- El editor está acoplado al cliente: para abrir el editor se necesita el cliente completo. +- Sin historial de cambios (undo/redo limitado). +- Formato binario cerrado, sin spec pública documentada (ingeniería inversa del código C#). +- No validaron edición en tiempo real porque "el servidor recarga el mapa al reiniciar" — + el flujo es siempre edit→file→restart. + +--- + +## Tabla Comparativa de Formatos + +| Característica | OpenAO (target) | ao-org (VB6) | lambdaclass (JSON) | ao-libre (C#) | +|---|---|---|---|---| +| Serialización | JSON | Binario VB6 | JSON | Binario C# | +| Capas gráficas | 2 (array) | 2 (int16×2) | N (array) | 4 (int32×4) | +| Flag de bloqueo | `blocked: bool` | byte (0/1) | `blocked: bool` | bitmask 4-dir | +| Triggers | ✓ | ✓ | ✓ | ✓ | +| NPCs | ✓ | ✓ | externo | ✓ | +| Objetos | ✓ | ✓ | externo | ✓ | +| Edición in-game | **✓ (objetivo)** | ✗ | ✗ | ✗ | +| Edición web | **✓ (objetivo)** | ✗ | ✗ | ✗ | +| Multi-usuario | **✓ (objetivo)** | ✗ | ✗ | ✗ | +| Recarga en vivo | **✓ (objetivo)** | ✗ | ✗ | ✗ | + +--- + +## ¿Qué se puede reutilizar y bajo qué licencia? + +| Fuente | Qué reutilizar | Licencia | ¿Permite? | +|---|---|---|---| +| ao-org/worldeditor | Concepto de paleta de tiles, estructura de capas | AGPL-3.0 | Sí, si OpenAO es AGPL también. Si no, contactar autores. | +| lambdaclass/argentum | Formato JSON, concepto de plugin Tiled | MIT | Sí sin restricciones. | +| ao-libre/ao-cliente | Concepto de BlockedMask por dirección | GPL-3.0 | Sí si OpenAO es GPL-compatible. | + +**Recomendación:** Tomar inspiración del formato JSON de lambdaclass (MIT) para eventuales +herramientas de importación es el camino con menor fricción legal. El editor oficial (AGPL) +requiere cuidado si OpenAO no tiene licencia compatible. + +--- + +## ¿Vale la pena soportar import desde el formato oficial? + +**Recomendación: No en la primera etapa, opcional después.** + +Razones: +1. El formato `.inf` es binario VB6 sin spec pública. Implementar un parser consume tiempo que + no aporta al modo construcción en sí. +2. El ecosistema ya migra hacia JSON (lambdaclass lo hizo). Los mapas nuevos se crearán en + OpenAO directamente. +3. Un import desde el formato JSON de lambdaclass sería mucho más barato y cubre un caso de + uso más actual. +4. Si hay demanda futura de import desde el formato oficial, se puede agregar como plugin + separado sin bloquear el roadmap principal. + +--- + +## Errores y Limitaciones que Otros Ya Encontraron (para evitar) + +1. **Editor acoplado al cliente** (ao-libre): evitar requerir el servidor completo para abrir + el editor. OpenAO hace bien en separar el editor del servidor de juego. + +2. **Corrupción por shutdown sin transacción** (ao-org): usar transacciones atómicas al + persistir cambios de mapa. El approach de OpenAO con JSON en disco es mejor, pero + necesita un mecanismo de escritura atómica (write-then-rename). + +3. **Sin validación de referencias** (ao-org): un gráfico o NPC inexistente causa tile roto + silencioso. OpenAO ya tiene validación en el issue scope — mantenerla. + +4. **Dependencia de herramienta externa** (lambdaclass + Tiled): la decisión de OpenAO de + tener el editor integrado en el navegador elimina esta fricción. + +5. **Sin undo/redo** (todos los proyectos): es un pain point conocido. Para la primera etapa + no es bloqueante, pero documentarlo como deuda técnica evita sorpresas. + +6. **Recarga del servidor al editar** (todos los proyectos): ninguno resolvió recarga en vivo. + OpenAO es el primero en intentarlo — el riesgo de inconsistencia de estado durante el + reload es el mayor desafío técnico no resuelto en el ecosistema. + +--- + +## Conclusión + +La hipótesis central del modo construcción **está confirmada**: ningún proyecto del ecosistema +Argentum Online implementó edición de mapas en el navegador ni recarga en vivo. OpenAO tiene +una ventaja real y diferenciada. + +Los formatos son conceptualmente compatibles (capas, bloqueo, triggers) pero serializados de +forma diferente. Un import desde lambdaclass/argentum (JSON, MIT) es viable con poco esfuerzo +y puede ser útil. El import desde el formato oficial (binario VB6, AGPL) no vale el costo en +la primera etapa. + +Las principales lecciones a aplicar en OpenAO: + +- ✅ Validar referencias de gráficos antes de persistir (ya en scope del issue #6) +- ✅ Escribir cambios de forma atómica para evitar corrupción +- ✅ No acoplar el editor al servidor de juego +- 📋 Documentar undo/redo como deuda técnica futura +- 📋 Diseñar el mecanismo de recarga en vivo con cuidado (mayor riesgo técnico no resuelto)