RFC: About reworking the Non-Civilopedia Tutorials

[SomeTroglodyte]

Idea Description

The tutorials that float at the top of WorldScreen while waiting for you to perform some action are a bit drab, a bit too hardcoded, not moddable in any way - and in the cramped portrait mode they're placed uglily below the shifted buttons' lower edge.

Since I had ideas to redo Tutorials - but the other kind, the popup kind - and just recently saw the high degree of conceptual similarity to Event - I got to toy with some stuff. Not polished, but I'll pause and while that code is parked show a glimpse and..

Request input

• worth it or are these so stale and always-skipped by new players that dropping them is preferable?
• would modders use the format for their events too and what might be missing?
• Anyone has a - or wants to do a - license-compatible decoration for the "Meet another civilization" tut?
• Feels fast, but - it's going through the Unique and Conditionals testing system in WorldScreen.update() - which gets called not at 60fps from render() but still way more often than you'd think. Still thinking whether and how some of that could be optimized.
• And, oh, another idea: Show Events in Civilopedia? Then maybe existing mods would would want to add the "hidden" Unique to most of theirs... Even if I'd not display the choices or even their names, but maybe search for the trigger and display that... And of course these here would all need the hidden marker.
• The "completed" system is unchanged, but maybe that could be Unique-formalized too. I just haven't got a good idea that would really help.

Little clip, starting from scratch. The popup kind interferes often, and some of the floating tutorials are missing ¹
https://github.com/yairm210/Unciv/assets/63000004/009ee7b5-038a-4475-bf2a-6f4a04034964

Events.json

[
    {
        "name":"Tutorial Task: [Move unit]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Move a unit!", "centered":true},
            {"extraImage":"Tutorials/Move unit", "imageSize":140}
            {"text":"Click on a unit → Click on a destination → Click the arrow popup."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Units] is greater than [0]>"
            "Unavailable <if tutorial [Move unit] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Found city]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Found a city!", "centered":true},
            {"extraImage":"Tutorials/Found city", "imageSize":140}
            {"text":"Select the Settler → Click on 'Found city'."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Settler] is greater than [0]>"
            "Unavailable <if tutorial [Found city] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Enter city screen]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Enter the city screen!", "centered":true},
            {"extraImage":"Tutorials/Enter city screen", "imageSize":100}
            {"text":"Click the city button twice."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Cities] is greater than [0]>"
            "Unavailable <if tutorial [Enter city screen] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Pick technology]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Pick a technology to research!", "centered":true},
            {"extraImage":"Tutorials/Pick technology", "imageSize":180}
            {"text":"Click on the tech button → select technology → click 'Research' (bottom right)."},
		],
        "uniques": [
            "Only available <if tutorials are enabled>"
            "Unavailable <if tutorial [Pick technology] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Pick construction]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Pick a construction!", "centered":true},
            {"extraImage":"Tutorials/Pick construction", "imageSize":120}
            {"text":"Enter city screen → Click on a unit or building → click 'add to queue'."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Cities] is greater than [0]>"
            "Unavailable <if tutorial [Pick construction] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Pass a turn]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Pass a turn!", "centered":true},
            {"extraImage":"Tutorials/Pass a turn", "imageSize":180}
            {"text":"Cycle through units with 'Next unit' → Click 'Next turn'."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [turns] is less than [3]>"
            "Unavailable <if tutorial [Pass a turn] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Reassign worked tiles]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Reassign worked tiles!", "centered":true},
            {"extraImage":"Tutorials/Reassign worked tiles", "imageSize":140}
            {"text":"Enter city screen → click the assigned tile to unassign → click an unassigned tile to assign population."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Cities] is greater than [0]>"
            "Unavailable <if tutorial [Reassign worked tiles] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Meet another civilization]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Meet another civilization!", "centered": true},
            {"extraImage":"Tutorials/Meet another civilization", "imageSize":130}
            {"text":"Explore the map until you encounter another civilization!"},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [turns] is greater than [1]>"
            "Unavailable <if tutorial [Meet another civilization] is completed>"
        ]
        "choices": [
            {
                "text":"Got it",
                "triggeredUniques": ["Mark tutorial [Meet another civilization] complete"],
            },
        ]
    },
    {
        "name":"Tutorial Task: [Open the options table]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Open the options dialog!", "centered":true},
            {"extraImage":"Tutorials/Open the options table", "imageSize":130}
            {"text":"Click the menu button (top left) → click 'Options'."},
		],
        "uniques": [
            "Only available <if tutorials are enabled>"
            "Unavailable <if tutorial [Open the options table] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Construct an improvement]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Construct an improvement!", "centered":true},
            {"extraImage":"Tutorials/Construct an improvement", "imageSize":150}
            {"text":"Construct a Worker unit →> Move it to a Plains or Grassland tile → Click 'Construct improvement' → Choose the farm → Leave the worker there until it's finished."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Cities] is greater than [0]>"
            "Unavailable <if tutorial [Construct an improvement] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Create a trade route]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Create a trade route!", "centered":true},
            {"extraImage":"Tutorials/Create a trade route", "imageSize":120}
            {"text":"Construct roads between your capital and another city. Or, automate your worker and let him get to that eventually."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Cities] is greater than [1]>"
            "Unavailable <if tutorial [Create a trade route] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Conquer a city]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Conquer a city!", "centered":true},
            {"extraImage":"Tutorials/Conquer a city", "imageSize":160}
            {"text":"Bring an enemy city down to low health → Enter the city with a melee unit."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when at war>"
            "Unavailable <if tutorial [Conquer a city] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [Move an air unit]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"Move an air unit!", "centered":true},
            {"extraImage":"Tutorials/Move an air unit", "imageSize":140}
            {"text":"Select an air unit →> select another city within range → Move the unit to the other city."},
		],
        "uniques": [
            "Only available <if tutorials are enabled> <when number of [Air units] is greater than [0]>"
            "Unavailable <if tutorial [Move an air unit] is completed>"
        ]
    },
    {
        "name":"Tutorial Task: [See your stats breakdown]",
        "presentation":"Floating",
        "civilopediaText":[
			{"text":"See your stats breakdown!", "centered":true},
            {"extraImage":"Tutorials/See your stats breakdown", "imageSize":140}
            {"text":"Enter the Overview screen (top right corner) → Click on 'Stats'."},
		],
        "uniques": [
            "Only available <if tutorials are enabled>"
            "Unavailable <if tutorial [See your stats breakdown] is completed>"
        ]
    },
]

Branch still needs ironing out translation stuff, like cleaning no longer needed templates, and TFW respect for hidden, and make the new field a non-TFW one, and some stuff that's suboptimal already in old code...

Footnotes

1. Meet another civilization because resolved before its turn came up ², Create a trade route because it needs 2 cities first, Move an air unit - would have needed to get Oil and buy a plane, Conquer a city - too lazy to start a war for the demo. ↩

2. Pity because it shows off these can have choices - this one tends to stay a long time, so I gave it a "Got it" button. ↩

[yairm210]

I am 100% in favor
Better tutorials are something that I've failed for years to make any real dent on, and this looks like a good way forward
Not sure we need "choices" though

[yairm210]

I don't think we need a "unavailable if X is complete" on each of them, since that's the default state for a tutorial 🤔

[SomeTroglodyte]

Better tutorials are something that I've failed for years to make any real dent on

Same here. There's code in master that was meant as preparation to unify all three kinds, way back to early Uniques or even before. The special treatment in WorldScreen and Civilopedia - I once had a vision they could all go. Now that we have triggers and events, the Event context seemed closer to these, which I partially dislike very much since - unify with other Tutorials now how now... Probably make the popup type another presentation type, and leave the pedia-only ones where they are, change pedia caption maybe to something more general, and really give Events some space in pedia?

Not sure we need "choices" though

Mad modders - can be quite useful I think. I don't have the imagination to make something out of the increased possibilities, but maybe they have. That's unfinished - I mean to make the existence of choices optional entirely, all presentation modes (dunno if the code is already there or not). No choices = normal float or alert with a default OK, and click-behind enabled. Choices exist = alert becomes modal. +documentation. +allow no-choice events that still trigger something, same as having only one choice but tighter presentation...
... Having them in a floating tut - as I said, I have the experiment in that json to allow simply clicking away with a "Got it" button the one that most often stays a long time, and can't be intentionally cleared quickly and reliably otherwise: Meet another civ. Works well. In the end, I believe we can allow modders to "invent" new "tutorial completed" keys and manage them with triggers, and say, have "offer" type time-spanning events.

I don't think we need a "unavailable if X is complete" on each of them

Definitely in the "unfinished" corner - to think about that, what's redundant, where loopholes may be or not....