Tutorial Improvements #5938

adQuid · 2025-02-23T15:49:12Z

Brief Description of What This PR Does

Updates a few sequences and a lot of text of tutorials, aiming to avoid leading the player down "rabbit holes" of the more complicated bits of the game, improve some clarity, optimize use of limited player attention, and add a little bit a scientific narrative poetry to do some story-telling while trying to explain the game.

Related Issues

Progress Checklist

Note: before starting this checklist the PR should be marked as non-draft.

PR author has checked that this PR works as intended and doesn't
break existing features:
https://wiki.revolutionarygamesstudio.com/wiki/Testing_Checklist
(this is important as to not waste the time of Thrive team
members reviewing this PR)
Initial code review passed (this and further items should not be checked by the PR author)
Functionality is confirmed working by another person (see above checklist link)
Final code review is passed and code conforms to the
styleguide.

Before merging all CI jobs should finish on this PR without errors, if
there are automatically detected style issues they should be fixed by
the PR author. Merging must follow our
styleguide.

hhyyrylainen

I didn't play with the new tutorial yet, so this is just an architectural review for now. I think the HUD control from individual tutorials needs a bit more work, but other than that other problems were just minor.

hhyyrylainen · 2025-02-25T09:32:59Z

simulation_parameters/Constants.cs

    public const float MICROBE_MOVEMENT_EXPLAIN_TUTORIAL_DELAY_CONTROLLER = 1.0f;
-    public const float MICROBE_MOVEMENT_TUTORIAL_REQUIRE_DIRECTION_PRESS_TIME = 2.2f;
+    public const float MICROBE_MOVEMENT_TUTORIAL_REQUIRE_DIRECTION_PRESS_TIME = 1.6f;


I think this should not be reduced until we have a popup for the player to pick their preferred movement mode.

hhyyrylainen · 2025-02-25T09:34:01Z

simulation_parameters/Constants.cs

    public const float TUTORIAL_ENTITY_POSITION_UPDATE_INTERVAL = 0.2f;
-    public const float GLUCOSE_TUTORIAL_TRIGGER_ENABLE_FREE_STORAGE_SPACE = 0.14f;
+    public const float GLUCOSE_TUTORIAL_TRIGGER_ENABLE_FREE_STORAGE_SPACE = 0.03f;


Doesn't this cause problems with the player being able to find glucose way too soon? I've balanced the tutorial so that at most you need to spend like one second cluelessly in the glucose cloud wondering if it is working or not. With less storage space the player may need to spend a lot longer inside a cloud attempting to absorb it even when their storage is full.

This variable could be put back probably given the other tutorials, but there's a new change later to set the glucose manually so that there's always enough free space to finish that tutorial phase.

Yeah, I did see that code later. To me it doesn't seem exactly good that the player data is passed to the tutorial like that to be modified, that's part of the major architectural problem I think exists here I commented on in my review.

hhyyrylainen · 2025-02-25T09:35:11Z

src/tutorial/microbe_stage/GlucoseCollecting.cs


                if (!HasBeenShown && data.EntityPosition.HasValue && CanTrigger && !overallState.TutorialActive())
                {
+                    // force player microbe to have the right amount of Glucose missing
+                    compounds.TakeCompound(Compound.Glucose, compounds.GetCapacityForCompound(Compound.Glucose));


I see this change. I personally would prefer to keep the approach where the tutorial only triggers after the player can reasonable be expected to have enough missing storage space.

I might be convinced to see this is better but I think 0.2 glucose buffer is pretty low safety margin and we should not make the player more likely to die during the tutorial.

I was toying with the idea of having a check to make sure that the glucose never falls below 0.1 during this stage, but I didn't for two reason:

it would be complex and likely error prone messaging code (and you said you wanted small incremental changes)

This is immediately after the player reads a message that says "if you don't have ATP you die". 5-10 seconds into the tutorial, I'm more afraid of players wondering what they are supposed to do after 15 seconds of nothing happening and getting lost in menus than dying from the thing the tutorial was talking about killing you and having to respawn

It's all subjective, but I think a key problem in the early tutorial is a lack of responsiveness. All the streamers I watched are eager to do things and see results, and our first tutorials don't do that very well.

I would actually suggest a pretty simple code addition to the _Process method of the stage: check if the tutorial state is active (i.e. a tutorial is open) and the compounds panel is not open (and the player has not gotten to the editor yet, this should prevent players exploiting it), if so add glucose to the player.

The movement tutorial is meant to last roughly 30 seconds for the slower players. So all tutorials need to be timed so that it still leaves enough time for the movement tutorial to be shown at a relaxed pace.

hhyyrylainen · 2025-02-25T09:37:49Z

src/tutorial/microbe_stage/DayNightTutorial.cs

@@ -21,8 +21,11 @@ public override bool CheckEvent(TutorialState overallState, TutorialEventType ev
        {
            case TutorialEventType.MicrobePlayerEnterSunlightPatch:
            {
+                MicrobeHUD hud = ((HUDEventArgs)args).HUD;


I think it is pretty dirty to pass the HUD like this.

Also the environment panel has to be shown for temperature change with thermosynthesis.

I don't immediately have a good idea here, but I think that some kind of system like "wants pause" going through the tutorial state would be better. Maybe some kind of event system where the TutorialState offers an event callback any active HUD registers to, and individual tutorials can then send events through like "EnvironmentPanelRequired"?

I agree that the args is a little abused in our tutorials. If you have a better pattern you prefer, however, you'll probably need to explain to me how it's going to work...

I did lay out a rough idea. After having it stew in my head for a while, I think it is probably the best option, so adding a method in TutorialState to trigger a tutorial event that is listened to by active HUD instances, would be the way to go in my opinion. Then the tutorials can send events like "compounds panel should be visible" etc. and the relevant HUD then reacts to it.

hhyyrylainen · 2025-02-25T09:39:51Z

src/tutorial/microbe_editor/EditorUndoTutorial.cs

-                if (!HasBeenShown && CanTrigger && !overallState.TutorialActive())
+                OrganelleDefinition placedOrganelle = ((OrganellePlacedEventArgs)args).Definition;
+
+                if (!HasBeenShown && CanTrigger && !overallState.TutorialActive()


I really think we need to tutorialize the undo feature earlier than when placing the nucleus.

We could have another tutorial reminding about undo when placing the nucleus (if the player ATP balance / resource balance is not good). But I don't think we should give up the undo tutorial, because back in the dark ages people used to often ask on our discord how to undo. And I don't want to go back to that.

This isn't the undo tutorial waiting until the player is ready for the nucleus, this is the editor tutorial telling the player to put a nucleus on first, then explaining why that would be a terrible idea and explaining the undo button.

It is entirely possible for a player to ignore this advice and skip this phase by doing different modifications, but I opted to not force the player to read more walls of text if they are aren't ignoring instructions.

But then the player is allowed to skip like half of the hands on tutorial for the first editor cycle, which I don't think is good...

hhyyrylainen · 2025-02-25T09:40:36Z

src/tutorial/microbe_editor/EditorRedoTutorial.cs

I think the redo tutorial had a pretty nice flow to it and it didn't add too much time. And it synergizes really well with the general undo tutorial that is early in the process.

I don't think anyone sees an undo button and can't guess what the button next to it does, and every time you interrupt flow to read a box of text is another couple players who get bored and turn off the tutorial before the important parts.

hhyyrylainen · 2025-02-25T09:41:40Z

src/tutorial/TutorialEventArgs.cs

@@ -62,12 +62,16 @@ public void ReuseEvent(bool usesScreenRelativeMovement, Vector3 movementDirectio

 public class EntityPositionEventArgs : TutorialEventArgs
 {
-    public EntityPositionEventArgs(Vector3? position)
+    public EntityPositionEventArgs(Vector3? position, CompoundBag compounds, MicrobeHUD hud)


Which compounds are these, the entity's or the player's? I think that needs naming clarification. Also I'd totally remove the HUD as I think it just doesn't fit at all into the idea of event args. At most I think a hack with the sender of the event could be done but even that seems not very clean design.

I'll rename the compounds. As for the HUD I have no attachment to this pattern, I just didn't see a cleaner way to send it.

After reading the code it seems like it is the current player's data, which kind of doesn't fit logically as the position is for another entity and the player data is just tacked on... So I would really prefer if that data was also stripped so that we follow more separation of concerns (disallowing the tutorial from directly messing with the player state).

src/microbe_stage/MicrobeStage.cs

adQuid added 20 commits February 22, 2025 11:38

start with environment and compounds panels closed

f09c026

close panels the right way

55f390e

glucose tutorial now opens compounds panel

291d38b

change editor entry message

73ae030

trim the editor entry panel

d2bccfd

tweek glucose tutorial more

2cc73ca

tuning tutorial text some more

56b1a52

day night tutorial turns environment panel back on

3c1335b

trimmed down tutorial text a bit more

8b95e19

add encouragement

22bed1a

more text changes

71a4efe

linter appeasement

9daffb2

linter appeasement

f15c0ca

make text more sagany

6bd8922

panels reopen after editor cycle if you turn tutorials off

80a1502

make environment panel text less photosynthesis specific

b60ed91

resolve merge conflicts

b017700

tune up editor tutorial

aa347c7

bugfixes

4e461cf

linter appeasement

7774878

hhyyrylainen added this to the Release 0.8.2 milestone Feb 24, 2025

adQuid added 2 commits February 24, 2025 22:07

fix process panel bug

fb5f018

Merge branch 'master' into improved-tutorial

7b246b7

adQuid marked this pull request as ready for review February 25, 2025 03:32

adQuid added the review label Feb 25, 2025

adQuid added 4 commits February 24, 2025 22:45

more text tuning

c0fdbeb

more text updates

e01b05e

add stepping stone cloud for players who turn off tutorial

6a31e38

slightly lower cloud size

10e08f3

hhyyrylainen requested changes Feb 25, 2025

View reviewed changes

improved variable name

183e2a0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tutorial Improvements #5938

Tutorial Improvements #5938

adQuid commented Feb 23, 2025 •

edited

Loading

hhyyrylainen left a comment

hhyyrylainen Feb 25, 2025

hhyyrylainen Feb 25, 2025

adQuid Feb 25, 2025

hhyyrylainen Feb 25, 2025

hhyyrylainen Feb 25, 2025

adQuid Feb 25, 2025

hhyyrylainen Feb 25, 2025

hhyyrylainen Feb 25, 2025

adQuid Feb 25, 2025

hhyyrylainen Feb 25, 2025

hhyyrylainen Feb 25, 2025

adQuid Feb 25, 2025

hhyyrylainen Feb 25, 2025

hhyyrylainen Feb 25, 2025

adQuid Feb 25, 2025

hhyyrylainen Feb 25, 2025

adQuid Feb 25, 2025

hhyyrylainen Feb 25, 2025

Tutorial Improvements #5938

Are you sure you want to change the base?

Tutorial Improvements #5938

Conversation

adQuid commented Feb 23, 2025 • edited Loading

hhyyrylainen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adQuid commented Feb 23, 2025 •

edited

Loading