SuperChat DOC

SUPERCHAT 2.0.0 - DOCUMENTATION Unreal Engine 5.7 and 5.8 | Windows (Win64) CelestiaDominance

PURPOSE SuperChat provides replicated text chat for Unreal multiplayer projects. Use the native chat panel or connect the component to your own UMG interface. Messages are routed by the server using channel rules, the sender's current pawn position, team membership, and optional Blueprint authorization hooks.

The plugin contains C++ source, with no Blueprint assets or example maps. It requires no additional plugins. You create the gameplay Blueprints, input bindings, channel assets, and optional custom widgets appropriate for your project.

1. CONNECT CHAT TO YOUR PLAYER Add one SuperChat Component to your PlayerController Blueprint. A controller component is recommended when chat history should survive pawn replacement or death. Alternatively, place it on the player's replicated Pawn or Character; that pawn must be the controller's current possessed pawn.

Use exactly one registered SuperChat component across the controller and its current pawn. Do not add it to both. Find Chat Component accepts a PlayerController and returns the single valid component, or None for a missing or ambiguous setup. Get Chat Player Controller resolves the controller belonging to a component.

The component enables replication by default. Keep the owning actor replicated and owned by the relevant player. Calls from a client must use that client's own component. Server code can also send through a player's authoritative component. Arbitrary world actors and unpossessed pawns are not supported chat owners.

Connect your chosen input action to Open Chat UI or Toggle Chat UI on the local player's component. No gameplay input action or key binding is imposed by the plugin. With Auto Create UI enabled, the native panel is created locally in its closed state. Opening it reveals and focuses its text input. Press Enter or click Send to submit text. Call Close Chat UI from your own close/cancel action.

For manual creation, disable Auto Create UI and call Create Chat UI when the local controller is ready. Create Chat UI creates the closed panel; Open Chat UI creates it if necessary and opens it. Dedicated servers never create the UI.

2. SEND MESSAGES AND SELECT CHANNELS Send Message takes text plus the Global, Near, Local, or Team enum value. Send Message To Channel Name takes text and a channel name. Send Message To Current Channel uses the current selection. Get Available Channel Names supplies options for your own selector. Set Current Channel Name changes the selection; Get Current Channel Name reads it.

Without a channel data asset, the native choices are: - Global: unlimited distance. - Near: 1,000 Unreal units (10 metres with the usual centimetre scale). - Local: 5,000 Unreal units (50 metres). - Team: unlimited distance, but matching nonnegative team IDs are required.

Near and Local use the server's current pawn positions. A finite-range sender without a valid pawn is rejected; recipients without a valid pawn cannot receive finite-range messages. Client-supplied positions and ranges do not control delivery.

The Custom enum alone does not identify a custom channel. Use Send Message To Channel Name with a defined name. System is reserved for Send System Message on the server. Invalid enum values and unknown channel names are rejected instead of being sent globally.

3. CUSTOM CHANNEL ASSETS Create a Data Asset using SuperChatChannelDataAsset as its class, then assign it to Channel Data on the component. Each Channels entry has: - Channel Name: a unique nonempty name, such as Squad or Trade. - Max Distance: a positive distance for spatial filtering; zero or a negative value for unlimited distance. - Require Matching Team: require equal, nonnegative IDs in each player's Channel Team Ids map under that channel name.

You can use built-in names in the asset to override their distance. Team always requires matching team IDs, even if Require Matching Team is unchecked. Duplicate names, None, System, and nonfinite distance values are invalid. Invalid entries are excluded from the selector. If every entry in a nonempty asset is invalid, no valid current channel is available.

A nonempty asset supplies the visible channel choices. This selector is not an authorization list: built-in channels remain callable by name or enum. To restrict who may send a channel, implement BP Can Send Message on a SuperChat Component Blueprint subclass.

Keep channel definitions and relevant defaults consistent on server and clients, preferably through shared class defaults and a referenced asset. Configuration properties are not automatically replicated. If your game changes them at runtime, synchronize the settings through your own project logic. The server's configuration decides actual delivery.

4. TEAM AND FACTION INTEGRATION On the server, set Channel Team Ids on every participating player's component. For built-in Team, use the key Team. For example, assign Team = 7 to two players and Team = 9 to another. The first two can exchange Team messages; the third is excluded. A missing key or negative ID means no valid team membership.

For a custom Squad channel, enable Require Matching Team and assign Squad = 3 to its members. Add a positive Max Distance when squad chat should also be proximity limited.

For additional permissions, create a Blueprint subclass of SuperChatComponent and override: - BP Can Send Message: runs on the sender's server component. Return false to reject the send with Permission Denied. Use this for roles, faction membership, chat bans, or project-specific channel access. - BP Should Receive Message: runs on the recipient's server component for delivery to Target PC. Return false to exclude that recipient. It adds a restriction after native distance and team checks; it cannot relax those checks. The sender still receives an acceptance copy of an accepted message for local reconciliation.

Grant team IDs, admin permission, and display-name overrides on the server. Client-side changes do not grant authority. Use Sender Player Id, Sender Unique Id, Sender Team Id, Channel Name, and Origin Location from the message when integrating with your own systems.

5. USE YOUR OWN UI Option A - a widget derived from SuperChatWidget: 1) Create a Widget Blueprint whose parent class is SuperChatWidget and design its layout. 2) Set Use Default Native UI to false. Disable Auto Viewport Layout if your own widget controls positioning and size. 3) Assign that Blueprint to Chat Widget Class on the component. 4) Implement BP On History Changed. Replace or reconcile your displayed rows with the supplied Messages array. Each row can use Sender Name, Content, Channel Name, Timestamp, and Pending. 5) Wire your Send button or text commit event to Get Chat Component, then Send Message To Current Channel or Send Message To Channel Name. 6) Use BP On Message Rejected to show rejection feedback and BP On Chat Input Visibility Changed to show or hide your input controls.

Set Chat Component explicitly binds a manually created SuperChatWidget to its component. Set its Owning Player correctly when creating it. The component's built-in creation path supplies both ownership and binding automatically.

Option B - any existing project widget: Disable Auto Create UI. Keep a reference to the correct local component using Find Chat Component. Bind On Message History Changed, then call Get Message History and rebuild or reconcile your rows. Populate an initial snapshot immediately after binding. Bind On Message Rejected for feedback, and call the public send/channel nodes from your existing controls. Unbind your own event bindings when the widget is destroyed or rebound.

Choose one history-rendering path. Do not append the entire history on every change without first replacing or reconciling existing rows. BP On Message Added and the component's On Message Received are for confirmed, unmuted messages; they are useful for notifications or sounds. They do not represent every preview, removal, or clear operation.

Add Chat Message, Set Message History, and Clear Message List affect a SuperChatWidget's display. Use component send functions for networking and Clear Message History to clear the component's local history.

6. PENDING MESSAGES, HISTORY, AND REJECTIONS Local Echo On Send displays a pending preview before server acceptance. The preview has Pending = true and a Request Id. The server's accepted version replaces it, including censored or shortened content. Rejections remove the pending preview and raise On Message Rejected with Request Id and Reason. Pending previews are not proof that another player received a message.

On Message History Changed fires for additions, preview reconciliation, trimming, and clearing. Get Message History returns the current local snapshot. Max Message History defaults to 100; zero disables that cap. History is transient and belongs to the component. There is no persistence, automatic late-join backlog, or offline message queue. A missing recipient component does not accumulate messages for later delivery.

Clear Message History clears only this component's local history. Incoming messages continue to update history while the panel is hidden or removed, without reopening or reattaching it. Explicit Open Chat UI can reattach the existing panel.

Rejection reasons and checks: - Invalid Owner: check possession, client ownership, registration, and duplicate components. - Invalid Channel: check the name, enum, duplicate asset entries, and reserved System name. - Invalid Content: text is empty after cleanup, or an enabled command is empty. - Message Too Long: the request exceeds 4,096 UTF-16 code units. - Rate Limited: wait before sending again or adjust server rate settings. - Moderated: a Reject-policy word match was found. - Missing Team: assign a nonnegative server team ID for the channel. - Missing Pawn: a distance-limited sender has no valid current pawn position. - Permission Denied: server authorization refused the message or the sender lacks admin permission. - Pending Limit: 64 requests are already awaiting completion.

7. MODERATION AND ADMIN COMMANDS Max Message Length defaults to 200 UTF-16 code units. Longer accepted text is shortened without splitting a UTF-16 surrogate pair. Zero uses the 4,096-unit ceiling. Requests beyond the ceiling are rejected. Control characters are replaced with spaces and surrounding whitespace is trimmed.

Configure Bad Words on the server. Matching is case-insensitive substring matching, not whole-word or language-aware moderation. Censor replaces matching characters with asterisks; Reject refuses the message. An empty word entry is ignored.

Rate limiting defaults to a 0.25-second minimum interval and six accepted rate-limit attempts per four-second window. Attempts that pass the limiter can still be rejected by later validation. The limiter uses real time and applies before admin commands. Configure Enable Rate Limit, Min Seconds Between Messages, Spam Window Seconds, and Spam Max Messages In Window for your game.

Mute Sender By Unique Id and Mute Sender By Name filter future incoming messages locally. Corresponding unmute nodes and Clear Mute List are available. Existing history is not retroactively removed. Names can be shared by players; use unique IDs when your online identity setup supplies them. Without an online ID, the component uses a session player-ID fallback. These mute settings are not a server ban system.

Enable Admin Commands reserves text beginning with /. Set Is Chat Admin on the authoritative server component to grant access. /clear and /clearchat clear current chat histories for connected players with valid components. Other nonempty commands raise On Admin Command on the server with a lowercase command name, arguments, and Requesting PC; your project implements their behavior. Unknown commands do nothing unless handled by your binding.

Send System Message is a server-only broadcast helper. It uses the System channel, applies basic text bounds, and consults recipient filtering. It does not apply player bad-word or rate-limit settings. Validate external text in your own server logic before using it.

8. NATIVE PANEL AND INPUT SETTINGS Theme Preset offers Classic, Dark, Neon, High Contrast, and Custom. Apply Theme Preset changes the palette at runtime; Reapply Theme Preset reapplies the selected preset. To keep manual colors, choose Custom or disable Auto Apply Theme Preset On Begin Play. Theme properties cover channel colors, local/other message colors, font, accent, header, message panel, input, and button colors.

Auto Close After Send closes the input after submission. Hide Widget When Closed hides the entire panel. Closing hides the header and input controls; Closed Shows Messages Only also removes the themed message-panel background and padding. Closed Message Fade In Seconds, Display Seconds, and Fade Out Seconds control closed-message fading. Close Chat UI With Delay temporarily retains the closed panel before hiding it when Hide Widget When Closed is enabled.

Manage Input Mode defaults to true. Opening the native panel uses Game and UI input and shows the cursor. Closing returns to Game Only and restores the previous cursor visibility. It does not restore an arbitrary previous menu input mode. Set Manage Input Mode to false when your own menu system owns focus, cursor state, and input mode, and handle those transitions yourself. For custom Designer widgets, focus your own editable field in your widget logic.

Auto Viewport Layout uses Default Viewport Size (420 x 260 by default), Anchor, Alignment, Offset (20, -20 by default), and optional safe-zone padding. Layout adapts to available player-screen space and DPI without changing the configured default size. Turn it off for a project-managed layout. Debug placement options are intended for diagnosing visibility.

9. UPDATING FROM VERSION 1 Existing public send and UI helper names are retained. Recompile your component/widget Blueprints and rebuild clients and server together; mixing version 1 and version 2 network builds is unsupported.

Populate server Channel Team Ids for built-in Team chat. Team no longer relies on a permissive Blueprint filter to establish membership. Use BP Can Send Message for access rules and BP Should Receive Message for additional recipient restrictions.

Move custom UI history rendering to On Message History Changed or BP On History Changed. A confirmed-message-only append handler cannot handle pending-preview replacement or server clears by itself. Check the new rejection event to surface failed sends.

Keep one component per player, configure the owning player explicitly for custom widgets, and use Manage Input Mode = false where an existing project UI already owns input.

10. VALIDATION AND SCOPE Version 2.0.0 was built with normal and strict include settings for Win64 Editor Development, Game Development, and Game Shipping on UE 5.7 and 5.8. Validation covered component/channel automation, custom Blueprint compilation, dedicated-server pawn ownership with three clients, cooked listen-server controller ownership with two remote clients, moderation/reconciliation, and cooked native/custom UI lifecycle checks. Cooked runtime tests used Development builds; Shipping was compile-validated.

SuperChat supplies text chat inside your Unreal multiplayer session. It does not include a hosting backend, accounts, voice chat, or cross-session storage. Your project provides the multiplayer session and any persistence or external service integrations.

Support: https://discord.gg/9Zc4wbwqG9