From Chris: Help creating tutorials, please!

[Asteroid]

my goal is for it to ALL be xml

I have a few technical suggestions for this:
- Support some kind of templating for the text: T4, Razor or Handlebars for instance, so it's trivial to insert variables in the middle of the text, do conditional formatting, and the like. T4 and Razor-style template engines also allow arbitrary C# code within the template, useful for advanced users writing tutorials.
- Let us easily call into custom code located in the External Code solution from within the tutorial XML, so the whole thing is extensible and doesn't feel constraining.

Beyond that I guess we'll need complete control over what the AI and other factions are doing, so we can e.g. send a wave on demand and whatever else we can think of, and so it doesn't mess up the tutorial with surprise attacks (unless we're in the final tutorial where we take the training wheels off).

[RocketAssistedPuffin]

Tutorial AI apparently already can't launch attacks by itself. In fact it has no income whatsoever.

[x4000]

I'm not planning on advanced interpretive scripting in the tutorial xml, as that would kind of defeat the point of the simplicity.   My hope is to create enough of a broad nomenclature in there (so to speak) that people can express everything through xml.  If something genuinely radically new is desired then we'd have to add in the new nomenclature and associated code.  But by keeping things flexible and broad, that should work out just fine.

My inspiration for a lot of this is the way that I designed the bullet logic for the SHMUP patterns and such in TLF and Starward Rogue.  That was incredibly powerful without requiring an ounce of code.  And in a lot of ways, the requirements here are simpler than that because it's a linear progression.

Main thing will be getting a list of features for tutorial mapgen and for tutorials playing out actually put together and in practice: https://bugtracker.arcengames.com/view.php?id=21702

I have a list of things I have planned that cover the basics and should allow for recreation of the sort of tutorials that Keith and then Badger did earlier in this game, but then we'll push beyond that.

Things like how the tutorial AI works are things that we'll need to adjust and tweak over time.  I'm not sure why they have no income, for instance.  Some "tutorials" should really just be a regular instance of the game with a hand-designed map and some specified objectives, while others would control when waves arrive and what is in them, etc.  So it's something that needs more flexibility than it currently has.

So far my focus has been on mapgen with tutorials.

[BadgerBadger]

The original tutorial was just the player crushing the AI in a straightforward fashion on a couple planets. I didn't want the AI to have any income because I wanted it to be as easy as possible.
I think you will probably want to define multiple tutorial AIs as you go for different tutorial scenarios.

[x4000]

Actually it now lets you assign any AI during the tutorial xml setup, so I think we're good.  I had forgotten that wasn't hardcoded.

[Asteroid]

I'm not planning on advanced interpretive scripting in the tutorial xml

Sounds good, keeping it simple is a valid goal. It might still be worth looking into logic-free template engines like Handlebars, then. It's really easy to use even for non-coders.

[x4000]

Third party integration is always a potential PITA when accounting for three platforms, and it has syntax I need to  learn, etc.  I much prefer to just roll my own using native xml.  This will only be about the dozenth time I've implemented some sort of framework for things like this in xml before.  So it's a pretty well-trodden path for me.  It's not repeat work on my part, but rather a matter of how to hook it up to the game internals that always differs (by game).  Right now I think it's the most energy-efficient way to create these things in terms of everybody's time.

[Asteroid]

Third party integration is always a potential PITA when accounting for three platforms, and it has syntax I need to  learn, etc.  I much prefer to just roll my own using native xml.  This will only be about the dozenth time I've implemented some sort of framework for things like this in xml before.  So it's a pretty well-trodden path for me.  It's not repeat work on my part, but rather a matter of how to hook it up to the game internals that always differs (by game).  Right now I think it's the most energy-efficient way to create these things in terms of everybody's time.

Can't argue with the 3rd-party integration pain part. Though I think you might be imagining it as more complicated than it is? What I had in mind is something like this:

<TutorialStep name="KillStuff">
Keep going {{PlayerName}}! There are {{NumberOfShipsLeft}} left to kill!
</TutorialStep>

Where PlayerName and NumberOfShipsLeft are variables in the C# object you pass as context to the template. The XML is just something I made up, I haven't looked at how the current tutorials are made. The double brackets are just the standard Handlebars syntax. There you go, you learned the syntax . Any more advanced syntax such as conditionally displaying whitespace around the variable if it's not null or empty is just sugar (but insanely simpler than reinventing the wheel).

Either way, your call. As long as we have tutorials, I'm happy.

[x4000]

That sort of text replacement is pretty straightforward in general, particularly when you don't need to have too many variables or update it too frequently.  We've done that in a variety of games, though usually with single curly brackets rather than double.  I think we did that in Tidalis and Shattered Haven, as well as a few other games.

Anyhow, yeah, that's the general idea!

[x4000]

my goal is for it to ALL be xml

I have a few technical suggestions for this:
- Support some kind of templating for the text: T4, Razor or Handlebars for instance, so it's trivial to insert variables in the middle of the text, do conditional formatting, and the like. T4 and Razor-style template engines also allow arbitrary C# code within the template, useful for advanced users writing tutorials.

You know, I had been thinking of just replacing custom text tags in a pretty simple way, but I'm realizing that with multiple conditions it's useful to be able to say something like {condition1.PlanetName} instead of just {PlanetName}.  I could brute force that, but I had really been hoping to use string interpolation until I found out that isn't dynamic:

https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/string-interpolation

It's a real bummer that doesn't work.  There are other solutions out there for making it so that you can use named lists of variables, but those all require that you pass in all the variables as parameter lists to String.FormatWith() or similar, and they don't support properties or methods or variables on objects.

There's an option that I could use based on this: https://dotnetfiddle.net/MoqJFk

But I keep thinking there has to be a better way.  Surely there's a library for this sort of thing.  But any searches for dynamic string interpolation don't really come up with much. 

And working with dynamic compilation or reflection isn't really an option, because those then are in a different namespace and can't access the local variables I'd want them to be referecning.

Stuff like this doesn't fit the bill at all: https://stackoverflow.com/questions/39874172/dynamic-string-interpolation

This is neat, but seems like overkill and I don't think would get the job done anyway: https://github.com/benjamin-hodgson/Pidgin  That one mentions some alternatives, but none of them are suitable.

Handlebar or similar seems to be only for web-based processing of stuff in the main.

I may need to just bite the bullet and handle this the simple but typo-prone way with a lot of stupid text on my part, but I was curious first if anyone has any ideas on this first.

[x4000]

For now I think I have an idea on how to implement it based on this: https://dotnetfiddle.net/MoqJFk

If that works, I'll just stick with that.  But I'm still a bit away from actually having it working where I can test it.

[Asteroid]

For now I think I have an idea on how to implement it based on this: https://dotnetfiddle.net/MoqJFk

If that works, I'll just stick with that.  But I'm still a bit away from actually having it working where I can test it.

https://github.com/rexm/Handlebars.Net

Definitely not web-only despite using the same syntax as the corresponding Javascript-based project. I've used it with great success to format automated report emails and other moderately complex and dynamic documents.

[x4000]

That's very cool, but without IDE colorization and with it not being a format that I'm naturally already familiar with, my eyes kind of glaze over when looking at it. I think it's intense enough to be off-putting to a lot of potential tutorial designers.

For the time being I've managed to get the other solution working, and it's simple and does the job in a really concise way.  There's only but so complex the formatting is intended to be, anyway.

I could see expanding this at some point to include an alternative syntax for more power if it's for some reason ever needed, and a flag on the nodes just says which format to use -- simple or robust.  But for now, KISS is definitely my principle. 

[Asteroid]

That's very cool, but without IDE colorization and with it not being a format that I'm naturally already familiar with, my eyes kind of glaze over when looking at it. I think it's intense enough to be off-putting to a lot of potential tutorial designers.

Well... you don't have to use the advanced syntax if you don't want to, and the base syntax does exactly what you described above with properties within properties. Syntax coloration is just one click away with a Visual Studio or VS Code plugin, I can't exactly show off the color in forums can I.

My feeling is that you're reinventing the wheel and that once you get annoyed enough with whitespace (a problem whenever a variable can be empty, it really messes up the tooltips in-game) you'll want a more complex solution. So I suggest you try to be compatible with the basic syntax of Handlebars.NET or other template engine so you can seamlessly switch implementation if you decide to.

Searching google for "logic-less c# template engines" yields some other interesting solutions, for instance https://github.com/lunet-io/scriban which is a port of the Liquid template engine. I haven't tested but they seem to have claims of performance and interesting controls to deal with whitespace too: https://github.com/lunet-io/scriban/blob/master/doc/language.md#14-whitespace-control

[x4000]

I think you're vastly overestimating the sort of text manipulation that I intend here. Generally speaking we need to insert a planet name or a player name or something, or a ship name, and it's related to a specific condition.  The number of condition types are actually shockingly few in order to allow for a huge number of things the game can do.

Given there's no scripting in this, just sets of conditions and triggers to pre-fabricated actions as needed in a few rare cases (spawn a wave is one of the few ones, or spawn new ships on a certain planet), the actual framework is a lot more concise than you might think.  So very many things fall under just a few categories that can be reused again and again that you can make really complex scenarios with lots of complex goals without having more than a dozen or two condition types.

And most of the text is hardcoded, because it's flavor and explanation text, aside from some things that are pulling the name of a ship or planet or whatever.  There's no need for whitespace management, because if you have something returning an empty string that means your tutorial is at least a little bit busted and needs to be fixed.

It's not really reinventing the wheel, it's using a different wheel someone else created that just does something more basic.  I only need to be able to call properties on one level of object, not on sub-objects, and I don't have any interest in arbitrary code execution abilities.

I basically needed a gas powered lawnmower, not a supercar turbo...thing.  I'm not a car guy.