Chapter 14: Smart Objects

Smart Objects are user-programmable canvas graphics that let you create custom visual elements using JavaScript code. They enable effects, charts, decorations, and animated visuals that go beyond the built-in element types.

What Are Smart Objects?

A Smart Object is a scene element driven by a JavaScript drawing function. The code receives a 2D canvas context and draws whatever you need—gradients, charts, particle effects, animated patterns, and more.

Smart Objects can be:

• Static: A single rendered frame (e.g., a gradient, a chart)
• Animated: Multi-frame sequences with configurable frame count and FPS

Adding a Smart Object

1. Open the element palette on the right sidebar
2. Look for the Smart Objects section
3. Browse available definitions by category:
   • Builtin: Pre-made smart objects included with FX Express
   • Charts: Data visualization elements
   • Progress: Progress bars, loaders
   • Decorative: Visual accents and patterns
   • Transition: Scene transition effects
   • Custom: Your own uploaded smart objects
4. Click or drag a smart object to the canvas

Smart Object Parameters

Smart Objects accept configurable parameters that control their appearance:

Parameter Type	Description	Example
Number	Numeric value with min/max range	Line thickness, count
String	Text input	Labels, titles
Color	Color picker value	Fill color, stroke color
Boolean	On/off toggle	Show grid, enable shadow
Select	Dropdown from predefined options	Style variant, direction

Editing Parameters

1. Select the smart object on the canvas
2. Open the Properties panel
3. Adjust parameter values
4. The smart object re-renders with updated settings

Animation Support

Smart Objects can be animated:

• Frame Count: Total number of animation frames
• FPS: Playback speed (frames per second)
• Each frame calls the render function with an incrementing frameIndex
• Use frameIndex / totalFrames to calculate animation progress

Smart Objects as Transitions

Smart Objects can serve as custom scene transitions:

1. Open Scene Settings
2. Go to the Transition tab
3. Select Smart Object as the transition type
4. Choose a transition-category smart object
5. The cutTime property (0–1) specifies when the scene cut occurs during the transition

AI-Assisted Creation

FX Express can generate smart object code using AI:

1. Open the Smart Object editor
2. Click the AI generation button
3. Describe the visual effect you want
4. Review and edit the generated code
5. Save as a custom smart object

Performance

• Smart Object renders are cached using an LRU cache for efficiency
• Static smart objects render once and reuse the result
• Animated smart objects render per frame during playback
• Keep canvas operations simple for best performance

Troubleshooting

Smart Object Not Rendering

• Check for JavaScript errors in the code
• Verify all required parameters have values
• Ensure canvas dimensions are valid

Animation Stuttering

• Reduce frame count or complexity
• Check FPS setting (30fps is standard)
• Simplify drawing operations

Parameters Not Updating

• Re-select the element to refresh
• Check parameter types match expected values

---

← Previous: Variables | Next: Track Mattes →