Skip to main content

clairlune_render/
package.rs

1//! Frozen scene packages (PLAN.md section 9c): how saved wallpapers are kept.
2//!
3//! A package holds the *output* of the generator for one scene at one size,
4//! not its inputs: for each theme the scene supports, the scene graph (layout,
5//! character track, props, emitters, lighting), the palette, the glyph masks
6//! and the baked background; plus the activity definition, the character
7//! frames the scene can show and the props' pixel art. Playback reads only the
8//! package, never the generator, the activity catalog or the built-in art, so
9//! a saved scene plays the same after any of them change.
10//!
11//! ```text
12//! scene/
13//! ├── package.json          format, recipe, size, art, per-theme scene data
14//! ├── background-dark.png   indexed, no animated elements
15//! ├── background-light.png
16//! └── sprites.png           the character frames, stacked (RGBA)
17//! ```
18//!
19//! What is *code* rather than data (particle motion, lighting bands, the
20//! state machine, palette layout) is the package player for format 1; a
21//! committed golden package (`tests/golden/packages`) pins its output.
22
23use crate::art::{OwnedPixmap, Pixmap, SceneArt};
24use crate::atlas::GlyphAtlas;
25use crate::bake::bake_static;
26use crate::clock::Clock;
27use crate::frame::{IncrementalFrame, PixelRect, hero_time_with_art, render_frame_with_art};
28use crate::palette::IndexedPalette;
29use crate::{IndexedImage, encode_png};
30use clairlune_scene::activity::{Activity, Catalog, builtin_catalog};
31use clairlune_scene::{
32    BuildError, BuildOptions, Rgb, SceneGraph, SceneRecipe, SpriteKind, Theme, build_with,
33};
34use clairlune_sprites::{Animation, Character, Frame, PackagedCharacter, builtin_character};
35use serde::{Deserialize, Serialize};
36use std::collections::BTreeMap;
37use std::fmt;
38use std::path::Path;
39
40/// The package format this build writes. Older formats stay readable.
41pub const PACKAGE_FORMAT: u32 = 1;
42
43#[derive(Debug)]
44pub enum PackageError {
45    Io(std::io::Error),
46    Json(serde_json::Error),
47    Png(String),
48    /// Written by a newer Clairlune.
49    UnsupportedFormat(u32),
50    Invalid(String),
51}
52
53impl fmt::Display for PackageError {
54    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
55        match self {
56            PackageError::Io(e) => write!(f, "{e}"),
57            PackageError::Json(e) => write!(f, "package.json: {e}"),
58            PackageError::Png(e) => write!(f, "image: {e}"),
59            PackageError::UnsupportedFormat(v) => write!(
60                f,
61                "scene package format {v} is newer than this version reads ({PACKAGE_FORMAT})"
62            ),
63            PackageError::Invalid(e) => write!(f, "scene package: {e}"),
64        }
65    }
66}
67
68impl std::error::Error for PackageError {}
69
70impl From<std::io::Error> for PackageError {
71    fn from(e: std::io::Error) -> Self {
72        PackageError::Io(e)
73    }
74}
75
76impl From<serde_json::Error> for PackageError {
77    fn from(e: serde_json::Error) -> Self {
78        PackageError::Json(e)
79    }
80}
81
82/// The art a package carries.
83#[derive(Clone, Debug)]
84pub struct PackageArt {
85    activity: Option<Activity>,
86    character: PackagedCharacter,
87    props: Vec<(SpriteKind, OwnedPixmap)>,
88}
89
90impl SceneArt for PackageArt {
91    fn activity(&self) -> Option<&Activity> {
92        self.activity.as_ref()
93    }
94    fn character(&self) -> &dyn Character {
95        &self.character
96    }
97    fn prop(&self, kind: SpriteKind) -> Option<&dyn Pixmap> {
98        self.props
99            .iter()
100            .find(|(k, _)| *k == kind)
101            .map(|(_, p)| p as &dyn Pixmap)
102    }
103}
104
105/// One theme's frozen scene.
106#[derive(Clone, Debug)]
107struct ThemeScene {
108    theme: Theme,
109    /// Laid out with Clawd; `graph_unattended` is the same with Buddy off.
110    graph: SceneGraph,
111    graph_unattended: SceneGraph,
112    palette: IndexedPalette,
113    atlas: GlyphAtlas,
114    background: IndexedImage,
115    hero_ms: u64,
116}
117
118/// A frozen scene: plays without the generator.
119#[derive(Clone, Debug)]
120pub struct ScenePackage {
121    pub recipe: SceneRecipe,
122    pub width: u32,
123    pub height: u32,
124    /// The generator that made it (for information; playback ignores it).
125    pub generator_version: u32,
126    art: PackageArt,
127    themes: Vec<ThemeScene>,
128}
129
130impl ScenePackage {
131    /// Builds the scene in every theme it supports and freezes the result.
132    pub fn capture(recipe: &SceneRecipe, width: u32, height: u32) -> Result<Self, BuildError> {
133        Self::capture_with(
134            recipe,
135            width,
136            height,
137            builtin_catalog(),
138            builtin_character(),
139        )
140    }
141
142    /// [`capture`](Self::capture) with another activity catalog and character
143    /// (the developer preview loads both from disk).
144    pub fn capture_with(
145        recipe: &SceneRecipe,
146        width: u32,
147        height: u32,
148        catalog: &Catalog,
149        character: &dyn Character,
150    ) -> Result<Self, BuildError> {
151        let mut themes = Vec::new();
152        let mut graphs = Vec::new();
153        for theme in [Theme::Dark, Theme::Light] {
154            let opts = BuildOptions {
155                width,
156                height,
157                theme,
158                buddy: true,
159            };
160            match build_with(catalog, recipe, &opts) {
161                Ok(g) => graphs.push(g),
162                Err(BuildError::ThemeLocked(_)) => {}
163                Err(e) => return Err(e),
164            }
165        }
166        let first = graphs.first().ok_or(BuildError::ThemeLocked(Theme::Dark))?;
167        let activity = first
168            .activity
169            .as_deref()
170            .and_then(|id| catalog.get(id))
171            .cloned();
172        let art = PackageArt {
173            character: capture_character(character, activity.as_ref()),
174            props: capture_props(&graphs),
175            activity,
176        };
177        for mut graph in graphs {
178            let atlas = GlyphAtlas::for_grid(&graph.grid);
179            let palette = IndexedPalette::for_graph(&graph)
180                .with_sprite_colors(character_colors(&art.character));
181            let background = bake_static(&graph, &atlas);
182            // The background replaces the cells; a loaded package has none.
183            graph.cells = Vec::new();
184            let hero_ms = hero_time_with_art(&graph, &art);
185            let mut graph_unattended = graph.clone();
186            graph_unattended.buddy = false;
187            themes.push(ThemeScene {
188                theme: graph.theme,
189                graph,
190                graph_unattended,
191                palette,
192                atlas,
193                background,
194                hero_ms,
195            });
196        }
197        Ok(ScenePackage {
198            recipe: recipe.clone(),
199            width,
200            height,
201            generator_version: recipe.generator_version,
202            art,
203            themes,
204        })
205    }
206
207    /// Themes this scene has, dark first.
208    pub fn themes(&self) -> Vec<Theme> {
209        self.themes.iter().map(|t| t.theme).collect()
210    }
211
212    fn theme(&self, theme: Theme) -> Option<&ThemeScene> {
213        self.themes.iter().find(|t| t.theme == theme)
214    }
215
216    /// The still-frame time in a theme.
217    pub fn hero_ms(&self, theme: Theme) -> Option<u64> {
218        self.theme(theme).map(|t| t.hero_ms)
219    }
220
221    /// One frame, or `None` if the scene has no such theme.
222    pub fn frame(
223        &self,
224        theme: Theme,
225        buddy: bool,
226        t_ms: u64,
227        clock: Clock,
228    ) -> Option<(IndexedImage, &IndexedPalette)> {
229        let t = self.theme(theme)?;
230        let graph = if buddy { &t.graph } else { &t.graph_unattended };
231        let img = render_frame_with_art(
232            &t.background,
233            graph,
234            &t.atlas,
235            &t.palette,
236            t_ms,
237            clock,
238            &self.art,
239        );
240        Some((img, &t.palette))
241    }
242
243    /// A frame to play the scene live, starting from the bare background;
244    /// move it with [`ScenePackage::advance`].
245    pub fn incremental(&self, theme: Theme) -> Option<IncrementalFrame> {
246        self.theme(theme)
247            .map(|t| IncrementalFrame::new(&t.background))
248    }
249
250    /// Moves a live frame to `t_ms` and returns the rectangles that changed;
251    /// the frame then equals [`ScenePackage::frame`] at that time.
252    pub fn advance(
253        &self,
254        frame: &mut IncrementalFrame,
255        theme: Theme,
256        buddy: bool,
257        t_ms: u64,
258        clock: Clock,
259    ) -> Option<Vec<PixelRect>> {
260        let t = self.theme(theme)?;
261        let graph = if buddy { &t.graph } else { &t.graph_unattended };
262        Some(frame.advance(
263            &t.background,
264            graph,
265            &t.atlas,
266            &t.palette,
267            t_ms,
268            clock,
269            &self.art,
270        ))
271    }
272
273    /// The still (hero) frame in a theme.
274    pub fn still(&self, theme: Theme, buddy: bool) -> Option<(IndexedImage, &IndexedPalette)> {
275        let t = self.hero_ms(theme)?;
276        self.frame(theme, buddy, t, Clock::Live)
277    }
278
279    /// The palette in a theme.
280    pub fn palette(&self, theme: Theme) -> Option<&IndexedPalette> {
281        self.theme(theme).map(|t| &t.palette)
282    }
283
284    /// The scene graph in a theme (layout, emitters, loop length).
285    pub fn graph(&self, theme: Theme) -> Option<&SceneGraph> {
286        self.theme(theme).map(|t| &t.graph)
287    }
288
289    /// Writes the package into `dir` (created if needed).
290    pub fn save(&self, dir: &Path) -> Result<(), PackageError> {
291        std::fs::create_dir_all(dir)?;
292        let mut sheet = SpriteSheetWriter::default();
293        let character = self
294            .art
295            .character
296            .iter()
297            .map(|((activity, state), anim)| AnimationFile {
298                activity: activity.clone(),
299                state: state.clone(),
300                name: anim.name.clone(),
301                frames: anim.frames.iter().map(|f| sheet.add(f)).collect(),
302            })
303            .collect();
304        let file = PackageFile {
305            format: PACKAGE_FORMAT,
306            generator_version: self.generator_version,
307            recipe: self.recipe.clone(),
308            width: self.width,
309            height: self.height,
310            activity: self.art.activity.clone(),
311            character,
312            props: self
313                .art
314                .props
315                .iter()
316                .map(|(k, p)| PropFile {
317                    kind: *k,
318                    width: p.width,
319                    height: p.height,
320                    pixels: p.pixels.clone(),
321                })
322                .collect(),
323            themes: self
324                .themes
325                .iter()
326                .map(|t| ThemeFile {
327                    theme: t.theme,
328                    graph: t.graph.clone(),
329                    palette: t.palette.colors().to_vec(),
330                    atlas: t.atlas.clone(),
331                    hero_ms: t.hero_ms,
332                })
333                .collect(),
334        };
335        for t in &self.themes {
336            let mut png = Vec::new();
337            encode_png(&t.background, &t.palette, &mut png)
338                .map_err(|e| PackageError::Png(e.to_string()))?;
339            std::fs::write(dir.join(background_name(t.theme)), png)?;
340        }
341        std::fs::write(dir.join("sprites.png"), sheet.png()?)?;
342        let json = serde_json::to_string(&file)?;
343        let tmp = dir.join("package.json.part");
344        std::fs::write(&tmp, json)?;
345        std::fs::rename(tmp, dir.join("package.json"))?;
346        Ok(())
347    }
348
349    /// Reads a package written by this or an older version.
350    pub fn load(dir: &Path) -> Result<Self, PackageError> {
351        let text = std::fs::read_to_string(dir.join("package.json"))?;
352        let probe: FormatProbe = serde_json::from_str(&text)?;
353        if probe.format > PACKAGE_FORMAT || probe.format == 0 {
354            return Err(PackageError::UnsupportedFormat(probe.format));
355        }
356        let file: PackageFile = serde_json::from_str(&text)?;
357        let sheet = SpriteSheetReader::open(&std::fs::read(dir.join("sprites.png"))?)?;
358        let mut character = PackagedCharacter::default();
359        for a in &file.character {
360            let frames = a
361                .frames
362                .iter()
363                .map(|f| sheet.frame(f))
364                .collect::<Result<Vec<_>, _>>()?;
365            character.insert(
366                &a.activity,
367                &a.state,
368                Animation {
369                    name: a.name.clone(),
370                    frames,
371                },
372            );
373        }
374        let art = PackageArt {
375            activity: file.activity,
376            character,
377            props: file
378                .props
379                .into_iter()
380                .map(|p| {
381                    if p.pixels.len() != (p.width * p.height) as usize {
382                        return Err(PackageError::Invalid(format!("prop {:?} size", p.kind)));
383                    }
384                    Ok((
385                        p.kind,
386                        OwnedPixmap {
387                            width: p.width,
388                            height: p.height,
389                            pixels: p.pixels,
390                        },
391                    ))
392                })
393                .collect::<Result<_, _>>()?,
394        };
395        let mut themes = Vec::new();
396        for t in file.themes {
397            let (background, colors) =
398                decode_indexed(&std::fs::read(dir.join(background_name(t.theme)))?)?;
399            let palette = IndexedPalette::from_colors(t.palette);
400            if colors != palette.rgb_bytes()
401                || (background.width, background.height) != (file.width, file.height)
402            {
403                return Err(PackageError::Invalid(format!(
404                    "{} background does not match its palette or size",
405                    t.theme.as_str()
406                )));
407            }
408            let mut graph_unattended = t.graph.clone();
409            graph_unattended.buddy = false;
410            themes.push(ThemeScene {
411                theme: t.theme,
412                graph: t.graph,
413                graph_unattended,
414                palette,
415                atlas: t.atlas,
416                background,
417                hero_ms: t.hero_ms,
418            });
419        }
420        if themes.is_empty() {
421            return Err(PackageError::Invalid("no themes".into()));
422        }
423        Ok(ScenePackage {
424            recipe: file.recipe,
425            width: file.width,
426            height: file.height,
427            generator_version: file.generator_version,
428            art,
429            themes,
430        })
431    }
432}
433
434fn background_name(theme: Theme) -> String {
435    format!("background-{}.png", theme.as_str())
436}
437
438/// Every `(activity, state)` the scene can show: all states of its activity
439/// (the state machine may reach any), or the idle fallback.
440fn capture_character(from: &dyn Character, activity: Option<&Activity>) -> PackagedCharacter {
441    match activity {
442        Some(a) => PackagedCharacter::capture(
443            from,
444            a.animation
445                .states
446                .keys()
447                .map(|s| (a.id.as_str(), s.as_str())),
448        ),
449        None => PackagedCharacter::capture(from, [("", "idle")]),
450    }
451}
452
453/// Every colour the captured frames use, in a stable order.
454fn character_colors(c: &PackagedCharacter) -> Vec<Rgb> {
455    let mut out: Vec<Rgb> = Vec::new();
456    for (_, anim) in c.iter() {
457        for f in &anim.frames {
458            for rgb in f.pixels.iter().flatten() {
459                if !out.contains(rgb) {
460                    out.push(*rgb);
461                }
462            }
463        }
464    }
465    out
466}
467
468/// The pixel art of every prop the scene places, in either Buddy state.
469fn capture_props(graphs: &[SceneGraph]) -> Vec<(SpriteKind, OwnedPixmap)> {
470    let mut out: Vec<(SpriteKind, OwnedPixmap)> = Vec::new();
471    for g in graphs {
472        for s in g.props.iter().chain(&g.unattended) {
473            if s.kind != SpriteKind::Character && !out.iter().any(|(k, _)| *k == s.kind) {
474                out.push((s.kind, OwnedPixmap::copy_of(s.kind.map())));
475            }
476        }
477    }
478    out
479}
480
481// ---- On-disk format 1 ---------------------------------------------------
482
483#[derive(Deserialize)]
484struct FormatProbe {
485    format: u32,
486}
487
488#[derive(Serialize, Deserialize)]
489struct PackageFile {
490    format: u32,
491    generator_version: u32,
492    recipe: SceneRecipe,
493    width: u32,
494    height: u32,
495    activity: Option<Activity>,
496    character: Vec<AnimationFile>,
497    props: Vec<PropFile>,
498    themes: Vec<ThemeFile>,
499}
500
501#[derive(Serialize, Deserialize)]
502struct AnimationFile {
503    activity: String,
504    state: String,
505    name: String,
506    frames: Vec<FrameFile>,
507}
508
509/// A frame's place in `sprites.png` and its timing and anchors.
510#[derive(Serialize, Deserialize)]
511struct FrameFile {
512    y: u32,
513    width: u32,
514    height: u32,
515    duration_ms: u32,
516    anchors: BTreeMap<String, (i32, i32)>,
517}
518
519#[derive(Serialize, Deserialize)]
520struct PropFile {
521    kind: SpriteKind,
522    width: u32,
523    height: u32,
524    pixels: Vec<Option<Rgb>>,
525}
526
527#[derive(Serialize, Deserialize)]
528struct ThemeFile {
529    theme: Theme,
530    graph: SceneGraph,
531    palette: Vec<Rgb>,
532    atlas: GlyphAtlas,
533    hero_ms: u64,
534}
535
536/// Stacks frames top to bottom in one RGBA image; identical frames share
537/// their pixels.
538#[derive(Default)]
539struct SpriteSheetWriter {
540    width: u32,
541    rows: Vec<(u32, u32, Vec<Option<Rgb>>)>,
542    height: u32,
543}
544
545impl SpriteSheetWriter {
546    fn add(&mut self, f: &Frame) -> FrameFile {
547        let y = match self
548            .rows
549            .iter()
550            .find(|(_, w, px)| *w == f.width && *px == f.pixels)
551        {
552            Some((y, _, _)) => *y,
553            None => {
554                let y = self.height;
555                self.rows.push((y, f.width, f.pixels.clone()));
556                self.height += f.height;
557                self.width = self.width.max(f.width);
558                y
559            }
560        };
561        FrameFile {
562            y,
563            width: f.width,
564            height: f.height,
565            duration_ms: f.duration_ms,
566            anchors: f.anchors.clone(),
567        }
568    }
569
570    fn png(&self) -> Result<Vec<u8>, PackageError> {
571        let (w, h) = (self.width.max(1), self.height.max(1));
572        let mut rgba = vec![0u8; (w * h * 4) as usize];
573        for (y0, fw, px) in &self.rows {
574            for (i, p) in px.iter().enumerate() {
575                let Some(c) = p else { continue };
576                let (x, y) = (i as u32 % fw, y0 + i as u32 / fw);
577                let o = ((y * w + x) * 4) as usize;
578                rgba[o..o + 4].copy_from_slice(&[c.r, c.g, c.b, 255]);
579            }
580        }
581        let mut out = Vec::new();
582        let mut enc = png::Encoder::new(&mut out, w, h);
583        enc.set_color(png::ColorType::Rgba);
584        enc.set_depth(png::BitDepth::Eight);
585        let mut writer = enc
586            .write_header()
587            .map_err(|e| PackageError::Png(e.to_string()))?;
588        writer
589            .write_image_data(&rgba)
590            .map_err(|e| PackageError::Png(e.to_string()))?;
591        writer
592            .finish()
593            .map_err(|e| PackageError::Png(e.to_string()))?;
594        Ok(out)
595    }
596}
597
598struct SpriteSheetReader {
599    width: u32,
600    height: u32,
601    rgba: Vec<u8>,
602}
603
604impl SpriteSheetReader {
605    fn open(bytes: &[u8]) -> Result<Self, PackageError> {
606        let mut dec = png::Decoder::new(std::io::Cursor::new(bytes));
607        dec.set_transformations(png::Transformations::EXPAND);
608        let mut reader = dec
609            .read_info()
610            .map_err(|e| PackageError::Png(e.to_string()))?;
611        let mut buf = vec![0; reader.output_buffer_size().unwrap_or(0)];
612        let info = reader
613            .next_frame(&mut buf)
614            .map_err(|e| PackageError::Png(e.to_string()))?;
615        if info.color_type != png::ColorType::Rgba {
616            return Err(PackageError::Png("sprites.png must be RGBA".into()));
617        }
618        buf.truncate(info.buffer_size());
619        Ok(SpriteSheetReader {
620            width: info.width,
621            height: info.height,
622            rgba: buf,
623        })
624    }
625
626    fn frame(&self, f: &FrameFile) -> Result<Frame, PackageError> {
627        if f.width > self.width || f.y + f.height > self.height {
628            return Err(PackageError::Invalid(
629                "a frame lies outside sprites.png".into(),
630            ));
631        }
632        let mut pixels = Vec::with_capacity((f.width * f.height) as usize);
633        for y in f.y..f.y + f.height {
634            for x in 0..f.width {
635                let o = ((y * self.width + x) * 4) as usize;
636                let p = &self.rgba[o..o + 4];
637                pixels.push((p[3] != 0).then_some(Rgb {
638                    r: p[0],
639                    g: p[1],
640                    b: p[2],
641                }));
642            }
643        }
644        Ok(Frame {
645            width: f.width,
646            height: f.height,
647            pixels,
648            duration_ms: f.duration_ms,
649            anchors: f.anchors.clone(),
650        })
651    }
652}
653
654/// Decodes an 8-bit indexed PNG to its indices and palette bytes.
655fn decode_indexed(bytes: &[u8]) -> Result<(IndexedImage, Vec<u8>), PackageError> {
656    let png_err = |e: &dyn fmt::Display| PackageError::Png(e.to_string());
657    let dec = png::Decoder::new(std::io::Cursor::new(bytes));
658    let mut reader = dec.read_info().map_err(|e| png_err(&e))?;
659    let palette = reader
660        .info()
661        .palette
662        .as_ref()
663        .ok_or_else(|| PackageError::Png("background must be indexed".into()))?
664        .to_vec();
665    let mut buf = vec![0u8; reader.output_buffer_size().unwrap_or(0)];
666    let info = reader.next_frame(&mut buf).map_err(|e| png_err(&e))?;
667    if info.color_type != png::ColorType::Indexed || info.bit_depth != png::BitDepth::Eight {
668        return Err(PackageError::Png("background must be 8-bit indexed".into()));
669    }
670    buf.truncate(info.buffer_size());
671    Ok((
672        IndexedImage {
673            width: info.width,
674            height: info.height,
675            pixels: buf,
676        },
677        palette,
678    ))
679}