> For the complete documentation index, see [llms.txt](https://docs.openbrim.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbrim.org/developers/llm-guides/ai-component-instances.md).
# 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
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.openbrim.org/developers/llm-guides/ai-component-instances.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.