ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
:toc: left
:toclevels: 5

= Map

This module adds map features.

== Extension

=== Map.Entity

Client-side map entity.

[source,lua]
----
self.id 
self.cfg 

-- called when the entity is loaded
Entity:load()

-- called when the entity is unloaded
Entity:unload()

-- called to check if the entity is active
-- px, py, pz: player position
-- should return true if active
Entity:active(px, py, pz)

-- called at each render frame if the entity is active
-- time: seconds since last frame
Entity:frame(time) 
----

`Entity.command` table can be created to define entity commands, the same way as for the `Extension.proxy` table.

=== User

[source,lua]
----
self.map_areas

-- create/update a player area
-- cb_enter(user, name): (optional) called when entering the area
-- cb_leave(user, name): (optional) called when leaving the area
User:setArea(name,x,y,z,radius,height,cb_enter,cb_leave)

User:removeArea(name)

User:inArea(name)
----

=== Server

[source,lua]
----
self.cfg
----

=== Client

[source,lua]
----
self.entities -- map of id (number or name) => entity
self.def_entities -- defined entities
self.frame_entities -- active entities for the next frames
self.areas

-- ent: Map.Entity class
Map:registerEntity(ent)

-- add entity
-- ent: registered entity name
-- cfg: entity config
-- return id (number) or nil on failure
Map:addEntity(ent, cfg)

-- id: number or string
Map:removeEntity(id)

-- id: number (update added entity) or string (create/update named entity)
-- ent: registered entity name
-- cfg: entity config
Map:setEntity(id, ent, cfg)

-- entity command
-- id: number or string
-- command: command name
-- ...: arguments
Map:commandEntity(id, command, ...)

-- GPS

-- set the GPS destination marker coordinates
Map:setGPS(x,y)

-- DOOR

-- set the closest door state
-- doordef: .model or .modelhash
-- locked: boolean
-- doorswing: -1 to 1
Map:setStateOfClosestDoor(doordef, locked, doorswing)

-- TUNNEL

Map.tunnel.addEntity = Map.addEntity
Map.tunnel.setEntity = Map.setEntity
Map.tunnel.removeEntity = Map.removeEntity
Map.tunnel.commandEntity = Map.commandEntity
Map.tunnel.setGPS = Map.setGPS
Map.tunnel.setStateOfClosestDoor = Map.setStateOfClosestDoor
----

== Map entity

=== Map.PosEntity 

Specialized entity with a position and default active behavior by distance.

.config
[horizontal]
pos:: `{x,y,z}` (must be floats)
active_distance:: (optional) maximum distance for the entity to be active, default is 250

=== PoI

**Point of Interest** generic map entity (blip/marker).
Inherits from `Map.PosEntity`.

.config
[horizontal]
blip_id, blip_color:: (optional) blip id/color (ex: https://wiki.gtanet.work/index.php?title=Blips)
blip_scale:: (optional) float
blip_flashes:: (optional) mode number `1` or `2` (flashes or flashes alternate)
title:: (optional) title (used for the blip)
marker_id:: (optional) marker id (ex: https://wiki.gtanet.work/index.php?title=Marker)
scale:: (optional) `{sx,sy,sz}` marker scale
color:: (optional) `{r,g,b,a}` marker color
height:: (optional) marker height
rotate_speed:: (optional) number of z-axis rotations per second

.commands
[horizontal]
`setBlipRoute()`:: set player blip route to `PoI` blip

=== PlayerMark

Mark on player ped.

.config
[horizontal]
player:: player server id
blip_id, blip_color:: (optional) blip id/color (ex: https://wiki.gtanet.work/index.php?title=Blips)
blip_scale:: (optional) float
blip_flashes:: (optional) mode number `1` or `2` (flashes or flashes alternate)
title:: (optional) title (used for the blip)
