텍스트 채팅 개요

Roblox는 TextChatService를 통해 실시간 세션에서 플레이어 간의 텍스트 기반 메시징을 제공합니다. 이 클래스는 전체 채팅 시스템을 관리하는 단일 인스턴스 클래스이며, 채팅 메시지 필터링, 관리 및 사용자 권한을 포함합니다. 이 서비스는 기본 기능을 제공하며, 사용자 정의 요구 사항에 따라 메시지를 전달하거나 특정 플레이어에게 특별한 권한이나 관리를 추가하고, 특정 작업을 실행하기 위한 사용자 정의 명령을 생성하는 등의 방법으로 채팅을 확장하고 사용자 정의할 수 있는 메서드와 이벤트 세트를 제공합니다.

UI 구성

TextChatService는 게임의 필요에 맞게 사용자 정의할 수 있는 기본 UI를 제공합니다. 이러한 구성 요소를 비활성화하면 관련 UI 요소가 숨겨집니다. 원할 경우 이러한 UI 요소를 사용자 정의 인터페이스로 교체할 수도 있습니다:

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

자세한 내용은 채팅 창 및 버블 채팅을 참조하세요.

채널, 메시지 및 명령

• TextChannel — 텍스트 채널은 클라이언트에서 서버로 사용자 전송 메시지를 전달하며, 서버는 권한에 따라 다른 사용자에게 이를 표시합니다. 텍스트 채널은 기능을 수행하기 위해 TextChatService에 부모로 설정되어야 합니다.

  TextChatService.CreateDefaultTextChannels가 true로 설정된 경우, 서비스는 자동으로 두 개의 텍스트 채널인 RBXGeneral 및 RBXSystem을 생성합니다. 추가 TextChannel 인스턴스를 수동으로 생성하고 이를 TextChatService에 부모로 설정할 수도 있습니다.

• TextSource — TextChannel의 사용자. AddUserAsync()가 호출될 때 텍스트 소스는 TextChannel에 직접 부모로 설정됩니다. 텍스트 소스는 채널 내에서 사용자의 메시지 전송 능력과 같은 세부 권한을 포함합니다. 단일 사용자가 여러 텍스트 채널에 있을 경우, 여러 텍스트 소스와 연결됩니다.

• TextChatMessage — 텍스트 채널의 메시지. 채팅 메시지는 메시지 발신자, 원본 메시지, 필터링된 메시지 및 생성 타임스탬프와 같은 기본 정보를 포함합니다.

• TextChatCommand — 사용자가 PrimaryAlias 또는 SecondaryAlias 속성과 일치하는 메시지를 전송하여 특정 작업이나 동작을 호출할 수 있게 합니다. 채팅 명령은 기능을 수행하기 위해 TextChatService에 부모로 설정되어야 합니다.

  TextChatService.CreateDefaultCommands가 true로 설정된 경우, 기본 채팅 명령이 자동으로 생성됩니다. 추가 TextChatCommand 인스턴스를 수동으로 생성하고 이를 TextChatService에 부모로 설정할 수도 있습니다.

채팅 흐름도

텍스트 채팅은 클라이언트-서버 모델을 사용하며, 발신 클라이언트, 서버, 수신 클라이언트로 구성됩니다.

1. 플레이어가 로컬 장치에서 메시지를 전송하면 TextChannel:SendAsync() 메서드가 트리거됩니다. 이 메서드는 메시지를 처리하고 그것이 채팅 명령인지 일반 채팅 메시지인지 결정합니다.

   • 메시지가 채팅 명령인 경우, 정의된 작업을 수행하기 위해 TextChatCommand.Triggered 이벤트가 발생합니다. 추가 단계는 필요하지 않습니다.

   • 메시지가 일반 채팅 메시지인 경우, 발신 클라이언트에서 발신자에게 메시지를 표시하기 위해 TextChatService.SendingMessage 이벤트가 발생합니다. 동시에 TextChannel:SendAsync()는 메시지를 서버로 전달합니다.

2. 서버는 TextChannel.ShouldDeliverCallback을 발생시켜 권한 및 Roblox 커뮤니티 필터링 요구 사항에 따라 메시지를 다른 플레이어에게 전달할지 여부를 결정합니다.

3. TextChannel.ShouldDeliverCallback이 메시지가 다른 플레이어에게 전달될 수 있다고 판단하면, 서버는 필터를 적용하고 TextChannel.OnIncomingMessage를 두 번 발생시킵니다:

   1. 첫 번째는 발신 클라이언트에서 발생하며, 서버가 TextChatService.MessageReceived 이벤트를 통해 메시지를 처리하고 있음을 신호합니다. 이 이벤트는 발신 클라이언트의 로컬 메시지를 서버에서 처리된 메시지로 교체합니다. 원본 메시지가 필터링을 필요로 하지 않았다면 메시지는 동일합니다.

   2. 두 번째는 수신 클라이언트에서 발생하며, TextChatService.MessageReceived 이벤트를 트리거하여 다른 플레이어에게 메시지를 표시합니다.

텍스트 채팅 후크 및 콜백

TextChatService API는 채팅 메시지의 외관과 전달을 명확하게 분리하도록 권장합니다. 텍스트 채팅 시스템의 여러 인스턴스는 중앙 집중식으로 명확한 위치에서 형식을 지정할 수 있는 후크와 콜백을 제공합니다.

조건부 메시지 전달

TextChannel.ShouldDeliverCallback 콜백은 서버에서만 정의되어야 합니다. 메시지가 전송될 때 텍스트 채널의 각 TextSource 자식에 대해 콜백이 발생하여 메시지를 전달할지 여부를 결정합니다. 이 콜백은 추가 게임 플레이 컨텍스트에 따라 달라질 수 있는 사용자 정의 메시지 전달 논리를 구현하는 데 사용할 수 있습니다. 예를 들어:

• 근접 기반 채팅에서는 사용자가 가까운 사람에게만 메시지를 보낼 수 있습니다.
• 특정 속성을 가진 사용자가 다른 사용자에게 메시지를 보내는 것을 방지합니다.

메시지 표시 사용자 정의

기본 TextChatService UI는 리치 텍스트를 사용하여 메시지가 표시되는 방식을 형식화하고 사용자 정의합니다. 다음 콜백을 사용하여 메시지가 사용자에게 표시되기 전에 형식을 지정할 수 있습니다. 예를 들어 사용자 이름에 색상이나 채팅 태그를 추가하거나 메시지 내용을 형식화할 수 있습니다.

다음 콜백은 표시될 TextChatMessage마다 호출되어 TextChannel, TextSource 또는 TextChatMessage 내용에 따라 채팅 창의 외관을 사용자 정의할 수 있습니다. 클라이언트가 메시지를 전송하면 이 콜백은 메시지가 서버로 전송될 때 한 번 호출되며, TextChatMessage.Status 값은 Enum.TextChatMessageStatus.Sending이 됩니다. 메시지가 서버에 수신되고 다른 사용자에게 전달되고 있을 때, 발신 클라이언트는 업데이트된 Enum.TextChatMessageStatus 값으로 메시지를 다시 받습니다.

• TextChatService.OnIncomingMessage — 이 콜백은 클라이언트에서만 정의되어야 합니다. 이 콜백은 메시지가 수신될 때 발생하며, 서버에서 수신되거나 로컬 클라이언트가 방금 메시지를 보낸 경우입니다. 이 콜백은 모든 TextChannel 인스턴스에서 수신된 모든 TextChatMessage에 대해 호출되며, 사용자에게 표시되기 전에 메시지를 처리하는 첫 번째 콜백입니다.
• TextChannel.OnIncomingMessage — 이 콜백은 클라이언트에서만 정의되어야 합니다. 이 콜백은 서버에서 메시지를 수신할 때 발생합니다. 이 콜백은 TextChannel에서 수신된 모든 TextChatMessage에 대해 호출됩니다. TextChatService.CreateDefaultTextChannels에서 생성된 기본 TextChannel 인스턴스는 이 콜백이 정의되어 있으며, 덮어쓸 수 있습니다.
• TextChatService.OnBubbleAdded — 이 콜백은 클라이언트에서만 정의되어야 합니다. 채팅 창 UI에서 메시지의 외관과는 독립적으로 채팅 버블의 외관을 사용자 정의하는 데 사용합니다.
• TextChatService.OnChatWindowAdded — 이 콜백은 클라이언트에서만 정의되어야 합니다. 채팅 버블의 외관과는 독립적으로 채팅 창 UI에서 채팅 메시지의 외관을 사용자 정의하는 데 사용합니다.

레거시 채팅에서 마이그레이션

이 섹션은 TextChatService를 사용하여 일반적인 채팅 기능 및 동작을 구현하기 위한 대체 방법을 제공하여 레거시 채팅 시스템에서 마이그레이션하는 데 도움을 줍니다.

1. 탐색기 창에서 TextChatService를 선택합니다.

2. 속성 창에서 ChatVersion 드롭다운을 찾아 TextChatService를 선택합니다.

   

기본 기능

두 시스템 모두 동일한 기본 채팅 기능을 공유하지만, 일반적으로 TextChatService 구현은 더 지속 가능하고 반복하기 쉽습니다.

메시지 필터링

TextChatService는 각 플레이어의 계정 정보를 기반으로 채팅 메시지를 자동으로 필터링하므로 모든 종류의 채팅 메시지에 대해 수동으로 텍스트 필터링을 구현할 필요가 없습니다.

창 및 버블 채팅

TextChatService의 채팅 창 및 버블 채팅 동작 및 사용자 정의 옵션은 레거시 채팅 시스템과 동일합니다. 레거시 채팅 시스템은 채팅 모듈이나 Players 컨테이너를 사용하여만 사용자 정의를 허용하므로, 이 서비스는 모든 채팅 창 및 버블 채팅 속성을 관리하기 위해 전용 클래스(ChatWindowConfiguration 및 BubbleChatConfiguration)를 제공합니다. 또한 모든 스크립트를 작성할 필요 없이 Studio 설정을 사용하여 버블 채팅의 외관 및 동작 속성을 쉽게 조정하고 미리 볼 수 있습니다.

발화자 "추가 데이터" 마이그레이션

레거시 Lua 채팅 시스템은 개발자가 Speaker 클래스에서 SetExtraData를 사용할 수 있도록 허용했습니다. 이 데이터는 이름 색상, 채팅 색상 형식화 또는 주어진 발화자에 대한 이름 태그를 적용하는 데 사용되었습니다.

-- 레거시 채팅 시스템에서 발화자에 추가 데이터를 설정하는 예
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는 SetExtraData에 대한 직접적인 동등물이 없습니다. 대신, 메시지의 TextSource를 기반으로 리치 텍스트를 사용하여 메시지의 외관을 사용자 정의하기 위해 콜백인 OnWindowAdded를 사용합니다.

다음은 Player 객체의 속성에 접근하여 레거시 Lua 채팅의 "추가 데이터"를 에뮬레이트하는 예입니다:

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)

그런 다음 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