ProTip Advice and Tutoring System B: 130

[CdrCross]

Update 13/11/22 - Made some changes per Max's recommendations.

Introduction and Overview

The goal of the ProTip system is to provide new players to Unitystation responsive, automatic advice that will help them navigate our complicated game. With a flexible and easy-to-use trigger system, the ProTip system could potentially become a simple and low-maintenance means of easing the new player experience. The system is largely inspired by the Learning Helper from Rimworld. This issue very much ties in with Issue #3728 on implementing Mentors. Ideally, the system should be implemented so that non-technical contributors can write and configure new Advice. This issue has/will have a bounty of USD130.

The GUI

The GUI should be a text box that appears in the top right of the screen, approximately taking up the same space as admin tools currently do, given that the overlap between admins and players needing advice should be approximately zero. Advice is mostly just text, but it should ideally be able to contain hyperlinks to Wiki articles on more advanced topics. Control advice should also be responsive to customized keybindings. Every Advice window must contain buttons to contact a Mentor for further questions, a button linking to the Wiki front page, an X button to close the window as well as a button to adjust Advice Frequency, see below.

When the round first starts for a new player to the server, or when a player presses the “Adjust Advice frequency”-button, the hint window should pop up in the top right, offering to tailor the level of advice to the experience level the player chooses by pressing one of the following buttons:

1. New to Space Station 13 (All Advice)
2. New to Unitystation (Only Advice on new features in Unitystation)
3. Somewhat Experienced (Life critical Advice only)
4. Robust (No Advice)

Each piece of advice will only be shown once to a given player, and then a Help section of the Escape menu will offer a list of all advice, for players to re-read if they need to be reminded of something.

The Triggers

Advice pop-ups should trigger based on a variety of circumstances around the player. The system should be able to detect the following:

• The player holding a specific object
• The player holding one of a class of objects (Holding any gun, for example)
• Being near a world object; contains both the object ID and trigger range (The clone scanner, for example)
• Opening a GUI (Opening the hacking screen should trigger hacking advice, for example)
• Health states (The player taking damage, going unconscious, or dying)
• The player being in a hazardous area (Extreme cold or low O2 atmosphere, for example)
• Time from player joining the server
• (Cancelled) Player actions (For walking through sequential steps, like building a wall following a girder)
• (Cancelled) Nearby players’ health states; contains both the relevant health state and trigger range (Finding someone unconscious or dead, for example)
• Changing intents or using resist, rest, and other player intents/stances
• Switching states on particular objects (Like flicking on a Stun Baton)

If multiple triggers are fired before the current protip disappears, then the ProTip’s lifespan could be significantly reduced and the new protip takes its place, but only if the advice level is of a higher priority - else, the less (or equally) important protips could be shelved and instead displayed at the next trigger instance. This would help to reduce a sudden rush of popups at the start of the game and distribute them a little more evenly throughout the round, reducing information overload and the non-ending stream of popups.

The Anatomy of an Advice

• Any given instance of Advice must contain the following data:
• Experience level of the advice (Integer; if the player’s chosen experience level is higher than the level of the advice, the advice will not trigger)
• Trigger conditions (See above chapter)
• Text Advice (A string supporting hyperlinks)
• If possible: Reference objects or UI (Information on objects in the game world or UI elements that the Advice GUI should point to and highlight while the advice is on screen)

Ideally, all the Advices and associated triggers of a given server should be able to be contained in a simple configuration text file, where you for Each Advice have the Advice text itself, alongside invoking a trigger type and giving the relevant arguments. Ideally, the system should also support AND or OR arguments, to allow for combination and differentiation of triggers.

The Writing

Advice should be OOC, as being encouraging and helpful to the new player takes priority over worldbuilding. The writing will be a balance between matter-of-fact brevity, and having enough meta-text and encouragement to make sure new players do not feel stressed, condescended or discouraged from continuing their discovery of the game. Additionally, the system should introduce basic systems and brief overviews of deeper systems, but not rob players of the aforementioned discovery of the game’s depth.

The Checklist (prioritised order)

• Issue Mentors B: 30 #3728 should be completed before this Issue.
• Implementing the Advice object, with relevant properties (See Anatomy of an Advice), in a format that non-technical contributors can work with to add new advice without needing developer backing.
• Implementing the Help sub-menu in the Escape Menu, containing a button that links to the Wiki, a Mentorhelp button, and an archive of every Advice.
• Implementing the Trigger system, per the relevant chapter.
• Designing (possibly with assistance from the UX Team) and implementing the Advice GUI as described above, also being mindful of the GUI Style Guide.
• Implementing the ability for the Advice GUI to highlight/point to game objects and UI elements. (Low priority. Pursue only if you have a quick solution.)
• Leave a hook for Advice to be translated, when official translation support releases.

[Bod9001]

is Bounty, leave comment if you contributed towards this bounty

[PerfectTangent]

@dapocalypse make sure you claim bounties before you start working on them. Can you comment on this issue so I can assign you?

[dapocalypse]

Sure, I claim this then

[PerfectTangent]

@dapocalypse any progress made?

[dapocalypse]

@dapocalypse any progress made?

No I am currently working on my SATs

[PerfectTangent]

@dapocalypse based on our previous conversation on this bounty, I am going to unassign you. Thanks for working on it, nevertheless!

[baszworks]

in terms of creating the advice giving object and give the ProTip Advice and Tutoring System more significance, than a chatbox. how about we redraw or get a little buddy like everyone's favorite friend in the 90s? Lets call him PATS.

(images for explanation, obviously US needs their own adaptation.)

https://images.app.goo.gl/y6aMmTgxssJKziv9A
https://images.app.goo.gl/39mAwzFTQgeRQkx28

Lets call him PATS.

[Borimino]

I have done a bit of thinking on the JSON for this: https://docs.google.com/document/d/1gax1pabp7qGEVLpvYm3blalMoTFh2uEz3SIYV8aYr60/edit?usp=drivesdk

[PerfectTangent]

That's a good list. A couple more I could think to add are:

• what is the player's role ("You are a chef. Here's how to play the role:")
• has a server event been triggered and has been announced. ("sometimes random events will occur. This means...")
• has a new ghost role been opened while the player is a ghost. ("Hey, if you're tired of waiting to be revived, there's a new opportunity to rejoin the game as someone else."
• has the player's character name been mentioned in chat. ("Someone has mentioned you by name. Here's how to use radios to respond:")
• Has the player done antagonising behaviour while they are not an antagonist. (release a plasma canister, set off a bomb, killed someone)
• has the player received flavor text from particular interactions ("Oh no, it appears you have contracted some sort of disease. That coughing means it's contagious.") this is distinct from the trigger for having the condition in the first place because some conditions like diseases are not communicated to the player except through chat notifications.

[Borimino]

@PerfectTangent Those last 2 are a bit hard for me to fully understand.

5. Is there a list of antagonising behaviour anywhere?
   • Should it just be a trigger for that whole category, or should individual actions be selectable when making the trigger?
6. Should that just be for getting any flavor text, or is there an appropriate list somewhere?
   • Should it be triggered for any flavor text on that list, or should individual flavor texts be selectable when making the trigger?

The others I have added to the list in the Google Docs document

[PerfectTangent]

5. Is there a list of antagonising behaviour anywhere?
   • Should it just be a trigger for that whole category, or should individual actions be selectable when making the trigger?

The admin alert log examples are a good start. logs are already made for when a person plasmabombs and for when a non-antagonist kills someone. Adding hooks into both of those should be pretty trivial.

6. Should that just be for getting any flavor text, or is there an appropriate list somewhere?
   • Should it be triggered for any flavor text on that list, or should individual flavor texts be selectable when making the trigger?

no, it should be for a couple specific use cases, such as when displaying symptoms of a disease, hallucinating sounds, character mood changes, witnessing particular actions like using an Emag or something. I don't have a list, these are just ideas.

[MaxIsJoe]

• The player holding a specific object
• The player holding one of a class of objects (Holding any gun, for example)
• Being near a world object; contains both the object ID and trigger range (The clone scanner, for example)
• Opening a GUI (Opening the hacking screen should trigger hacking advice, for example)
• Health states (The player taking damage, going unconscious, or dying)
• The player being in a hazardous area (Extreme cold or low O2 atmosphere, for example)
• Time from player joining the server
• Changing intents or using resist, rest, and other player intents/stances
• Switching states on particular objects (Like flicking on a Stun Baton)

[MaxIsJoe]

Just made this to showcase the progress on protip objects being done

[MaxIsJoe]

@CdrCross the last PRs are finally merged. Can you review what else that needs to be done?

[CdrCross]

To be honest, this has been such a long time in the pipe, and I am currently so disconnected from the game, that I am ultimately not the right person to evaluate your work.
That said, you seem to have ticked every box I listed, and your work looks incredibly impressive. Final tweaks or no, I definitely think you have earned your bounty and then some. @corp-0 Do you agree?

[corp-0]

I agree

[MaxIsJoe]

Alrighty, do I send an invoice of 130 to @PerfectTangent ?

[PerfectTangent]

you would. However, as the main donator to this bounty originally (I put up half of the money for this and the mentors bounty), and I have stayed in touch with the game, I can evaluate it.

[PerfectTangent]

It works very well, and is a massive improvement to the game. Evaluated, approved, and paid. Very well done.