From 64f7108499b4799540ef03ee3b72729febc090b3 Mon Sep 17 00:00:00 2001 From: Anton Tarasenko Date: Sat, 8 Aug 2020 20:11:32 +0700 Subject: [PATCH] Document broadcasting events and related classes --- sources/Events/Broadcast/BroadcastEvents.uc | 28 ++- .../Broadcast/BroadcastEventsObserver.uc | 2 +- .../Events/Broadcast/BroadcastListenerBase.uc | 167 ++++++++++++------ 3 files changed, 122 insertions(+), 75 deletions(-) diff --git a/sources/Events/Broadcast/BroadcastEvents.uc b/sources/Events/Broadcast/BroadcastEvents.uc index 61cacfc..fbbe102 100644 --- a/sources/Events/Broadcast/BroadcastEvents.uc +++ b/sources/Events/Broadcast/BroadcastEvents.uc @@ -1,8 +1,8 @@ /** * Event generator for events, related to broadcasting messages * through standard Unreal Script means: - * 1. text messages, typed by a player; - * 2. localized messages, identified by a LocalMessage class and id. + * 1. text messages, typed by a player; + * 2. localized messages, identified by a LocalMessage class and id. * Allows to make decisions whether or not to propagate certain messages. * Copyright 2020 Anton Tarasenko *------------------------------------------------------------------------------ @@ -56,12 +56,10 @@ static function bool CallCanBroadcast(Actor broadcaster, int recentSentTextSize) return true; } -static function bool CallHandleText -( +static function bool CallHandleText( Actor sender, out string message, - name messageType -) + name messageType) { local int i; local bool result; @@ -76,13 +74,11 @@ static function bool CallHandleText return true; } -static function bool CallHandleTextFor -( +static function bool CallHandleTextFor( PlayerController receiver, Actor sender, out string message, - name messageType -) + name messageType) { local int i; local bool result; @@ -97,11 +93,9 @@ static function bool CallHandleTextFor return true; } -static function bool CallHandleLocalized -( +static function bool CallHandleLocalized( Actor sender, - LocalizedMessage message -) + LocalizedMessage message) { local int i; local bool result; @@ -116,12 +110,10 @@ static function bool CallHandleLocalized return true; } -static function bool CallHandleLocalizedFor -( +static function bool CallHandleLocalizedFor( PlayerController receiver, Actor sender, - LocalizedMessage message -) + LocalizedMessage message) { local int i; local bool result; diff --git a/sources/Events/Broadcast/BroadcastEventsObserver.uc b/sources/Events/Broadcast/BroadcastEventsObserver.uc index 989c478..5674e87 100644 --- a/sources/Events/Broadcast/BroadcastEventsObserver.uc +++ b/sources/Events/Broadcast/BroadcastEventsObserver.uc @@ -40,7 +40,7 @@ enum InjectionLevel // `BroadcastEventsObserver` will be places in the broadcast handlers' // chain as a normal `BroadcastHandler` // (through `RegisterBroadcastHandler()` call), which can lead to incorrect - // handling of `HandleText` and `HandleLocalized` events. + // handling of `HandleText()` and `HandleLocalized()` events. BHIJ_Registered, // `BroadcastEventsObserver` will be injected at the very beginning of // the broadcast handlers' chain. diff --git a/sources/Events/Broadcast/BroadcastListenerBase.uc b/sources/Events/Broadcast/BroadcastListenerBase.uc index 6cf6b0d..b739a26 100644 --- a/sources/Events/Broadcast/BroadcastListenerBase.uc +++ b/sources/Events/Broadcast/BroadcastListenerBase.uc @@ -24,89 +24,147 @@ class BroadcastListenerBase extends Listener abstract; -static final function PlayerController GetController(Actor sender) +/** + * Helper function for extracting `PlayerController` of the `sender` Actor, + * if it has one / is one. + */ +static public final function PlayerController GetController(Actor sender) { local Pawn senderPawn; senderPawn = Pawn(sender); - if (senderPawn != none) return PlayerController(senderPawn.controller); + if (senderPawn != none) { + return PlayerController(senderPawn.controller); + } return PlayerController(sender); } -// This event is called whenever registered broadcast handlers are asked if -// they'd allow given actor ('broadcaster') to broadcast a text message, -// given that none so far rejected it and he recently already broadcasted -// or tried to broadcast 'recentSentTextSize' symbols of text -// (that value is periodically reset in 'GameInfo', -// by default should be each second). -// NOTE: this function is ONLY called when someone tries to -// broadcast TEXT messages. -// If one of the listeners returns 'false', - -// it will be treated just like one of broadcasters returning 'false' -// in 'AllowsBroadcast' and this method won't be called for remaining -// active listeners. +/** + * This event is called whenever registered broadcast handlers are asked if + * they'd allow given actor ('broadcaster') to broadcast a text message. + * + * If injection level for Acedia's broadcast handler is `BHIJ_Root`, this event + * is guaranteed to be generated before any of the other `BroadcastHandler`s + * receive it. + * + * NOTE: this function is ONLY called when someone tries to + * broadcast TEXT messages. + * + * You can also reject a broadcast after looking at the message itself by + * using `HandleText()` event. + * + * @param broadcaster `Actor` that requested broadcast in question. + * @param recentSentTextSize Amount of recently broadcasted symbols of text + * by `broadcaster`. This value is periodically reset in 'GameInfo', + * by default should be each second. + * @return If one of the listeners returns 'false', - + * it will be treated just like one of broadcasters returning 'false' + * in 'AllowsBroadcast' and this method won't be called for remaining + * active listeners. Return `true` if you do not wish to block + * `broadcaster` from broadcasting his next message. + * By default returns `true`. + */ static function bool CanBroadcast(Actor broadcaster, int recentSentTextSize) { return true; } -// This event is called whenever a someone is trying to broadcast -// a text message (typically the typed by a player). -// This function is called once per message and allows you to change it -// (by changing 'message' argument) before any of the players receive it. -// Return 'true' to allow the message through. -// If one of the listeners returns 'false', - -// it will be treated just like one of broadcasters returning 'false' -// in 'AcceptBroadcastText' and this method won't be called for remaining -// active listeners. -static function bool HandleText -( +/** + * This event is called whenever a someone is trying to broadcast + * a text message (typically the typed by a player). + * It is called once per message and allows you to change it + * (by changing 'message' argument) before any of the players receive it. + * + * See also `HandleTextFor()`. + * + * @param sender `Actor` that requested broadcast in question. + * @param message Message that `sender` wants to broadcast, possibly + * altered by other broadcast listeners. + * @param messageType Name variable that describes a type of the message. + * Examples are 'Say' and 'CriticalEvent'. + * @return If one of the listeners returns 'false', - + * it will be treated just like one of broadcasters returning 'false' + * in `AcceptBroadcastText()`: this event won't be called for remaining + * active listeners and message will not be broadcasted. + */ +static function bool HandleText( Actor sender, out string message, - optional name messageType -) + optional name messageType) { return true; } -// This event is similar to 'HandleText', but is called for every player -// the message is sent to. -// If allows you to alter the message, but the changes are accumulated -// as events go through the players. -static function bool HandleTextFor -( +/** + * This event is called whenever a someone is trying to broadcast + * a text message (typically the typed by a player). + * This event is similar to 'HandleText', but is called for every player + * the message is sent to. + * + * Method allows you to alter the message, but note that changes are + * accumulated as events go through the players. + * + * @param receiver Player, to which message is supposed to be sent next. + * @param sender `Actor` that requested broadcast in question. + * @param message Message that `sender` wants to broadcast, possibly + * altered by other broadcast listeners. + * But keep in mind that if you do change the message for one client, - + * clients that come after it will get an already altered version. + * That is, changes to the message accumulate between different + * `HandleTextFor()` calls for one broadcast. + * @param messageType Name variable that describes a type of the message. + * Examples are 'Say' and 'CriticalEvent'. + * @return If one of the listeners returns 'false', - + * message would not be sent to `receiver` at all + * (but it would not prevent broadcasting it to the rest of the players). + * Return `true` if you want it to be broadcasted. + */ +static function bool HandleTextFor( PlayerController receiver, Actor sender, out string message, - optional name messageType -) + optional name messageType) { return true; } -// This event is called whenever a localized message is trying to -// get broadcasted to a certain player ('receiver'). -// Return 'true' to allow the message through. -// If one of the listeners returns 'false', - -// it will be treated just like one of broadcasters returning 'false' -// in 'AcceptBroadcastText' and this method won't be called for remaining -// active listeners. -static function bool HandleLocalized -( +/** + * This event is called whenever a someone is trying to broadcast + * a localized message. It is called once per message, but, + * unlike `HandleText()`, does not allow you to change it. + * + * @param sender `Actor` that requested broadcast in question. + * @param message Message that `sender` wants to broadcast. + * @return If one of the listeners returns 'false', - + * it will be treated just like one of broadcasters returning 'false' + * in `AcceptBroadcastLocalized()`: this event won't be called for + * remaining active listeners and message will not be broadcasted. + */ +static function bool HandleLocalized( Actor sender, - BroadcastEvents.LocalizedMessage message -) + BroadcastEvents.LocalizedMessage message) { return true; } -// This event is similar to 'HandleLocalized', but is called for -// every player the message is sent to. -static function bool HandleLocalizedFor -( +/** + * This event is called whenever a someone is trying to broadcast + * a localized message. This event is similar to 'HandleLocalized', but is + * called for every player the message is sent to. + * + * Unlike `HandleTextFor()` method does not allow you to alter the message. + * + * @param receiver Player, to which message is supposed to be sent next. + * @param sender `Actor` that requested broadcast in question. + * @param message Message that `sender` wants to broadcast. + * @return If one of the listeners returns 'false', - + * message would not be sent to `receiver` at all + * (but it would not prevent broadcasting it to the rest of the players). + * Return `true` if you want it to be broadcasted. + */ +static function bool HandleLocalizedFor( PlayerController receiver, Actor sender, - BroadcastEvents.LocalizedMessage message -) + BroadcastEvents.LocalizedMessage message) { return true; } @@ -114,7 +172,4 @@ static function bool HandleLocalizedFor defaultproperties { relatedEvents = class'BroadcastEvents' -} - - // Text messages can (optionally) have their type specified. - // Examples of it are names 'Say' and 'CriticalEvent'. \ No newline at end of file +} \ No newline at end of file