Targeting bones

[Garanas]

Description

A unit blueprint can have the field AI.TargetBones. The field is a table of strings, referencing bones that can be used by weapons to aim at when they want to fire at the unit. If the field is not set, the aiming point is determined by taking the position of the root bone + 0.5 * SizeY, which is again a field in a unit blueprint. The value SizeY is used in combination with SizeX, SizeZ and CollisionOffsetX, CollisionOffsetY and CollisionOffetZ to determine the collision box of a unit. The root bone of a unit is (usually) the bone that matches the name of the unit. Note that the aim location is solely defined by taking the root bone and 0.5 * SizeY, all the other values are not taken into account.

Mesh extents (red), collision box (blue) and bone hierarchy (white lines with gizmo's) of a T3 UEF Power plant

The behavior can be reproduced easiest with beam weapons and temporarily making a unit (with no targeting bones) ignore all collisions (via unit.DisallowCollisions . After that, changes to the SizeY field if the unit has no targeting bones, or adding / removing targeting bones and then reloading the blueprint (using /EnableDiskwatch as a program argument`) are picked up immediately.

The current use of targeting bones can be inconsistent, and damaging at best. As a few examples:

    -- DRLK001, Cybran 'Bouncer' T3 MAA
    AI = {
        TargetBones = {
            'Turret01',
            'DRLK001',
        },
    },

One of the targeting bones of the bouncer is DRLK001, which is slightly below the surface. Any weapon that aims for this particular bone has a significant disadvantage in comparison to aiming for Turret01, as the latter is just above the center of the unit. As a consequence, in particular beam weapons will have a lot of trouble aiming for this particular unit half the time.

Mesh extents (red), collision box (blue) and bone hierarchy (white lines with gizmo's) and the chosen target bones (highlighted with yellow) of the Tech 3 Bouncer

List of useful hotkeys:

• Alt + V: Show bones
• Alt + B: Show bone names
• Alt + Ctrl + Shift + c: Show collision boxes

Course of action

Our aim is to fix the targeting bones. There are three approaches that we can take. We'll describe each one, where the first is preferred over the second, and the second preferred over the third.

1. Use existing bones

This is the most viable option for the average mobile unit. Mobile units have a lot of bones that can be used. We prefer bones that:

• Do not translate (move), rotation is fine as that doesn't influence the aiming process.
• Are well within the collision box (at least 20% of the unit speed in distance, vital for beam weapons to function properly)
• Are close to the center in terms of the x/z plane
• Are above the center in terms of the y-axis

Note that these conditions naturally reduce the number of (reasonable) target bones to 1 or 2 - that is fine. It is visually almost impossible to identify the average unit with more than two target bones (looks at the command units), unless you specifically pay attention to it very closely and forget about the fact that you're playing a game.

On average, the larger the unit the more target bones are valid. As an example, I can imagine a naval factory to have three targeting bones spread out of the longest axis of the structure.

2. No targeting bones

This is a viable option for the average unit. In particular, the average air unit can get away with this. When no targeting bones are defined the location to aim at is defined as described before: the center of the collision box without taking into account any offsets.

3. No targeting bones + offset the collision box

This is a bit of a hack and it only works on structures that are not amphibious. Do not use this approach for anything else as we'll be extending the collision box into the negative y-axis (into the ground). The idea is that if we increase the vertical size (using SizeY) but then also move the collision box down (using CollisionOffsetY) then we can leave the effective collision box the same (the portion above the ground), while allowing weapons to aim higher (because they do not take into account the offset when computing the center of the collision box).

This is useful for units where approach 2 is not sufficient - as an example, tech 1 power generators and other structures that are quite close to the surface can make use of this technique if they lack the bones to increase the height of where units (and in particular: beam weapons) aim at.

4. Add new target bones to the mesh

This is a last effort and should only be applied when all the other approaches give insufficient results. It is likely only to be used on large, non-square like units such as the average tech 3 battleship and the like. But even then it is important to first check if the other approaches work out fine. The new bones should be evenly spread out of the unit, usually two or three new targeting bones work. Make sure that all the criteria in the test plan and all the criteria of approach 1 are taken into account when you approach this.

It is vital that the new mesh doesn't contain the mesh, but just bone adjustments. This is a bit tricky. Therefore, If you find a unit that requires this, it is best to flag it and discuss it in this issue. Once flagged, it is best to leave it alone and let someone else do it as it isn't a trivial procedure. In particular, it can only be done using the exporter for 3ds max, the one used for Blender fails.

Test plan

For each unit that you tackle, make sure that:

• The target bone in question is near the center of the unit - target bones that are near the edge can cause beam weapons to miss if they end up targeting that bone
• A group of mantis can hit the unit in question, all projectiles should hit by default
• A seraphim destroyer can hit the unit in question when the destroyer is in the water, near the shore of the beach position on the map Seton's Clutch, similar to the image attached. By all means, this only makes sense if the unit is high enough to be able to be damaged by the destroyer. A fabricator, as one example, is likely too low due to the beam having no arc at all.

On top of that, if you're working with air units then also make sure that:

• A lighting tank should at all moments hit the air unit, regardless of what target bone it picks

And last, if the unit you're working on a naval unit then also make sure that:

• Both submarines and surface units can hit the unit accordingly.

Other issues with units

While working on units this closely, do also note down other potential issues that you find with them. An example is the collision box not properly representing the mesh, or the wrong hover effects on the tech 2 Seraphim hover tank as fixed by #4083 . If it is a small issue, feel free to fix it while you're at it. Just make sure to note the changes accordingly.

Learning goals

Feeling more comfortable working with the repository and learn how to collaboratively work together on a larger issue.

Progress

Claim the group of units that you intend to work on before you start. That prevents duplicated work.

To make it easier to review, stick to one pull request per faction, per layer per tech. As an example, if you do all the targeting bones of the land units of the Cybran faction, you'll have four pull requests: one for tech 1 Cybran land units, tech 2 Cybran land units, tech 3 Cybran land units and last one for the Cybran Experimentals.

Mention this issue in your pull request, that makes it easier to see what has already been done.

• Cybran faction
• • Land units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Air units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Naval units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Structures
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• UEF faction
• • Land units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Air units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Naval units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Structures
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• Aeon faction
• • Land units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Air units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Naval units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Structures
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• Seraphim faction
• • Land units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Air units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Naval units
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4
• • Structures
• • • Tech 1
• • • Tech 2
• • • Tech 3
• • • Tech 4

[Hdt80bro]

I'll check all the UEF AI bones

[Garanas]

👍 , I'm going to finalize the description in a bit!

[MrRowey]

Was going to look at the Aeon Stuff waiting for description to be finalised :) + list of any that are already done

[Garanas]

@Hdt80bro / @MrRowey Go for it 👍.

The shields (via #4063) and transports (via #4058) have already been tackled. Everything else requires a look.

[Garanas]

Oh, and feel free to remove meshes that purely add additional target bones if it is viable to achieve a similar result with one of the other approaches.

[Garanas]

Adjusted the progress section - approach it by faction, type and then tech for each separate pull request. With that, one pull request should contain between 1 to about 10 units each.

[Garanas]

And to simplify the reviewing process - make sure to add mp4s of the result. You can easily do this using Screen to Gif, but then instead of a gif make it a mp4 (the software supports that too).

[Garanas]

Dips on all the Seraphim related changes.

[Garanas]

While working on #4082 I noticed that sometimes the collision box does not update after saving the blueprint and spawning in a new unit. Best to restart the map every now and then to make sure what you're seeing reflects reality.