Shared

Um sistema de verificação espacial de alta performance para o mundo do jogo. Zones definem uma área 3D (sphere, box ou polygon) e avaliam se uma posição está dentro ou fora daquela região, de forma semelhante a um colshape.

Internamente, as Zones utilizam um spatial grid para restringir com eficiência as zones relevantes antes de executar testes precisos de posição.

Para Lua, isto substitui o PolyZone e aproveita a biblioteca GLM para alta performance e eficiência de memória.

As Zones também estão disponíveis em JS, utilizando nossa biblioteca de utilidades para operações de geometria, grid e espaciais.

Zones do lado do servidor não suportam eventos de trigger do jogador. Os manipuladores onEnter, onExit e inside estão indisponíveis.

As zones em Lua e JavaScript não são compatíveis em termos de API. As definições TypeScript e os comentários TSDoc no pacote npm servem como referência oficial para a JavaScript API.

Polygon/Prism Zone

Cria um polígono a partir dos vértices fornecidos, que é então colocado no mundo e extrudado até a altura fornecida para formar uma forma 3D.

lib.zones.poly(data)

data: table
- points: vector3[]
  - Um array de pontos 3D que definem a forma do polígono.
- thickness?: number
  - A altura do polígono, padrão 4.
- onEnter?: function(self: table)
- onExit?: function(self: table)
- inside?: function(self: table)
- debug?: boolean

import { Zone } from "@overextended/ox_lib";
import { Vector2 } from "@overextended/core/vector";

Zone.Prism(vertices: Vector2[], height: number, z: number)

Box Zone

lib.zones.box(data)

data: table
- coords: vector3
- size?: vector3
  - Padrão: vec3(2, 2, 2)
- rotation?: number
  - Ângulo em graus, padrão 0.
- onEnter?: function(self: table)
- onExit?: function(self: table)
- inside?: function(self: table)
- debug?: boolean

import { Zone } from "@overextended/ox_lib";
import { Vector3 } from "@overextended/core/vector";

Zone.Cuboid(origin: Vector3, width: number, depth: number, height: number, heading?: number)

Sphere Zone

lib.zones.sphere(data)

data: table
- coords: vector3
- radius?: number
  - Padrão: 2
- onEnter?: function(self: table)
- onExit?: function(self: table)
- inside?: function(self: table)
- debug?: boolean

import { Zone } from "@overextended/ox_lib";
import { Vector3 } from "@overextended/core/vector";

Zone.Sphere(coords: Vector3, radius: number)

Métodos

onEnter

Uma função chamada quando o jogador entra na zone. Ela pode ser anexada à zone após a instanciação, ou na tabela data se estiver usando Lua.

local function onEnter(self)
    print('entered zone', self.id)
end

zone.onEnter = onEnter

function onEnter(this: Zone) {
  console.log(`entered zone ${this.id}`)
}

zone.onEnter = onEnter;

onExit

Uma função chamada quando o jogador sai da zone. Ela pode ser anexada à zone após a instanciação, ou na tabela data se estiver usando Lua.

local function onExit(self)
    print('exited zone', self.id)
end

zone.onExit = onExit

function onExit(this: Zone) {
  console.log(`exited zone ${this.id}`)
}

zone.onExit = onExit;

inside

Uma função chamada a cada frame enquanto o jogador está dentro da zone. Ela pode ser anexada à zone após a instanciação, ou na tabela data se estiver usando Lua.

local function inside(self)
    print('you are inside zone', self.id)
end

zone.inside = inside

function inside(this: Zone) {
  console.log(`you are inside zone ${this.id}`)
}

zone.inside = inside;

remove

Zones podem ser excluídas usando o método remove.

zone:remove()

zone.remove()
// or
Zone.delete(zone.id)

contains

Avalia se um ponto está dentro da zone.

zone:contains(vec3(1, 1, 1))

import { Vector3 } from "@overextended/ox_lib";

zone.contains(new Vector3(1, 1, 1))

Retorna: boolean

setDebug

Ativa ou desativa o modo debug para uma zone, opcionalmente com cores personalizadas.

Para JavaScript, defina zone.shouldDraw ou chame manualmente zone.draw(...args).

local zone = lib.zones.box({...})

-- Enable debug with default colors
zone:setDebug(true)

-- Enable debug with custom colors
zone:setDebug(true, vec4(255, 0, 0, 100))

-- Disable debug
zone:setDebug(false)

Funções utilitárias

getAllZones

Retorna todas as zones registradas.

lib.zones.getAllZones()

Retorna: CZone[]

import { Zone } from "@overextended/ox_lib";

Zone.getAll();

Retorna: Set<Zone>

getCurrentZones

Retorna todas as zones nas quais o jogador está atualmente.

lib.zones.getCurrentZones()

Retorna: CZone[]

import { Zone } from "@overextended/ox_lib";

Zone.getCurrent();

Retorna: Set<Zone>

getNearbyZones

Retorna todas as zones próximas ao jogador.

lib.zones.getNearbyZones()

Retorna: CZone[]

import { Zone } from "@overextended/ox_lib";

Zone.getNearby(point);

point?: Vector2 | Vector3
- O padrão é a posição atual do jogador.

Retorna: Set<Zone>

Exemplos de uso

function onEnter(self)
    print('entered zone', self.id)
end

function onExit(self)
    print('exited zone', self.id)
end

function inside(self)
    print('you are inside zone ' .. self.id)
end

local poly = lib.zones.poly({
    points = {
        vec(413.8, -1026.1, 29),
        vec(411.6, -1023.1, 29),
        vec(412.2, -1018.0, 29),
        vec(417.2, -1016.3, 29),
        vec(422.3, -1020.0, 29),
        vec(426.8, -1015.9, 29),
        vec(431.8, -1013.0, 29),
        vec(437.3, -1018.4, 29),
        vec(432.4, -1027.2, 29),
        vec(424.7, -1023.5, 29),
        vec(420.0, -1030.2, 29),
        vec(409.8, -1028.4, 29),
    },
    thickness = 2,
    debug = true,
    inside = inside,
    onEnter = onEnter,
    onExit = onExit
})

local sphere = lib.zones.sphere({
    coords = vec3(442.5363, -1017.666, 28.65637),
    radius = 1,
    debug = true,
    inside = inside,
    onEnter = onEnter,
    onExit = onExit
})

local box = lib.zones.box({
    coords = vec3(442.5363, -1017.666, 28.65637),
    size = vec3(1, 1, 1),
    rotation = 45,
    debug = true,
    inside = inside,
    onEnter = onEnter,
    onExit = onExit
})

import { Zone } from "@overextended/ox_lib";
import { Vector2, Vector3 } from "@overextended/core/vector";

function onEnter(this: Zone) {
  console.log(`entered ${this.id}`)
}

function onExit(this: Zone) {
  console.log(`exited ${this.id}`)
}

function inside(this: Zone) {
  console.log(`inside ${this.id}`)
}

const shouldDraw = true;

Zone.Prism([
  new Vector2(413.8, -1026.1),
  new Vector2(411.6, -1023.1),
  new Vector2(412.2, -1018.0),
  new Vector2(417.2, -1016.3),
  new Vector2(422.3, -1020.0),
  new Vector2(426.8, -1015.9),
  new Vector2(431.8, -1013.0),
  new Vector2(437.3, -1018.4),
  new Vector2(432.4, -1027.2),
  new Vector2(424.7, -1023.5),
  new Vector2(420.0, -1030.2),
  new Vector2(409.8, -1028.4)
], 2, 29)

Zone.Sphere(new Vector3(442.5363, -1017.666, 28.65637), 1)

Zone.Cuboid(new Vector3(442.5363, -1017.666, 28.65637), 1, 1, 1)

Zone.map.forEach((zone) => {
  zone.inside = inside;
  zone.onEnter = onEnter;
  zone.onExit = onExit;
  zone.shouldDraw = shouldDraw;
})

Script de criação de Zones

Você pode usar nosso criador de zones embutido com /zone, passando poly, box ou sphere como argumento. Os controles disponíveis serão exibidos no lado direito.

As zones serão salvas em ox_lib/created_zones.lua no formato escolhido.

local poly = lib.zones.poly({
    name = poly,
    points = {
        vec(447.9, -998.8, 25.8),
        vec(450.3, -998.2, 25.8),
        vec(449.9, -995.5, 25.8),
        vec(447.2, -995.6, 25.8),
        vec(446.3, -997.9, 25.8),
    },
    thickness = 2,
})

{
    name = poly,
    points = {
        vec(447.9, -998.8, 25.8),
        vec(450.3, -998.2, 25.8),
        vec(449.9, -995.5, 25.8),
        vec(447.2, -995.6, 25.8),
        vec(446.3, -997.9, 25.8),
    },
    thickness = 2,
},

exports.ox_target:addPolyZone({
    name = poly,
    points = {
        vec(447.9, -998.8, 25.8),
        vec(450.3, -998.2, 25.8),
        vec(449.9, -995.5, 25.8),
        vec(447.2, -995.6, 25.8),
        vec(446.3, -997.9, 25.8),
    },
    thickness = 2,
})

On this page