shepard / bardbot Goto Github PK

Basics

Unlocks are a way for story authors to set persistent boolean flags on a player from within the story as well as request the state of those flags. They are persistent in that they keep their state after a playthrough ended and can be accessed in another playthrough of the same user. That way they can be used for example to implement some "new game+" content.

Example

Player reaches a certain part or end of the story. The story triggers an unlock with the id "good_end". The game engine shows the player a message "Unlocked! Good end".
The player finishes the story and starts again. At the beginning, the story checks if the "good_end" unlock has been achieved. Based on that, it grants the player some bonus items.

Triggering unlocks

Via a tag in the story:
# unlock: unlock id, text for user

• When reached in the story, it posts an embed with the title "Unlocked!", an icon of an open lock and the text the author defined in the embed description (can be left empty).
• Also stores the unlock id for the tuple (user id, story id). An unlock id is scoped to the story it was triggered in (so you don't have to worry about id clashes with other story authors).
• Allowed characters, length etc. of unlock ids to be defined.

Potentially, authors don't want users to know they unlocked something. Therefore, silent unlocks could also be a thing:
# silent-unlock: unlock id
or:
# unlock: unlock id, _silent_
Maybe leaving out the text parameter makes it silent while providing the ',' for it (or '-' as a text) will make it show the unlock but without text?

Checking for unlocks

Via an external function:
hasUnlocked('unlock id')
Checks if the provided unlock id was triggered by this user in this story already (whether in this playthrough or another).

Depends on #2.

Motivation

With the basic unlock system, unlock ids are scoped to a story and the state of an unlock id can be requested from within the story it belongs to via hasUnlocked('unlock id').

While this makes sure there are no unlock id clashes across stories, it would still be desirable if a story could check the state of an unlock id of another story. This way, a story author writing a sequel to a previous story of theirs can "import" some of the achievements of a player of the previous story and adjust its behaviour accordingly.

Solution

For this, the story author needs to be able to identify the story that they want to check an unlock id of, ideally via a string parameter to the external function hasUnlocked.

• The story id saved in the database could be used. It's a UUID auto-generated when a story gets uploaded to a server. It is unique and never changes. The admin interface would have to provide access to it. However, it's also quite cryptic, it doesn't convey to a reader what story is being identified. And it's not available until after the story has been created in the server, so the story author can't know it beforehand.
• The title of the story is much more readable. But it can also be changed after the fact, making its use for identification purposes from within the story content quite fragile.
• A user-defined id could be added. This could maybe be set via a metadata tag or in the admin interface when creating the story. The admin code would ensure it is unique in the server. It would not be changable afterwards.

Accessing the state of an unlock from another story would then be done via the external function call:
hasUnlocked('unlock id', 'story id')

A story author will not be able to change the state of an unlock from another story. Similar behaviour can probably be achieved by instead triggering an unlock in the current story and having the other story check its state.

Depends on #2.

When defining a story suggestion, the story admin will be able to enter an unlock id in a text field in the same dialog where they can enter the text for the suggestion. The unlock id will be shown on the detail administration view of the suggestion.

With this, the suggestion is now conditional. It will only be shown to the player at the end of a story playthrough if the unlock has been triggered for the player beforehand.
Additionally, when the player sees a list of stories via /story show or /story start, this will now also show stories which are linked as suggestions of stories for which the user has achieved the unlock id stored in the suggestion.

Potential external functions for providing information from the Discord environment to a story:

• getServerName() - Server name of the server this story belongs to, as configured in the server settings.
• getPlayerName() - Display name of the user currently playing the story.
• getPlayerServerName() - Display name of the user currently playing the story, as set in their server profile.
• getBotName() - Display name of the bot user running the story.
• getBotServerName() - Display name of the bot user running the story, as set in its server profile.

Motivation

When defining a character in a story, apart from the mandatory name, the author can set a colour and a URL for a profile picture / avatar.
The colour is currently used for the small strip on the side of the embed of the character speech. Finding a good picture for every character can be difficult. When no URL to a picture is set, the game will currently just not show a picture.

Solution

When no URL is set, auto-generate a picture based on the other data. The name can be used for initials. If a colour is defined, it can be used as a background colour.

• We can generate an image locally and upload it as an attachment to the first character speech message. After that, we might want to find out the URL of the uploaded file from the message and cache that (store it in the database?) so we can just point to that in the next message, instead of uploading it again.
• Alternatively, we can point to a web service to generate the picture for us.
  • https://singlecolorimage.com/api.html would work for just single-colour images without initials. Seems to send cache headers but browser rerequests it anyway? Need to make sure we don't get rate limited by it.
  • https://boringavatars.com/ could be used for a more interesting image based on the colour.

Depends on #2.

Motivation

With the basic unlock system, the player might be unfirmed that they achieved an unlock. With #3 an unlock can be used to suggest more (potentially secret) stories conditionally and using #4 an unlock in one story can influence the behaviour of another story.
However, the information that a player has achieved an unlock is not available to anyone outside of the playthrough.

Solution

Potential scenarious are:

• The story owner or an admin gets informed via DM that a player triggered an unlock. They could react to this by awarding the player with a role in the server.
• An admin might want to check which players have achieved a certain unlock or which unlocks have been achieved by a certain player. Again, they could use this to hand out some kind of reward later on. Possible command: /manages-stories show-unlocks <user>.
• An unlock could be posted as an achievement in the server in a designated channel.
• Unlocks could be tracked as stats. ("14 other people have unlocked this." / "15% of players have unlocked this.")

Feedback needs to be collected which of these scenarios are relevant to server admins.
Potential privacy concerns need to be considered.

Motivation

Currently, the bot will print out all available content of a story up until the next choice as fast as possible, combining lines of text into single messages as much as possible (although there are some improvements to be made to combine character speech embeds). From time to time, Discord will slow it down, creating unnatural pauses in the message sending.
The two main way to influence this currently are the pause tag, which shows ··· Bot is typing... for three seconds before sending the next message, and the standalone tag, which prevents a line from being combined with other lines into one message.
The desired effect of the pause tag (a dramatic pause) is often not really achieved. It can be hard to tell it apart from a pause created by Discord slowing the bot down. And often, the user is still busy reading the previously sent content and doesn't really see the pause at the right time.

Solution

• Maybe messages shouldn't be posted without delay (by default).
• Introduce a message posting speed / delay.
• When posting with delay, don't combine lines into single messages? It's as if they all had the standalone tag.
• Pause works on top of posting delay?
• Should regular text flow faster than character speech by default?
• Setting posting speed for the next text via a speed tag.
  • Default: speed: 0 - post without delay.
  • speed: 1 - post with one second delay.
  • Up to speed: 10 - post with 10 seconds delay.
• The speed will be used for all following lines until it is changed again. (Might be problematic with the stateless nature of the story - will have to store the speed state with the rest of the state, maybe as a variable.)
• Documentation:
  • Change section "Other helpful tags" int "Advanced: Controlling the text flow" and add description of speed tag.
  • Update section "Playing" which talks about messages taking time to arrive. Update section "Discord formatting" as well.