## Warps control

Control Module - Warps - Stores warps for each force.

### Usage

    -- Making a new spawn warp
    local player = game.player
    local force = player.force
    local spawn_id = Warps.add_warp(force.name, player.surface, player.position, player.name, 'Spawn')

    Warps.set_spawn_warp(spawn_id, force)
    Warps.make_warp_tag(spawn_id)

    -- Making a new warp with a warp area
    local player = game.player
    local force = player.force
    local warp_id = Warps.add_warp(force.name, player.surface, player.position, player.name)

    Warps.make_warp_area(warp_id)
    Warps.make_warp_tag(warp_id)

### Dependencies

expcore.datastore
utils.global
config.warps

### Getters

get_warp(warp_id) | Gets the warp information that is linked with this id
get_force_warp_ids(force_name) | Gets all the warp ids that a force has
get_spawn_warp_id(force_name) | Get the id of the spawn warp
get_editing(warp_id, player_name) | Gets the editing state for a player

### Setters

add_warp(force_name, surface, position[, player_name][, warp_name]) | Add a new warp for a force, the warp must have a surface and a position
remove_warp(warp_id) | Removes a warp and any data linked to it
update_warp(warp_id[, new_name][, new_icon][, player_name='server']) | Update the name and icon for a warp
set_editing(warp_id, player_name, state) | Set the editing state for a player, can be used as a warning or to display a text field
on_update(handler) | Adds an update handler for when a warp is added, removed, or updated

### Map Integration

make_warp_tag(warp_id) | Add or update the chat tag for this warp
remove_warp_tag(warp_id) | Remove the chart tag for this warp
make_warp_area(warp_id) | Add a warp area for the warp, purely cosmetic
remove_warp_area(warp_id) | Remove the warp area for a warp
set_spawn_warp(warp_id, force) | Set a warp to be the spawn point for a force, force must own this warp
teleport_player(warp_id, player) | Teleport a player to a warp point

### Dependencies

# expcore.datastore
# utils.global
# config.warps

### Getters

# get_warp(warp_id)

  Gets the warp information that is linked with this id

  Parameters:
  - warp_id : (string) the uid of the warp you want to get
  Returns:
  - (table) the warp information
  Usage:

      -- Getting warp information outside of on_update
      local warp = Warps.get_warp(warp_id)

# get_force_warp_ids(force_name)

  Gets all the warp ids that a force has

  Parameters:
  - force_name : (string) the name of the force that you want the warp ids for
  Returns:
  - (table) an array of all the warp ids
  Usage:

      -- Getting the warp ids for a force
      local warp_ids = Warps.get_force_warp_ids(game.player.force.name)

# get_spawn_warp_id(force_name)

  Get the id of the spawn warp

  Parameters:
  - force_name : (string) the name of the force that you want to get the spawn warp for
  Returns:
  - (string or nil) the uid of the spawn warp for this force if there is one
  Usage:

      -- Getting the spawn warp id
      local spawn_id = Warps.get_spawn_warp_id(game.player.force.name)

# get_editing(warp_id, player_name)

  Gets the editing state for a player

  Parameters:
  - warp_id : (string) the uid of the warp you want to check
  - player_name : (string) the name of the player that you want to check
  Returns:
  - (boolean) weather the player is currently editing this warp
  Usage:

      -- Check if a player is editing a warp or not
      local editing = Warps.get_editing(warp_id, game.player.name)

### Setters

# add_warp(force_name, surface, position[, player_name][, warp_name])

  Add a new warp for a force, the warp must have a surface and a position

  Parameters:
  - force_name : (string) the name of the force to add the warp for
  - surface : (LuaSurface) the surface that the warp will be on
  - position : (Position) the position that the warp will be on
  - player_name : (string) the name of the player that is adding the warp (optional)
  - warp_name : (string) the name of the warp that is being added, if omited default is used (optional)
  Returns:
  - (string) the uid of the warp which was created
  Usage:

      -- Adding a new warp for your force at your position
      local player = game.player
      local warp_id = Warps.add_warp(player.force.name, player.surface, player.position, player.name)

# remove_warp(warp_id)

  Removes a warp and any data linked to it

  Parameters:
  - warp_id : (string) the uid of the warp that you want to remove
  Usage:

      -- Removing a warp
      Warps.remove_warp(warp_id)

# update_warp(warp_id[, new_name][, new_icon][, player_name='server'])

  Update the name and icon for a warp

  Parameters:
  - warp_id : (string) the uid of the warp that you want to update
  - new_name : (string) the new name that you want the warp to have (optional)
  - new_icon : (string) the new icon that you want the warp to have (optional)
  - player_name : (string) the name of the player that made the edit (default: 'server')
  Usage:

      -- Changing the name and icon for a warp
      Warps.update_warp(warp_id, 'My Warp', 'iron-plate', game.player.name)

# set_editing(warp_id, player_name, state)

  Set the editing state for a player, can be used as a warning or to display a text field

  Parameters:
  - warp_id : (string) the uid of the warp that you want to effect
  - player_name : (string) the name of the player you want to set the state for
  - state : (boolean) the new state to set editing to
  Usage:

      -- Setting your editing state to true
      Warps.set_editing(warp_id, game.player.name, true)

# on_update(handler)

  Adds an update handler for when a warp is added, removed, or updated

  Parameters:
  - handler : (function) the handler which is called when a warp is updated
  Usage:

      -- Add a game print when a warp is updated
      Warps.on_update(function(warp)
          game.print(warp.force_name..' now has the warp: '..warp.name)
      end)

### Map Integration

# make_warp_tag(warp_id)

  Add or update the chat tag for this warp

  Parameters:
  - warp_id : (string) the uid of the warp you want the chart tag for
  Returns:
  - (boolean) true if a new tag was made, false if it was updated
  Usage:

      -- Adding a chart tag for a new warp
      local tag_added = Warps.make_warp_tag(warp_id)

# remove_warp_tag(warp_id)

  Remove the chart tag for this warp

  Parameters:
  - warp_id : (string) the uid for the warp that you want to remove the chart tag from
  Returns:
  - (boolean) true if the tag was valid and was removed, false if the tag was invalid
  Usage:

      -- Removing the chart tag from a warp
      local removed = Warps.remove_warp_tag(warp_id)

# make_warp_area(warp_id)

  Add a warp area for the warp, purely cosmetic

  Parameters:
  - warp_id : (string) the uid of the warp you want the area for
  Usage:

      -- Adding a warp area for a warp
      Warps.make_warp_area(warp_id)

# remove_warp_area(warp_id)

  Remove the warp area for a warp

  Parameters:
  - warp_id : (string) the uid of the warp that you want to remove the area for
  Usage:

      -- Remove the warp area for a warp
      Warps.remove_warp_area(warp_id)

# set_spawn_warp(warp_id, force)

  Set a warp to be the spawn point for a force, force must own this warp

  Parameters:
  - warp_id : (string) the uid of the warp that you want to be the spawn for the force
  - force : (LuaForce) the force that you want to set the spawn for
  Usage:

      -- Set your forces spawn to a warp
      Warps.set_spawn_warp(warp_id, game.player.force)

# teleport_player(warp_id, player)

  Teleport a player to a warp point

  Parameters:
  - warp_id : (string) the uid of the warp to send the player to
  - player : (LuaPlayer) the player to teleport to the warp
  Usage:

      -- Teleport yourself to a warp point
      Warps.teleport_player(warp_id, game.player)