Execution Model

[LilBudyWizer]

For lack of a better term. Who knows what I would know if I knew what I don't know. I recently started my first mod. I had lots of problems figuring out the basics of what does what and what do I really need. Once I got ModInfo worked out I found I got error messages if there were syntax errors in the file but not for semantic errors. I was just trying to do a

console.log("Hello World!");

I thought maybe log isn't supported so I tried info, warn, error, nothing produced a message. I tried adding a call to thisIsATest() just to generate an error and still nothing. I tried throwing errors, still nothing. I just wasn't running. I finally tracked it down to my imports. The mod was dealing with options so I have the following imports:

import '/core/ui/options/options.js';
import { Options, OptionType } from '/core/ui/options/model-options.js';
import { CategoryType }   from '/core/ui/options/options-helpers.js';
import { ScreenOptions }  from '/core/ui/options/screen-options.js';

That's what I have now and that works. It wasn't what I had and what I had didn't work. What I was using for reference initially didn't show import filename as a valid syntax so I eliminated that one. It was sort of down the rabbit hole and trying lots of things out of desperation so I'm not sure exact order I did things. That seemed to actually be what gets my code to execute. I switched to using MDN for documentation which seems a great deal more thorough and authoritative. It says that format executes the script. My code seems to execute when you click the options button on the main menu. It uses the context manager to push the "screen-option" panel. I haven't traced back to how main-menu gets executed because it's deeper down the rabbit hole than I need to go. I imagine at some point the engine calls a script that gets the whole ball rolling.

ScreenOptions is the actual panel. It has, for lack of a better term, raw imports of options.js and screen-options-category.js. The screen-options-categories.js script is a worker that creates the tabs, scrollable lists of controls and headers within those lists. The options.js script has no actual exports. It just uses Options defined in model-options.js. The model-options.js script instantiates OptionsModel as Options as a const which I assume makes it a singleton. The screen-options.js script has

Controls.define('screen-options', {
    createInstance: ScreenOptions,
    description: 'Screen for adjusting game options.',
    styles: ['fs://game/core/ui/options/screen-options.css'],
});

That seems a common thing. I didn't chase it down the rabbit hole but I assume that's what causes it to end up in the ContextManager. It isn't clear to me how that got executed to add it to the ContextManager. The main menu doesn't do a raw import on it, it seems to depend upon it already being there. I also don't understand how model-options.js got executed since nothing does a raw import on it. As near as I can tell a raw import doesn't actually execute the code. One thought, which makes sense, is that a raw import triggers an immediate execution while a normal import is a deferred execution. So before a script can actually execute all its imports have to execute. The imports would be rather useless if they don't actually execute. It seems that would have to be a single execution so that initialization code doesn't execute repeatedly.

The real question to me is how did my code get executed? Obviously it loaded my script because of ModInfo, but nothing in ModInfo says when to execute it. When it's read seems the obvious answer. It runs once everything it imports directly or indirectly executes. That doesn't explain why it executes every time the options panel is opened. It very clearly runs every time the options panel opens. I have a switch that's not backed by a store. While the options panel is open it retains its state. If I close and reopen the panel it reverts to the default state. That is as intended, but it shows the code is executing every time the panel opens. As near as I can tell it does not execute otherwise.

On a practical basis it was that raw import that made it run. Without that it didn't run. So is that chaining my script to that script? Every time options.js runs then my script runs? Interestingly if I move it down from the first line then my code executes before it. So whatever tab I add an option to becomes the first tab. The option I add to that tab becomes the first option listed.

I would appreciate it anyone could offer some insight or clarity. Even just pointing me to a resource would be appreciated.