The upcoming "Template System"

[RndName]

So, to clarify some things about the current ongoing rework of the ground object (Sorry this will be a long message but its a huge change):

(The draft documentation which will be extended to a wiki page later can be found here: https://github.com/RndName/dcs_liberation/blob/ground-object-refactoring/doc/templates/templates.md)

The template system

The Template System is a complete rework of the generator-based logic to build theater-ground-objects (Liberation Objects). In the original system the generator was written in python and generated a group with a defined and static logic, written in code. The template sytem will now decouple the alignment / positioning from units and the definition of theire actual type (like Ural-375). The template system allows to define the layout and set which unit types or classes (All logistic units for example) are able to fit into the template. Ultimately this will allow to have generalized templates which can be reused by multiple types of units. Best example is the definition of a SAM layout. Previously we had a generator for every different SAM Site, now we can just reuse the alignemnt (e.g. 6 Launchers in a circle alignment) with more generalization.

What is this rework about?

This rework is mainly a technical retrofit of the underlying code base so in short term there will not be many visible changes but for the long term there will be major benefits of this rework. Why? I will come to this point after explaining what it's all about.

Technical background (aka why would you do this?)

In the current system we use generators (in pyhton written deterministic definition of where which unit should be placed in relation to a center point) which grown over the past to allow randomization and more needs for variation in the looking of the generated units from the generator.
The main problem with this generators is that they couple the general "layout" (aka. the positioning and alignment of units) with the exact definition of which type the unit has to be (e.g. exact definition of Ural-375 and ZSU-23) and that they are written in strict python code.
So whenever some one wanted to create a different looking group you copy pasted the existing generator and changed some variables like Ural-375 to M 818. This got really messy over the time and is not really maintanable any more. (We have like 10 Generators generating the exact looking group with just different units).
Not really user friendly and of course not modder friendly. So most people dont want to dive into the generator hell and optimize things there. You dont believe me? Take a look at this generator over here: https://github.com/dcs-liberation/dcs_liberation/blob/develop/gen/sam/sam_sa10.py

As i started working on the Advanced IADS features and thought about the mod support for the SAM Site Asset Pack i come to the point of reworking this whole system: Create a system which allows to decouple the Unit-definition from the actual positioning / alignment. I called it the "Template System".

How will the template system be realized?

The System mainly breaks down the Generator in two Steps: the template and the UnitGroup (this name is debatable. I was not really creative!). The template defines placeholder positions for units using the dcs mission editor instead of code (no more worrying about x+42 y+1337 and guessing where the unit will be). As we can not store enough information in the .miz and due to the fact that .miz is a binary format which we can not review at all there will also be a yaml file for each template. I will call this the "Template Mapping".
This mapping will allow to define information like Unit1 can be any unit of the class "Logistics" or "AAA" instead of defining the actual unit. But to allow more fine-tuned templates this is also possible. Also this mapping file will give information about how this template can be used. For example you can define that the template can be used for SHORAD AirDefense and AAA.
With this decoupling of unit and acutal positioning we can now "Generalize" all templates we have in the system. For example we use the same layout for SA-10, SA-10B, SA-12, SA-20, SA-20B, SA-23 and even have different versions using just AAA or SHORAD. With the new template system we once define the layout with one .miz and one or two yamls.
For easier things like SHORAD or AAA we can define even more generalized templates (example: https://github.com/RndName/dcs_liberation/blob/ground-object-refactoring/resources/templates/anti_air/Short_Range_Anti_Air.yaml). There can be more of these templates with just a different positioning! Liberation will take care about the rest.
So what is the UnitGroup thing you were talking about? The UnitGroup is the logical connection between a set of units (e.g. Ural-375 + SA-8) which the faction has acces to and the possible templates where the set of units can be used in (See how the SHORAD Template linked has two units with the classes "SHORAD" and "Logistics").
These UnitGroups will be generated automatically based on the available templates and the faction file, so nothing to worry about as user or designer.
The most important thing here is that we can define Roles and Tasks for templates. Units will have classes like SHORAD, SearchRadar, AAA or Logistics and will be matched according to what they are capable of. In different wording: Can a unit of Class XY fulfill the Task ZZZ?. This will all be calculated once during campaign generation.

The overall concept in a picture: Concept

Example of a template mapping file:

name: Short Range Anti Air Group
role: AntiAir
generic: true
tasks:
  - SHORAD
groups:
  - name: SHORAD Group 0
    unit_count:
      - 2
    unit_classes:
      - SHORAD
  - name: SHORAD Group 1
    optional: true
    unit_count:
      - 1
      - 2
    unit_classes:
      - Logistics
template_file: resources/templates/anti_air/shorad.miz

Technically this allows us to seperate the complete logic of how a group should look like and what units it should have. The different parts of liberation just now ask the faction: Can you give me a group with the Task SHORAD or AAA which i can place somewhere. The faction will then select a capable unit from these UnitGroups with the possible templates.
I know UnitGroup is a bad wording here. Think about what Squadrons and Packages are for Aircraft - it comes to a similar idea but different implentation. As i am not with the military i am not quite sure what the right term would be here - hopefully you guys have better ideas :D

And of course: all existing generators and the layout they define is migrated into this new template system by script. So it will not get lost! It can be fine tuned after the technical retrofit is done.

Key Take-Aways:

• Generators in Pyhton will go away
• Templates are made from a .miz file and a .yaml mapping.
• It allows to decouple the actual positioning and alignment and lets us generalize reccuring layouts by defining wich unit class or type can fullfill the task in a yaml file
• Units all have Classes defined in the corresponing unit .yaml file!
• Templates allow to define Role and Tasks so that it can later be matched to the units

This is a major change / rework of some fundamental logic of liberation. Of course there will be documentation about it and a special wiki page explaining how to add / modify templates, which changes where made to factions and many more.
But unfortunately this is really time consuming and its hard to do this between work and the rest of the life so excuse me if this takes some time to be complete.
I'll frequently put raw documentation in this file https://github.com/RndName/dcs_liberation/blob/ground-object-refactoring/doc/templates/templates.md which gets updated reguallary.
Keep in mind this rework and the concept over here is not carved in stone and can (and should) change over time.
You can find a lot of technical things there and a lot will be extended :)

So whenever you have ideas, inputs, thought or whatever feel free to communicate it! This is a living thing and i rely on feedback to build it like you need it.

[RndName]

As it was asked on discord: This template system also will allow campaign designers to precisely define which Template or even UnitGroup should be used at a specific location (Of course only if wanted - the current random approach with placing a unit is still the go-to).
This will allow for example to place a RL SA-2 Site exactly where it would sit IRL with the correct template and orientation :)
Example: https://github.com/RndName/dcs_liberation/blob/ground-object-refactoring/doc/templates/campaign_preset_trigger_zones.png

[ghost]

Get a 404 on the above .png URL. Just sayin.

[RndName]

Yeah you're right thanks. The function got reverted from the initial PR and will come into the game with a separate PR as its a bigger function.

[RndName]

Update: This function already found its way into the develop branch. A lot of stuff changed during the reviews. The latest docs can be found over here: https://github.com/dcs-liberation/dcs_liberation/wiki/Layouts