Map file structure

[Dracks]

We need to define the file structure for saving the map, and being able to send it to the server and share between instances. This issue is created as a way to write down proposals and requirements accessible for everybody. At some moment some discord meeting will be created to finalize the decision.

What needs to be save:

1. The size of the map (yeah, I know, seems obvious)
2. The terrain tiles
3. Owner of the building
4. Units and his owner

Open questions:

• Did we wish to simply consider a map as a snapshot of a match?
  This will allow things like start a match with a building half captured, to compensate the first turn advantage, in that case, the file format maybe can be the same as the one to synchronize with the server
• Did we wish to have a version key on the map?
  allowing to identify the terrain by version & name and avoiding then to save the terrain info on the match? Or we prefer to have the terrain info on the match level, and then simply drop all matches older than X?

Please add proposals as comments.

[Dracks]

My proposal will be something like:

enum TileType{
    start_road_left,
    start_road_right,
    start_road_up,
    start_road_down,
    plane,
    mountain,
    ...
}

type Building = {
    type: BuildingType
    capture_state?: int
    position: Vector2i
    owner: PlayerId
}

type Unit {
    type: UnitType
    owner: PlayerId
    position: Vector2i
}

type MapFile = {
    name: string;
    size: Vector2i;
    tiles: TileType[][];
    interactive: Array<Building | Unit>
}

P.D.: I used pseudo typescript syntax, as It's easy for me to write down

[HunterNN]

This is the structure that I have in my mind. It highlights the importance of this particular file structure.

[Dracks]

I like your diagram, but I will change some stuff:

flowchart LR
    awbwMap[AWBW Map]
   
    awbwMap --import--> Editor
    Editor <--> MapFile
    MapFile <-.-> Server
    Game <--> MapFile
    Game <--> Server
    MapFile <-.-> FileSystem
    

Loading

[Darkbladecr]

I already put together a simple schema for the units and terrain? I don't know if you want to just extend this?
As per the Discord discussion we probably don't need the fine grained detail of the sprite (road horizontal, road NE bend, etc.) used in the tile, but rather just the tile type (road, woods, mountain). It is then up to the client (godot) to decide how to visually show this.

AWBW is simply a int array based on their sprite specific tiles, so importing will be easy to parse into our terrain type system.

I agree that the root MapFile should be similar in structure to the actual match schema.
Terrain schema
Unit schema

Something similar to this (following the typescript convention):

interface ITerrain {
  name: string;
  description: string;
  type: ETerrainType;
  defense: number;
  health: number;
  can_capture: boolean;
  capture_value: number;
  owner: number;
  funds: number;
  ammo: number;
}

interface IUnit {
  name: string;
  description: string;
  cost: number;
  health: number;
  mp: number;
  movement_type: EMovementType;
  fuel: number;
  turn_fuel: number;
  hidden_turn_fuel: number;
  vision: number;
  ammo: number;
  weapons: [EWeapon, EWeapon];
  min_range: number;
  max_range: number;
  can_supply: boolean;
  can_repair: boolean;
  can_capture: boolean;
  can_move_and_attack: boolean;
  can_hide: boolean;
  can_dive: boolean;
  can_carry: boolean;
  carrying_types: EUnit[];
  carrying_size: number;
}

interface MapFile {
  name: string;
  author: string;
  playerNum: number;
  shape: [number, number];
  terrain: ITerrain[][];
  units: IUnit[][];
}

interface IPlayer {
  CO: ECO;
  country: ECountry;
  power: number;
}

interface Game extends MapFile {
  players: IPlayer[];
}

[Darkbladecr]

Then for replays, we would have a set of actions that we can embed into the map file that can be read by any replay client.

[FlygonC]

I don't know if it really matters but, I'd like to point out that the actual map data does not have to be a 2D array. It can be 1D as long as the intended dimensions of the map (which shouldn't change) is also stored.
Finding a tile at a specific coordinate can be done with [y * width + x] when using this map structure.
Again, I don't know if 1D is any faster or takes up any less space, it just made sense in my personal project that had the tiles as objects.
My other thought, that I had working in my personal project, was to have a separate list for pre-captured properties. Something like after building the map, it iterates the pre-capture list which says [tile x,y starts owned by player 1, ...] if it's actually a property at said tile.

[HunterNN]

Good point about the one-dimensional array. However, I would prefer to keep it in 2D for better readability for humans. I currently like Darkblade's version, but there are some unnecessary values such as unit movepoints or min/max range. These values should not be included in every map save since they are provided by the types.

interface ITerrain {
  id: string;  // tile id e.g. RIVER
  id_tile: string;  // exact tile id e.g. SWRIVER
  health: number;
  capture_value: number;
  owner: number;  // Player.ID
  ammo: number;
}

interface IUnit {
  id: string;
  health: number;
  fuel: number;
  ammo: number;
  carrying: IUnit[];
  owner: number;  // Player.ID
  is_hidden: bool  // e.g. submerged submarines
}

interface MapFile {
  name: string;
  author: string;
  playerNum: number;
  shape: [number, number];
  terrain: ITerrain[][];
  units: IUnit[][];
  players: IPlayer[];
}

interface IPlayer {
  ID: number;
  CO: ECO;
  country: ECountry;
  power: number;
  money: number;
}

I have removed the extended MapFile and implemented those values directly in the MapFile instead. I'm not sure what the original idea behind having a separate extended MapFile was (?).

[FlygonC]

2D or 1D, it's just going to be a wall of numbers without an interface, regardless. I'm not sure how readability of the raw file really matters in this instance since we're going to have a tool for creating and editing that translates it to something user friendly on the front.

[Dracks]

yeah, but if there is some problem on the code that generates the view, makes it easy to understand and debug.

[Dracks]

I agree on @HunterNN , usually two dimensions are more human friendly.

Keep in mind that if we don't wish to put the specs of the units/cos on the match, then we need some kind of versioning, to avoid brake current games. Also, in the replays, will be nice to have this info. In a project I colaborated in the past, we created some kind of versioning for the base info, It didn't work as well as expected, but it didn't work wrong in general.

[HunterNN]

I was talking with Dracks and it makes sense to use the specific tile definition without tile map generation. This keeps the loading of the map simple. Additionally, if we were to change the auto tiling, it would help to preserve old maps. This is also how AWBW maps work (except for shores). @Darkbladecr Would that be ok for you?

[Darkbladecr]

Yes I agree with this!

[Dracks]

Hi, I just had an idea, not sure yet if it's a good idea or a bad idea, but at least is something different, that can make sense (at least from the map-editor point of view)

class UnitInfo {
   owner: PlayerID
   unitType: "infantery" | "tank" | ...
   health: int
  ...
}

class BuildingInfo {
   owner: PlayerId
   capture_points: number
   ...
}

class PositionData {
  terrain: "forest" | "road" | "plane" | "ocean" | "river" | "city" | "industry" ...
  tile: TileId // I expect some int, or similar
  building?: BuildingInfo
  unit?: UnitInfo
}

class Map {
   size: Vector2i
   map: PositionData[][]
}

[HunterNN]

I have uploaded a version of the file structure to the wiki and will keep it up-to-date. Here's one question I have: Should we use compression for map files?
https://docs.godotengine.org/en/stable/classes/class_zippacker.html
https://docs.godotengine.org/en/stable/classes/class_zipreader.html
https://docs.godotengine.org/en/stable/classes/class_streampeergzip.html

[Dracks]

yeah, I think makes sense, but for the first versions, maybe we can use without the zip? that will make more easy to debug I think.