Components
A component is a thing you draw once and place many times. The drawing is the definition, each placed copy is an instance. Change the definition and every instance follows; change one instance and only that copy differs. Instances also carry their own values, which formulas read as Hero.speed.
Try it
Select a few shapes and press Ctrl+Shift+K. They become a component and the selection turns into one instance. Place a second copy and call the two Hero and Hero2.
Double-click Hero to open the definition. In the Custom Properties section add a number called health. Select a text inside, and write this in its content:
// Text inside the component: content
`Health: ${health}`Go back out. Each copy now has a health field in its panel, and the text follows it:
// Button: on click
Hero.health -= 10Hero loses 10, Hero2 keeps its own value.
What an instance can change
An instance stays linked to its definition. Anything you change on a copy is stored as an override on that copy only: the colour of one child, a position, a size, a custom property value. Set the value back to the definition's and the override disappears.
What you have not changed keeps following the definition. Edit the definition and every instance updates, including the paints (a colour changed in the definition changes every copy that did not override it).
- Shapes inside the definition are the same in every instance. Adding, removing or reordering them happens in the definition.
- Child properties (fill, size, position) can be overridden per instance.
- Custom properties are meant to be set per instance. Their default lives in the definition.
- Formulas, events and clips are part of the definition and run separately in each instance.
Each instance has its own state while the scene plays. Two copies of Hero can play different clips at the same time and neither affects the other.
Custom properties
Open the definition and use the Custom Properties section of the panel to add a property. Pick a name and a type. The panel offers number, integer, boolean, string, multiline text, range, percent, angle, axis, color, paint, point, enum and node reference.
The definition holds the default. Every instance shows the property in its own panel with its own value. From outside the component you address it like any property:
// Hero2.x
Hero.x + 200// Button: on click
Hero.speed = 5// Meter.w
Hero.health * 2Formulas that read Hero.health update when it changes. A value is animatable when its type can be interpolated, such as number or color.
When a property changes on an instance, the instance fires a change event with the property name and the new value.
this and names inside a component
Inside the definition, a custom property is a plain name. A formula on any child of the component reads it without a node name:
// Bar inside the component: w
health * 2From outside, the same value is Hero.health, and which copy you read depends on the instance you name. Inside, the name always means the copy the formula runs in. That is why one definition works for any number of instances: its formulas never name a specific copy.
this is the node that holds the formula, as everywhere. In a formula on Bar, this is Bar, not the component. To reach the component's own values use the property name (health). To reach another child of the component use its name (Label.content). ## Exposed instances
When a component contains other component instances, each one is exposed under a camelCase name made from its layer name: Left Arm becomes leftArm, eye mask becomes eyeMask. If two layers give the same name, they become head1 and head2.
An exposed instance can be reached from the parent with a path:
head.activeClipis the clip of the nestedhead.tail.rotationis the rotation of the nestedtail.head.leftEye.pupilDirectiongoes down more than one level.
These paths are what the timeline of the outer component records. Keyframe head.activeClip and the nested head changes clip as part of the outer animation, without copying the head. Skeleton and bone wrappers are skipped, so the body parts of a rig are exposed as a flat list.
The exposed paths appear in the panel of the instance, in a section per exposed child with its position, rotation and clip.
Slots with text
A text inside a component can show a property with the ${name} template, as in the first example. The text changes with each instance's own value, in the editor as well as while playing. This is the usual way to make one button with many labels.
Resizing
An instance can be resized like any shape. Its Scaling mode row in the panel has two modes (the default is Scale):
- Scale is the default. The whole drawing is scaled, content and all, like a placed picture.
- Resize changes the size of the instance and lays the children out again by their constraints. Pin a label to both sides in the definition and it stretches with the copy. A card made wider gets a wider body and the same margins.
Resize works when the definition allows it. The definition has the same Scaling mode row, set to Resize by default. Set it to Scale and its instances are locked to Scale.
Resizing one copy leaves the others as they were. When you edit the definition you work at the size you opened it.
Events
An instance has the same events as any shape: click, mouseenter, tick and the rest (see Events). A definition can also declare events of its own, and its instances list them next to the built-in ones.
A handler inside the definition runs inside that instance and can read its properties by name. A handler on the instance runs in the scene where the instance is placed.
Clips
A component can have several clips. Switch them from outside with Hero.play('walk') or by writing Hero.activeClip. The panel shows a Clip row when a component has more than one clip. See Clips and timeline control for play(), stopPlayback() and activeClip.
What is not there yet
- Non-visual components (a timer or a connection to a server) do not exist. A component always holds shapes. Use the
tickevent and delay() for timing. - To hand a value from inside to the outside, publish it as a custom property of the component.