How does "include" in .lua work?

[Serp]

When I use include("modLUA"), where does the file look for this modLUA ?
I think you can include all files, which are in the same mod?
Is it possible to include a file which is in another mod?

and:
if I include a .lua in which I call several Events directly. Will they be called twice ? One time in the included lua and one time in the lua which includes?


The problem is the following (not really important to read, would be enough if you can answer my main questions ):
In my modpack I use the "fortress borders" mod and the "Units - Colonists and Pioneers" mod. I improved the fortress borders mod a bit.
What I want to do now is: Before cities, founded by pioneers, gets their additional tiles, remove tile ownership from the forts near to that city.
-> I have to link these too mods. The easiest thing to do is to include the ColonistsLUA.lua in the "fortress borders" lua and call the Colonists function after the "fortress border" functions are done.

 

[DarkScythe]

I kind of explained it a bit in this post here although for a different purpose.

Basically, include() is a Firaxis-supplied file inclusion method which looks through files included into its VFS via Lua's string.find() method.

When a file is called via include() the game tries to find a close match adhering to the rules of string.find() and then basically writes the contents of that file into the current file's context, though it won't be able to read locals since it is akin to being in its own do end block.

So, to answer you questions, yes you can include all files (though whether this is a good idea depends on what exactly you are trying to include,) and yes you can include files from other mods, as they are also loaded into VFS.

I don't know why you would duplicate Event calls like that, but I believe it will run through all the code in both 'files' and thus run the events in duplicate.

I have no idea nor experience with either of those mods you listed, so I cannot provide more specific help there, sorry.

 

[Serp]

Thanks for your answer

Where can I read the rules for string.find() ?

Because at the moment it seems like I'm not able to include a file from another mod...
On the top of fortress script I write include("ColonistsLUA").
And in a function of the fortress script, I try to call a function from ColonistsLUA. I also tried a global variable.. (to be sure: a global variable is defined by simply write "abc =3" somewhere in a script, right? )
In both cases I get the error message "attempt to call global 'abcfunction' (a nil value)"

 

[DarkScythe]

You can find more information about it on this writeup in 'Programming in Lua' although more technical specifications can be found in the Lua manual.

Yes, a global variable in Lua is defined as simply 'abc = 3' without the local designation.

As far as why your include won't work, there are two primary reasons (potentially.)

First, recall that I said the game, when executing include(), will check the game's VFS for files to include. If your mod does not provide such a file, then it relies on that particular file already existing in VFS from somewhere else.

In this case, this means it would be an issue of mod loading order -- if your mod loads before the mod which provides / adds ColonistsLUA into the VFS, then your Lua would absolutely not find anything. This can be remedied by setting your mod to reference or require that particular mod, thus forcing the game to delay loading your mod until its dependent mods have loaded first. This would ensure that the ColonistsLUA file you depend on already exists in the VFS.

However, here you will potentially run into a second problem, such that even if you do the recommendation above, it still might not work.

Typically, any Lua file which we want to include() from within other Lua files / contexts must be imported into VFS.

However, our "main" or primary Lua file which handles this logic is not included into VFS, but rather, is set as an entry point from within ModBuddy. I assume it is designed this way so that the Lua can be set up in its own context.

In this case, if ColonistsLUA is the main Lua file of that particular mod, then include() might not be able to see it regardless, because it wouldn't exist in the VFS.

That said, I've never tried including other primary scripts, so it could still potentially work, but I would assume it shouldn't.

Even if it does, you will effectively duplicate all functions in the original script, because everything will run when it first loads, then will run again when you include it into your own mod.

 

[Serp]

You can find more information about it on this writeup in 'Programming in Lua' although more technical specifications can be found in the Lua manual.

Yes, a global variable in Lua is defined as simply 'abc = 3' without the local designation.

As far as why your include won't work, there are two primary reasons (potentially.)

First, recall that I said the game, when executing include(), will check the game's VFS for files to include. If your mod does not provide such a file, then it relies on that particular file already existing in VFS from somewhere else.

In this case, this means it would be an issue of mod loading order -- if your mod loads before the mod which provides / adds ColonistsLUA into the VFS, then your Lua would absolutely not find anything. This can be remedied by setting your mod to reference or require that particular mod, thus forcing the game to delay loading your mod until its dependent mods have loaded first. This would ensure that the ColonistsLUA file you depend on already exists in the VFS.

However, here you will potentially run into a second problem, such that even if you do the recommendation above, it still might not work.

Typically, any Lua file which we want to include() from within other Lua files / contexts must be imported into VFS.

However, our "main" or primary Lua file which handles this logic is not included into VFS, but rather, is set as an entry point from within ModBuddy. I assume it is designed this way so that the Lua can be set up in its own context.

In this case, if ColonistsLUA is the main Lua file of that particular mod, then include() might not be able to see it regardless, because it wouldn't exist in the VFS.

That said, I've never tried including other primary scripts, so it could still potentially work, but I would assume it shouldn't.

Even if it does, you will effectively duplicate all functions in the original script, because everything will run when it first loads, then will run again when you include it into your own mod.

Thank you for this detailed explanation!

In addition to the problems you described comes the problem of MPMPM. I don't know for sure, how the loading order of this DLC version is.

So I have to incorporate all ColonistLUA functions into the fortress borders mod.