Updating the wiki mission scripting tutorial

[sturnclaw]

zonkmachine: regarding the ECM crashes / zero stock, that happens when you're attempting to get station stock from a station that hasn't been initialized yet. As part of an optimization for savefile size, station inventories/stocks (and more importantly BBS missions) are not actually generated until you land on them. That's an area I'd like to do some further work towards maybe restoring pre-generated station stocks, but for the time being only stations the player has actually visited during their time in-system have valid stock values.

The lua context has these tables/functions deliberately removed:
- io table
- os table
- package table (all of it's normal contents are removed, but some Pioneer-specific API takes its place)
- dofile() function
- loadfile() function
- load() function
- loadstring() function
- math.random() function
- math.randomseed() function

These additional functions are provided:
- logWarning (print(), but writes to the warning loglevel instead)
- math.deg2rad
- math.rad2deg
- package.core table (contains all "core" imports shadowed by Lua extension files, e.g. core["SpaceStation"] is shadowed by data/libs/SpaceStation.lua)
- package.reimport() function (reload the current module from disk, used for debug)
- package.thisModule() function (used in conjunction with package.reimport)

The game clock starts immediately as soon as the game is initialized and just before execution flow is returned back to Lua context, and stops just after execution flow leaves the Lua context and C++ code takes over and starts tearing down the game instance. It advances on a per-frame (per simulation update) basis.

[zonkmachine]

Thanks for the answer!

zonkmachine: regarding the ECM crashes / zero stock, that happens when you're attempting to get station stock from a station that hasn't been initialized yet. As part of an optimization for savefile size, station inventories/stocks (and more importantly BBS missions) are not actually generated until you land on them. That's an area I'd like to do some further work towards maybe restoring pre-generated station stocks, but for the time being only stations the player has actually visited during their time in-system have valid stock values.

Right, I suspected something like that.

The lua context has these tables/functions deliberately removed:
- io table
- os table
...
- package.reimport() function (reload the current module from disk, used for debug)
- package.thisModule() function (used in conjunction with package.reimport)

Thanks! This helped me search further and I found this, or much of it, is done in src/lua/core/Sandbox.cpp.

The game clock starts immediately as soon as the game is initialized and just before execution flow is returned back to Lua context, and stops just after execution flow leaves the Lua context and C++ code takes over and starts tearing down the game instance. It advances on a per-frame (per simulation update) basis.

The game clock start/stop was just an example. I still want a wiki page that goes through this in more detail. I could copy and past some of it from here but I don't think I would do a good job at it.

[zonkmachine]

The last of the chapters I set out to fix up, https://pioneerwiki.com/wiki/Surviving_a_reload, is basically done and I've removed the 'Outdated' banner. It still needs fact checking, especially considering the topic is 'surviving a reload' and it's abundantly clear in PR 5306 that I don't completely grasp that part of the code. Apart from fact checking it also needs a completing example that actually registers a mission.

[sturnclaw]

The last of the chapters I set out to fix up, https://pioneerwiki.com/wiki/Surviving_a_reload, is basically done and I've removed the 'Outdated' banner. It still needs fact checking, especially considering the topic is 'surviving a reload' and it's abundantly clear in PR 5306 that I don't completely grasp that part of the code. Apart from fact checking it also needs a completing example that actually registers a mission.

zonkmachine, looking good!

There's one thing I would like to see in that tutorial (and it's a bit more of an advanced topic that the existing mission modules don't make good use of) - the Tracking Adverts section should ideally mention that the flavor table reference is fine to store during runtime, but that the actual strings (e.g. Hello, Click here..., and other flavor data) are static and should not be serialized - instead the flavor index should be saved to disk. Similarly, the serialization section shouldn't be saving ad.bodytext and other related strings as part of the saved data, instead it should store an index into a flavors table and "reconstitute" the ad from the saved data + the flavor data. This is something that might be better handled in an "advanced" section building on the previous, as it involves some transformations of the serialized data and some changes in the setup. Unfortunately there aren't many modules to pull from as reference for this behavior, but it is the correct way to handle strings like this and plays much nicer with the player changing UI languages during a savefile.

Also, (I just checked) - there is no Translate module or a GetFlavours call; because the nomenclature of each module's flavors tends to be rather different, testing for the number of related text strings is generally reimplemented in each module (admittedly not ideal). I'd recommend a comment line describing the intent of getting the number of flavors rather than writing the whole thing out in actual code.

[zonkmachine]

There's one thing I would like to see in that tutorial (and it's a bit more of an advanced topic that the existing mission modules don't make good use of) - the Tracking Adverts section should ideally mention that the flavor table reference is fine to store during runtime, but that the actual strings (e.g. Hello, Click here..., and other flavor data) are static and should not be serialized - instead the flavor index should be saved to disk. Similarly, the serialization section shouldn't be saving ad.bodytext and other related strings as part of the saved data, instead it should store an index into a flavors table and "reconstitute" the ad from the saved data + the flavor data. This is something that might be better handled in an "advanced" section building on the previous, as it involves some transformations of the serialized data and some changes in the setup. Unfortunately there aren't many modules to pull from as reference for this behavior, but it is the correct way to handle strings like this and plays much nicer with the player changing UI languages during a savefile.

Also, (I just checked) - there is no Translate module or a GetFlavours call; because the nomenclature of each module's flavors tends to be rather different, testing for the number of related text strings is generally reimplemented in each module (admittedly not ideal). I'd recommend a comment line describing the intent of getting the number of flavors rather than writing the whole thing out in actual code.

Right. I missed the GetFlavours call but I remember trying, and failing, to wrap my mind around it earlier. I don't know how to fix that example up properly. I would be very happy if someone experienced could finish what's wrong or lacking from the Surviving a reload page.

[zonkmachine]

Right. I missed the GetFlavours call...

The whole https://pioneerwiki.com/wiki/Surviving_ ... ng_adverts part really... I don't know how to update that to the new translation system.

[zonkmachine]

There's one thing I would like to see in that tutorial (and it's a bit more of an advanced topic that the existing mission modules don't make good use of) - the Tracking Adverts section should ideally mention that the flavor table reference is fine to store during runtime, but that the actual strings (e.g. Hello, Click here..., and other flavor data) are static and should not be serialized - instead the flavor index should be saved to disk. Similarly, the serialization section shouldn't be saving ad.bodytext and other related strings as part of the saved data, instead it should store an index into a flavors table and "reconstitute" the ad from the saved data + the flavor data. This is something that might be better handled in an "advanced" section building on the previous, as it involves some transformations of the serialized data and some changes in the setup. Unfortunately there aren't many modules to pull from as reference for this behavior, but it is the correct way to handle strings like this and plays much nicer with the player changing UI languages during a savefile.

Fixed! Added passage on the topic here: https://pioneerwiki.com/wiki/Surviving_ ... ze_strings

Also, (I just checked) - there is no Translate module or a GetFlavours call; because the nomenclature of each module's flavors tends to be rather different, testing for the number of related text strings is generally reimplemented in each module (admittedly not ideal). I'd recommend a comment line describing the intent of getting the number of flavors rather than writing the whole thing out in actual code.

Fixed! The GetFlavours are now gone.

I think the only important thing to cover now is 'mission descriptions'.

[sturnclaw]

zonkmachine: Thanks! I very much appreciate your efforts in maintaining the wiki, and tackling the (nontrivial) task of keeping it up to date with "best practices"!

We're looking at migrating the more technical developer / contributor wiki content to the Workflow section of the Pioneer Developer Docs, so I'd like to ask you to migrate your scripting tutorial there if you have the time in the coming weeks/months. The dev docs are maintained via git workflow, and I'd be happy to provide push access to that repo to active wiki contributors :D

I can only dangle the ease of writing in Markdown rather than wiki syntax, and having proper code highlighting (including inline diff support if you feel inclined to illustrate the line-by-line changes needed to a script file) as the incentive for this task however...

[zonkmachine]

Markdown and code highlighting? I'm on. Hit me with whatever I need to write on there.
Does this include using tools like https://www.rubberduckdev.com/mediawiki-to-md/ or similar or is it manual work?

[zonkmachine]

We're looking at migrating the more technical developer / contributor wiki content to the Workflow section of the Pioneer Developer Docs, so I'd like to ask you to migrate your scripting tutorial there if you have the time in the coming weeks/months. The dev docs are maintained via git workflow, and I'd be happy to provide push access to that repo to active wiki contributors :D

Right, I did look into it but I found it a bit too much to get into at this point. I haven't forgotten about it though. Give it a year or two...