# Blueprint Graph System The blueprint graph system provides the data structures and type system for visual scripting. It defines the file format, graph structure, connections, and type inference. The implementation is in `crates/ui/src/graph/`. ## Blueprint Asset Format The top-level file format for `.bp_graph` files: ```rust pub struct BlueprintAsset { pub format_version: u32, pub main_graph: GraphDescription, pub local_macros: Vec, pub variables: Vec, pub editor_state: Option, pub blueprint_metadata: BlueprintMetadata, } ``` This contains everything about a blueprint - graphs, variables, metadata, and editor state. ## Graph Description A graph is a collection of nodes and connections: ```rust pub struct GraphDescription { pub nodes: HashMap, pub connections: Vec, pub metadata: GraphMetadata, pub comments: Vec, } ``` Nodes are stored in a HashMap by ID. Connections link node pins together. ## Node Instance A node in a graph: ```rust pub struct NodeInstance { pub id: String, pub node_type: String, pub position: (f32, f32), pub inputs: Vec, pub outputs: Vec, pub metadata: NodeMetadata, } ``` Each node has a type (like "Add", "Branch", "Print"), inputs, outputs, and position. ## Pin Instance A pin on a node: ```rust pub struct PinInstance { pub id: String, pub name: String, pub data_type: DataType, pub default_value: Option, pub is_execution: bool, } ``` Pins can be data pins (typed values) or execution pins (control flow). ## Connections A connection links two pins: ```rust pub struct Connection { pub id: String, pub from_node: String, pub from_pin: String, pub to_node: String, pub to_pin: String, } ``` This represents an edge in the graph - data flows from `from_pin` to `to_pin`. ## Type System The blueprint type system parses Rust types: ```rust pub struct TypeInfo { pub base_type: String, pub wrappers: Vec, pub is_wildcard: bool, } pub enum WrapperType { Vec, HashMap, HashSet, Arc, Box, Ref, RefMut, Option, Result, } ``` Types are parsed from strings like `Vec>` into structured form. ## Type Parsing Parse a Rust type string: ```rust let type_info = TypeInfo::parse("Vec>"); assert_eq!(type_info.base_type, "String"); assert_eq!(type_info.wrappers, vec![ WrapperType::Vec, WrapperType::Arc, ]); ``` The parser handles nested wrappers and references. ## Wildcard Types Generic types use wildcards: ```rust let type_info = TypeInfo::parse("Vec"); assert!(type_info.is_wildcard); assert_eq!(type_info.base_type, "wildcard"); ``` Wildcards match any type for generic nodes. ## Pin Colors Types have deterministic colors for visual clarity: ```rust pub struct PinColor { pub r: f32, pub g: f32, pub b: f32, pub a: f32, } let color = type_info.generate_color(); ``` Colors are generated by hashing the type name and converting to HSV. ## Pin Icons Different wrapper types have different icons: ```rust pub enum PinIcon { Circle, // Primitives Square, // Vec Diamond, // HashMap/HashSet Triangle, // Arc Hexagon, // Box HollowCircle, // Ref/RefMut Star, // Option Cross, // Result Rainbow, // Wildcard } ``` This provides visual feedback about the type structure. ## Pin Style Combined color and icon: ```rust pub struct PinStyle { pub color: PinColor, pub icon: PinIcon, pub is_rainbow: bool, } let style = type_info.generate_style(); ``` Wildcard types get rainbow styling. ## Class Variables Blueprints can have member variables: ```rust pub struct ClassVariable { pub id: String, pub name: String, pub data_type: DataType, pub default_value: Option, pub description: String, } ``` These are like fields in a struct. ## Local Macros Reusable subgraphs: ```rust pub struct SubGraphDefinition { pub id: String, pub name: String, pub graph: GraphDescription, pub inputs: Vec, pub outputs: Vec, } ``` Macros are like functions - they have inputs, outputs, and a graph body. ## Blueprint Comments Comment boxes for documentation: ```rust pub struct BlueprintComment { pub id: String, pub text: String, pub position: (f32, f32), pub size: (f32, f32), pub color: [f32; 4], pub contained_node_ids: Vec, } ``` Comments can contain nodes for grouping. ## Blueprint Metadata Metadata about the blueprint: ```rust pub struct BlueprintMetadata { pub blueprint_type: String, pub parent_class: Option, pub description: String, pub category: String, pub tags: Vec, } ``` Types can be "Actor", "Widget", "Component", etc. ## Editor State UI state for restoring the editor: ```rust pub struct BlueprintEditorState { pub open_tab_ids: Vec, pub active_tab_index: usize, pub graph_view_states: HashMap, } pub struct GraphViewState { pub pan_offset_x: f32, pub pan_offset_y: f32, pub zoom: f32, } ``` This preserves camera position and open tabs between sessions. ## Creating a Blueprint Create a new empty blueprint: ```rust let mut blueprint = BlueprintAsset::new("MyBlueprint"); blueprint.blueprint_metadata.blueprint_type = "Actor".to_string(); blueprint.blueprint_metadata.description = "My custom actor".to_string(); ``` ## Adding Nodes Add a node to the graph: ```rust let node = NodeInstance { id: "node_1".to_string(), node_type: "Add".to_string(), position: (100.0, 200.0), inputs: vec![ PinInstance { id: "a".to_string(), name: "A".to_string(), data_type: DataType::parse("f32"), default_value: Some("0.0".to_string()), is_execution: false, }, PinInstance { id: "b".to_string(), name: "B".to_string(), data_type: DataType::parse("f32"), default_value: Some("0.0".to_string()), is_execution: false, }, ], outputs: vec![ PinInstance { id: "result".to_string(), name: "Result".to_string(), data_type: DataType::parse("f32"), default_value: None, is_execution: false, }, ], metadata: NodeMetadata::default(), }; blueprint.main_graph.nodes.insert(node.id.clone(), node); ``` ## Connecting Nodes Connect two pins: ```rust let connection = Connection { id: "conn_1".to_string(), from_node: "node_1".to_string(), from_pin: "result".to_string(), to_node: "node_2".to_string(), to_pin: "input".to_string(), }; blueprint.main_graph.connections.push(connection); ``` ## Serialization Blueprints are saved as JSON: ```rust let json = serde_json::to_string_pretty(&blueprint)?; std::fs::write("MyBlueprint.bp_graph", json)?; ``` The format is human-readable and version-controlled. ## Deserialization Load a blueprint from JSON: ```rust let json = std::fs::read_to_string("MyBlueprint.bp_graph")?; let blueprint: BlueprintAsset = serde_json::from_str(&json)?; ``` ## Type Compatibility Check if types are compatible for connections: ```rust fn can_connect(from_type: &TypeInfo, to_type: &TypeInfo) -> bool { if from_type.is_wildcard || to_type.is_wildcard { return true; // Wildcards match anything } // Check base type match if from_type.base_type != to_type.base_type { return false; } // Check wrapper compatibility from_type.wrappers == to_type.wrappers } ``` ## Limitations Current implementation: - No type inference (types are explicit) - No automatic type conversion - Limited validation (can create invalid graphs) - No dependency tracking between nodes Future improvements: - Type inference engine - Automatic coercion (i32 → f32) - Graph validation on save - Smart connection routing

Related Documentation

Blueprint Node System

Quark Command System

Pulsar Architecture

Related Documentation

Blueprint Node System

Quark Command System

Pulsar Architecture