Skip to main content

AEROSIM-TS-1

Project task

Implement the normalized flight-force evaluator

Each fixed simulation step produces lift, drag, thrust, gravity, and net force/moment values from validated bounded gameplay parameters.

AEROSIM-TS-1Canonical ID TASK-0001
Verified flow state
Done
Owner
AeroSim Architecture and Delivery
Component
@corp-v1-aerosim/flight-core — flight force model
Repository
corp-v1-aerosim/corp-v1-aerosim

Delivery scope

Implement the pure evaluateFlightForces(input: FlightForceInput): FlightForceResult function. FlightForceInput contains AircraftKinematicState, ControlAxes, AircraftHandlingConfig, EnvironmentVector, and fixedStepSeconds; FlightForceResult contains liftBodyN, dragBodyN, thrustBodyN, gravityWorldN, netForceWorldN, and netMomentBodyNm. Validate every scalar before calculation and never mutate the input state.

Implementation contract

Implementation artifacts

  • packages/flight-core/src/physics/evaluate-flight-forces.ts
  • packages/flight-core/src/contracts/flight-force.ts
  • packages/flight-core/test/physics/evaluate-flight-forces.spec.ts

Inputs

  • FlightForceInput {state:{positionM, velocityMps, attitudeQuaternion, angularVelocityRadps}, controls:{pitch,roll,yaw,throttle}, aircraft:AircraftHandlingConfig, environment:{gravityMps2,windWorldMps,airDensityKgM3}, fixedStepSeconds}; control axes and throttle are normalized to [-1,1] and [0,1].

Outputs

  • FlightForceResult {liftBodyN:Vec3, dragBodyN:Vec3, thrustBodyN:Vec3, gravityWorldN:Vec3, netForceWorldN:Vec3, netMomentBodyNm:Vec3}; all components are finite and inputs remain byte-equivalent after evaluation.

Failure boundaries

  • Throw FlightForceInputError(code='NON_FINITE_STATE') before calculation when any position, velocity, attitude, or angular-velocity component is NaN or infinite.
  • Throw FlightForceInputError(code='CONTROL_OUT_OF_RANGE') for pitch, roll, or yaw outside [-1,1], or throttle outside [0,1].
  • Throw FlightForceInputError(code='INVALID_AIRCRAFT_CONFIG') when mass, wing area, inertia, force coefficient, or control-authority values are non-finite, zero where positive is required, or outside schema bounds.
  • Throw FlightForceInputError(code='INVALID_STEP') unless fixedStepSeconds is the configured positive fixed step; do not clamp or emit a partial force result.

Excluded scope

  • Position, velocity, and attitude integration is owned by EP3-FT1-02.
  • Terrain contact, collision impulses, structural damage, fuel burn, engine startup, and CFD-grade aerodynamics are not implemented here.

Verification steps

  • Run packages/flight-core/test/physics/evaluate-flight-forces.spec.ts.
  • Assert zero-throttle level-flight, full-throttle, climb, descent, bank, headwind, and tailwind fixtures against committed numeric vectors and tolerances.
  • Inject every non-finite field, each control bound violation, zero/negative mass and inertia, and an incorrect timestep; assert the exact FlightForceInputError code and absence of output.
  • Run the mutation guard that deep-freezes FlightForceInput and compares its serialized value before and after evaluation.

Traceability

Requirements

Dependencies

None

UI/UX applicability

non_visual

This Task owns technical or behavioral acceptance and does not claim direct visual conformance to the approved UI/UX package.

Acceptance evidence

Verified delivery: application PR #8 reviewed head 18d5854695e31946c72242b2e26f2d9efa2f3c74, merged as 589e445bb22ea501834fd60e27bd9d2636c802e6; final Wave 1 integration head 7d43415f042123871516df10ecc18cc1c4beb034 passed Gitea Actions publish task 1735 and validate task 1736. Release completion verified on product 1.0.0.0 at GitOps revision 5d3712d89dfbf7dacd993348e55f497d126c7bf9 with Argo Synced/Healthy, exact image digests, authenticated API/database access, and three-world configured-flight acceptance.

Current evidence boundary

No current implementation, acceptance, release, or deployment evidence is claimed for this planned Task. Any prior implementation may be used only as prototype and discovery evidence.