concinnity_world/schema/
scene_import.rs

1//! Scene-import schema.
2
3/// Imports a 3D scene file as a single declaration.
4///
5/// One `SceneImport` stands in for the whole asset graph a scene file
6/// describes: its [Texture](#texture)s, [Material](#material)s,
7/// [Mesh](#mesh)es, [Model](#model)s, and [Prop](#prop)s. The build expands the
8/// import into those concrete assets, so `world.jsonl` stays small and
9/// human-editable while the full graph lives in the lock file and compiled
10/// blob. Geometry and texture pixels are never inlined into `world.jsonl`.
11///
12/// Supported `source` formats: `.fbx` and `.glb`.
13///
14/// **Generated names** are prefixed with the import's own asset `name`
15/// (`<name>_mat_0`, `<name>_prim_0`, `<name>_model_0`, ...), so they never
16/// clash with hand-authored assets. Because they only appear in the lock file
17/// and blob, you never reference them by hand.
18///
19/// **Camera:** the import frames a [Camera3D](#camera3d) to the scene's bounds
20/// so a freshly imported scene is immediately viewable. It is suppressed when
21/// the world already declares a `Camera3D` (yours wins) or when `emit_camera`
22/// is set to `false`.
23///
24/// ```rust
25/// # use concinnity_world::registry::build_only::SceneImport;
26/// SceneImport {
27///     source: "assets/Bistro/BistroExterior.fbx".into(),
28///     texture_max_size: 512,
29///     ..Default::default()
30/// };
31/// ```
32#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
33#[serde(default)]
34pub struct SceneImport {
35    /// Path to the scene file, relative to the project root. `.fbx` or `.glb`.
36    pub source: String,
37    /// Ceiling on the longest edge of each imported texture, in pixels. Large
38    /// source maps (2K-4K) are box-filtered down so the compiled scene, which
39    /// stores uncompressed pixels, stays within a sane memory budget. `0` keeps
40    /// each texture at its source resolution.
41    pub texture_max_size: u32,
42    /// Emissive factor applied to a material that carries an emissive map. Scene
43    /// files often ship a zero emissive factor that would cancel the map, so a
44    /// textured emissive gets this punchy factor instead.
45    pub emissive_map_strength: f32,
46    /// Whether to emit a [Camera3D](#camera3d) framed to the scene's bounds.
47    /// Suppressed automatically when the world already declares a `Camera3D`.
48    pub emit_camera: bool,
49}
50
51impl Default for SceneImport {
52    fn default() -> Self {
53        Self {
54            source: String::new(),
55            texture_max_size: 512,
56            emissive_map_strength: 3.0,
57            emit_camera: true,
58        }
59    }
60}
61
62#[cfg(test)]
63mod tests {
64    use super::*;
65
66    #[test]
67    fn an_import_emits_a_camera_so_the_scene_is_viewable_immediately() {
68        // `cn add foo.glb` writes one SceneImport line, so the expansion has to
69        // produce something navigable without any further authoring.
70        let s = SceneImport::default();
71        assert!(s.emit_camera);
72        assert_eq!(s.texture_max_size, 512);
73        assert_eq!(s.emissive_map_strength, 3.0);
74        assert!(s.source.is_empty());
75    }
76
77    #[test]
78    fn an_authored_import_parses_and_round_trips_through_postcard() {
79        let s: SceneImport = serde_json::from_str(
80            r#"{"source":"bistro.fbx","texture_max_size":2048,
81                "emissive_map_strength":1.0,"emit_camera":false}"#,
82        )
83        .unwrap();
84        assert_eq!(s.source, "bistro.fbx");
85        assert!(!s.emit_camera);
86
87        let bytes = postcard::to_allocvec(&s).unwrap();
88        let back: SceneImport = postcard::from_bytes(&bytes).unwrap();
89        assert_eq!(back.texture_max_size, 2048);
90        assert_eq!(back.emissive_map_strength, 1.0);
91        assert!(!back.emit_camera);
92    }
93}
concinnity_world/schema/scene_import.rs

concinnity_world/schema/
scene_import.rs
