NOTES.md

Notes

Durable investigation notes that are useful context but are not active implementation instructions.

Asset Packaging Observations

• 2026-07-10: Future aircraft asset packaging should prefer generated modular packages over one giant archive split into arbitrary chunks. The useful boundary is not equal-sized files; it is cache/update/load control by dependency group. A likely path is: keep the current versioned loose-file cache as the base layer, generate a canonical asset manifest from simulator-specific package data, label assets by role, then use those labels for prefetching, cache diagnostics, and optional packaging.
• 2026-07-10: For MSFS, layout.json and package conventions make modular grouping practical. Candidate groups are base config/layout/manifest, behavior XML, selected model glTF/bin files, cockpit texture ranges, exterior/livery textures, sound banks, html_ui avionics, effects, and localization. Do not assume groups will be evenly sized; local packages are dominated by SimObjects, especially DDS textures, .bin model buffers, and .PCK sound banks.
• 2026-07-10: X-Plane and FlightGear should not be assumed to have MSFS-style manifests. They need adapter-generated manifests by parsing their native aircraft definitions and references. Folder-based splitting alone is too fragile for cross-simulator support.
• 2026-07-10: Compression is optional and should be measured. Small text-heavy assets such as XML, JSON, JS, config, and localization are good candidates for compressed modules. Large DDS/bin/PCK assets should generally remain directly addressable and versioned so the loader can range-load, cache, and skip them. If a texture group becomes too large, consider splitting by cockpit/exterior/livery/resolution or mip/range strategy before wrapping everything in one solid archive.

Performance Observations

• 2026-05-29: During the pedestal long-session investigation, A330 samples showed high offscreen PFD/ND gauge counters while the camera was framed on the MCDU/pedestal area. That evidence is useful for future generic VCockpit optimization work, but it did not explain the reported bug because the user-visible lag occurred while looking at the pedestal. Do not use those counters as justification for a pedestal fix unless a separate look-away/look-back freshness investigation proves the behavior is safe.
• 2026-05-29: The VCockpit offscreen-surface suspension experiment was rejected for the pedestal bug because it optimized the look-away case instead of the visible MCDU/pedestal symptom. Future offscreen gauge throttling should be treated as a separate optional optimization and must prove gauge freshness when returning to a surface.
• 2026-05-29: Repeated SimVar.GetRegisteredId calls inside gauge frames were observed during the same investigation. A local fast cache is useful because it reduces visible and offscreen gauge churn without changing gauge active/inactive behavior.
• 2026-05-29: Generic VCockpit unknown dirty events from bridge/runtime notifications should not force a full static DOM/SVG/text recapture. DOM mutations are the authoritative signal for static-layer refresh; canvas writes are the authoritative signal for dynamic canvas redraw.

Rejected Experiments

• A320 wing transform: the old X180 * bind * X180 experiment is rejected as heuristic. It helped a narrow subset, but it is not documented by MSFS and broke other left-side skinned parts.
• Blend-gbuffer decals: the implicit primitive/material-order decal depth-bias experiment for ASOBO_material_blend_gbuffer materials without explicit ASOBO_material_draw_order was rejected after A320 testing showed worse z-fighting. Keep it reverted.
• 2026-07-13: A330 flap index 4 is authoritative but visually appears near 3.8, short of the FULL gate. Percent/detent remapping distorted intermediate positions; changing the LOCK_FLAPS child bind rotation from -0.7535° to -15°, smaller values, zero, and +7.5° did not add lever travel. +7.5° looked closer at FULL only by shifting the clip, misaligned index 0, and caused clipping near 2/3. Raw glTF lever keyframes are 20.7535, 10.7535, 0.7535, -10.8465, -19.2465°, already spanning exactly 40°; the child -0.7535° cancels the center keyframe to level the release clip, so recursively accumulating it is incorrect. The unresolved mismatch is in reproduced hierarchy/pivot/mesh alignment or interpretation, not a missing detent offset or sweep; do not land compensating constants.

Material And Geometry Findings

• The A32NX flap/wing decal issue is not a WingFlex or skin bind-pose bug. The affected FLAPS_02_* and FLAPS_01_* meshes contain WINGS base primitives and ASOBO_material_blend_gbuffer decal primitives (METALFLAPS, plus RIBBONS on FLAPS_02_*) inside the same skinned mesh.
• In bind pose, before runtime animation, METALFLAPS vertices already sit about 1.5-1.9 mm median from the covered WINGS surface, with p95 offsets about 4.1-5.1 mm.
• The current A330 flap meshes use ordinary A339_AIRFRAME_WING_PARTS / A339_AIRFRAME_BLACK primitives and do not have comparable flap-local blend-gbuffer decal primitives.
• Depth masking fixes visibility/occlusion only. It does not by itself resolve A32NX flap surface alignment because MSFS geometry decals are not equivalent to independent forward transparent meshes; the SDK describes them as a special pass over a covered mesh with per-component blend factors into the background material/G-buffer.
• A330 stabilizer-root blend-gbuffer evidence: node2.010 / node2.011 are static standalone decal meshes parented beside visible node147.001 / node147.002 stabilizer receiver meshes under the same trim-axis transforms, so same-parent receiver projection is a generic loader requirement and not an aircraft-specific exception. The top-level node2.008 layer lacks an equivalent structural parent receiver binding; resolving that class without guessing remains blocked on a real deferred/G-buffer receiver resolve. 2026-06-05: WebGPU blend-gbuffer render-target depth fallback experiment rejected: a second full-scene render into a depth target caused interaction/scroll responsiveness problems. Final forward fallback should use depth masking only when framebuffer depth copy is available, while receiverless color blend-gbuffer layers remain visible as base surfaces. 2026-06-05: Forward blend-gbuffer rendering needs separate roles. Receiverless color blend-gbuffer layers without ASOBO_material_draw_order, such as the A330 stabilizer-root background layer observed as node2008, behave like physical/base surfaces in the forward fallback and should render in the base pass with blend-depth masking disabled. Draw-order blend-gbuffer strips without an authoritative same-glTF receiver should stay out of the decal pass because promoting them creates camera-dependent floating shells. 2026-06-05: Agent-browser screenshots under backups/agent-browser/elevator-stabilizer-render-pass/, webgpu-decal-fix/, webgpu-decal-standalone/, webgpu-decal-strip/, and webgpu-decal-strip-final/ are intentional visual evidence for the stabilizer-root floating decal investigation and final receiver/decal role checks. 2026-06-11: Reported A339X gauge-side checklist/SVG issues: /VFS/config/a339x/a330-941/checklists.json5 JSON5 processing can throw Cannot add property 0, object is not extensible, and gauge DOM/SVG can emit invalid rotateX(0deg) transform plus NaN text x/y length errors. Current main viewer __DevApi run reported zero active VCockpit gauges, so this remains a gauge-host/package-compatibility repro target rather than a confirmed core engine state bug. 2026-06-11: MCDU screen/menu behavior needs separate gauge-host investigation. Cold-and-dark local display brightness fallback was fixed to keep missing L:/I: brightness variables dark, but full MCDU correctness still depends on loading/running the HTML gauge host and its SimVar/LVar bridge. 2026-06-11: Engine state writes for combustion/N1/throttle are working through canonical state and MSFS aliases, but visible fan/engine spin is not currently exposed as a node animation trigger in __DevApi; only wing-flex engine pivot nodes were found. Treat engine fan/spool visuals as missing animation coverage unless a hidden binding is later found. 2026-06-11: Cockpit knob/scroll interaction remains a limiting factor. __DevApi.turn, drag, pointer, and wheel APIs exist, but full MSFS knob/scroll semantics across stock template variants are not route-complete and should be improved generically, not patched per aircraft.

MSFS Cockpit Interaction Research

• 2026-07-11: MSFS cockpit interaction is authored per MouseRect/input-event, rather than being a fixed global left-click/right-click scheme. The generic event contract includes primary, secondary, and tertiary press/down/release; increment/decrement; hover/leave; and enter/exit lock. Mouse buttons are configurable bindings, though the default PC mapping is primary=left, secondary=right, tertiary=middle.
• 2026-07-11: Support both MSFS interaction modes. Legacy permits direct, one-click mouse manipulation, while Lock selects/locks a target so mapped primary/secondary/tertiary and directional actions operate it. A pushable rotary commonly rotates through a locked primary drag and uses secondary to push; tertiary may be authored as pull. Do not infer push/pull or direction from mesh names.
• 2026-07-11: Preserve distinct interaction lifecycles. Buttons may be stateless, held/momentary, timed long-press, toggleable, or multi-state. Discrete switches are normally gated between states, may include momentary spring return (default minimum 0.75 s for external/inc-dec activation), and covers can prevent access or force a safe state. Knobs and levers may be bounded or infinite continuous controls; buttons can be merged into knobs/levers.
• 2026-07-11: Generic avionics behavior: tune standby, not active, frequency with separate whole-MHz and fractional-kHz encoders, then use the aircraft-authored swap action. Altimeter baro adjustment is an indexed KOHLSMAN setting, generally 28.2-31.3 inHg in stock templates with 0.01 inHg steps; STD is a separate standard-pressure command, not a guessed numeric click behavior. Flaps use a commanded handle position (discrete detent or continuous) and a separate actual trailing-edge position, which may lag due to the flap motor.
• 2026-07-11: Current viewer evidence: pointer support admits left and right buttons, but both press paths dispatch the default LeftSingle; release dispatches LeftRelease; only a right-button drag emits LeftDrag; the wheel is consumed for camera zoom; and middle/tertiary plus hover/leave semantics are not routed. This is a generic compatibility gap to address through the MSFS adapter/viewer input dispatcher, not a per-aircraft workaround.