The poll system that was added to BZFlag 1.10 is very basic from the client-side. The clients knows nothing about polls. The server just sends chat messages to notify the client that a poll is starting and about the status of the poll. To start, veto, and vote in a poll requires using slash commands through chat. This is a proposal for better client integration and making polls a first-class citizen by building actual protocol messages around it. Recent 2.4 builds also provide the ability for plugins to register custom poll types, so it should work with custom poll types as well.
In order to display an UI to begin a poll, the client should be aware what types of polls are available. Different poll types may also have different types of targets, such as a player, a team, or some freeform text value (or values?).
MsgPollTypes (PT) [Server->Client]
- UByte PollTypeCount
- Repeated Data (PollTypeCount times):
- UByte PollTypeID
- StdString PollTypeName
- UByte PollTargetType (0 = player, 1 = team, 255 = custom)
To start a poll, the data from MsgPollEnumerate will be used to build the UI, and then pass the selected type and target (stored in a 16-bit signed integer or a string, either sending both or just the specific one for that type) to the server, requesting the start of a poll.
MsgPollRequest (PR) [Client->Server]
- UByte PollTypeID
- UByte PollTargetType
- Short PollTargetID
- StdString PollTargetString
If the server grants the request and begins the poll, the MsgPollStart message will inform the clients about the new poll.
MsgPollStart (PS) [Server->Client]
- UByte PollTypeID
- UByte PollTargetType
- StdString PollTarget (string representation of whatever the target of the poll is)
- UByte PollAllowVote (boolean informing a user if they are allowed to vote)
- Short PollVotesRequired (number of additional votes required to pass)
- UShort PollDuration (duration of the poll in seconds)
-OR-
MsgPollStart (PS) [Server->Client]
- StdString PollMessage (full [multi-line?] message describing what the poll is about)
- UByte PollAllowVote (boolean informing a user if they are allowed to vote)
- Short PollVotesRequired (number of additional votes required to pass)
- UShort PollDuration (duration of the poll in seconds)
I'm not sure if PollTypeID or PollTargetType would be necessary. We could probably just include a fully written message on the server to present to the client instead of making the client build the message based on poll type, target type and poll target.
During the poll, status updates would be sent. Currently I can only think of updating the number of "yes" votes remaining to pass the poll. The client would already know the duration of the poll so that can be tracked by the client.
MsgPollUpdate (PU) [Server->Client]
- Short PollVotesRequired
An admin can cancel a poll (aka veto).
MsgPollCancel (PC) [Client->Server]
(no data? or should we assign a random/incremental ID to a poll and pass that back?)
There would just be a simple message to vote in a poll.
MsgPollVote (PV) [Client->Server]
- UByte PollVote (boolean, 1 = yes, 0 = no)
When the poll completes (either the poll passes early with enough yes/no votes, the time limit is reached, or the poll is cancelled), a message is sent with the results.
MsgPollEnd (PE) [Server->Client]
- UByte PollResult (enum indicating result: 2 = normal end, enough yes votes reached, 1 = normal end, did not receive enough yes votes, 0 = poll cancelled)
- StdString PollAction (Message describing the action that has been taken, if any)
Possibly some additional fields for the number of votes?