Message Queue - kinggath/WorkshopFramework GitHub Wiki

The idea behind the message queue is simple:

  1. Allow players to decide when non-critical messages appear on screen.
  2. Provide mod authors a simple interface to work with to accomplish this.

With that in mind, Workshop Framework handles just about everything, all you have to do is route your Message.Show calls through Workshop Framework's new Message Manager. It can even handle displaying quest objectives (which to players often just look like messages).

Message Manager supports multiple types of messages: simple Message form .Show() calls, Message forms with float replacement, and several variations of Message plus aliases, and all of these types include fields to also set quest objectives. You simply route your message calls through these functions, and Workshop Framework will decide whether to show the message or queue it up, depending on the player's settings.

What types of messages should I route through this system?

Generally, non-time-sensitive notifications. Things like notifying the player that something happened in their settlements they might be waiting for, or some long-running action has finally completed. The types of things the player might want to know, but aren't so important that they need to be popping up on screen.

I tend to think of it like email versus text. Things that aren't super urgent, I might email to someone knowing they'll read it when they have time, whereas important things I'd send as a text (or maybe even call about). So send your "email" level messages via WSFW Message Manager and everything else should continue to be displayed how you're used to.

If the player needs to select an option, you should NOT send it through this. The integer you're expecting will not be returned.

Using the Message Manager

To start, setup a new property or load via GetFormFromFile the WSFW_MessageManager quest, and then cast it as WorkshopFramework:MessageManager. (Note: In a future update, I'll expose this system more simply via the API using global functions). This will give you access to a series of Show functions you can route your messages through.

ShowMessage

This is the simplest type, it works just like the basic Message.Show() command, but has the additional benefit of accepting a Quest objective to go with it.

Parameters: Message aMessage, float afArg1 = 0.0, float afArg2 = 0.0, float afArg3 = 0.0, float afArg4 = 0.0, float afArg5 = 0.0, float afArg6 = 0.0, float afArg7 = 0.0, float afArg8 = 0.0, float afArg9 = 0.0, Quest akQuestRef = None, Int aiObjectiveID = -1, Int aiStageCheck = -1, Bool abForceShowNow = false

aMessage: The actual message form you want to display to the player afArg1 through afArg9: Floats you're using with the basic text replacement system akQuestRef: If you need to also display an objective, include this. aiObjectiveID: The objective number to display. aiStageCheck: If sent, before displaying the quest objective, the quest will be checked to make sure this stage hasn't been completed. This way you can prevent Message Manager from re-displaying an Objective that is no longer relevant.

Alias Based Messages

The remaining types all use special Structs as the function parameters. To use these structs, include this line near the top of your script:

import WorkshopFramework:Library:DataStructures

Then create your data struct in order to use it as a parameter, example:

AliasMessage thisMessage = new AliasMessage

thisMessage.amMessage = MyMessage thisMessage.amObjectRef = SomeObjectRef thisMessage.amAlias = SomeRefAlias ...

Note there is also a ShowBasicMessage function which uses the same Struct format as the alias types described below, you can use this, or the ShowMessage function and they will do the same things. ShowMessage is essentially an API-like function to avoid needing to create the struct. Full API support for all of these as global functions will likely come in the next update.

ShowAliasMessage

This will make use of the Text Replacement system to work with a single Reference Alias.

Parameters: AliasMessage aMessage, Bool abForceShowNow

aMessage: Struct of type ALiasMessage. It has the same fields as ShowMessage and they serve the same functions, the unique fields are:

ReferenceAlias amAlias: The ReferenceAlias you want amObjectRef added to ObjectReference amObjectRef: The ObjectReference you want added to amAlias Bool bAutoClearAlias = true: If true, the alias will be cleared immediately after the message is shown

abForceShow: This is used internally to actually display the messages regardless of circumstances and settings, these are used by the player controls so they can view the messages via holotape.

ShowLocationMessage

This will make use of the Text Replacement system to work with a single Location Alias.

Parameters: LocationMessageaMessage aMessage, Bool abForceShowNow

aMessage: Struct of type LocationMessage. It has the same fields as ShowMessage and they serve the same functions, the unique fields are:

LocationAlias lmLocationAlias: The LocationAlias you want lmLocation added to Location lmLocation: The Location you want added to lmLocationAlias Bool bAutoClearAlias = true: If true, the alias will be cleared immediately after the message is shown

abForceShow: This is used internally to actually display the messages regardless of circumstances and settings, these are used by the player controls so they can view the messages via holotape.

ShowLocationAndAliasMessage

This will make use of the Text Replacement system to work with a single Location Alias plus a single Reference Alias.

Parameters: LocationAndAliasMessage aMessage, Bool abForceShowNow

aMessage: Struct of type LocationAndAliasMessage. It has the same fields as ShowMessage and they serve the same functions, the unique fields are:

LocationAlias lamLocationAlias: The LocationAlias you want lamLocation added to Location lamLocation: The Location you want added to lamLocationAlias ReferenceAlias lamAlias: The ReferenceAlias you want lamObjectRef added to ObjectReference lamObjectRef: The ObjectReference you want added to lamAlias Bool bAutoClearAlias = true: If true, the aliases will be cleared immediately after the message is shown

abForceShow: This is used internally to actually display the messages regardless of circumstances and settings, these are used by the player controls so they can view the messages via holotape.