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