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, builtin_catalog};
31use clairlune_scene::{
32    BuildError, BuildOptions, Rgb, SceneGraph, SceneRecipe, SpriteKind, Theme, build,
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        let mut themes = Vec::new();
134        let mut graphs = Vec::new();
135        for theme in [Theme::Dark, Theme::Light] {
136            let opts = BuildOptions {
137                width,
138                height,
139                theme,
140                buddy: true,
141            };
142            match build(recipe, &opts) {
143                Ok(g) => graphs.push(g),
144                Err(BuildError::ThemeLocked(_)) => {}
145                Err(e) => return Err(e),
146            }
147        }
148        let first = graphs.first().ok_or(BuildError::ThemeLocked(Theme::Dark))?;
149        let activity = first
150            .activity
151            .as_deref()
152            .and_then(|id| builtin_catalog().get(id))
153            .cloned();
154        let art = PackageArt {
155            character: capture_character(activity.as_ref()),
156            props: capture_props(&graphs),
157            activity,
158        };
159        for mut graph in graphs {
160            let atlas = GlyphAtlas::for_grid(&graph.grid);
161            let palette = IndexedPalette::new(&graph.family);
162            let background = bake_static(&graph, &atlas);
163            // The background replaces the cells; a loaded package has none.
164            graph.cells = Vec::new();
165            let hero_ms = hero_time_with_art(&graph, &art);
166            let mut graph_unattended = graph.clone();
167            graph_unattended.buddy = false;
168            themes.push(ThemeScene {
169                theme: graph.theme,
170                graph,
171                graph_unattended,
172                palette,
173                atlas,
174                background,
175                hero_ms,
176            });
177        }
178        Ok(ScenePackage {
179            recipe: recipe.clone(),
180            width,
181            height,
182            generator_version: recipe.generator_version,
183            art,
184            themes,
185        })
186    }
187
188    /// Themes this scene has, dark first.
189    pub fn themes(&self) -> Vec<Theme> {
190        self.themes.iter().map(|t| t.theme).collect()
191    }
192
193    fn theme(&self, theme: Theme) -> Option<&ThemeScene> {
194        self.themes.iter().find(|t| t.theme == theme)
195    }
196
197    /// The still-frame time in a theme.
198    pub fn hero_ms(&self, theme: Theme) -> Option<u64> {
199        self.theme(theme).map(|t| t.hero_ms)
200    }
201
202    /// One frame, or `None` if the scene has no such theme.
203    pub fn frame(
204        &self,
205        theme: Theme,
206        buddy: bool,
207        t_ms: u64,
208        clock: Clock,
209    ) -> Option<(IndexedImage, &IndexedPalette)> {
210        let t = self.theme(theme)?;
211        let graph = if buddy { &t.graph } else { &t.graph_unattended };
212        let img = render_frame_with_art(
213            &t.background,
214            graph,
215            &t.atlas,
216            &t.palette,
217            t_ms,
218            clock,
219            &self.art,
220        );
221        Some((img, &t.palette))
222    }
223
224    /// A frame to play the scene live, starting from the bare background;
225    /// move it with [`ScenePackage::advance`].
226    pub fn incremental(&self, theme: Theme) -> Option<IncrementalFrame> {
227        self.theme(theme)
228            .map(|t| IncrementalFrame::new(&t.background))
229    }
230
231    /// Moves a live frame to `t_ms` and returns the rectangles that changed;
232    /// the frame then equals [`ScenePackage::frame`] at that time.
233    pub fn advance(
234        &self,
235        frame: &mut IncrementalFrame,
236        theme: Theme,
237        buddy: bool,
238        t_ms: u64,
239        clock: Clock,
240    ) -> Option<Vec<PixelRect>> {
241        let t = self.theme(theme)?;
242        let graph = if buddy { &t.graph } else { &t.graph_unattended };
243        Some(frame.advance(
244            &t.background,
245            graph,
246            &t.atlas,
247            &t.palette,
248            t_ms,
249            clock,
250            &self.art,
251        ))
252    }
253
254    /// The still (hero) frame in a theme.
255    pub fn still(&self, theme: Theme, buddy: bool) -> Option<(IndexedImage, &IndexedPalette)> {
256        let t = self.hero_ms(theme)?;
257        self.frame(theme, buddy, t, Clock::Live)
258    }
259
260    /// The palette in a theme.
261    pub fn palette(&self, theme: Theme) -> Option<&IndexedPalette> {
262        self.theme(theme).map(|t| &t.palette)
263    }
264
265    /// The scene graph in a theme (layout, emitters, loop length).
266    pub fn graph(&self, theme: Theme) -> Option<&SceneGraph> {
267        self.theme(theme).map(|t| &t.graph)
268    }
269
270    /// Writes the package into `dir` (created if needed).
271    pub fn save(&self, dir: &Path) -> Result<(), PackageError> {
272        std::fs::create_dir_all(dir)?;
273        let mut sheet = SpriteSheetWriter::default();
274        let character = self
275            .art
276            .character
277            .iter()
278            .map(|((activity, state), anim)| AnimationFile {
279                activity: activity.clone(),
280                state: state.clone(),
281                name: anim.name.clone(),
282                frames: anim.frames.iter().map(|f| sheet.add(f)).collect(),
283            })
284            .collect();
285        let file = PackageFile {
286            format: PACKAGE_FORMAT,
287            generator_version: self.generator_version,
288            recipe: self.recipe.clone(),
289            width: self.width,
290            height: self.height,
291            activity: self.art.activity.clone(),
292            character,
293            props: self
294                .art
295                .props
296                .iter()
297                .map(|(k, p)| PropFile {
298                    kind: *k,
299                    width: p.width,
300                    height: p.height,
301                    pixels: p.pixels.clone(),
302                })
303                .collect(),
304            themes: self
305                .themes
306                .iter()
307                .map(|t| ThemeFile {
308                    theme: t.theme,
309                    graph: t.graph.clone(),
310                    palette: t.palette.colors().to_vec(),
311                    atlas: t.atlas.clone(),
312                    hero_ms: t.hero_ms,
313                })
314                .collect(),
315        };
316        for t in &self.themes {
317            let mut png = Vec::new();
318            encode_png(&t.background, &t.palette, &mut png)
319                .map_err(|e| PackageError::Png(e.to_string()))?;
320            std::fs::write(dir.join(background_name(t.theme)), png)?;
321        }
322        std::fs::write(dir.join("sprites.png"), sheet.png()?)?;
323        let json = serde_json::to_string(&file)?;
324        let tmp = dir.join("package.json.part");
325        std::fs::write(&tmp, json)?;
326        std::fs::rename(tmp, dir.join("package.json"))?;
327        Ok(())
328    }
329
330    /// Reads a package written by this or an older version.
331    pub fn load(dir: &Path) -> Result<Self, PackageError> {
332        let text = std::fs::read_to_string(dir.join("package.json"))?;
333        let probe: FormatProbe = serde_json::from_str(&text)?;
334        if probe.format > PACKAGE_FORMAT || probe.format == 0 {
335            return Err(PackageError::UnsupportedFormat(probe.format));
336        }
337        let file: PackageFile = serde_json::from_str(&text)?;
338        let sheet = SpriteSheetReader::open(&std::fs::read(dir.join("sprites.png"))?)?;
339        let mut character = PackagedCharacter::default();
340        for a in &file.character {
341            let frames = a
342                .frames
343                .iter()
344                .map(|f| sheet.frame(f))
345                .collect::<Result<Vec<_>, _>>()?;
346            character.insert(
347                &a.activity,
348                &a.state,
349                Animation {
350                    name: a.name.clone(),
351                    frames,
352                },
353            );
354        }
355        let art = PackageArt {
356            activity: file.activity,
357            character,
358            props: file
359                .props
360                .into_iter()
361                .map(|p| {
362                    if p.pixels.len() != (p.width * p.height) as usize {
363                        return Err(PackageError::Invalid(format!("prop {:?} size", p.kind)));
364                    }
365                    Ok((
366                        p.kind,
367                        OwnedPixmap {
368                            width: p.width,
369                            height: p.height,
370                            pixels: p.pixels,
371                        },
372                    ))
373                })
374                .collect::<Result<_, _>>()?,
375        };
376        let mut themes = Vec::new();
377        for t in file.themes {
378            let (background, colors) =
379                decode_indexed(&std::fs::read(dir.join(background_name(t.theme)))?)?;
380            let palette = IndexedPalette::from_colors(t.palette);
381            if colors != palette.rgb_bytes()
382                || (background.width, background.height) != (file.width, file.height)
383            {
384                return Err(PackageError::Invalid(format!(
385                    "{} background does not match its palette or size",
386                    t.theme.as_str()
387                )));
388            }
389            let mut graph_unattended = t.graph.clone();
390            graph_unattended.buddy = false;
391            themes.push(ThemeScene {
392                theme: t.theme,
393                graph: t.graph,
394                graph_unattended,
395                palette,
396                atlas: t.atlas,
397                background,
398                hero_ms: t.hero_ms,
399            });
400        }
401        if themes.is_empty() {
402            return Err(PackageError::Invalid("no themes".into()));
403        }
404        Ok(ScenePackage {
405            recipe: file.recipe,
406            width: file.width,
407            height: file.height,
408            generator_version: file.generator_version,
409            art,
410            themes,
411        })
412    }
413}
414
415fn background_name(theme: Theme) -> String {
416    format!("background-{}.png", theme.as_str())
417}
418
419/// Every `(activity, state)` the scene can show: all states of its activity
420/// (the state machine may reach any), or the idle fallback.
421fn capture_character(activity: Option<&Activity>) -> PackagedCharacter {
422    let from = builtin_character();
423    match activity {
424        Some(a) => PackagedCharacter::capture(
425            from,
426            a.animation
427                .states
428                .keys()
429                .map(|s| (a.id.as_str(), s.as_str())),
430        ),
431        None => PackagedCharacter::capture(from, [("", "idle")]),
432    }
433}
434
435/// The pixel art of every prop the scene places, in either Buddy state.
436fn capture_props(graphs: &[SceneGraph]) -> Vec<(SpriteKind, OwnedPixmap)> {
437    let mut out: Vec<(SpriteKind, OwnedPixmap)> = Vec::new();
438    for g in graphs {
439        for s in g.props.iter().chain(&g.unattended) {
440            if s.kind != SpriteKind::Character && !out.iter().any(|(k, _)| *k == s.kind) {
441                out.push((s.kind, OwnedPixmap::copy_of(s.kind.map())));
442            }
443        }
444    }
445    out
446}
447
448// ---- On-disk format 1 ---------------------------------------------------
449
450#[derive(Deserialize)]
451struct FormatProbe {
452    format: u32,
453}
454
455#[derive(Serialize, Deserialize)]
456struct PackageFile {
457    format: u32,
458    generator_version: u32,
459    recipe: SceneRecipe,
460    width: u32,
461    height: u32,
462    activity: Option<Activity>,
463    character: Vec<AnimationFile>,
464    props: Vec<PropFile>,
465    themes: Vec<ThemeFile>,
466}
467
468#[derive(Serialize, Deserialize)]
469struct AnimationFile {
470    activity: String,
471    state: String,
472    name: String,
473    frames: Vec<FrameFile>,
474}
475
476/// A frame's place in `sprites.png` and its timing and anchors.
477#[derive(Serialize, Deserialize)]
478struct FrameFile {
479    y: u32,
480    width: u32,
481    height: u32,
482    duration_ms: u32,
483    anchors: BTreeMap<String, (i32, i32)>,
484}
485
486#[derive(Serialize, Deserialize)]
487struct PropFile {
488    kind: SpriteKind,
489    width: u32,
490    height: u32,
491    pixels: Vec<Option<Rgb>>,
492}
493
494#[derive(Serialize, Deserialize)]
495struct ThemeFile {
496    theme: Theme,
497    graph: SceneGraph,
498    palette: Vec<Rgb>,
499    atlas: GlyphAtlas,
500    hero_ms: u64,
501}
502
503/// Stacks frames top to bottom in one RGBA image; identical frames share
504/// their pixels.
505#[derive(Default)]
506struct SpriteSheetWriter {
507    width: u32,
508    rows: Vec<(u32, u32, Vec<Option<Rgb>>)>,
509    height: u32,
510}
511
512impl SpriteSheetWriter {
513    fn add(&mut self, f: &Frame) -> FrameFile {
514        let y = match self
515            .rows
516            .iter()
517            .find(|(_, w, px)| *w == f.width && *px == f.pixels)
518        {
519            Some((y, _, _)) => *y,
520            None => {
521                let y = self.height;
522                self.rows.push((y, f.width, f.pixels.clone()));
523                self.height += f.height;
524                self.width = self.width.max(f.width);
525                y
526            }
527        };
528        FrameFile {
529            y,
530            width: f.width,
531            height: f.height,
532            duration_ms: f.duration_ms,
533            anchors: f.anchors.clone(),
534        }
535    }
536
537    fn png(&self) -> Result<Vec<u8>, PackageError> {
538        let (w, h) = (self.width.max(1), self.height.max(1));
539        let mut rgba = vec![0u8; (w * h * 4) as usize];
540        for (y0, fw, px) in &self.rows {
541            for (i, p) in px.iter().enumerate() {
542                let Some(c) = p else { continue };
543                let (x, y) = (i as u32 % fw, y0 + i as u32 / fw);
544                let o = ((y * w + x) * 4) as usize;
545                rgba[o..o + 4].copy_from_slice(&[c.r, c.g, c.b, 255]);
546            }
547        }
548        let mut out = Vec::new();
549        let mut enc = png::Encoder::new(&mut out, w, h);
550        enc.set_color(png::ColorType::Rgba);
551        enc.set_depth(png::BitDepth::Eight);
552        let mut writer = enc
553            .write_header()
554            .map_err(|e| PackageError::Png(e.to_string()))?;
555        writer
556            .write_image_data(&rgba)
557            .map_err(|e| PackageError::Png(e.to_string()))?;
558        writer
559            .finish()
560            .map_err(|e| PackageError::Png(e.to_string()))?;
561        Ok(out)
562    }
563}
564
565struct SpriteSheetReader {
566    width: u32,
567    height: u32,
568    rgba: Vec<u8>,
569}
570
571impl SpriteSheetReader {
572    fn open(bytes: &[u8]) -> Result<Self, PackageError> {
573        let mut dec = png::Decoder::new(std::io::Cursor::new(bytes));
574        dec.set_transformations(png::Transformations::EXPAND);
575        let mut reader = dec
576            .read_info()
577            .map_err(|e| PackageError::Png(e.to_string()))?;
578        let mut buf = vec![0; reader.output_buffer_size().unwrap_or(0)];
579        let info = reader
580            .next_frame(&mut buf)
581            .map_err(|e| PackageError::Png(e.to_string()))?;
582        if info.color_type != png::ColorType::Rgba {
583            return Err(PackageError::Png("sprites.png must be RGBA".into()));
584        }
585        buf.truncate(info.buffer_size());
586        Ok(SpriteSheetReader {
587            width: info.width,
588            height: info.height,
589            rgba: buf,
590        })
591    }
592
593    fn frame(&self, f: &FrameFile) -> Result<Frame, PackageError> {
594        if f.width > self.width || f.y + f.height > self.height {
595            return Err(PackageError::Invalid(
596                "a frame lies outside sprites.png".into(),
597            ));
598        }
599        let mut pixels = Vec::with_capacity((f.width * f.height) as usize);
600        for y in f.y..f.y + f.height {
601            for x in 0..f.width {
602                let o = ((y * self.width + x) * 4) as usize;
603                let p = &self.rgba[o..o + 4];
604                pixels.push((p[3] != 0).then_some(Rgb {
605                    r: p[0],
606                    g: p[1],
607                    b: p[2],
608                }));
609            }
610        }
611        Ok(Frame {
612            width: f.width,
613            height: f.height,
614            pixels,
615            duration_ms: f.duration_ms,
616            anchors: f.anchors.clone(),
617        })
618    }
619}
620
621/// Decodes an 8-bit indexed PNG to its indices and palette bytes.
622fn decode_indexed(bytes: &[u8]) -> Result<(IndexedImage, Vec<u8>), PackageError> {
623    let png_err = |e: &dyn fmt::Display| PackageError::Png(e.to_string());
624    let dec = png::Decoder::new(std::io::Cursor::new(bytes));
625    let mut reader = dec.read_info().map_err(|e| png_err(&e))?;
626    let palette = reader
627        .info()
628        .palette
629        .as_ref()
630        .ok_or_else(|| PackageError::Png("background must be indexed".into()))?
631        .to_vec();
632    let mut buf = vec![0u8; reader.output_buffer_size().unwrap_or(0)];
633    let info = reader.next_frame(&mut buf).map_err(|e| png_err(&e))?;
634    if info.color_type != png::ColorType::Indexed || info.bit_depth != png::BitDepth::Eight {
635        return Err(PackageError::Png("background must be 8-bit indexed".into()));
636    }
637    buf.truncate(info.buffer_size());
638    Ok((
639        IndexedImage {
640            width: info.width,
641            height: info.height,
642            pixels: buf,
643        },
644        palette,
645    ))
646}