Kayfy

Música no jogo, tocada pelo app do celular ou pela mesa de DJ. O som sai em 3D de uma caixa de som, do bluetooth do carro ou da mesa. No fone, só o dono ouve.

Precisa de: ox_lib, krs_helper e a API de música kayfy-api

Opcionais: phone, para o app; target, ox_target ou qb-target, para as opções na caixa; skinshop, para o acessório do fone.

Relação com o celular

O Kayfy não depende do phone, mas sem ele a única tela de música é a da mesa de DJ. Com os dois ligados, o app Kayfy aparece no celular e no tablet, já instalado no personagem novo. Se o kayfy parar, o app some.

Instalação

A API é um programa Node à parte, entregue em uma pasta própria. Ela não é um resource. Precisa de Node 20 ou mais novo e de MySQL ou MariaDB, e cria as próprias tabelas.

1. No config.json da API, preencha Server.PublicUrl com o endereço que os jogadores usam para chegar nela e Security.PlayerSecret com um segredo longo. Libere a porta no firewall.
2. Ligue a API com start.bat e deixe sempre ligada.
3. Configure o server.cfg:

setr ox:locale "pt-br"
setr kayfy_api_url "http://IP_PUBLICO_DA_MAQUINA:3000"
set kayfy_player_secret "MESMO_SEGREDO_DA_API"

ensure oxmysql
ensure ox_lib
ensure krs_helper
ensure kayfy

Coloque o framework antes do krs_helper. Veja a ordem de instalação.

4. Crie os itens no inventário: earbuds ou headphones para o fone; speaker_party, speaker_flip, speaker_bluetooth e speaker_go para a caixa.
5. Dê o grupo Kayfy aos jogadores, ou libere para todos. Veja Permissão.

Convar	Tipo	Para quê
kayfy_api_url	setr	Base da API, igual ao Server.PublicUrl, sem barra no fim. Vale sobre apiUrl
kayfy_player_secret	set, nunca setr	Igual ao Security.PlayerSecret
ox:locale	setr	Idioma: pt-br, en, es, fr, zh-cn, hi, ar ou bn

Como usar

Modo	Como funciona	Exige
Caixa de som	Ao tocar fora do carro, a caixa aparece na mão	Item de caixa e grupo Kayfy
Bluetooth	Dentro do carro, o som sai do veículo. Cada veículo tem um único dono	Grupo Kayfy
Fone	Escolha o fone no app. Só o dono ouve	Item de fone e grupo Kayfy
Mesa de DJ	Chegue perto da mesa e aperte a tecla mostrada na tela. Cada mesa tem um único dono	Grupo da mesa

Comando	Tecla	O que faz
/kayfy_radio	G	Larga ou pega a caixa
kayfy_dj	E	Usa a mesa de DJ por perto

O app abre pelo celular, com /celular ou F1. Com o target, a caixa ganha as opções de pegar e desligar. As opções no chão só existem no target do krs. Nos outros, G e o comando fazem o mesmo.

O dono perde a caixa ao se afastar mais de stealDistance. O bluetooth para ao se afastar mais de maxDistance do veículo.

Permissão

Por padrão, caixa, carro e fone exigem o grupo Kayfy, e a mesa de exemplo exige Premium. Para liberar para todos, troque a lista por {}: radio = {}.

Framework	Como dar o grupo Kayfy
krs, Creative	Grupo Kayfy, pelo comando de grupo do admin
QBCore	Em Config.Groups do krs_helper: Kayfy = { "kayfy" }, e dê esse job, gang ou ACE
vRP	Em Config.Groups do krs_helper: Kayfy = { "kayfy" }, e dê o grupo kayfy
Sem framework	add_ace group.vip group.Kayfy allow e add_principal identifier.license:SUA_LICENSE group.vip

O mesmo vale para Premium e para Admin, que abre o painel de destaques da API.

A permissão é conferida de novo em next, resume e setVolume. Se ela caiu, o som para nessa ação.

Configuração

Tudo fica em config.lua, aberto. O que faltar usa o padrão do script e o console avisa em uma linha. Na tabela está o valor que vem no config.lua. Quando o padrão do script é outro, ele aparece em "O que muda". Os textos ficam em locales/*.json.

Geral

Opção	Padrão	O que muda
apiUrl	"http://127.0.0.1:3000"	Base da API, para teste local. Em produção, use a convar
prop	"krs_speaker_black"	Modelo da caixa. Também há _blue, _red, _green, _white e _pink. Sem a opção: "prop_boombox_01"
features	os 4 true	Liga e desliga radio, bluetooth, headphones e dj
permission	{ "Kayfy" } nos 3 modos	Grupos de radio, bluetooth e headphones
adminPermission	{ "Admin" }	Quem recebe o passe de admin da API
headphoneItems	{ "earbuds","headphones" }	Itens que valem como fone. {} não exige item
speakerItems	4 itens	{ item = "modelo" }: a caixa exibida é a do item. {} não exige item, e é o valor sem a opção
maxDistance	150	Distância do dono ao veículo que encerra o bluetooth
stealDistance	60	Distância do dono à caixa que apaga a caixa
blacklist	{ "spawn_do_veiculo" }	Modelos sem bluetooth. Sem a opção: {}
allowBluetoothOnBikes	false	Bluetooth em moto e bicicleta

Som

Opção	Padrão	O que muda
range.vehicle	["*"] = { 48,100 } e 7 modelos de exemplo	{ alcance, volume% } por modelo. Acima de 100, aumenta o som
range.radio	{ 20,100 }	Alcance e volume da caixa
client.baseVolume	0.5	Multiplicador global, de 0 a 1
client.refreshRate	4	Atualizações de posição por segundo
client.realism	true	Abafa o som de veículo fechado
client.realismIgnore	{ "pbus2" }	Modelos que não abafam. Sem a opção: {}
client.blockedInteriors	{}	Pontos { x, y, z } em interiores sem som
client.stopOnDeath	true	Para o som ao morrer

Mesa de DJ

Opção	Padrão	O que muda
dj	1 mesa de exemplo	Mesas. Sem a opção: nenhuma
djUseDistance	3.0	Distância para abrir a tela
djPlayDistance	10.0	Distância para continuar tocando. Mais longe, a tela fecha
client.djKey	"e"	Tecla padrão

dj = {
	{ table = { 120.81,-1280.32,29.49 }, speaker = { 112.71,-1287.38,28.46 }, range = 50, volume = 100, permission = { "Premium" } }
}

Caixa e fone

Opção	Padrão	O que muda
client.radioCommand	"kayfy_radio"	Comando da caixa, sem /. Letras, números, _ e -. "" desliga
client.dropRadioKey	"g"	Tecla padrão. "" deixa sem tecla, e o jogador escolhe
client.hand	osso 18905, move_m@bag	Posição da caixa na mão e estilo de andar
client.handByModel	4 modelos	Posição na mão por modelo. Sem a opção: vazio
client.headphoneProp	"Beat Off"	Trecho do nome do acessório no skinshop. "" desliga
client.headphoneModel	"kroma_headphones"	Fone 3D na cabeça, visto só por quem usa. "" usa headphoneProp, e é o valor sem a opção
client.headphoneAttach	osso 31086	Posição do fone 3D

Tela e integrações

Opção	Padrão	O que muda
client.minimumHealth	101	Vida mínima para abrir a tela
client.targetResource	"target"	"target", "ox_target" ou "qb-target". Para outro, copie um bloco em hooks.lua
client.skinshopResource	"skinshop"	Resource de skinshop
client.brandName	"Kayfy"	Nome na tela
client.brandColor, client.brandColorStrong	"#1ed760", "#1db954"	Cores da tela
client.notifyColor	"vermelho"	Cor do aviso: "verde", "amarelo" ou "vermelho"
client.notifyTime	7000	Duração do aviso, em ms

Para programadores

Exports do cliente:

exports.kayfy:GetState()              -- último estado, ou false
exports.kayfy:Command({ name = "togglePlay" })
exports.kayfy:Api("search", { "título" })   -- { data } ou { error }
exports.kayfy:Allowed()               -- true se o jogador pode usar algum modo

Comandos: playQueue, togglePlay, next, previous, jumpTo, setShuffle, setRepeat, addToQueue, playNext, removeFromQueue, moveInQueue, clearQueue, setVolume, setLocalVolume, setMuted, setStreamerMode, setRespectStreamer, setSyncPhoneVolume, toggleMode e stop.

Métodos de Api: search, searchPlaylists, searchArtists, songs, playable, related, trending, artistTracks, featured, featuredPlaylist, externalPlaylist, likes, like, unlike, playlists, createPlaylist, updatePlaylist, deletePlaylist, addToPlaylist, removeFromPlaylist, history e addHistory.

Exports do servidor, em adapter.lua, aberto:

exports.kayfy:hasPermission(source, grupo)
exports.kayfy:hasItem(source, itens)

Troque esses dois para usar outra regra de grupo ou item.

Eventos de cliente: kayfy:state sai com estado, tempoMs. kayfy:phoneVolume entra com um número de 0 a 1.

Ganchos em hooks.lua, aberto: KayfyWindowsOpen(vehicle) devolve true para veículo aberto, false para fechado e nil para a regra padrão. KayfyTargetModel e KayfyTargetGround registram as opções no target.

Problemas comuns

Mensagem	Causa
Você não tem permissão para usar o rádio	Falta o grupo de permission.radio. Há mensagens iguais para bluetooth, fone e mesa
Você não tem uma caixa de som	O jogador não tem nenhum item de speakerItems
Você não tem um fone de ouvido	O jogador não tem nenhum item de headphoneItems
Esta função está desligada neste servidor	O modo está false em features
Este veículo já está tocando uma música	O veículo tem outro dono
Este veículo não possui Bluetooth	O modelo está em blacklist
O bluetooth não pode ser emparelhado em motos ou bicicletas	allowBluetoothOnBikes está false
Esta mesa de som já está em uso	A mesa tem outro dono
Você está longe da mesa de som	O jogador passou de djPlayDistance
Não foi possível criar a caixa de som.	A caixa não apareceu em 3 segundos. Confira o modelo em prop ou speakerItems
Muitas ações seguidas. Aguarde um instante.	Mais de 10 pedidos pendentes do mesmo jogador
apiUrl vazio: qualquer link de áudio será aceito.	Sem kayfy_api_url e sem apiUrl. Defina a convar
convar kayfy_player_secret vazia	Defina o segredo igual ao da API
client.radioCommand inválido	O nome tem caractere proibido ou é kayfy_dj. O script volta ao padrão