Knowledgebase

User Tools

Site Tools

You are here: HOME » tools » rotorlibafm_xml_tool_docs
tools:rotorlibafm_xml_tool_docs

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
tools:rotorlibafm_xml_tool_docs [2026/07/19 14:09] – created rocktools:rotorlibafm_xml_tool_docs [2026/07/20 12:25] (current) – [12. Required Handoff Notes] rock
Line 1: Line 1:
- 
- 
 ====== RotorLib XML Profile Authoring Guide ====== ====== 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. 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. 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.
 +
 ===== 1. Prepare The Source Material ===== ===== 1. Prepare The Source Material =====
 +
 Before entering values, collect these files and references: Before entering values, collect these files and references:
 +
   - The target helicopter addon source.   - The target helicopter addon source.
   - The target model, memory points, Geometry LOD, LandContact points, and any proxy gear/wheel geometry.   - The target model, memory points, Geometry LOD, LandContact points, and any proxy gear/wheel geometry.
Line 12: Line 15:
   - A closest matching BIS or mod RotorLib XML baseline.   - A closest matching BIS or mod RotorLib XML baseline.
   - Real aircraft data, if available: mass, dimensions, rotor diameter, blade count, engine power, RPM, wheel dimensions, and gear layout.   - 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: Use the closest proven RotorLib XML as the baseline. Match by:
 +
   - Approximate aircraft mass class.   - Approximate aircraft mass class.
   - Main rotor count and tail rotor arrangement.   - Main rotor count and tail rotor arrangement.
Line 18: Line 23:
   - Role: light, attack, transport, heavy transport.   - Role: light, attack, transport, heavy transport.
   - Similar rotor RPM and engine/transmission layout.   - 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. 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.
 +
 ===== 2. Coordinate System ===== ===== 2. Coordinate System =====
 +
 RotorLib coordinates use: RotorLib coordinates use:
 +
 ^ Axis ^ Direction ^ ^ Axis ^ Direction ^
 | ''X'' | Right | | ''X'' | Right |
 | ''Y'' | Forward | | ''Y'' | Forward |
 | ''Z'' | Up | | ''Z'' | Up |
 +
 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. 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: Useful rules:
 +
   - Positive ''X'' moves a point to the aircraft right side.   - Positive ''X'' moves a point to the aircraft right side.
   - Positive ''Y'' moves a point toward the nose.   - Positive ''Y'' moves a point toward the nose.
   - Positive ''Z'' moves a point upward.   - Positive ''Z'' moves a point upward.
   - Wheel, skid, tail rotor, rotor hub, and stabilizer positions should be measured relative to the same aircraft reference/datum used by the baseline XML.   - 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. If the exact datum is unclear, compare the baseline XML values against visible geometry and memory points. Preserve the same convention when adapting it.
 +
 ===== 3. Step 1: Baseline And Target Identity ===== ===== 3. Step 1: Baseline And Target Identity =====
 +
 Enter: Enter:
 +
 ^ Value ^ Where To Find It ^ Notes ^ ^ Value ^ Where To Find It ^ Notes ^
 | Profile name | XML file name or aircraft class name | Use a readable name such as ''RTD_MyHelicopter''. | | Profile name | XML file name or aircraft class name | Use a readable name such as ''RTD_MyHelicopter''. |
Line 39: Line 55:
 | XML path in addon | Planned packed PBO path | Use addon-relative paths only. Do not use ''Q:\'', ''C:\'', or other local absolute paths. | | XML path in addon | Planned packed PBO path | Use addon-relative paths only. Do not use ''Q:\'', ''C:\'', or other local absolute paths. |
 | Closest baseline XML | Bundled BIS XML or another working profile | Record this for later comparison and tuning notes. | | Closest baseline XML | Bundled BIS XML or another working profile | Record this for later comparison and tuning notes. |
 +
 Example Arma config pattern: Example Arma config pattern:
 +
 <code cpp> <code cpp>
 class RotorLibHelicopterProperties class RotorLibHelicopterProperties
Line 46: Line 64:
 }; };
 </code> </code>
 +
 Verify the exact placement and property names against a working vanilla helicopter config before packing. Verify the exact placement and property names against a working vanilla helicopter config before packing.
 +
 ===== 4. Step 2: Airframe ===== ===== 4. Step 2: Airframe =====
 +
 ==== 4.1 Mass ==== ==== 4.1 Mass ====
 +
 Enter mass in kilograms. Enter mass in kilograms.
 +
 Best sources, in order: Best sources, in order:
 +
   - Geometry LOD mass from the finished model.   - Geometry LOD mass from the finished model.
   - Existing addon config/source documentation.   - Existing addon config/source documentation.
   - Real aircraft maximum takeoff weight or empty weight, depending on what you are modelling first.   - Real aircraft maximum takeoff weight or empty weight, depending on what you are modelling first.
   - Closest baseline XML scaled to the new helicopter.   - 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. Start with a realistic operating/test mass, not necessarily the absolute maximum load. Later, test loaded and unloaded behavior separately.
 +
 ==== 4.2 Dimensions ==== ==== 4.2 Dimensions ====
 +
 Enter approximate dimensions in meters: Enter approximate dimensions in meters:
 +
 ^ Value ^ How To Measure ^ ^ Value ^ How To Measure ^
 | Length | Nose to tail extent, excluding main rotor unless using it deliberately for rough inertia. | | Length | Nose to tail extent, excluding main rotor unless using it deliberately for rough inertia. |
 | Width | Left-right body/gear/skid span. For ground stability, gear/skid span is often more useful than fuselage width. | | Width | Left-right body/gear/skid span. For ground stability, gear/skid span is often more useful than fuselage width. |
 | Height | Bottom contact point to upper fuselage/mast area. Use a consistent rough body height for inertia estimates. | | Height | Bottom contact point to upper fuselage/mast area. Use a consistent rough body height for inertia estimates. |
 +
 These dimensions are used for first-pass inertia and generated contact positions. They are not a substitute for measured contact or rotor stations. These dimensions are used for first-pass inertia and generated contact positions. They are not a substitute for measured contact or rotor stations.
 +
 ==== 4.3 Center Of Gravity ==== ==== 4.3 Center Of Gravity ====
 +
 +Enter center of gravity offsets in meters:
 +
 +^ Value ^ Meaning ^
 +| ''CG X'' | Lateral CG offset. Positive is right. |
 +| ''CG Y'' | Longitudinal CG offset. Positive is forward. |
 +| ''CG Z'' | Vertical CG offset. Positive is up. |
 +
 +Where to derive it:
 +
 +  - Geometry LOD mass center, if available.
 +  - Model authoring package mass properties.
 +  - Real aircraft station data.
 +  - 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.
 +
 +==== 4.4 Moments Of Inertia ====
 +
 +Use sourced moments of inertia if available. If not, estimate them temporarily from mass and dimensions:
 +
 +<code>
 +Ixx = 1/12 * mass * (length^2 + height^2)
 +Iyy = 1/12 * mass * (width^2 + height^2)
 +Izz = 1/12 * mass * (width^2 + length^2)
 +</code>
 +
 +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.
 +
 +===== 5. Step 3: Rotors =====
 +
 +==== 5.1 Main Rotor Geometry ====
 +
 +^ Value ^ How To Find Or Calculate It ^
 +| Radius | Measure hub center to blade tip. Rotor diameter / 2. |
 +| Chord | Average blade width. Use real blade data or measure the model blade. |
 +| Blade count | Count visible main rotor blades. |
 +| Design RPM | Use real aircraft data, baseline XML, or stable in-game RotorLib RPM from a close aircraft. |
 +| Clockwise | Determine from model animation or baseline. Wrong direction can invert yaw/control behavior. |
 +| Twist | Use blade data if available; otherwise start from the closest baseline. |
 +| Swash phase | Preserve from the baseline unless cyclic response demands a deliberate change. |
 +
 +Main rotor radius has a large effect because disc area is:
 +
 +<code>
 +disc_area = pi * radius^2
 +</code>
 +
 +Do not tune lift primarily by abusing mass or power. First verify radius, blade count, RPM, collective range, and aerodynamic tables.
 +
 +==== 5.2 Main Rotor Hub Position ====
 +
 +Measure the main rotor hub in RotorLib coordinates:
 +
 +^ Value ^ Direction ^
 +| Hub X | Right positive |
 +| Hub Y | Forward positive |
 +| Hub Z | Up positive |
 +
 +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.
 +
 +==== 5.3 Main Rotor Mechanical Values ====
 +
 +^ Value ^ Source Guidance ^
 +| Rotor inertia | Copy from a similar rotor or estimate cautiously. Affects spool-up and autorotation. |
 +| Blade flapping inertia | Prefer a baseline value. Affects cyclic response and damping. |
 +| Hinge offset | Use rotor head geometry or baseline. |
 +| Brake torque | Use source data or baseline. Only relevant when rotor brake behavior is modelled. |
 +
 +==== 5.4 Tail Rotor ====
 +
 +Measure or derive:
 +
 +^ Value ^ Guidance ^
 +| Radius | Tail rotor diameter / 2. |
 +| Chord | Average tail blade width. |
 +| Blade count | Visible tail rotor blade count. |
 +| Design RPM | Baseline drive-train ratio or real aircraft data. |
 +| Position X/Y/Z | Tail rotor hub station in RotorLib coordinates. ''Y'' distance from CG is the yaw moment arm. |
 +| Rotation direction | Preserve from a working baseline until yaw sign is verified. |
 +| Twist / lift slope | Use real data or closest baseline. |
 +
 +Tail rotor setup is a common cause of uncontrollable yaw. Verify sign and authority in hover before tuning forward flight.
 +
 +===== 6. Step 4: Engine And Drive Train =====
 +
 +==== 6.1 Power ====
 +
 +Enter horsepower references:
 +
 +^ Value ^ Meaning ^
 +| Emergency power HP | Short-term maximum/emergency power. Current Arma RTD XML uses ''emergencyPowerHP''. |
 +| Takeoff power HP | Short-duration takeoff power reference. |
 +| Continuous power HP | Maximum continuous operating power. |
 +
 +Sources:
 +
 +  - Real engine/aircraft data.
 +  - Existing addon documentation.
 +  - Closest baseline XML.
 +  - Conservative estimate based on aircraft mass class.
 +
 +==== 6.2 Torque ====
 +
 +If max torque is unavailable, estimate:
 +
 +<code>
 +torque_Nm = power_hp * 745.699872 / (rpm * 2 * pi / 60)
 +</code>
 +
 +Use the shaft RPM expected by the engine/controller, not necessarily visible rotor RPM unless the drive train is 1:1.
 +
 +==== 6.3 Controller And RPM ====
 +
 +^ Value ^ Guidance ^
 +| Target RPM | Copy from baseline or derive from rotor RPM and drive-train ratio. |
 +| Rotation resistance | Preserve baseline value first. Tune only after RPM behavior is understood. |
 +| Controller P/I/D/offset | Copy from working profiles unless you know the controller behavior. |
 +
 +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.
 +
 +===== 7. Step 5: Controls =====
 +
 +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.
 +
 +==== 7.1 Collective ====
 +
 +^ Value ^ Guidance ^
 +| Collective min deg | Lower blade pitch range. Too high causes excessive lift at low collective. |
 +| Collective max deg | Upper blade pitch range. Too low prevents liftoff. |
 +
 +Tune so the helicopter lifts and hovers at plausible collective for the test mass.
 +
 +==== 7.2 Cyclic ====
 +
 +^ Value ^ Guidance ^
 +| Lateral min/max | Roll cyclic authority. Verify sign in game. |
 +| Longitudinal min/max | Pitch cyclic authority. Verify sign in game. |
 +
 +If pitch or roll is reversed, check ''A1''/''B1'' signs, swash phase, rotor rotation direction, and coordinate conversion before changing unrelated values.
 +
 +==== 7.3 Pedals ====
 +
 +Pedal min/max maps to tail rotor collective. Wrong sign or tail rotor direction usually causes immediate yaw problems.
 +
 +Test:
 +
 +  - Low collective yaw response.
 +  - Hover yaw authority.
 +  - High collective anti-torque margin.
 +
 +===== 8. Step 6: Ground Contacts =====
 +
 +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:
 +
 +^ Contact Kind ^ Use For ^ XML Notes ^
 +| Wheel | Nose, main, tail wheels | Uses wheel radius, roll axis, brake torque, friction, steering, suspension. |
 +| Skid | Skid shoes, skid contact pads | Uses a small proxy radius and high sliding friction. Usually not steerable or brakable. |
 +| Fixed hull point | Tail bumper, belly point, auxiliary hard contact | Uses zero/short suspension and small proxy radius. Usually no steering/braking. |
 +
 +The XML still exports compatible ''FGGroundContact200'' structure. The contact kind is written into the XML comment so the authoring intent remains visible.
 +
 +==== 8.1 More Than Three Contacts ====
 +
 +Do not force every aircraft into nose-left-right wheel layout.
 +
 +Use as many contacts as needed:
 +
 +  - Wheeled tricycle gear: nose, left main, right main.
 +  - Four-wheel gear: front left, front right, rear left, rear right.
 +  - Skids: front/rear contact points for left skid and right skid.
 +  - 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.
 +
 +==== 8.2 MountStation ====
 +
 +''MountStation'' is the suspension attach/reference point in aircraft coordinates. It is not automatically the wheel midpoint.
 +
 +^ Attribute ^ Direction ^
 +| ''x'' | Right positive |
 +| ''y'' | Forward positive |
 +| ''z'' | Up positive |
 +
 +For a wheel contact:
 +
 +  - Measure the strut attach point or contact reference point used by the baseline.
 +  - ''SuspensionLength'' is the uncompressed distance from ''MountStation'' to the wheel midpoint along ''SliderAxis''.
 +  - With a vertical slider, ''SliderAxis x="0" y="0" z="1"'' is common.
 +
 +For a skid contact:
 +
 +  - Place ''MountStation'' at the skid contact/reference point or the nearest simple suspension reference.
 +  - Use a short ''SuspensionLength'' and high sliding friction.
 +  - Add several points along the skid.
 +
 +For a fixed hull point:
 +
 +  - Place ''MountStation'' at the physical hard-contact point.
 +  - Use ''SuspensionLength = 0'' or a very small value.
 +  - Use ''maxCompression = 0'' or a very small value.
 +
 +==== 8.3 SuspensionLength, SliderAxis, And Compression ====
 +
 +Common structure:
 +
 +<code xml>
 +<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>
 +</code>
 +
 +Definitions:
 +
 +^ Value ^ Meaning ^
 +| ''SliderAxis'' | Direction of suspension travel. Vertical contacts usually use ''0,0,1''. |
 +| ''SuspensionLength'' | Uncompressed distance from ''MountStation'' to wheel midpoint or contact reference. |
 +| ''maxCompression'' | Maximum compression travel. It should not exceed ''SuspensionLength''. |
 +
 +If the aircraft sinks into the ground:
 +
 +  - Check ''MountStation Z''.
 +  - Check ''SuspensionLength''.
 +  - Increase spring stiffness.
 +  - Check contact radius.
 +
 +If the aircraft bounces:
 +
 +  - Increase damping.
 +  - Reduce spring stiffness if it is excessive.
 +  - Check that contact stations are not too high or too low.
 +
 +==== 8.4 Spring And Damper ====
 +
 +A useful first spring estimate:
 +
 +<code>
 +springConstant = supported_weight_per_contact_N / desired_static_compression_m
 +</code>
 +
 +Where:
 +
 +<code>
 +supported_weight_per_contact_N = mass_kg * 9.81 / number_of_primary_contacts
 +</code>
 +
 +Example:
 +
 +<code>
 +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
 +</code>
 +
 +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.
 +
 +==== 8.5 Wheel Dimensions ====
 +
 +^ Value ^ How To Derive ^
 +| Wheel radius | Tyre diameter / 2. Measure the model or use real wheel data. |
 +| Wheel mass | Real wheel/gear mass if known, otherwise baseline value. |
 +| RollAxis | Wheel axle direction. Most main wheels use ''x="1" y="0" z="0"''. |
 +
 +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.
 +
 +==== 8.6 Friction And Brakes ====
 +
 +^ Value ^ Guidance ^
 +| ''slidingFriction'' | Higher values resist sideways sliding. Skids usually need higher friction than wheels. |
 +| ''resistanceTorqueNoBrake'' | Rolling resistance with no brake. |
 +| ''resistanceTorqueFullBrake'' | Brake resistance torque at full brake. |
 +| ''isBrakable'' | True for wheels that should brake. Usually false for skids and hull points. |
 +
 +Taxi and landing rollout should be tuned in game. Friction values that look reasonable in XML can still produce bad ground behavior.
 +
 +==== 8.7 Steering ====
 +
 +Use steering only where the contact physically steers.
 +
 +^ Value ^ Guidance ^
 +| ''isSteerable'' | True for steerable nose/tail wheels. |
 +| ''maxTorque'' | Steering motor authority. |
 +| ''maxRotSpeed'' | Steering rotation speed. |
 +| ''controllerGain'' | Response gain. Too high may oscillate. |
 +| ''inverseRotation'' | Flip if visual steering turns opposite to input. |
 +| ''keepCenter'' | Usually true for nose wheels. |
 +
 +Skids and hull contacts should normally be non-steerable.
 +
 +==== 8.8 Damage Threshold ====
 +
 +''Damage thresholdLoad'' is the contact load where damage/failure should occur.
 +
 +Start around several times the static supported load per contact:
 +
 +<code>
 +thresholdLoad = static_supported_load_per_contact * 3 to 6
 +</code>
 +
 +Then tune hard landings. If normal landings break gear, raise it. If severe impacts never damage the gear, lower it.
 +
 +===== 9. Step 7: Export And Review =====
 +
 +Export:
 +
 +  - XML.
 +  - JSON input/profile.
 +  - Authoring report.
 +
 +Before testing:
 +
 +  - Confirm the XML is well formed.
 +  - Confirm addon config points to the packed XML path.
 +  - Confirm there are no local development paths such as ''Q:\'' in the final addon config.
 +  - Confirm imported baseline sections such as drive trains were preserved when needed.
 +  - Confirm every estimated value is noted.
 +
 +===== 10. First In-Game Test Order =====
 +
 +Use this order. Do not tune forward flight before ground and hover basics work.
 +
 +  - XML load: no RotorLib parse errors.
 +  - Ground stance: correct height, no sinking, no bounce, no tip-over.
 +  - Engine and rotor RPM: reaches target RPM, no runaway or immediate RPM collapse.
 +  - Liftoff: plausible collective setting.
 +  - Hover: stable enough to observe trim and control signs.
 +  - Pedals: correct yaw sign and sufficient authority.
 +  - Cyclic: correct pitch/roll sign and plausible response rate.
 +  - Taxi/landing rollout: brakes, steering, skids, and hull points behave as intended.
 +  - Forward flight: acceleration, trim, top speed, stabilizer effects.
 +  - Autorotation and edge cases.
 +
 +===== 11. Common Problems =====
 +
 +^ Symptom ^ Check First ^
 +| XML does not load | XML syntax, schema names, packed path, ''RTDconfig'' path. |
 +| Aircraft sinks into ground | Contact Z, SuspensionLength, radius, spring constant. |
 +| Aircraft bounces | Damper, spring constant, maxCompression, contact placement. |
 +| Aircraft tips on ground | Contact width/length, CG, missing skid/hull points. |
 +| Cannot lift | Mass, rotor radius, RPM, collective range, lift tables, engine torque. |
 +| Climbs too aggressively | Collective minimum, lift coefficients, rotor RPM, mass. |
 +| Spins uncontrollably | Tail rotor sign, rotation direction, pedal mapping, tail rotor station. |
 +| Pitch or roll reversed | A1/B1 signs, swash phase, rotor rotation direction. |
 +| Cyclic too twitchy | Moments of inertia, cyclic range, dampers, flapping values. |
 +| RPM unstable | Engine controller, torque, rotation resistance, drivetrain ratio. |
 +
  
tools/rotorlibafm_xml_tool_docs.1784470183.txt.gz · Last modified: by rock

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial 4.0 International
CC Attribution-Noncommercial 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki