# Component Instances
## Overview
This guide covers how to **create and use library component instances** in ParamML - a fundamental feature for building reusable, parametric components.
**What you'll learn:**
* What object instances are
* How to create instances
* What gets copied to instances
* Basic usage patterns
* Simple nested instances
**For advanced topics** (Export dependencies, complex nesting, debugging): → See `AI-Export.md`
***
## What are Object Instances?
An **object instance** is created when you use a Library Component as a building block in your own component.
**Think of it like:**
* **Component Definition** = Blueprint/Template (e.g., "Cube")
* **Instance** = Using that blueprint (e.g., "MyCube")
### Analogy
```
Component Definition (Cube)
↓ (instantiate)
Instance (MyCube, YourCube, AnotherCube...)
```
Like a cookie cutter (component) making multiple cookies (instances).
***
## Creating an Instance
### Basic Syntax
To create an instance, use the component name as the `T` (Type) attribute:
```xml
```
### Simple Example
### Simple Example
**Component definition:**
```xml
```
**Creating instances:**
```xml
```
**Using instances:**
```xml
```
***
## What Gets Copied to an Instance
When you create an instance, **only specific content appears**:
### ✅ What Gets Copied
1. **Input parameters** (`Role="Input"`)
2. **Everything inside ``**
### ❌ What Does NOT Get Copied
* Parameters without `Role="Input"` that are outside Export
* Objects outside Export
* Geometry (Volume, Surface, Point objects)
* Internal calculations outside Export
### Example: What Appears
**Component definition:**
```xml
```
**Instance:**
```xml
```
**What you can access:**
```xml
```
***
## The Export Object
The `` object controls **what is accessible** when someone creates an instance of your component.
### Why Export Exists
Export creates a **clean interface** - only exposing what users need, hiding implementation details.
**Without Export:**
* ❌ Everything would be accessible
* ❌ Implementation details exposed
* ❌ Hard to refactor without breaking code
* ❌ Messy, confusing interface
**With Export:**
* ✅ Clean, simple interface
* ✅ Hide complexity
* ✅ Can change internals without breaking users
* ✅ Clear what's intended for external use
### Basic Export Example
```xml
```
**Instance sees only:**
```xml
```
**⚠️ Note:** The `weight` calculation has a dependency issue. See `AI-Export.md` for details on the **Dependency Rule**.
***
## Setting Instance Parameters
### Set Input Values
```xml
```
### Use Expressions
Instance parameters can be expressions:
```xml
```
### Reference Other Instances
```xml
```
***
## Nested Instances (Simple)
Instances can contain other instances.
### Simple Nesting
**Building block:**
```xml
```
**Component using Bolt:**
```xml
```
**Using Connection:**
```xml
```
**Key point:** The nested `Bolt` instance must be **inside Export** for external access.
***
## The `Exported="1"` Attribute
You'll see `Exported="1"` on nested instances.
### How It Works
**In component definition (what you write):**
```xml
```
**In instance (system generates):**
```xml
```
**What it means:** Marks the object as an exported instance, allowing nested access.
**Rule:** Never write `Exported="1"` - the system adds it automatically.
***
## Common Patterns
### Pattern 1: Multiple Instances of Same Component
```xml
```
### Pattern 2: Instances with Different Parameters
```xml
```
### Pattern 3: Instance Coordinates from Another Instance
```xml
```
## Quick Troubleshooting
### Problem: "Can't access parameter from instance"
**Check:**
1. Is the parameter inside ``?
2. Does the parameter have `Role="Input"`?
3. If neither → it's not accessible from outside
**Solution:** Move parameter inside Export or add `Role="Input"`
### Problem: "Can't access nested object"
**Check:**
1. Is the nested object instance inside ``?
**Solution:** Move the nested object instance inside Export
### Problem: "Calculation gives wrong value in instance"
**Likely cause:** Missing dependency (parameter referenced but not exported)
**Solution:** See `AI-Export.md` for the **Dependency Rule**
***
## Next Steps
**You now know:**
* ✅ How to create instances
* ✅ What gets copied to instances
* ✅ How to use instance values
* ✅ Simple nested instances
***
## Quick Reference
### Create Instance
```xml
```
### What Gets Copied
* ✅ `Role="Input"` parameters
* ✅ Everything inside ``
* ❌ Everything else
### Access Instance Values
```xml
```
### Export for Accessibility
```xml
```