Panoramica della chat testuale

Roblox offre messaggistica basata su testo tra i giocatori nelle sessioni dal vivo tramite TextChatService, una classe singleton responsabile della gestione dell'intero sistema di chat, inclusi il filtraggio dei messaggi di chat, la moderazione e i permessi degli utenti. Questo servizio ha la sua funzionalità standard e fornisce anche un insieme di metodi ed eventi per estendere e personalizzare la chat, come la consegna di messaggi in base a requisiti personalizzati, l'aggiunta di permessi speciali o moderazione a giocatori specifici e la creazione di comandi personalizzati per eseguire azioni specifiche.

Configurazione dell'interfaccia utente

TextChatService fornisce un'interfaccia utente predefinita che può essere personalizzata per soddisfare le esigenze del tuo gioco. Disabilita una di queste configurazioni per nascondere il relativo elemento dell'interfaccia utente. Se desiderato, puoi anche sostituire questi elementi dell'interfaccia utente con interfacce personalizzate:

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Per ulteriori informazioni, consulta Finestra di chat e Chat a bolle.

Canali, messaggi e comandi

• TextChannel — I canali di testo inviano i messaggi inviati dagli utenti dal client al server, che poi li visualizza ad altri utenti in base ai permessi. I canali di testo devono essere parentati a TextChatService per funzionare.

  Se TextChatService.CreateDefaultTextChannels è impostato su true, il servizio crea automaticamente due canali di testo, RBXGeneral e RBXSystem. Puoi anche creare manualmente ulteriori istanze di TextChannel e parentarle a TextChatService.

• TextSource — Un utente in un TextChannel. Le fonti di testo sono direttamente parentate al TextChannel quando viene chiamato AddUserAsync(). Le fonti di testo contengono permessi dettagliati di un utente nel canale, come la loro capacità di inviare messaggi. Se un singolo utente è in più canali di testo, è associato a più fonti di testo.

• TextChatMessage — Un messaggio in un canale di testo. I messaggi di chat contengono informazioni di base come il mittente del messaggio, il messaggio originale, il messaggio filtrato e il timestamp di creazione.

• TextChatCommand — Consente agli utenti di invocare azioni o comportamenti specifici inviando messaggi che corrispondono alle proprietà PrimaryAlias o SecondaryAlias. I comandi di chat devono essere parentati a TextChatService per funzionare.

  Se TextChatService.CreateDefaultCommands è impostato su true, i comandi di chat predefiniti verranno creati automaticamente. Puoi anche creare manualmente ulteriori istanze di TextChatCommand e parentarle a TextChatService.

Diagramma di flusso della chat

La chat testuale utilizza il modello client-server, con un client di invio, il server e client di ricezione.

1. Un giocatore invia un messaggio dal proprio dispositivo locale, attivando il metodo TextChannel:SendAsync(). Questo metodo elabora il messaggio e determina se si tratta di un comando di chat o di un messaggio di chat normale.

   • Se il messaggio è un comando di chat, attiva l'evento TextChatCommand.Triggered per eseguire l'azione definita. Non sono necessari ulteriori passaggi.

   • Se il messaggio è un messaggio di chat normale, attiva l'evento TextChatService.SendingMessage per visualizzare il messaggio al mittente sul client di invio. Allo stesso tempo, TextChannel:SendAsync() passa il messaggio al server.

2. Il server attiva TextChannel.ShouldDeliverCallback per determinare se consegnare il messaggio ad altri giocatori in base ai permessi e ai requisiti di filtraggio della comunità di Roblox.

3. Se TextChannel.ShouldDeliverCallback determina che il messaggio è idoneo per la consegna ad altri giocatori, il server applica eventuali filtri e attiva TextChannel.OnIncomingMessage due volte:

   1. La prima volta è sul client di invio e segnala che il server sta elaborando il messaggio tramite l'evento TextChatService.MessageReceived. Questo evento sostituisce il messaggio locale sul client di invio con il messaggio elaborato dal server. Il messaggio è identico se l'originale non richiedeva filtraggio.

   2. La seconda volta è sui client di ricezione, il che attiva l'evento TextChatService.MessageReceived per visualizzare il messaggio ad altri giocatori.

Hook e callback della chat testuale

L'API TextChatService incoraggia una chiara separazione tra l'aspetto e la consegna dei messaggi di chat. Più istanze del sistema di chat testuale forniscono hook e callback per formattare in posizioni centralizzate e chiare.

Consegnare messaggi in modo condizionale

Il callback TextChannel.ShouldDeliverCallback dovrebbe essere definito solo sul server. Il callback viene attivato per ogni figlio TextSource del canale di testo quando viene inviato un messaggio per determinare se il messaggio dovrebbe essere consegnato. Questo callback può essere utilizzato per implementare una logica di consegna dei messaggi personalizzata che può dipendere da ulteriori contesti di gioco, come:

• Chat basata sulla prossimità in cui gli utenti possono inviare messaggi solo a coloro che sono vicini a loro.
• Impedire agli utenti con determinati attributi di inviare messaggi ad altri.

Personalizzare la visualizzazione dei messaggi

L'interfaccia utente predefinita di TextChatService si basa su testo ricco per formattare e personalizzare come i messaggi vengono visualizzati. Puoi utilizzare i seguenti callback per formattare i messaggi prima che vengano visualizzati agli utenti, ad esempio per aggiungere colori o tag di chat ai nomi degli utenti o formattare il contenuto del messaggio.

I seguenti callback vengono chiamati su ogni TextChatMessage che sta per essere visualizzato, il che ti consente di personalizzare l'aspetto della finestra di chat in base al TextChannel, TextSource o al contenuto di TextChatMessage. Quando un client invia un messaggio, questi callback vengono chiamati una volta quando il messaggio viene inviato al server e il valore di TextChatMessage.Status sarà Enum.TextChatMessageStatus.Sending. Una volta che il messaggio è ricevuto dal server e viene consegnato ad altri utenti, il client mittente riceve nuovamente il messaggio con un valore aggiornato di Enum.TextChatMessageStatus.

• TextChatService.OnIncomingMessage — Questo callback dovrebbe essere definito solo sul client. Il callback viene attivato quando un messaggio viene ricevuto, sia dal server sia se il client locale ha appena inviato un messaggio. Il callback viene chiamato su ogni TextChatMessage ricevuto da tutte le istanze di TextChannel ed è il primo a elaborare il messaggio prima che venga visualizzato all'utente.
• TextChannel.OnIncomingMessage — Questo callback dovrebbe essere definito solo sul client. Il callback viene attivato quando un messaggio viene ricevuto dal server. Il callback viene chiamato su ogni TextChatMessage ricevuto dal TextChannel. Le istanze predefinite di TextChannel create da TextChatService.CreateDefaultTextChannels hanno questo callback definito e possono essere sovrascritte.
• TextChatService.OnBubbleAdded — Questo callback dovrebbe essere definito solo sul client. Usalo per personalizzare l'aspetto delle bolle di chat indipendentemente dall'aspetto del messaggio nell'interfaccia utente della finestra di chat.
• TextChatService.OnChatWindowAdded — Questo callback dovrebbe essere definito solo sul client. Usalo per personalizzare l'aspetto dei messaggi di chat nell'interfaccia utente della finestra di chat indipendentemente dall'aspetto del messaggio nelle bolle di chat.

Migrare dalla chat legacy

Questa sezione ti assiste nella migrazione dal sistema di chat legacy fornendo metodi alternativi per implementare funzionalità e comportamenti comuni della chat utilizzando TextChatService.

1. Nella finestra Explorer, seleziona TextChatService.

2. Nella finestra Properties, trova il menu a discesa ChatVersion e seleziona TextChatService.

   

Funzionalità di base

Sebbene entrambi i sistemi condividano le stesse funzionalità di chat di base, le implementazioni di TextChatService sono in generale più sostenibili e più facili da iterare.

Filtraggio dei messaggi

TextChatService filtra automaticamente i messaggi di chat in base alle informazioni dell'account di ciascun giocatore, quindi non è necessario implementare manualmente il filtraggio del testo per tutti i tipi di messaggi di chat.

Finestra e chat a bolle

Sia il comportamento e le opzioni di personalizzazione della finestra di chat che della chat a bolle di TextChatService sono identici a quelli del sistema di chat legacy. Poiché il sistema di chat legacy consente solo la personalizzazione utilizzando moduli di chat o il contenitore Players, il servizio fornisce classi dedicate (ChatWindowConfiguration e BubbleChatConfiguration) per gestire tutte le proprietà della finestra di chat e della chat a bolle. Inoltre, puoi facilmente regolare e visualizzare le proprietà di aspetto e comportamento della tua chat a bolle utilizzando le impostazioni di Studio anziché doverle tutte programmare.

Migrare "dati extra" dello speaker

Il sistema di chat Lua legacy consentiva agli sviluppatori di utilizzare SetExtraData sulla classe Speaker. Questi dati venivano utilizzati per formattare il colore del nome, il colore della chat o per applicare tag ai nomi di un determinato speaker.

-- Un esempio di impostazione di dati extra su uno speaker nel sistema di chat legacy
ChatService.SpeakerAdded:Connect(function(playerName)
	local speaker = ChatService:GetSpeaker(playerName)
	speaker:SetExtraData("NameColor", Color3.fromRGB(255, 255, 55))
	speaker:SetExtraData("ChatColor", Color3.fromRGB(212, 175, 55))
	speaker:SetExtraData("Tags", {{TagText = "YourTagName", TagColor = Color3.fromRGB(0, 255, 0)}, {TagText = "OtherTagName", TagColor = Color3.fromRGB(255, 0, 0)}})
end)

TextChatService non ha un equivalente diretto di SetExtraData. Invece, utilizza callback come OnWindowAdded per personalizzare l'aspetto dei messaggi utilizzando testo ricco in base al TextSource del messaggio.

Di seguito è riportato un esempio di emulazione dei "dati extra" della chat Lua legacy accedendo agli attributi sugli oggetti Player:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	player:SetAttribute("NameColor", Color3.fromRGB(255, 255, 55))
	player:SetAttribute("ChatColor", Color3.fromRGB(212, 175, 55))
	player:SetAttribute("isYourTag", true)
	player:SetAttribute("isOtherTag", true)
end)

Quindi puoi utilizzare il callback OnChatWindowAdded per personalizzare l'aspetto della finestra di chat in base agli attributi impostati sul giocatore:

local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

TextChatService.OnChatWindowAdded = function(textChatMessage)
	local textSource = textChatMessage.TextSource
	if textSource then
		local player = Players:GetPlayerByUserId(textSource.UserId)
		if player then
			local overrideProperties = TextChatService.ChatWindowConfiguration:DeriveNewMessageProperties()
			overrideProperties.PrefixText = textChatMessage.PrefixText
			overrideProperties.Text = textChatMessage.Text

			local nameColor = player:GetAttribute("NameColor")
			if nameColor and typeof(nameColor) == "Color3" then
				overrideProperties.PrefixTextProperties.TextColor3 = nameColor
			end

			local chatColor = player:GetAttribute("ChatColor")
			if chatColor and typeof(chatColor) == "Color3" then
				overrideProperties.TextColor3 = chatColor
			end

			local isYourTag = player:GetAttribute("isYourTag")
			if isYourTag == true then
				overrideProperties.PrefixText = `<font color='rgb(0, 255, 0)'>[YourTag]</font> {overrideProperties.PrefixText}`
			end

			local isOtherTag = player:GetAttribute("isOtherTag")
			if isOtherTag == true then
				overrideProperties.PrefixText = `<font color='rgb(255, 0, 0)'>[OtherTag]</font> {overrideProperties.PrefixText}`
			end

			return overrideProperties
		end
	end

	return nil
end