Font Combinations

Font Combinations (also known as Text Components) are pre-designed text layouts that appear in your asset library. Users can click on these components to automatically insert them into their designs. This guide explains how to prepare and customize the content.json file that defines these components.

What are Font Combinations?#

Font Combinations are serialized text blocks or groups of text blocks configured with specific styling, layout constraints, and behavior. They provide users with professionally designed text layouts that are easy to customize while maintaining their visual integrity.

When users browse the asset library, they see thumbnails of these text components. Clicking on a component automatically loads and inserts it into their current scene.

Default Components#

CE.SDK ships with over 20 pre-built font combinations including:

• Box - Text with decorative border elements
• Breaking - Bold, attention-grabbing headlines
• Cinematic - Movie poster-style text effects
• Glow - Text with luminous glow effects
• Greetings - Welcoming message layouts
• Promo - Promotional and sale-focused designs
• Quote - Quote bubble and callout styles
• Speech - Dialog and conversation layouts
• Valentine - Romantic and heart-themed designs
• Handwriting - Script and handwritten font styles
• And many more…

Content.json Structure#

Font combinations are defined in a content.json file with the following structure:

{
  "version": "3.0.0",
  "id": "ly.img.textComponents",
  "assets": [
    {
      "id": "//ly.img.textComponents/box",
      "label": {
        "en": "Box"
      },
      "meta": {
        "uri": "{{base_url}}/ly.img.textComponents/data/Box.blocks",
        "thumbUri": "{{base_url}}/ly.img.textComponents/thumbnails/box.png",
        "mimeType": "application/ubq-blocks-string"
      }
    }
  ],
  "blocks": []
}

Key Properties#

• version: Content format version (currently “3.0.0”)
• id: Unique identifier for the asset source (“ly.img.textComponents”)
• assets: Array of component definitions

Asset Properties#

Each component in the assets array has:

• id: Unique identifier following the pattern //ly.img.textComponents/[name]
• label: Display name object with language codes (e.g., {"en": "Box"})
• meta:
  • uri: Path to the .blocks file containing the serialized component
  • thumbUri: Path to the thumbnail image (400x320px PNG recommended)
  • mimeType: Always "application/ubq-blocks-string" for text components

The {{base_url}} placeholder gets replaced with your configured base URL.

Creating Custom Components#

1. Design Your Component#

Follow these best practices when designing text components:

Text Settings#

• Use variable text with a range of 0-1000 characters
• Set fixed frame with clipping enabled
• Avoid growing or shrinking frames to prevent scaling issues

Constraints Setup#

• Parent Group: Give the parent group all available constraint options for maximum flexibility
• Child Elements: Set constraints relative to the parent group to maintain proper relationships during resizing

Design Considerations#

• Use scopes and auto font-size features to enable easy editing
• Test components by dropping them into new files to verify constraint behavior
• Ensure components work as cohesive units that are easy to edit but difficult to accidentally break

2. Export Your Component#

Once your design is ready:

1. Select the complete text component (parent group with all children)
2. Use the BlockAPI to serialize it:

// Save the component to a string format
val componentString = engine.block.saveToString(listOf(componentBlockId))

Important: Use saveToString() rather than saveToArchive(). The string format ensures that font and resource references remain valid when the component is used in different environments.

Resource Management#

Text components often reference external resources like fonts and images. When using saveToArchive(), these resources get stored as temporary buffer resources that only exist in the current editor instance. If you later save the scene containing these components using scene.saveToString(), the buffer resources are lost, resulting in missing references.

Using saveToString() ensures that:

• Font references remain valid across different environments
• Components can be safely used in any scene
• Serialized scenes maintain all resource references

Best Practices:

1. Ensure font availability: Make sure all fonts used in your components are available in the target environment
2. Test in isolation: Always test components in fresh editor instances to verify resource loading
3. Validate references: Check that all asset URIs are accessible from your target environments

3. Create Component Files#

Save the .blocks File#

Save the serialized component string to a .blocks file:

• Use descriptive names matching your component ID (e.g., CustomBox.blocks)
• Store in your /data/ directory structure

Create Thumbnails#

Generate 400x320px PNG thumbnails:

1. Remove page background color from your design
2. Export as PNG using the block export API:

// Export component as 400x320px thumbnail
val thumbnailBuffer = engine.block.export(
  block = componentBlockId,
  mimeType = MimeType.PNG,
  options = ExportOptions(
    targetWidth = 400f,
    targetHeight = 320f,
  )
)

// Save thumbnail to file
File.createTempFile("customBox", ".png")
  .apply { outputStream().channel.write(thumbnailBuffer) }

4. Update content.json#

Add your new component to the assets array:

{
  "id": "//ly.img.textComponents/customBox",
  "label": {
    "en": "Custom Box",
    "de": "Benutzerdefinierte Box"
  },
  "meta": {
    "uri": "{{base_url}}/ly.img.textComponents/data/CustomBox.blocks",
    "thumbUri": "{{base_url}}/ly.img.textComponents/thumbnails/customBox.png",
    "mimeType": "application/ubq-blocks-string"
  }
}

5. Use Custom Assets#

To customize your application to use your custom assets, refer to Serve Assets.

Your custom font combinations will now appear in the text components section of the asset library.