Panoramica della chat testuale

Roblox offre la messaggistica basata su testo tra i giocatori in 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 le autorizzazioni 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 autorizzazioni 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 qualsiasi 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 della chat e Chat a bolle.

Canali, messaggi e comandi

• TextChannel — I canali di testo inviano i messaggi inviati dagli utenti dal client al server, il quale li visualizza ad altri utenti in base alle autorizzazioni. I canali di testo devono essere associati 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 istanze aggiuntive di TextChannel e associarle a TextChatService.

• TextSource — Un utente in un TextChannel. Le fonti di testo sono direttamente associate al TextChannel quando viene chiamato AddUserAsync(). Le fonti di testo contengono autorizzazioni dettagliate di un utente nel canale, come la loro capacità di inviare messaggi. Se un singolo utente è presente 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 della chat devono essere associati a TextChatService per funzionare.

  Se TextChatService.CreateDefaultCommands è impostato su true, i comandi di chat predefiniti verranno creati automaticamente. Puoi anche creare manualmente istanze aggiuntive di TextChatCommand e associarle 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 richiesti 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() invia il messaggio al server.

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

3. Se TextChannel.ShouldDeliverCallback determina che il messaggio può essere consegnato ad altri giocatori, il server applica eventuali filtri e attiva TextChannel.OnIncomingMessage due volte:

   1. La prima volta avviene sul client di invio e segnala che il server sta elaborando il messaggio attraverso 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 avviene sui client di ricezione, che attivano 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.

Condizionare la consegna dei messaggi

Il callback TextChannel.ShouldDeliverCallback dovrebbe essere definito solo sul server. Il callback viene attivato per ogni child TextSource del canale di testo quando un messaggio viene inviato 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.
• Prevenire l'invio di messaggi da parte di utenti con determinati attributi ad altri.

Personalizzare la visualizzazione dei messaggi

L'interfaccia utente predefinita di TextChatService si basa su rich text per formattare e personalizzare come vengono visualizzati i messaggi. 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 dei messaggi.

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 a 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 viene 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.

Migra dalla chat legacy

Questa sezione ti assiste nella migrazione dal sistema di chat legacy fornendo metodi alternativi per implementare funzionalità e comportamenti di chat comuni 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 sulla base delle 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

Comportamenti e opzioni di personalizzazione sia 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, è possibile regolare e visualizzare facilmente le proprietà di aspetto e comportamento della chat a bolle utilizzando le impostazioni di Studio invece di doverle tutte programmare.

Migra i "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 di nome per un dato speaker.

Legacy Chat System SetExtraData
-- 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 il testo ricco basato su TextSource del messaggio.

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

TextChatService SetAttributes
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:

TextChatService OnChatWindowAdded
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