AdamuSw/docs/superpowers/specs/2026-07-19-new-maps-import-design.md

New Maps Import — Design (Pilot: Arkania / World 83)

Date: 2026-07-19 Status: Approved (design), pending implementation plan Scope of this spec: Import ONE pilot map (Arkania, world index 83) end-to-end across server (OpenMU), PC client, and web admin panel. The other four maps (Acheron 84, Debenter 85, Uruk 86, Ferea 87) and the mobile client are explicitly out of scope for the pilot and will be replicated from the proven pilot template in follow-up work.

Background

A third-party map pack provides 5 maps with both client and server assets:

• Source: C:\Users\efpa\Downloads\Arkania Acheron Debenter Uruk Ferea\Arkania Acheron Debenter Uruk Ferea
• Client Side/Data: World83-87 (terrain: EncTerrain8N.att/.map/.obj, TerrainHeight.OZB, TerrainLight.OZJ, tile textures, minimap.map), Object83-87 (object BMD models + textures), Local/Eng (ImgsMapName/*.OZT map-name images, Minimap/*.bmd, movereq_eng.bmd).
• Server Side/Data: MapManager.txt (classic C++ MuServer map config — reference only), Move/Gate.txt, Move.txt, MoveSummon.txt (warp gates — reference only), Terrain/Terrain83-87.att (walkability/safezone attributes).

The server-side files are classic C++ MuServer format and are NOT consumed by OpenMU — except the .att terrain files, which match OpenMU's terrain resource format exactly.

Key technical findings (verified)

1. Terrain is a drop-in for OpenMU. OpenMU loads map terrain via GameMapDefinition.TerrainData, populated by _mapDefinition.UpdateTerrainFromResources(TerrainVersionPrefix) in BaseMapInitializer, from an embedded resource Resources/Terrain{Number}.att. The pack's server Terrain83.att is 65539 bytes, header 00 ff ff 04 — byte-for-byte the same format as OpenMU's existing Resources/Terrain1.att (65539, 00 ff ff 04). The client's EncTerrain83.att (65540, encrypted) is NOT what the server wants; the server-side .att is.
2. Indices 82-87 are free in the current OpenMU (AdamuSw) map set — no collision at 83.
3. Web admin panel needs no code changes. Once a GameMapDefinition (number 83) exists in the DB, it appears automatically in:
   • /edit-config-grid/GameMapDefinition (GameMaps CRUD)
   • /map-editor → visual MapEditor (renders terrain from TerrainData; CreateNewSpawnArea, CreateNewEnterGate, CreateNewExitGate, duplicate/remove/undo/save)
   • /edit-config-grid/WarpInfo (/move warp list), /edit-config-grid/MonsterDefinition (monsters)
4. Monster spawns / NPCs are NOT in the pack. The seeded map is intentionally EMPTY (scenery + walkable + safezone only). Spawns, NPCs and gates are added by the user via the web MapEditor.
5. Index→name ambiguity. Pack folders are World83-87 (no World82). MapManager.txt labels 82=Arkania,83=Acheron,…,87=TeamvsTeam (off-by-one / stock reference). The pack's own title order ("Arkania Acheron Debenter Uruk Ferea") + available folders (83-87) imply 83=Arkania, 84=Acheron, 85=Debenter, 86=Uruk, 87=Ferea. Pilot uses World83 = Arkania, to be confirmed against the pack screenshots during implementation.

Chosen approach

Approach A — OpenMU-native C# map initializer + terrain resource + DB update-plugin. This mirrors every existing OpenMU map and the proven Imperial-items dual-path pattern (see android-add-new-weapon-item). Rejected alternatives: (B) pure-panel creation — not viable, the 65KB TerrainData byte[] cannot be entered via a web form; (C) build a C++→OpenMU map converter to use the MapEditor Import — unnecessary work for a pilot.

Components / changes

Server repo: AdamuSw (Gitea, branch off main).

1. Terrain resource — copy pack Server Side/Data/Terrain/Terrain83.att → src/Persistence/Initialization/Resources/Terrain83.att. Verify it is included as an embedded resource by the .csproj (the Resources/*.att glob); add explicitly if not globbed.
2. Map initializer — src/Persistence/Initialization/VersionSeasonSix/Maps/Arkania.cs:
   • Number => 83
   • Name => "Arkania"
   • TerrainVersionPrefix => string.Empty
   • Safezone / spawn gate as required by BaseMapInitializer (minimal; a single safe spawn gate so players don't spawn on a blocked tile).
   • Empty CreateMonsterSpawns / NPC init (spawns added later via panel).
   • Follow the existing map-class pattern (many inherit a Version075.Maps.* base; Arkania is new so it derives from BaseMapInitializer directly, like other SeasonSix-only maps).
3. Registration (fresh seed) — add Arkania to the map initializer list so a zero DB seeds it (alongside Weapons.Initialize()-style wiring in the SeasonSix data-initialization).
4. DB update-plugin (existing DB) — src/Persistence/Initialization/Updates/AddArkaniaMapUpdateSeason6.cs:
   • UpdateVersion = next free number (after the Imperial 95).
   • Idempotency guard: if a map with Number == 83 already exists, skip.
   • Creates the map by invoking the same logic as the initializer.
   • Applied at runtime only via AdminPanel → Updates (per the Imperial finding; DataUpdateService is only triggered there). Do NOT call SaveChanges inside the plugin.
5. Access / warp (for testing) — a WarpInfo entry ("Arkania", target map 83, coordinates on a safe tile, level/zen cost) so the map is reachable via /move Arkania, plus an entrance ExitGate. May be seeded or added via panel; seeding it keeps the pilot self-contained for verification.
6. PC client — copy World83, Object83, and the Local/Eng additions (ImgsMapName/Arkania.OZT, Minimap/Minimap_World83_eng.bmd if present, merge movereq_eng.bmd) into D:\AdaMu\AdaMu\Data. Verify the MUnique engine supports world index 83 (terrain/object loading is generic; if a world-index cap or per-index table blocks it, add support in vendor/MuMain source and rebuild Main.exe per pc-munique-client-build).

Data flow

Server loads map 83 from GameConfiguration → UpdateTerrainFromResources decodes Terrain83.att into walkable/safezone grid → player issues /move Arkania (or uses the entrance gate) → server places them on the safe spawn tile of map 83 → PC client renders Data/World83 (terrain + objects) → empty but walkable map. In the web panel, MapEditor renders the same terrain from TerrainData; the user places MonsterSpawnArea/gates/NPCs and saves → they take effect on the live server.

Verification

1. Server build: docker build -f Startup/Dockerfile -t adamu-openmu:dev . succeeds; map 83 present in built config (symbol/log check). Local dotnet build is expected to fail at the source-gen pre-step (normal, per Imperial notes).
2. Web: map "Arkania" appears in /edit-config-grid/GameMapDefinition; /map-editor renders its terrain (not blank).
3. PC client: /move Arkania enters the map; terrain and objects render; no crash; safezone correct; player can walk.
4. Only after all three pass is the pilot considered done.

Out of scope (follow-up, after pilot proven)

• Maps 84-87 (Acheron/Debenter/Uruk/Ferea) — same template, replicated.
• Mobile client asset import + APK considerations.
• Authoring actual monster spawns / NPCs / drops (done by the user via panel; not part of the seed).
• Any C++→OpenMU map converter.

Risks

• Index/name mismatch → wrong map name shown. Mitigation: confirm World83 identity against pack screenshots before finalizing Name.
• Engine world-index support on the MUnique client for index 83 → if unsupported, requires a vendor/MuMain change + rebuild. Low likelihood (loading is data-driven) but flagged.
• Terrain resource not globbed by the csproj → map loads with empty terrain. Mitigation: verify embedded-resource inclusion during step 1.