RotorLib XML Profile Authoring Guide

This guide walks through creating an Arma 3 Advanced Flight Model RotorLib XML profile for a custom helicopter. It is written to match the RotorLib XML Profile Builder workflow and assumes the final XML will be tested in Arma 3 with Advanced Flight Model enabled.

The first XML is not a finished flight model. Treat it as a structured, documented starting point. Every estimated value should be recorded, tested, and replaced when better source data becomes available.

Before entering values, collect these files and references:

1. The target helicopter addon source.
2. The target model, memory points, Geometry LOD, LandContact points, and any proxy gear/wheel geometry.
3. The target vehicle config class.
4. Any existing RotorLibHelicopterProperties / RTDconfig reference.
5. A closest matching BIS or mod RotorLib XML baseline.
6. Real aircraft data, if available: mass, dimensions, rotor diameter, blade count, engine power, RPM, wheel dimensions, and gear layout.

Use the closest proven RotorLib XML as the baseline. Match by:

1. Approximate aircraft mass class.
2. Main rotor count and tail rotor arrangement.
3. Landing contact type: wheels, skids, fixed hull/tail points.
4. Role: light, attack, transport, heavy transport.
5. Similar rotor RPM and engine/transmission layout.

Keep the selected baseline recorded in the tool. Some sections, especially drive trains and control-system conventions, are easier to preserve from a working profile than to recreate from documentation.

RotorLib coordinates use:

All position values must be converted into this coordinate system. Do not assume Arma model-space labels or visual axes match the value names without checking the model and a known working XML.

Useful rules:

1. Positive X moves a point to the aircraft right side.
2. Positive Y moves a point toward the nose.
3. Positive Z moves a point upward.
4. Wheel, skid, tail rotor, rotor hub, and stabilizer positions should be measured relative to the same aircraft reference/datum used by the baseline XML.

If the exact datum is unclear, compare the baseline XML values against visible geometry and memory points. Preserve the same convention when adapting it.

Enter:

Example Arma config pattern:

class RotorLibHelicopterProperties
{
    RTDconfig = "\my_addon\air\RTD_MyHelicopter.xml";
};

Verify the exact placement and property names against a working vanilla helicopter config before packing.

Enter mass in kilograms.

Best sources, in order:

1. Geometry LOD mass from the finished model.
2. Existing addon config/source documentation.
3. Real aircraft maximum takeoff weight or empty weight, depending on what you are modelling first.
4. Closest baseline XML scaled to the new helicopter.

Start with a realistic operating/test mass, not necessarily the absolute maximum load. Later, test loaded and unloaded behavior separately.

Enter approximate dimensions in meters:

These dimensions are used for first-pass inertia and generated contact positions. They are not a substitute for measured contact or rotor stations.

Enter center of gravity offsets in meters:

Where to derive it:

1. Geometry LOD mass center, if available.
2. Model authoring package mass properties.
3. Real aircraft station data.
4. Baseline XML, adjusted only if your model is clearly nose/tail heavy.

For a first symmetric scaffold, keep CG X near zero. Small CG Y and CG Z changes can strongly affect hover trim, pitch, and ground attitude.

Use sourced moments of inertia if available. If not, estimate them temporarily from mass and dimensions:

Ixx = 1/12 * mass * (length^2 + height^2)
Iyy = 1/12 * mass * (width^2 + height^2)
Izz = 1/12 * mass * (width^2 + length^2)

Use Iyz = 0 for a first symmetric scaffold unless you have asymmetric mass data.

These estimates only unblock first flight. If the helicopter rotates too quickly, too slowly, or oscillates, revisit inertia before over-tuning dampers.

Main rotor radius has a large effect because disc area is:

disc_area = pi * radius^2

Do not tune lift primarily by abusing mass or power. First verify radius, blade count, RPM, collective range, and aerodynamic tables.

Measure the main rotor hub in RotorLib coordinates:

Use model memory points, animation axes, or measured geometry. The hub station affects moments because rotor thrust is applied at the hub and resolved into aircraft motion.

Measure or derive:

Tail rotor setup is a common cause of uncontrollable yaw. Verify sign and authority in hover before tuning forward flight.

Enter horsepower references:

Sources:

1. Real engine/aircraft data.
2. Existing addon documentation.
3. Closest baseline XML.
4. Conservative estimate based on aircraft mass class.

If max torque is unavailable, estimate:

torque_Nm = power_hp * 745.699872 / (rpm * 2 * pi / 60)

Use the shaft RPM expected by the engine/controller, not necessarily visible rotor RPM unless the drive train is 1:1.

Drive-train XML is not fully described by the BIS page. Preserve it from the closest working profile unless you have a specific reason to change shaft names, gear ratios, or rotor connections.

RotorLib actuator variables such as MainRotor/theta0, MainRotor/A1, MainRotor/B1, and TailRotor/theta0 are radians in the control system, even when the wizard accepts practical degree ranges.

Tune so the helicopter lifts and hovers at plausible collective for the test mass.

If pitch or roll is reversed, check A1/B1 signs, swash phase, rotor rotation direction, and coordinate conversion before changing unrelated values.

Pedal min/max maps to tail rotor collective. Wrong sign or tail rotor direction usually causes immediate yaw problems.

Test:

1. Low collective yaw response.
2. Hover yaw authority.
3. High collective anti-torque margin.

Ground contacts define how the helicopter stands, rolls, skids, compresses, bounces, steers, brakes, and takes landing damage.

RotorLib examples use FGGroundContact200 contacts. The tool supports three authoring intents:

The XML still exports compatible FGGroundContact200 structure. The contact kind is written into the XML comment so the authoring intent remains visible.

Do not force every aircraft into nose-left-right wheel layout.

Use as many contacts as needed:

1. Wheeled tricycle gear: nose, left main, right main.
2. Four-wheel gear: front left, front right, rear left, rear right.
3. Skids: front/rear contact points for left skid and right skid.
4. Hull/tail: tail bumper, belly protection point, nose probe guard, fixed hardpoint.

For skids, use several contact points along the skid length. A single point per skid can cause unstable tipping or unrealistic pivoting.

MountStation is the suspension attach/reference point in aircraft coordinates. It is not automatically the wheel midpoint.

For a wheel contact:

1. Measure the strut attach point or contact reference point used by the baseline.
2. SuspensionLength is the uncompressed distance from MountStation to the wheel midpoint along SliderAxis.
3. With a vertical slider, SliderAxis x=“0” y=“0” z=“1” is common.

For a skid contact:

1. Place MountStation at the skid contact/reference point or the nearest simple suspension reference.
2. Use a short SuspensionLength and high sliding friction.
3. Add several points along the skid.

For a fixed hull point:

1. Place MountStation at the physical hard-contact point.
2. Use SuspensionLength = 0 or a very small value.
3. Use maxCompression = 0 or a very small value.

Common structure:

<Suspension>
  <MountStation x="-0.896" y="-2.34" z="-1.71" />
  <SliderAxis x="0" y="0" z="1" />
  <SuspensionLength length="0.35" />
  <SpringParameters springConstant="76300" damperConstant="7234.76" maxCompression="0.2" />
</Suspension>

Definitions:

If the aircraft sinks into the ground:

1. Check MountStation Z.
2. Check SuspensionLength.
3. Increase spring stiffness.
4. Check contact radius.

If the aircraft bounces:

1. Increase damping.
2. Reduce spring stiffness if it is excessive.
3. Check that contact stations are not too high or too low.

A useful first spring estimate:

springConstant = supported_weight_per_contact_N / desired_static_compression_m

Where:

supported_weight_per_contact_N = mass_kg * 9.81 / number_of_primary_contacts

Example:

mass = 4500 kg
primary contacts = 3
desired static compression = 0.18 m

supported_weight = 4500 * 9.81 / 3 = 14715 N
springConstant = 14715 / 0.18 = 81750 N/m

Damper is normally copied from a similar BIS XML, then tuned. Too little damping causes bounce. Too much damping can make touchdown feel dead or cause odd settling.

For skids and hull points, the tool uses a small proxy radius because the RotorLib contact block still contains a Wheel element. Treat this as a contact-model proxy, not a visible wheel.

Taxi and landing rollout should be tuned in game. Friction values that look reasonable in XML can still produce bad ground behavior.

Use steering only where the contact physically steers.

Skids and hull contacts should normally be non-steerable.

Damage thresholdLoad is the contact load where damage/failure should occur.

Start around several times the static supported load per contact:

thresholdLoad = static_supported_load_per_contact * 3 to 6

Then tune hard landings. If normal landings break gear, raise it. If severe impacts never damage the gear, lower it.

Export:

1. XML.
2. JSON input/profile.
3. Authoring report.

Before testing:

1. Confirm the XML is well formed.
2. Confirm addon config points to the packed XML path.
3. Confirm there are no local development paths such as Q:\ in the final addon config.
4. Confirm imported baseline sections such as drive trains were preserved when needed.
5. Confirm every estimated value is noted.

Use this order. Do not tune forward flight before ground and hover basics work.

1. XML load: no RotorLib parse errors.
2. Ground stance: correct height, no sinking, no bounce, no tip-over.
3. Engine and rotor RPM: reaches target RPM, no runaway or immediate RPM collapse.
4. Liftoff: plausible collective setting.
5. Hover: stable enough to observe trim and control signs.
6. Pedals: correct yaw sign and sufficient authority.
7. Cyclic: correct pitch/roll sign and plausible response rate.
8. Taxi/landing rollout: brakes, steering, skids, and hull points behave as intended.
9. Forward flight: acceleration, trim, top speed, stabilizer effects.
10. Autorotation and edge cases.