+- Portal SAMP (https://portalsamp.com)
+-- Fórum: SA-MP (https://portalsamp.com/forumdisplay.php?fid=5)
+--- Fórum: Lançamentos (https://portalsamp.com/forumdisplay.php?fid=26)
+---- Fórum: Includes (https://portalsamp.com/forumdisplay.php?fid=27)
+---- Tópico: [Include] easyEnEx (/showthread.php?tid=5078)
easyEnEx - xbruno1000x - 17/08/2025
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);- 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.");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.