---
tags: UX, Design
---
# User Feedback (Mothblocks)

[toc]

## Maintainer Design Flows
:::warning
This section describes design flows that are meant to be upheld in the PR process. **PRs that go against this section are subject to closing.** Please do not edit this section unless you are a maintainer. Comments via sidebar are welcomed.
:::

Every action in the game must have some sort of feedback. This is both so as a player you know when your actions went through, as well as improving game feel. Good sounds can even help immersion. There are two types of feedback: visual and auditory.

Examples of great feedback in SS13 are:
- Using a wrench on to deconstruct something displaying a `do_after` (visual feedback) and a sound effect.
- Defibrilators displaying a `do_after`, then a powerful sound effect.

These are good not just because they combine both visual and auditory feedback, but because a `do_after` **keeps your eyes on your character and the world**. Contrast this with something like a stun baton. Toggling a stun baton (at the time of writing) plays a sound effect, changes the sprite, and makes a chat message. The sound effect is good (if a little quiet). Toggling the sprite is also good, since that way you always know which mode you're in. The chat message, however, is bad. It clogs up the chat window from more important stuff, and doesn't provide any useful information (since you already can see your stun baton is toggled). Both the chat message and the sprite change *force you to divert your attention away from your player and the world*. You have to look down in order to check your hands, and you need to look down and to the right to see the chat.

The best feedback doesn't move the player's eyes. This doesn't always mean putting alerts on the player. For example, if you have a button in chat, the feedback should probably also be in chat since that is where the player is currently looking.

An important thing to consider when using different feedback methods is to avoid creating overlap. Failing a `do_after` should not create a "failed!" `balloon_alert` because the user has already been informed of the failure by the do_after. However, if the condition for the failure was caused by an uncommon factor (say, something in the extra_checks is no longer true), it would be reasonable to add a "condition lost!" alert.

With all that said, let's talk about some of the types of feedback you will encounter.

## to_chat/visible_message/audible_message/show_message

All of these write text to the player's chat window, and nothing more.

**Pros**
- Very easy to use as a developer.
- Customizable. You can apply whatever crazy CSS you want, though even just the standard "warning" / "info" / etc are nice and consistent.
- They are preserved in history.
- For `visible_message` and `audible_message`, you get blind/deaf checks for free.

**Cons**
- They force the player to look away from the world, and if used for anything not chat related will make them move their eyes.
- Used a *lot*, meaning chat is regularly cluttered with things you don't care about.


- Due to the implementation of the anti-clutter system (the "x5" counter), using it for modal-style input makes it confusing to read. As an example, consider something that when enabled/disabled only has a chat message. If you click the button 3 times, you would see "Enabled (x2). Disabled". It is hard to tell which mode you're actually in, and thus the feedback just becomes useless.

### Assessment

Very common over the life of the codebase, but is often not the best feedback to use. Use to_chat sparingly, and **avoid it if archival is not important**. For instance, enabling/disabling something should not use to_chat as it is unlikely you'll want to go back and see.

Consider the alternative methods of visual feedback...

## say/manual_emote

These not only go to your chat, but also display an in-world Runechat message.

**Pros**
- Easy to use as a developer.
- Keeps player's eyes on what they want to focus on, as the Runechat message is in world.

**Cons**
- Not always thematically appropriate. A lot of feedback is intended towards the player, and not the character.

**Notes**
- Only those who can hear will see `say`.
- Still fills chat. **This should be fixed to allow for say/manual_emote to only create the Runechat message, as well as some equivalent to handle blindness/deafness as easily as `visible_message` and `audible_message`**
- If this is possible, anything that should not be archived should move to this system. For example, sneezing.

### Assessment

`say` and `manual_emote` are not quite there yet in terms of beating out `visible_message` or `audible_message`, but with some API additions can be a very powerful tool to replace them. For example, a to_chat of "The machine beeps, and flashes red." could become an emote of "beeps and flashes red".

## balloon_alert/balloon_alert_to_viewers

Balloon alerts fade text from the bottom upwards.

**Pros**
- Keeps player's eyes on what they want to focus on, as the balloon alert is in world.
- No residue is left behind, such as chat messages.

**Cons**
- Must be kept extremely short, both because of how fast they fade away and due to their size.
- Bad for anything you want to check back on later, as there is no residue.

### Guidelines

- Should be as short as possible. Avoid using object names (`[src]`, `[src.name]`) unless necessary.
- Keep lowercase, except for acronyms/proper nouns like AI.
- For failure states, end with "!". For pending states, like before a do_after, end with "...". Otherwise, no trailing punctiation.
- doing something...
- couldn't do something!
- did something

### Assessment

`balloon_alerts` are like what `say` and `manual_emote` should have the option to be, with no residue left behind. Balloon alerts are good for quick, temporary actions (such as toggling modes), while `say`/`manual_emote` are good for temporary, in-world notifications that can last longer, but still leave no residue.

## Sprite changes

**Pros**
- A toggled sprite change (such as stun batons) provides instant understanding of what if it is enabled or disabled without any extra input.
- Makes items look a lot better.
- Changes made with `flick` (or are otherwise temporary) leave no residue behind.
- If done on machines, turfs, etc then the player does not need to look away.

**Cons**
- Requires art to be done.
- For items, requires the player to look away from the screen if the only feedback.

### Assessment
If you have the art to do so, sprite changes are an excellent way to improve feedback. For items, make sure they are not the only visual feedback as to keep the player's eyes in the same place.

## playsound

**Pros**
- Can keep the player's eyes in one place, since they won't need to look away.
- Good sounds create good game feel.
- Good sounds help immersion.

**Cons**
- Requires art to be done.
- Can't be guaranteed to be heard, either because the player is hard of hearing or simply if there is too much action and sounds going on.

**Notes**
- In most circumstances, will not be heard by the in-game deaf.

### Assessment
Sounds are very important to improving game feel. However, in most circumstances (usually something like a literal jukebox), they should not be your only form of feedback. This is to not exclude hard of hearing players or players in intense situations.

## On projectiles

Knowing who shot what is important. However, putting this information in the chat and making people scroll back up is lazy and gamey, and most importantly clogs the chat. This is especially bad for things like PKAs, which flood your chat with their repeated firing. This is also something silencers use as balance--they do not log in chat.

Projectiles should not log in chat. However, firing a gun should also create a big, noticeable muzzle flash, with powerful sounds. This forces players to divert their attention to the shooter, where they are then expected to remember who shot it themselves. Silencers would not have this muzzle flash, keeping them identical to how they are now.

## Non-Maintainer Design Flows
:::info
This section describes various design flows that are not yet incorporated into the maintainer-approved design. **Working towards these flows does not guarantee merge, nor does going against these flows guarantee close. Please resort to `###` and below for heading tags, and preferably `Title (Author)` for easy reference. Titles can be set with YAML metadata. Ping Cobby on Discord if you need assistance embedding/generating your note.**
:::

#### goofball

please add some way to view a log of all to_chat/balloon actions the player gets that's visible somewhere

my reasoning:
I (and possibly others) have serious issues w/ memory to the point of "i can't remember what step im on in a step-by-step guide i'm following right now and constantly have to refer back to the guide and what i've done already to figure that out", and having that text log available will ease the burden of remembering what i've done recently

i know this sounds like a dumb complaint but ss13 is a game i really like playing because not only is it complex, but also i have a perfect log of everything i've done and witnessed to look back on when i have moments of forgetfullness that are unfortunately becoming more and more common the more years go by