Main Map

Main Map

Purpose

The Main Map is the world overview where players browse, select, and enter individual Realms (tiles). It provides high‑level information (coordinates, ownership, and resource bonus) and is the starting point for all realm‑level actions.

Player View

  • Tiled world: a 2D/iso grid of selectable tiles ("Realms").

  • Each tile = one Realm you can enter to manage buildings, turns, and units.

  • Bonus icon/color on the tile shows its resource specialty: Food, Wood, Stone, or Iron.

  • Hover/Select: shows coordinates, name (if set), and bonus.

  • Click a tile to open that Realm’s interior screen (The Land).

Controls

  • Pan/Drag: Left‑click and drag the map to move the camera.

  • Zoom: Mouse wheel to zoom in/out (clamped to comfortable limits).

  • Right‑click: (If enabled on your build) opens contextual UI elsewhere; main map typically uses left‑click to enter a Realm.

  • Disable system context menu: The app suppresses the browser context menu on canvas for better UX; text inputs still allow it.

Tip: If you lose your place, use any in‑app “Back to Map”/reload button to recenter.

Tiles (Realms)

Coordinates

  • UI: 1‑indexed (X, Y) displayed to players (e.g., 1,1).

  • On‑chain: 0‑indexed for contract calls. The app subtracts 1 from UI coords before sending to contracts.

Resource Bonus

Each tile has one permanent bonus: Food, Wood, Stone, or Iron.

  • In a Realm, your per‑turn yield for the bonus resource is effectively doubled compared to a non‑bonus resource (the interior calculator adds an extra base chunk for the bonus).

  • The bonus also skins backgrounds/tiles in the Realm view for visual feedback.

Ownership

  • Every tile has an occupant (owner) address on‑chain.

  • Actions that modify state (e.g., building, listing items) require that your connected wallet is the tile’s occupant.

Naming a Realm (optional)

  • Players can set a Realm Name on a tile for a token fee (e.g., 10,000 LOP).

  • Names are stored on‑chain and are displayed in UI wherever that Realm is referenced.

What You Can Do From the Main Map

  • Browse: pan/zoom across the world to find interesting tiles (by bonus, position, etc.).

  • Inspect: view coordinates and (where shown) owner/name at a glance.

  • Enter Realm: select a tile to switch to its interior management screen.

Clan, marketplace, training, and tech actions happen inside the Realm screen after you enter a tile.

Visual Legend

  • Food tiles: green‑tinted/food icon

  • Wood tiles: brown/forest motif

  • Stone tiles: gray/rock motif

  • Iron tiles: dark/ore motif

(Exact palette/icons may vary by build; bonus type is always clearly indicated.)

Data & Contracts (Developer Notes)

Coordinate Conventions

  • UI -> Chain: (uiX, uiY) → (x = uiX - 1, y = uiY - 1) for every contract call.

  • Tile Key: some systems (e.g., marketplace/clan invites) compose a single key as tileKey = x * 256 + y (equivalent to (x << 8) | y). This encodes two 8‑bit axes (0..255) into one integer.

Common Reads on Main Map

  • Tile ownership: TileMap.getTileOccupant(x, y) → wallet address.

  • Bonus type: world metadata for the tile (used by UI and interior calculators).

  • Name: Clan/Name registry contract getTileName(x, y).

All reads use 0‑indexed (x, y).

Navigation Flow

  1. Player pans/zooms and selects a tile.

  2. App records the selected uiX, uiY and its bonusType.

  3. On entering The Land (interior), the app passes { x: uiX, y: uiY, bonusType } and begins on‑chain reads specific to that Realm (resources, buildings, soldiers, tech, etc.).

Error States & Feedback

  • Wallet not connected: prompt to connect before entering or acting on a Realm.

  • Not the owner: state‑changing actions are disabled; read‑only info still shown.

  • Invalid tile: graceful toast and no navigation.

Performance Notes (Dev)

  • Use camera culling / render only what’s visible.

  • Keep event handlers light; avoid expensive per‑tile DOM.

  • Avoid layout thrash on zoom; clamp min/max zoom.

QA Checklist

  • Selecting any tile reliably opens the correct Realm (off‑by‑one checks pass).

  • Bonus type on the main map matches interior backgrounds and the yield calculator.

  • Named tiles display consistently wherever referenced.

  • Non‑owners cannot trigger state‑changing actions from the map.

Glossary

  • Realm: A single playable tile on the Main Map.

  • Bonus Type: The resource specialty of a tile (Food/Wood/Stone/Iron).

  • Occupant: The on‑chain owner of a tile.

  • Interior (The Land): The management view for a selected Realm.

PreviousMasters of ManagementNextPlayer Lands

Last updated