Onboarding/Tutorial System

We need to implement a tutorial/onboarding experience for new players that explains the basic game controls and interface. Ideally this should be expandable/customizable by downstream/forks through yaml or config. To implement this as fast as possible (hopefully before the influx of players from PCTide), we should focus on getting this implemented as fast as possible and worry about supporting expansion/customization at a later date.

Part 1:

This is a system for allowing players to select tutorial/onboarding depth, from none to "everything" and can be used for both onboarding and other possible tutorial systems.

The first thing we need for onboarding/tutorialization is having some way of toggling/querying a user's onboarding preferences:

[ ] New players are shown a selection menu when spawning in on a server/fork that shows 4 options (in the future there will a 4th and optionally a 5th): No Onboarding, Familiar with SS13, Full Tutorial.
[ ] Selecting an option will save the selected onboarding level to the either the server database or the player's local datafile.
[ ] An additional "on-boarding progress" value will be stored in the same way, and can be incremented and saved to keep track of which part of onboarding that a player is in.
[ ] A list of ids that match onboarding steps that this player has completed.
[ ] A "completed onboarding" boolean that is saved in the same way, this boolean is set when the user selects "No onboarding", completes the onboarding or presses the dismiss/end button in onboarding.

Part 2:

The specifics for the onboarding system:

For the actual onboarding system:

[ ] Onboarding would be triggered after a player selected an onboarding option OR spawns in after rejoining/reconnecting (which resumes the last onboarding step)

Onboarding would have multiple helper methods that allow for UI prompts/highlights to be displayed and dismissed. Specifically:

[ ] Highlighting a UI element with an arrow or other visual highlight.
[ ] Highlight an ingame entity with an arrow/pointer or other visual indicator
[ ] Attach a text box at an offset to a UI element. With support for "pages" that a player can click through
[ ] Highlight a Keybind that a player needs to press
[ ] Highlights can be dismissed by mousing over/clicking on the UI element or after clicking through a linked textbox.
[ ] A togglable textbox on the HUD with pages and a dismiss button for displaying onboarding tips

Onboarding hints would be triggered via hooking/subscribing to events that are raised in code

[ ] Create a system that allows raising/subscribing to onboardingEvents
[ ] Onboarding highlights/hints listening would be enabled/disable depending on the onboarding progress variable
[ ] Players can click a "Dismiss tutorial" button at the top of the screen at any time during onboarding to end/exit out of onboarding.

An "Onboarding flow" is a defined onboarding "flow"/sequence that defines the number of and specific onboarding steps present in an instance of onboarding. Each option selected in part 1 (except for no onboarding) will correspond to an "Onboarding flow".

[ ] Onboarding Step Prototype allows for linking together event listeners, UI highlight tags and description sequences.
[ ] Onboarding flow has a list of OnboardingSteps which specify the order and flow of the onboarding.
[ ] Onboarding flow allows for additional 'contextual' onboarding steps to be defined which can be triggered at any time by a player's actions (IE sitting in a chair) but only once.

I've been wanting to tackle this in a PR for some time and I might give it a shot if that's alright. My idea would be contextual popups on the side of the screen like some RPGs I used to play had. You get prompts to do something, when the action succeeds it goes onto the next step, or the player can skip through the pages.

So for example, when you connect, the onboarding flow says "move using WASD", when that is done, the next step is triggered (for example : left click an object to take it etc). Any step can be skipped by the player, and the whole onboarding flow can be dismissed.

However, I think there should be more than two "Onboarding flows". There should be two general ones (the super newbie one and the "kinda used to the game" one), but also onboarding for different machines, items, systems that would popup throughout the game and can be : altogether disabled or dismissed. For example, if a player has completed the basic onboarding, the first time they'll play a specific job, an onboarding can be shown for that job etc.

This is a sample OnboardingFlow prototype I came up with. Please let me know if that's a good way to implement this

- type: onboardingFlow
  id: LearnMovementsFlow
  trigger: !type:PlayerSpawnEvent   # Here valid EntityEventArgs
  priority: 0                       # The higher priority flows will be played over low priority ones when multiple valid flows can be played
  interrupt: false        # Onboarding flows can interrupt ongoing ones (eg. When emergency shuttle is called for the first time, the newcomer should be explained what it is and informed to go there asap)
  steps:
    - content:
      - type: !type:SimpleText
        text: "Press WASD to move"
      resolve: !type:PlayerMoveEvent  # Valid EntityEventArgs
    - content:
      - type: !type:PointToObject
        entityType: Sunglasses
        text: "Click on an object to pick it up"
      resolve:
        type: !type:PlayerPickupEvent
        entityType: Sunglasses
    - content:
      - type: !type:MultiPageContent
        pages:
          - type: !type:SimpleText
            text: "Did you know you can throw items?"
          - type: !type:SimpleText
            text: "It's very cool"
      resolve: !type:PlayerPickupEvent

Each step is a OnboardingStep which contains:

A "resolve", it's the condition on which the onboarding step is considered "completed" and will continue to the next. There should be a way to specify arguments dependant on what type of step it is (eg. If you have to pickup an item, specify the item id)
"Content" is the UI definition part. What should be displayed? Just a simple text, multi-page content, text with image, text with in-world highlight, text with HUD highlight

Semi exhaustive list of what content types could exist Onboarding step content types

Simple text, as the name suggests. This should be Richtext
TextWithImage, text with an in-game screenshot when needed
PointToObject, points to the closest object in the world which matches the ID
PointToMob, same for mobs
HighlightWorld, darkens the whole screen except a specific position/object in the world for "in your face" highlighting
HighlightUI, same but for UI elements

@clement-or

I've been wanting to tackle this in a PR for some time and I might give it a shot if that's alright.

I've already started working on this unfortunately 😅, but once I finish setting up the onboarding systems and such I could definitely use some help setting up the events and hooking everything up in the prototypes.

My idea would be contextual popups on the side of the screen like some RPGs I used to play had. You get prompts to do something, when the action succeeds it goes onto the next step, or the player can skip through the pages.

Yep this is along the lines of what I had in mind, but more in-depth with actual stateful flows (ie: you complete actions to finish a "step") and more specific things and if you disconnect mid onboarding it would continue next time at the last "stage" you completed.

Each step is a OnboardingStep

Onboarding steps should be their own prototypes so that they can be reused and reordered across different flows.

There should be two general ones

Ideally onboarding should be scalable and allow for servers to define however many onboarding flows they want (and their display orders). In addition, I'd also like to implement the ability to switch between different levels of job/role onboarding as well.

space-wizards / space-station-14