Polyzones

Polyzones are used to allow player interaction, there are many types for different situations available.

Registering Zones

There are many types of zones for different situations, while there isn't always a correct answer there is a range of options.

AddBoxZone

Box zones create a square area around a vector3 using length and width measurements. These are used for area-based interactions like repair bays and garages.

Parameter	Required	Type	Description
name		String	Unique reference for the zone
coords		vector3	Position of the zone
length		Float	Length of the zone
width		Float	Width of the zone
options		Object	Settings of the zone

-- Zone Options
-- maxZ & minZ - Define the height of the box, the "start-stop" points of the box
-- heading - heading of the box
-- data - Data "attached" to zone

TMC.Functions.AddBoxZone('zone_example', coords, length, width, {
    maxZ = 20,
    minZ = 10,
    heading = 50,
    data = { value = true }
})

AddCricleZone

Circle zones create a spherical area around a vector3, these are usually used for point-based interactions like doors, peds and more.

Parameter	Required	Type	Description
name		String	Unique reference for the zone
coords		vector3	Position of the zone
radius		Float	Size of the sphere
options		Object	Settings of the zone

-- Zone Options
-- useZ - Defaults to false. If set to false, creates a verticle tube.
-- data - Data "attached" to zone

TMC.Functions.AddCircleZone('zone_example', coords, radius, {
    useZ = true,
    data = { value = true }
})

AddPolyZone

Poly zones create a customised shape around multiple points, these are usually used for areas that aren't square like buildings and large areas.

Parameter	Required	Type	Description
name		String	Unique reference for the zone
vectors		Object	Object with mulitple vector2 points
options		Object	Settings of the zone

-- Vectors example
local vectors = {
    vector2(1.0, 1.0),
    vector2(2.0, 2.0),
    vector2(3.0, 3.0),
    vector2(4.0, 4.0),
}

-- Zone Options
-- maxZ & minZ - Define the height of the box, the "start-stop" points of the box
-- data - Data "attached" to zone

TMC.Functions.AddPolyZone('zone_example', vectors, {
    maxZ = 20,
    minZ = 10,
    data = { value = true }
})

AddEntityZone

Entity zones create zones around a selected entity, these can be useful in hunting scripts as these are attached and follow entities, unlike the other options.

Parameter	Required	Type	Description
name		String	Unique reference for the zone
entity		Entity	Entity handle
options		Object	Settings of the zone

-- Zone Options
-- useZ - Defaults to false. If set to false, creates a verticle box.
-- scale - Width, Length and Height of the box created
-- data - Data "attached" to zone

TMC.Functions.AddEntityZone('zone_example', entity, {
    useZ = true,
    scale = { 2.5, 2.5, 2.5 }
    data = { value = true }
})

Registering Handlers

Zone handlers are used to register callbacks to be run when the player leaves and enters zones.

AddPolyZoneEnterHandler

The enter handler registers what callback is run when the player enters the zone

Parameter	Required	Type	Description
name		String	Unique reference for the zone
callback		Function	Callback function

-- The data parameter returns the data that was set when registering the zone.
-- This is helpful for passing information like current building etc.

TMC.Functions.AddPolyZoneEnterHandler('zone_example', function(data)
    
end)

AddPolyZoneExitHandler

The exit handler registers what callback is run when the player exits the zone

Parameter	Required	Type	Description
name		String	Unique reference for the zone
callback		Function	Callback function

-- The data parameter returns the data that was set when registering the zone.
-- This is helpful for passing information like current building etc.

TMC.Functions.AddPolyZoneExitHandler('zone_example', function(data)
    
end)

Development Commands

/pzcreate

Starts a polyzone creation session, depending on the type and additional inputs you'll see the location displayed. You'll be able to control the "last" point during creation with keybinds. A guide on how to control the zone based on the type of zone being created is below.

Circle:

• Arrow Keys: moves the center of the zone

• Ctrl: moves everything slower

• Z: changes between circle and sphere mode

• Scroll Wheel: change radius of the zone

• Alt + Scroll Wheel: changes height of the circle zone or the position of the sphere in sphere mode

Box:

• Arrow Keys: moves the center of the zone

• Ctrl: moves everything slower (position/size/rotation changes)

• Z: Change scroll mode between (scale/rotation and height mods)

• Scale/Rotation Mode:

  • Scroll Wheel: change heading/rotation

  • Alt + Scroll Wheel: change width

  • Shift + Scroll Wheel: change length

• Height Mode:

  • Scroll Wheel: changes the position of the center of the zone

  • Alt + Scroll Wheel: changes the bottom limit of the zone

  • Shift + Scroll Wheel: changes the top limit of the zone

Poly:

• Arrows Keys: moves the last added point

• Ctrl: Slow down movement

Parameter	Required	Type	Description
zoneType		String	Must be circle, box or poly
name		String	Name of the zone

/pzadd

Used during the creation of a poly type zone. Will add a new point at the characters current location.

/pzundo

Used during the creation of a poly type zone. Undoes the last point added.

/pzfinish

Finish the creation of a zone and display the config so it can be copied to clipboard.

/pzlast

Uses the last configuration (type, size, etc) and allows you to move it. Useful for adding multiple of the same zones (I.e. car park spaces).

/pzcancel

Stop the creation of the zone without finishing it.

/pzdebug

Shows all zones that have been created using the TMC commands. Useful to find locations and debug information.

The second parameter of distanceLimit is not required however it is highly recommended. Failing to do so will cause serious lag as your client attempts to render potentially thousands of zones at once.

Parameter	Required	Type	Description
distanceLimit		Number	The distance around the player to render zones. Highly recommend to use this in order to prevent major performance issues. Recommended maximum: 50