Unify autoconf and paste json mechanisms, clean them up, and document them

[samdeane]

TL;DR it would be nice to have all of this rationalised, cleaned and documented.

---

The differences between these two mechanisms are a little bit odd, and feel anachronistic.

You can't apply autoconf files to keyboard controllers, which doesn't make a great deal of sense, as the auto-linking mechanism is potentially useful.

Similarly, you can't (as far as I know) get auto-linking with the JSON format although in theory I can see no reason why it couldn't be added.

The

"type": {
                "methods": [],
                "events": []
            }

section of the JSON is either an un-used legacy of an earlier age, or perhaps an undocumented feature that could still be useful?

The slot naming and element linking support in JSON is not very useful, based as it is on slot position rather than element class.

Meanwhile there are some potentially useful features of either/both mechanisms that are missing:

• being able to suppress the generation of the _autoconf table but keep the linking
• being able to specify event handlers to apply to all elements of a given class where select: all is set, rather than having to enumerate them as _1, _2, etc (maybe this is possible? I haven't figured out the syntax yet if so)

Overall, it's a bit of a mess, which would be nice to have cleaned up.

[matpratta]

I don't think there's much documentation left about how autoconf works, most of the implementation I did on my CLI for DU involved looking at how public scripts did it and trying to adapt. That said, I think autoconf could be way smarter and maybe even use Lua for that.

For example, let's say instead of a conf file you wrote a small configuration script:

-- Gets a list of fuel tanks
local fuel_tanks = autoconf.getElementsByClass('FuelTank')

-- Links each of the fuel tanks with the name prefixed by "fuel_" and the incrementing number of that tank
for idx, fuel_tank in pairs(fuel_tanks) do
  autoconf.linkTo(fuel_tank, 'fuel_' .. idx)
end

Very simple to write, easy to read and understand how it works, plus adds a ton of flexibility too. Sure the example is really simple and won't show the whole power of the thing, but imagine you could use that Lua to not only query elements and link them, but actually insert the Lua code into each of the filters, etc. It becomes powerful really quickly. Plus it would be a single-run script, so lots of things could (and should) be disabled, like coroutines or maybe even access to library, system, etc.

[samdeane]

I’ve actually sort of written that code - it turns out that all linked elements are available in the global environment if you know how to decode their names. It would be great to have it properly supported though.

[samdeane]

being able to dynamically link things in Lua of course would be even better - but I can’t see that happening sadly (dare I say, it would be too useful!)

[NQ-Ligo]

On the backend, it is much more complex than it seems.

Also, dynamic linking is very problematic, because it means that the Lua decides to make the links, not the player. And also, it could be a nightmare on performance or server synchronization when players want to manage or monitor tons of elements, industries, containers...etc....

[matpratta]

@NQ-Ligo what I would suggest is replacing the XXX.conf files and syntax with XXX.autoconf.lua or something like that. In a nutshell, it would be a special Lua script that only executes once, in the moment the player runs the autoconfig from the UI, and has access to linking/querying the construct elements. It would work very similarly to how XXX.conf works today, but would use Lua syntax instead, which makes it much easier to understand and document, plus opens more possibilities regarding autoconfig files :)

I can understand not allowing dynamic linking at runtime though, it makes sense to have that limitation in place, we just need a better way to handle script installation, since there's a lot of differences between the JSON/YAML and CONF files, plus they don't seem to be very well documented anywhere.

[samdeane]

Yes, lua would make perfect sense, as would introducing some build-only API which the lua can access only whilst running autoconf.

This system could potentially form the first seeds of a more complete set of build-time lua APIs that would allow us to add other build tools (maybe even add build-time UI to assist with complex build tasks).