Updating the wiki mission scripting tutorial

sturnclaw
Posts: 79
Joined: Tue Sep 18, 2018 12:20 am

Re: Updating the wiki mission scripting tutorial

Post by 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
Posts: 30
Joined: Mon Sep 20, 2021 3:18 pm

Re: Updating the wiki mission scripting tutorial

Post by zonkmachine »

Thanks for the answer!
sturnclaw wrote: Thu Nov 11, 2021 11:22 pm 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.
sturnclaw wrote: Thu Nov 11, 2021 11:22 pm 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.
sturnclaw wrote: Thu Nov 11, 2021 11:22 pm 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
Posts: 30
Joined: Mon Sep 20, 2021 3:18 pm

Re: Updating the wiki mission scripting tutorial

Post by 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
Posts: 79
Joined: Tue Sep 18, 2018 12:20 am

Re: Updating the wiki mission scripting tutorial

Post by sturnclaw »

zonkmachine wrote: Wed Nov 17, 2021 4:18 pm 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
Posts: 30
Joined: Mon Sep 20, 2021 3:18 pm

Re: Updating the wiki mission scripting tutorial

Post by zonkmachine »

sturnclaw wrote: Fri Nov 26, 2021 10:01 pm 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
Posts: 30
Joined: Mon Sep 20, 2021 3:18 pm

Re: Updating the wiki mission scripting tutorial

Post by zonkmachine »

zonkmachine wrote: Tue Nov 30, 2021 7:11 pm 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
Posts: 30
Joined: Mon Sep 20, 2021 3:18 pm

Re: Updating the wiki mission scripting tutorial

Post by zonkmachine »

sturnclaw wrote: Fri Nov 26, 2021 10:01 pm 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
sturnclaw wrote: Fri Nov 26, 2021 10:01 pm 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
Posts: 79
Joined: Tue Sep 18, 2018 12:20 am

Re: Updating the wiki mission scripting tutorial

Post by 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
Posts: 30
Joined: Mon Sep 20, 2021 3:18 pm

Re: Updating the wiki mission scripting tutorial

Post by 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
Posts: 30
Joined: Mon Sep 20, 2021 3:18 pm

Re: Updating the wiki mission scripting tutorial

Post by zonkmachine »

sturnclaw wrote: Mon Jan 23, 2023 8:21 am 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...
Post Reply