I want to change this because when using a function it's more clear what's the input and what's the output of the computation.
My notion is: If the script wants some data from the engine it calls a function in Engine. If the script wants to send some data to the engine it should use yield or return.
All map generation scripts should reman working.
If there is a Engine.ExportMap(map) at the end of the script that can be replaced by:
function* GenerateMap() // note the asterisk { return map; }
Alternatively if you use rmgen and there is a g_Map.ExportMap() at the end of the script that can be replaced by:
function* GenerateMap() // note the asterisk { return g_Map; }
🎉 You are using the generator interface.
The generator runs after the global code finishes.
If Engine.ExportMap was called in the global code, GenerateMap isn't called. (To remain compatible)
You can move the remaining code inside the generator. You don't have to move all the code. (It might be more familiar to call Engine.LoadLibrary outside.)
g_Map has to stay a global. You might use global.g_Map.
All globals (g_Terrains, g_MapSettings, ...) are accessible from within the generator.
Calls like Engine.SetProgress(50); can be replaced by yield 50;.
The first (only) argument to the generator refers to the same object as g_MapSettings. You could replace g_MapSettings.
The values/properties g_MapSettings, Engine.SetProgress and Engine.ExportMap could be removed in a future version of 0 A.D., which would make the C++ side simpler.
In C++ i introduced a function-template RunGenerator which calls the generator and repeatetly calls next or throw on it. RunGenerator has a simmilar interface to ScriptFunction::Call. With the addition of expecting a callback function. The callback function is then repeatetly invoked with the yielded value.
Maybe RunGenerator is usefull to other parts of the engine. Note that infinite generators and calling next with a value (it's possible but not implemented) isn't possible with this design.
TODO:
Use errors which are instanceof Error.(made it)g_MapSettings, Engine.SetProgress and Engine.ExportMap should be removed before the generator is called. So they are not useable inside the generator.(that would be to hand to adopt to)
Refs: #4964