Creating Capsules

Capsules are collections of scripts that are accessible through the Revit ribbon. Launchpad Command lets you easily create and modify capsules to deploy your custom tools.

Overview

Launchpad Command provides tools for creating and managing capsules. Capsules are collections of scripts accessible from the Revit ribbon, similar to a custom add-in. Capsules are deployed through Launchpad Explorer, which supports Revit versions 2022 through 2026.

Understanding Capsules

A capsule is a self-contained package that includes:

• Configuration file (JSON format)

• Scripts folder containing C# code files

• Icons folder containing button images

• An organized structure for tabs, panels, and buttons

Capsules allow you to:

• Group related tools together

• Share tool collections with team members

• Organize custom Revit commands

• Create professional-looking ribbon interfaces

Creating a New Capsule

Method 1: Using the Capsule Creation Wizard

1. In Launchpad Command, go to Tools → Create New Capsule

2. In the dialog:

   • Enter a Capsule Name (e.g., "MyCustomTools")

   • Select or enter a Capsule Location (folder path)

   • Click Add Location to add the path to Launchpad Explorer's configuration

3. Click Create

The wizard automatically:

• Creates the capsule folder structure

• Generates a default configuration file

• Sets up Scripts and Icons folders

• Adds the location to Launchpad Explorer's search paths

Method 2: Manual Creation

You can also manually create a capsule structure:

MyCapsule/
├── capsule.json
├── Scripts/
└── Icons/

Editing Existing Capsules

Opening the Capsule Editor

1. Go to Tools → Edit Existing Capsule

2. Browse to select a capsule.json file

3. The Capsule Editor window opens

Using the Capsule Editor

The editor provides a visual interface for:

Left Panel - Capsule Structure

• Tree view showing the hierarchy

• Right-click context menus for adding/deleting items

• Drag-and-drop support for reorganizing

Right Panel - Properties

• Edit properties for selected items:

  • Capsule: Name, folder, version

  • Tab: Name

  • Panel: Name

  • Button: Type, name, title, tooltip, script file, icons

Adding Elements

1. Add Tab: Right-click capsule → Add Tab

2. Add Panel: Right-click tab → Add Panel

3. Add Button: Right-click panel → Add Button

Button Types

• Push Button: Standard single-click button

• Pulldown Button: Dropdown menu with multiple commands

• Split Button: Button with dropdown options

• Stacked Buttons: 2-3 buttons grouped vertically

Exporting Scripts to Capsules

Quick Export to My Launchpad Tools

1. Write your script in the Code Editor

2. Go to Tools → Export to Ribbon

3. Fill in the export dialog:

   • Tool Name: Internal name for the script

   • Button Title: Display text (use for line breaks)

   • Tooltip Description: Help text shown on hover

4. Click Export

This automatically:

• Creates/updates the "MyLaunchpadTools" capsule

• Copies your script and renames using proper naming convention

• Updates the capsule configuration

• Requires Revit restart to see changes

Manual Script Integration

1. Save your script with the naming convention: ButtonName_script.cs

2. Copy to the capsule's Scripts folder

3. Update the button's script file property in the Capsule Editor

Managing Capsule Locations

Configuring Launchpad Explorer Paths

1. Go to Tools → Manage Launchpad Explorer Config

2. View current capsule search paths

3. Add Path: Click to browse and add new locations

4. Remove Path: Select and click the delete button

Default Locations

Launchpad Explorer searches these locations:

• User-defined paths in the configuration

• %LocalAppData%\ArchSmarter\Capsules

• Assembly directory capsules folder

Capsule Structure

Configuration File (capsule.json)

json
{  
    "Name": "My Custom Tools",
    "Folder": "MyCustomTools",
    "Version": "1.0",
    "Tabs": [    
        {      
            "Name": "My Tab",      
            "Panels": [        
                {          
                    "Name": "My Panel",          
                    "Buttons": [            
                        {              
                            "Name": "MyButton",              
                            "Title": "My Button",              
                            "Type": "pushbutton",              
                            "Tooltip": "This is my button",              
                            "ScriptFile": "MyButton_script.cs",              
                            "Icon32File": "MyButton_32.png",              
                            "Icon16File": "MyButton_16.png"            
                        }
                     ]        
                }
            ]    
        }
    ]
}

File Naming Conventions

• Scripts: ButtonName_script.cs

• Large Icons: ButtonName_32.png (32x32 pixels)

• Small Icons: ButtonName_16.png (16x16 pixels)

Best Practices

1. Organize Your Capsules

• Group related functionality together

• Use descriptive names for tabs and panels

• Keep button titles concise but clear

2. Script Development

• Test scripts in Launchpad Command before exporting

• Include error handling in all scripts

• Add meaningful TaskDialog messages for user feedback

• Comment your code for future maintenance

3. Icon Design

• Use a consistent icon style across your capsule

• Ensure icons are clear at small sizes

• Save as PNG with transparency

• Follow the size requirements (16x16 and 32x32)

4. Version Control

• Keep capsules in version control (Git, SVN, etc.)

• Update version numbers when making changes

• Document changes in a changelog

5. Distribution

• Share entire capsule folders with team members

• Ensure all users have the capsule path configured

• Consider creating installer scripts for complex deployments

Troubleshooting

Common Issues

The capsule is not appearing in Launchpad Explorer

• Verify that the capsule path is in the Explorer configuration

• Check that the capsule.json file is valid JSON

• Restart Revit after adding new capsules

Script errors when clicking buttons

• Check if the script file exists in the Scripts folder

• Verify script filename matches the configuration

• Review the script for compilation errors

Icons not displaying

• Ensure icon files exist in the Icons folder

• Check the filename matches the configuration exactly

• Verify the image format is PNG

Changes not reflected

• Save all changes in the Capsule Editor

• Click "Apply Changes" for property updates

• Restart Revit to load configuration changes

Getting Help

• Check the Launchpad documentation

• Visit the ArchSmarter community forums

• Use the Feedback button in Launchpad Command

Advanced Topics

Creating Complex Button Types

Pulldown Buttons

json
{  
    "Name": "MyPulldown",  
    "Title": "Tools ▼",
    "Type": "pulldown",
    "Icon32File": "Tools_32.png",
    "Items": [    
        {      
            "Name": "Tool1",      
            "Title": "First Tool",      
            "ScriptFile": "Tool1_script.cs"
        },    
        {      
            "Name": "Tool2",      
            "Title": "Second Tool",      
            "ScriptFile": "Tool2_script.cs"    
        }  
    ]
}

Stacked Buttons

• Limited to 2-3 buttons per stack

• Buttons appear vertically grouped

• Useful for related commands

Integration with Team Workflows

1. Centralized Capsule Repository

   • Store capsules on a network drive

   • Configure all team members' Explorer paths

   • Implement update notifications

2. Capsule Templates

   • Create standard capsule structures

   • Define naming conventions

   • Establish icon design guidelines

3. Automated Deployment

   • Script capsule installation

   • Configure paths programmatically

   • Validate installations

This documentation provides a comprehensive guide for creating and managing capsules with Launchpad Command. Users can follow these steps to build custom tool collections that integrate seamlessly with Revit through Launchpad Explorer.