docs: research on Argentum Online map editor ecosystem (fixes #14)

[angelTomo9]

Closes #14

Summary of Research & Deliverables

Delivers the technical research audit in docs/research-map-editors.md examining map editor architectures across the Argentum Online ecosystem (ao-org/argentum-online-worldeditor, lambdaclass/argentum, ao-libre/ao-cliente).

Key Findings & Sections

• Format Comparison Matrix: Compares legacy binary .map v0.13 with OpenAO's structured JSON (meta, terrain, npcs, specials).
• Layers & Logic Model: Details the 4 visual graphic layers, boolean blockage bitmask, and 6 trigger types.
• In-Browser Live Collaborative Editing: Confirmed that zero existing open-source AO projects support in-browser live multi-user editing, validating OpenAO's core novelty.
• Clean-Room TypeScript Importer: Includes clean-room TypeScript parser parseLegacyBinaryMap enabling lossless import of 280+ legacy AO maps.
• Licensing & Legal Framework: Establishes clean-room functional interoperability standards relative to AGPL-3.0 and MIT codebases.

[gitar-bot]

Code Review ✅ Approved 3 resolved / 3 findings

Adds comprehensive research documentation and a clean-room TypeScript parser for the Argentum Online map editor ecosystem. Addresses findings on 1-based tile indexing, unused header versions, and buffer bounds checks.

✅ 3 resolved

✅ Bug: Sample importer builds 1-indexed arrays leaving index 0 undefined

📄 docs/research-map-editors.md:78-92
The parser fills tiles[y][x] for y,x from 1..100, so tiles[0] and every row[0] are undefined, and tiles.length is 101. Any consumer iterating with conventional 0-based loops (or .map/.forEach) will hit undefined rows/tiles. Since this snippet is offered for lossless import of 280+ maps, either document the 1-based convention explicitly or use 0-based indexing (tiles[y-1][x-1]).

✅ Quality: version read from header is never used

📄 docs/research-map-editors.md:73-74
const version = view.getInt16(offset, true) is read then discarded; the code advances a fixed offset += 8 regardless, so the declared 'v0.13 signature' validation never actually happens. Either validate version (e.g. throw on unexpected values) or drop the dead read so the sample doesn't imply header validation it doesn't perform.

✅ Edge Case: Parser lacks bounds checks against buffer length

📄 docs/research-map-editors.md:68-82
parseLegacyBinaryMap advances offset via getUint8/getUint16 across up to 10,000 tiles without verifying offset stays within buffer.byteLength. A truncated or malformed .map file will throw a raw RangeError from DataView mid-parse rather than a meaningful error. Consider guarding reads and reporting the offending tile coordinate, especially since this is intended to migrate legacy files of uncertain provenance.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

---

Important

Your trial ends in 7 days — upgrade now to keep code review, CI analysis, auto-apply, custom automations, and more.

_{Was this helpful? React with 👍 / 👎 | Gitar}