[Include] easyEnEx

***xbruno1000x***

Apresentação - easyEnEx (Atualizado v1.5)

Uma biblioteca leve e flexível para criar entradas e saídas (EnEx) no SA:MP — com suporte a Streamer, schedules e controle por jogador.

O que é?
A easyEnEx é uma dependência em Pawn criada para facilitar a criação e o gerenciamento de entradas/saídas (Exits/Entrances) em interiores do SA:MP — ideal para casas, lojas, armários, etc. Ela abstrai pickups, cria labels 3D, oferece controle de acesso (global e por jogador), agendamento por horário e facilita chamadas de evento para integrar sua lógica.

Novidades / Funcionalidades principais (última versão)

Criação dinâmica de EnEx com pickups via Streamer e labels 3D automáticos (nome personalizado na entrada e "Saída" no outro lado).
Parâmetros completos na criação: posição, ângulo, interior e virtual world para ambos os lados (entrada/saída), pickup id customizável e mensagem de entrada fechada personalizada.
Controle de bloqueio/desbloqueio: fechar/abrir EnEx global e por jogador (Enex_Close / Enex_Open / Enex_CloseForPlayer / Enex_OpenForPlayer).
Agendamento de funcionamento: definir horário de abertura/fechamento com suporte a intervalos que passam da meia-noite (Enex_SetSchedule + Enex_CheckSchedule).
Congelar jogador ao teletransportar (opcional) e desfazer o freeze automaticamente com timer.
Hooks e callbacks: integra com callbacks locais e hooks (OnPlayerAttemptEnEx via CallLocalFunction; OnPlayerDeniedEnEx opcional; OnPlayerEnterEnEx / OnPlayerExitEnEx).
Mensagens amigáveis ao jogador (mensagem padrão configurável ou personalizada por EnEx).
Compatibilidade e configuração: usa YSI Iterators, y_hooks, y_timers e Streamer; limite de EnEx configurável via MAX_ENEX.

Dependências

YSI 5 — (y_iterate, y_hooks, y_timers)
Streamer Plugin — para CreateDynamicPickup e streamdistance.
ZCMD (opcional) — apenas para exemplos de comandos no demo.

Constantes e comportamento padrão

MAX_ENEX — limite de entradas/saídas (pode ser definido antes de incluir a lib).
DEFAULT_PICKUPID — pickup usado por padrão (pode ser sobrescrito no Enex_Create).
DEFAULT_KEY — tecla padrão para ativar (por padrão KEY_SECONDARY_ATTACK).
MSG_ENTRADA_FECHADA — mensagem padrão quando a entrada estiver fechada (pode ser sobrescrita por Enex_Create).

Assinatura principal (criação)

Código:
stock Enex_Create(const name[*],

 Float:entX, Float:entY, Float:entZ, Float:entAng,

 Float:exX, Float:exY, Float:exZ, Float:exAng,

 ex_vwid = 0, ex_intid = 0, bool:freeze = false,

 en_vwid = 0, en_intid = 0,

 pickupid = DEFAULT_PICKUPID,

 const closedMsg[*] = MSG_ENTRADA_FECHADA);

Parâmetros importantes:

name: texto do label exibido na entrada (a saída recebe automaticamente "Saída").
entX/Y/Z, entAng: posição e ângulo da entrada.
exX/Y/Z, exAng: posição e ângulo da saída.
ex_vwid/ex_intid: virtual world e interior da saída.
freeze: se true, o jogador fica sem controle por breve tempo ao entrar.
en_vwid/en_intid: virtual world e interior da entrada.
pickupid: ID do modelo do pickup (DEFAULT_PICKUPID por padrão).
closedMsg: mensagem quando a entrada estiver trancada (string).

API / Funções úteis

Enex_Create(...) → cria e retorna o id do EnEx (ou -1 no erro).
Enex_Open(id) / Enex_Close(id) → abre / fecha globalmente um EnEx.
Enex_OpenForPlayer(playerid, enexid) / Enex_CloseForPlayer(playerid, enexid) → abre / fecha apenas para um jogador.
Enex_IsClosed(id) → retorna boolean se o EnEx está fechado globalmente.
Enex_SetSchedule(enexid, startHour, endHour) → define horário de funcionamento (horas inteiras 0–23).
Enex_CheckSchedule(enexid) → checa horário atual do servidor (usa gettime) e retorna se está aberto.
SendClosedMessage(playerid, enexid) → envia a mensagem de entrada fechada configurada.
SendScheduleMessage(playerid, enexid) → envia a mensagem com horário de funcionamento.
SetPlayerPosEnEx(playerid, x,y,z, angle, vwid=0, intid=0) → teleporta o jogador e ajusta câmera/virtual/interior.
GetXYInFrontOfEnEx(x,y,angle,&outX,&outY,distance) → utilitário para posicionar o jogador levemente à frente do EnEx.

Callbacks / Hooks disponíveis

OnPlayerAttemptEnEx(playerid, enexid) — (chamada local) é invocada antes do teleporte; se retornar 0, a ação é cancelada. (A biblioteca chama CallLocalFunction para isso.)
OnPlayerDeniedEnEx(playerid, enexid) — hook opcional chamado quando o jogador tenta acessar um EnEx fechado (útil para logs/efeitos).
OnPlayerEnterEnEx(playerid, enexid) — chamado quando o jogador entra (após validações).
OnPlayerExitEnEx(playerid, enexid) — chamado quando o jogador sai.

Comportamento de Schedule
A função de schedule aceita intervalos normais (ex: 09 → 18) e intervalos que atravessam meia-noite (ex: 22 → 06). A checagem usa a hora do servidor (gettime). Em caso de EnEx com schedule definido e fora do horário, o jogador recebe uma mensagem com o horário de funcionamento (formatada em HH:00).

Observações de implementação e notas técnicas

A implementação usa YSI Iterators para manter IDs livres/ocupados (Iter_Free / Iter_Add).
Pickups são criados com CreateDynamicPickup (Streamer). Labels 3D são criadas com CreateDynamic3DTextLabel. Ajuste TEXTLABEL_STREAMDISTANCE se necessário.
O freeze temporário ao teleporte usa um timer UnfreezePlayer[...] para restaurar o controle do jogador. Há um array de timers com tamanho 1000 por padrão na versão atual.
A tecla padrão para ativação é definida por DEFAULT_KEY (pode ser alterada antes de incluir a biblioteca).
A biblioteca valida enexid (0..MAX_ENEX-1) nas funções públicas onde aplicável.

Instalação

Copie o arquivo easyEnEx.inc para a pasta pawno/includes.
Tenha as dependências instaladas (YSI + Streamer).
Inclua no seu gamemode:

#include easyEnex
Compile e use Enex_Create(...) para adicionar EnEx no OnGameModeInit, por exemplo.

Exemplo rápido

Código:
// Cria uma casa: nome, posição da entrada, posição da saída, vw/int/freeze, pickup id, mensagem fechada

 new enex = Enex_Create("Casa do CJ",

 1950.0, -1790.0, 14.1, 0.0, // entrada

 260.0, -1000.0, 23.5, 90.0, // saída

 0, 0, false, // ex_vwid, ex_intid, freeze

 0, 0, // en_vwid, en_intid

 1318, "Entrada fechada! Volte depois.");

Temos um Gamemode de demonstração com exemplos práticos (duas entradas criadas — Casa do CJ e Armário). Veja o demo no repositório: Clique aqui para ver o demo

Changelog resumido (últimas adições)

Suporte a schedules (Enex_SetSchedule / Enex_CheckSchedule).
Controle por jogador (Enex_CloseForPlayer / Enex_OpenForPlayer).
Mensagem de horário ao tentar entrar fora do horário.
CallLocalFunction para OnPlayerAttemptEnEx (permite bloquear via retorno 0).
OnPlayerDeniedEnEx hook quando EnEx está fechado.
Melhor organização das constantes e parâmetros de Enex_Create (virtual/interior para ambos os lados).
Pequenas melhorias de UX: posicionamento levemente à frente do EnEx ao spawnear, criar textlabels com streamdistance configurável.

Créditos
Desenvolvido por: xBruno1000x — contribuições são bem-vindas! Se quiser, abra issue ou PR no repositório.

Suporte / Contato
Se quiser adicionar feature request (ex.: suporte a diferentes teclas por EnEx, ou integração com sistemas de permissão), diga o que tem em mente ou abra uma issue no GitHub do projeto.

https://github.com/xbruno1000x/easyEnex