diff --git a/CHANGELOG.md b/CHANGELOG.md index c0f69e86..078949cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ * **Double-click the Hand tool to fit the stage in the window** (#457, M8). A single click still selects the Hand tool without changing the view. +* **Fixed: shape hints were lost when opening Animate files.** Animate saves a shape tween's + hints as `morphHintsList`, which the XFL and `.fla` importer didn't read, so tweens came in + without them. They now come across with their letters and points. + * **Themes of your own** (#340, ADR 0117, M8): a theme is a small JSON file that names colours for the interface's roles, kept in `themes` in the settings folder (`data/themes` in a portable copy). diff --git a/crates/xfl/src/import.rs b/crates/xfl/src/import.rs index 91e72edc..5fa5e83d 100644 --- a/crates/xfl/src/import.rs +++ b/crates/xfl/src/import.rs @@ -772,7 +772,7 @@ impl<'a> Builder<'a> { } // Shape hints sit on both keyframes of a shape tween; they are paired up below. let shape_hints = craft_xfl::shape_hints::ShapeHints::new(f); - if !shape_hints.is_empty() { + if !shape_hints.is_empty() || crate::morph_hints::list(f).next().is_some() { raw_hints.insert(start, self.raw_hints(f)); } // Frame scripts are kept verbatim (ADR 0013 tier 1); those in the subset run. @@ -899,20 +899,26 @@ impl<'a> Builder<'a> { /// hint; it gives its point on this keyframe as `x`/`y` (or `startPoint="x, y"`, or /// `startX`/`startY`), and may carry its end point too (`endPoint`, or `endX`/`endY`); /// otherwise the end comes from the same hint on the next keyframe. Points are in pixels. - /// The order is `index` (or a letter `name`), else the order in the file. + /// The order is `index` (or a letter `name`), else the order in the file. Without + /// `shapeHints`, Animate's own `morphHintsList` is read (`morph_hints`). fn raw_hints(&mut self, frame: &X) -> Vec { + const MAX_LISTED: usize = anicraft_doc::MAX_SHAPE_HINTS * 4; let hints = craft_xfl::shape_hints::ShapeHints::new(frame); - let to_vec = |point: Option| { - point.map(|point| Vec2::new(point.x, point.y)).filter(|point| point.x.abs() < 1e6 && point.y.abs() < 1e6) + let to_vec = |point: Option| point.map(|point| Vec2::new(point.x, point.y)); + let listed: Vec<(Option, Option, Option)> = if hints.is_empty() { + crate::morph_hints::list(frame).take(MAX_LISTED).map(|hint| (None, hint.start, hint.end)).collect() + } else { + hints.iter().take(MAX_LISTED).map(|hint| (hint.index(), to_vec(hint.start_point()), to_vec(hint.end_point()))).collect() }; + let in_range = |point: Option| point.filter(|point| point.x.abs() < 1e6 && point.y.abs() < 1e6); let mut out: Vec = Vec::new(); - for (n, hint) in hints.iter().enumerate().take(anicraft_doc::MAX_SHAPE_HINTS * 4) { - let order = hint.index().unwrap_or(n); - let Some(here) = to_vec(hint.start_point()) else { + for (n, (index, here, end)) in listed.into_iter().enumerate() { + let order = index.unwrap_or(n); + let Some(here) = in_range(here) else { self.report.skip("shape hints without a position"); continue; }; - out.push(RawHint { order, here, end: to_vec(hint.end_point()) }); + out.push(RawHint { order, here, end: in_range(end) }); } out.sort_by_key(|h| h.order); if out.len() > anicraft_doc::MAX_SHAPE_HINTS { diff --git a/crates/xfl/src/lib.rs b/crates/xfl/src/lib.rs index 118c6562..cd170c45 100644 --- a/crates/xfl/src/lib.rs +++ b/crates/xfl/src/lib.rs @@ -9,6 +9,7 @@ pub mod edges; mod end_record; pub mod import; +mod morph_hints; pub mod text; pub mod video; /// The shared XML reader (`anicraft-xml`), under its old path. diff --git a/crates/xfl/src/morph_hints.rs b/crates/xfl/src/morph_hints.rs new file mode 100644 index 00000000..2acccee3 --- /dev/null +++ b/crates/xfl/src/morph_hints.rs @@ -0,0 +1,108 @@ +//! Shape hints as Animate saves them (ADR 0023). +//! +//! Animate writes a shape tween's hints as a `` on the keyframe that starts the +//! tween, one `` per hint in letter order +//! (`a` first), each record carrying its point on both keyframes. Learned by observing files +//! Animate saved; no Animate code involved. +//! +//! Each coordinate is decimal or `#` hex fixed point (signed 24.8, as in `edges`), in units of +//! 256 twips: `#FFFFFB.FB, #0.84` is (-1029, 132) twips, a vertex of the start shape. `key` is +//! 0 in every file seen and is not read; nor is the `` inside a frame's +//! ``, which was empty in every file seen. +//! +//! craft-xfl's `shape_hints` reads only the `` spelling; this belongs there. + +use crate::xml::Element as X; +use anicraft_geom::Vec2; + +/// One native unit is 256 twips. +const TWIPS_PER_UNIT: f32 = 256.0; +const TWIPS_PER_PIXEL: f32 = 20.0; + +/// One ``: its points in pixels on the start and end keyframes, each `None` when +/// missing or malformed. +#[derive(Clone, Copy, Debug, PartialEq)] +pub(crate) struct MorphHint { + pub start: Option, + pub end: Option, +} + +/// The hints a frame lists in ``, in file order (any child counts as a hint). +pub(crate) fn list(frame: &X) -> impl Iterator + '_ { + frame.list("morphHintsList").iter().map(|h| MorphHint { start: point(h, "startPoint"), end: point(h, "endPoint") }) +} + +/// A `"x, y"` attribute in pixels. +fn point(hint: &X, name: &str) -> Option { + let mut parts = hint.attr(name)?.split([',', ' ']).filter(|p| !p.trim().is_empty()); + let (x, y) = (number(parts.next()?)?, number(parts.next()?)?); + parts.next().is_none().then(|| Vec2::new(x * TWIPS_PER_UNIT / TWIPS_PER_PIXEL, y * TWIPS_PER_UNIT / TWIPS_PER_PIXEL)) +} + +/// A decimal number, or `#` hex fixed point: up to eight whole digits (two's complement once +/// shifted into 24.8) and up to two fraction digits (a single one is the high nibble). +fn number(s: &str) -> Option { + let s = s.trim(); + let value = match s.strip_prefix('#') { + Some(hex) => { + let (whole, frac) = hex.split_once('.').unwrap_or((hex, "")); + let digits = |d: &str| d.bytes().all(|b| b.is_ascii_hexdigit()); + if !digits(whole) || !digits(frac) || whole.len() > 8 || frac.len() > 2 || (whole.is_empty() && frac.is_empty()) { + return None; + } + let whole = if whole.is_empty() { 0 } else { u32::from_str_radix(whole, 16).ok()? }; + let frac = if frac.is_empty() { 0 } else { u32::from_str_radix(frac, 16).ok()? << if frac.len() == 1 { 4 } else { 0 } }; + (whole.wrapping_shl(8) | frac) as i32 as f32 / 256.0 + } + None => s.parse::().ok()?, + }; + value.is_finite().then_some(value) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn frame(xml: &str) -> X { + crate::xml::parse(xml.as_bytes()).unwrap() + } + + #[test] + fn reads_hex_and_decimal_points_in_units_of_256_twips() { + let f = frame( + r##" + + + "##, + ); + let hints: Vec<_> = list(&f).collect(); + assert_eq!(hints.len(), 2); + // (-1029, 132) twips; (-965, -2) twips. + assert_eq!(hints[0].start, Some(Vec2::new(-1029.0 / 20.0, 132.0 / 20.0))); + assert_eq!(hints[0].end, Some(Vec2::new(-965.0 / 20.0, -2.0 / 20.0))); + // (10708, 1221) twips; a single fraction digit is the high nibble: #28.A is 0x28A0. + assert_eq!(hints[1].start, Some(Vec2::new(10708.0 / 20.0, 1221.0 / 20.0))); + assert_eq!(hints[1].end, Some(Vec2::new(10400.0 / 20.0, 1280.0 / 20.0))); + } + + #[test] + fn malformed_points_are_none_never_a_panic() { + let bad = [ + "", ",", "1", "1,", "1, 2, 3", "#", "#.", "#G, 0", "#1.234, 0", "#123456789, 0", "nan, 0", "inf, 1", "1e40, 0", "#-1, 0", + "#+1, 0", "🙂, 1", "#FFFFFFFF.FF, #80000000", + ]; + for s in bad { + let f = frame(&format!(r#""#)); + let hint = list(&f).next().unwrap(); + assert_eq!(hint.end, None, "{s:?}"); + // The two largest hex values still decode, to finite numbers. + if s.starts_with("#FFFFFFFF") { + assert!(hint.start.is_some_and(|p| p.x.is_finite() && p.y.is_finite())); + } else { + assert_eq!(hint.start, None, "{s:?}"); + } + } + assert_eq!(list(&frame("")).count(), 0); + assert_eq!(list(&frame("")).count(), 0); + } +} diff --git a/crates/xfl/src/tests.rs b/crates/xfl/src/tests.rs index 7968e0b4..e1b784c7 100644 --- a/crates/xfl/src/tests.rs +++ b/crates/xfl/src/tests.rs @@ -434,6 +434,44 @@ fn shape_hints_come_across_in_either_form() { } } +#[test] +fn shape_hints_come_across_as_animate_writes_them() { + // `morphHintsList` on the start keyframe, both points per record, in units of 256 twips: + // (0, 0) and (300, 50) px, the end as hex fixed point and decimal. The list inside + // `MorphShape` is not the artist's and is left alone. + let hint = r##""##; + let doc = hinted_doc(&format!("{hint}{hint}{hint}"), ""); + let (d, report) = import(&HashMap::from([("DOMDocument.xml", doc)])).unwrap(); + assert!(report.skipped.keys().all(|s| !s.contains("hint")), "{:?}", report.skipped); + let l = &d.timeline(0).layers[0]; + let k = &l.keyframes[0]; + assert_eq!(k.hints.len(), 1); + assert!(k.hints[0].start.distance(anicraft_geom::Vec2::new(0.0, 0.0)) < 1e-3, "{:?}", k.hints[0]); + assert!(k.hints[0].end.distance(anicraft_geom::Vec2::new(300.0, 50.0)) < 1e-3, "{:?}", k.hints[0]); + assert!(anicraft_doc::placed_on(&k.elements, k.hints[0].start).is_some()); + assert!(anicraft_doc::placed_on(&l.keyframes[1].elements, k.hints[0].end).is_some()); + // Either spelling gives the same hints. + let native = hinted_doc(r#""#, ""); + let (n, _) = import(&HashMap::from([("DOMDocument.xml", native)])).unwrap(); + assert_eq!(n.timeline(0).layers[0].keyframes[0].hints, k.hints); +} + +#[test] +fn odd_morph_hints_are_reported_not_fatal() { + let many: String = (0..30).map(|_| r##""##).collect(); + let odd = r##""##; + let doc = hinted_doc(&format!("{odd}{many}"), ""); + let (d, report) = import(&HashMap::from([("DOMDocument.xml", doc)])).unwrap(); + assert_eq!(d.timeline(0).layers[0].keyframes[0].hints.len(), 26); + assert!(report.skipped.contains_key("shape hints past z"), "{:?}", report.skipped); + assert!(report.skipped.contains_key("shape hints without a position")); + // No end point, and no hints on the end keyframe to take one from. + let doc = hinted_doc(r#""#, ""); + let (d, report) = import(&HashMap::from([("DOMDocument.xml", doc)])).unwrap(); + assert!(d.timeline(0).layers[0].keyframes[0].hints.is_empty()); + assert!(report.skipped.contains_key("shape hints missing on the end keyframe")); +} + #[test] fn odd_shape_hints_are_reported_not_fatal() { let many: String = (0..30).map(|i| format!(r#""#)).collect(); diff --git a/docs/adr/0023-shape-hints.md b/docs/adr/0023-shape-hints.md index ddd10f14..183d5821 100644 --- a/docs/adr/0023-shape-hints.md +++ b/docs/adr/0023-shape-hints.md @@ -77,6 +77,12 @@ literature on polygon and Bézier blending. Nothing was copied. the next keyframe's `shapeHints`. Points within 2 px of an edge snap onto it. Hints past `z`, without a position or without an end are reported, never fatal. If real files turn out to use another layout, only this reader changes. + *Update (2026-11-18):* files Animate saves use another layout, a `` on the + tween's start keyframe with one `` per + hint in letter order; coordinates are decimal or `#` hex fixed point in units of 256 twips + (observed: they land exactly on the shapes' edge vertices). The importer reads that list + when a frame has no `shapeHints` (`crates/xfl/src/morph_hints.rs`); both map to the same + hints. ## Consequences