The New Customizable Autoconf System


Here’s how the magic works. The cockpit is a Control Unit, capable of “combining” elements together using a simple scripting language known commonly as Lua. This script has the ability to detect key presses by the player, then act accordingly. All actions that occur on your ship, including widgets, are initiated by a set of automatically generated Lua scripts. This is what we call « autoconfigure », or “Autoconf”.

What’s great about these Lua scripts is that they allow you to modify and customize at will. Up until now, the autoconf provided the same level of control for any flying construct. If you had scripted a particular set of actions or behavior for your ship through previous trial and error, you were required to manually apply it to each and every new construct. Needless to say, copy/pasting the same script multiple times is pretty tedious work.. There was no recipe in place to customize the behavior of the auto-configurator to produce custom-made configurations.

On Thursday, September 20th, we will be introducing in the new r0.12 version a new customizable autoconf system! It will be able to apply different autoconf configurations, called “schemas”, to varying types of cockpits. You will also be able to apply your own autoconf schemas to any ship of your choice via a simple contextual menu. In short, that means the super mouse-controlled, dynamic flying system that you’ve created can be duplicated and exchanged with friends with ease!

 

Structure of an AutoConf Schema

If you go into the data/lua folder in your game install path, you will find an autoconf directory with two subdirectories: default and custom. In the ‘default’ subdirectory, you will find the standard autoconf schemas that are used by the game. Do not edit these files. It may cause your constructs to no longer autoconfigure. In the custom subdirectory, you can place your own schemas by creating a copy of the given sample.conf file and renaming it.

This schema conf file is a yaml file containing three sections: the ‘name’ of the schema as it will appear in the contextual menu in the game, the ‘slots’ section, and the ‘handles’ sections.

 

Slots

The first thing autoconf does is link everything that must be linked to the Control Unit. Typically, this includes the fuel tanks, gyro, antigrav, and core unit. If you want to interact with an element via Lua, or simply display its widget, it needs to be linked first.

Linked elements will then appear inside a “slot” when you open the Lua editor. This slot will be given a name so that you can reference the plugged element in your script.

The “slots” section of the autoconf schema describes what to link and how. Here is an example:

slots:
	core:
    		class: CoreUnit
	antigrav:
    		class: AntiGravityGeneratorUnit
	container:
    		class: FuelContainer
    		select: all
	gyro:
    		class: GyroUnit

Each slot is listed by its name and associated with a class element that must be linked into said slot. In a future version, to know the class of a given element, you'll simply have to click it in the inventory and check its class descriptor on the info panel.

By default, autoconf will then find the first element of the given class and plug it into a free slot which will be named accordingly. If it does not find any element of that class in your construct, it will simply skip and move to the next slot linking descriptor. You can later test in Lua whether the slot has been created or not (with a syntax like “if myslot ~= nil then … end”). This means you can be fairly generous in your linking plan, allowing for a myriad of optional elements that may or may not be available in your ship, then dealing with said availability later in the Lua code.

Optionally, you can add a ‘select’ field with the value ‘all’ to specify that you want to plug all the elements of that class. The corresponding slots will be named with the given slot name, suffixed by an underscore and an index number. In regard to the above example with the ‘container’ slot, that would be container_1, container_2, etc.

When accessing these slots programmatically, you can use the slot name when it’s a unique slot, and use a convenience array named after the slot name when ‘select:all’ is used to plug several elements. In the above example, this would look like container[1], container[2], etc. The total number of such numbered slots is given by the variable ‘container_size’.

Please keep in mind that each Control Unit has a limited number of available slots at this time (that will later depend on the Control Unit level, specs, etc). If too many elements are plugged from the “slots” section, the autoconf will stop adding additional slots.

 

Handlers

The last section of the autoconf schema is the “handlers” section which describes event handlers. This is where the Lua scripting that you want to automatically install should be placed. This acts as a programmable Lua Editor window. It enables use of the slot names to refer to automatically plugged elements or slot arrays when using ‘select:all’.

This section describes which event is being caught for each slot, optionally what arguments to use, and what LUA code to run when the event is being triggered. Here is an extract taken from the sample.conf file:

system:
    	flush:
        	lua: |
                    local forward =  Nav:composeForwardAcceleration(
                                Nav.thrustManager:getAccelerationCommand())
                    local angularAcceleration = Nav:composeControlledStabAngularAcceleration(
                                Nav:getRollInput(), Nav:getPitchInput())
                            + Nav:composeTiltingAngularAcceleration()
                            + Nav:composeTurningAngularAcceleration(Nav:getYawInput())
                    Nav:setEngineCommand('vertical,torque', 
                            Nav:composeLiftUpAcceleration(Nav:getLiftInput()), 
                                angularAcceleration)
                    Nav:setEngineCommand('horizontal', forward, nullvector)
                    Nav:setEngineCommand('brake',
                            Nav:composeBrakingAcceleration(Nav:getBrakeInput()), nullvector)
                    Nav:setBoosterCommand('booster')

    	update:
        	lua: Nav:update()

    	actionStart:
        	args: [forward]
        	lua: Nav:decrease(Nav.pitch)

This above example describes event handlers for the “system” slot. For event handlers that correspond to events without arguments, merely describe the Lua code to be used after the “lua:” section. The “lua: |” syntax can be used to indicate that you want to use everything below, verbatim (see for example this tutorial on yaml syntax to know more: https://en.wikipedia.org/wiki/YAML#Syntax).

Do not put empty lines in your Lua code when using the “lua: |” trick. Yaml will treat this as the end of the verbatim section and resume parsing yaml instead of adding the rest of your Lua code.

If your event handler contains arguments, they can be declared with the optional “args” field followed by a yaml list of values. In the example above, we use this to declare an event handler for catching the ‘actionStart’ event, with a given ‘forward’ key descriptor as the argument. Using ‘*’ in the list of arguments means “catch all”, just like in the Lua Editor.

And that’s it! That’s all the new autoconf system needs to be able to do its job. We recommend that you look carefully at the sample.conf to learn what can be done in a schema (for example, the conditional show/hide of widgets, etc).

 

How to use a Custom Schema?

Right click on a Control Unit and select your schema in the list that will appear (as explained sooner, each schema being identified by its name, as given in the .conf file). The list is constructed upon the file extension, so keep the .conf extension to ensure that your schema is visible.

For example, if you step inside a blank Control Unit activating a cockpit, autoconf will attempt to decipher what manner of cockpit it is and automatically choose an autoconf schema among the default ones that we’ve provided. If you want to use your own schemas, you will always need to select them by hand.

 

Sharing Autoconf Schemas

Autoconf schemas can be found in the “custom” subdirectory of data/lua/autoconf. If you want to share your schemas at this time, you will need to send the corresponding files and let your friends copy them in the right place. Depending on the popularity of this feature, we may implement an in-game schema browser in the future which will allow you to upload schemas for the purpose of sharing/trading. The possibilities are huge and it’s our version of “modding” for Dual Universe, if we can put it that way.

We hope you’ll enjoy this new feature, and as usual, don’t hesitate to share your feedback with us!