aframe-troika-text

This package provides an A-Frame component and primitive for rendering three-dimensional text using Troika's text renderer.

It has similar performance and quality to A-Frame's built-in SDF text component, but brings some additional advantages:

• It reads font files directly (ttf, otf, woff) and does not require using an external tool to pre-generate SDF textures with the glyphs you think you'll need.

• It supports ligatures so you can use fonts like Material Icons.

• Rather than using a fully custom shader, it patches the built-in Three.js material shaders as needed, so you don't lose all the nice standard shader features like lighting and fog.

• Support for right-to-left/bidirectional language layout and shaping of Arabic text.

API

This package registers both a component (<a-entity troika-text="value:Hello" />) and a primitive (<a-troika-text value="Hello"></a-troika-text>). Use whichever is most convenient for you.

I've attempted to keep the API as close as possible to that of A-Frame's default text component and a-text primitive, however some things don't quite map exactly.

| Property on component | Attribute on primitive | Description | Default Value | |-----------------------|------------------------|-------------------------------------------------------------------------------------------------------------|---------------------------------| | align | align | Multi-line text alignment (left, center, right, justify). | left | | anchor | anchor | Horizontal positioning (left, center, right, align). | center | | baseline | baseline | Vertical positioning (top, center, bottom). | center | | clipRect | clip-rect | Four comma- or space-separated numbers defining a rectangle (minX, minY, maxX, maxY) outside which pixels will be hidden. | no clipping | | curveRadius | curve-radius | A cylindrical radius along which the text's plane will be curved. Positive = concave, negative = convex. | 0 | | color | color | Text color. This is a shortcut for specifying a custom material. | white | | depthOffset | depth-offset | Depth buffer offset to help prevent z-fighting. Negative numbers are closer to camera, positives further. | 0 | | direction | direction | Main bidi direction of the text: 'auto', 'ltr', or 'rtl' | 'auto' | | fillOpacity | fill-opacity | Opacity of the glyph's fill. | 1 | | font | font | URL to a font file - can be a .ttf, .otf, or .woff (no .woff2) or an <a-asset-item> id such as #font. | Roboto loaded from Google Fonts | | fontSize | font-size | Em-height at which to render the font, in meters. | 0.2 | | letterSpacing | letter-spacing | Letter spacing in meters. | 0 | | lineHeight | line-height | Line height as a multiple of the fontSize. | derived from font metrics | | maxWidth | max-width | Maximum width of the text block at which text will start wrapping, in meters. | Infinity (no wrapping) | | outlineBlur | outline-blur | A blur radius applied to the outer edge of the text's outlineWidth. | 0 | | outlineColor | outline-color | Color of an outline drawn around the glyph paths. | black | | outlineOffsetX | outline-offset-x | Horizontal offset of the outline (ala text-shadow), as a number in meters or a percentage of the font-size. | 0 | | outlineOffsetY | outline-offset-y | Vertical offset of the outline (ala text-shadow), as a number in meters or a percentage of the font-size. | 0 | | outlineOpacity | outline-opacity | Opacity of the outline, from 0 to 1. | 1 | | outlineWidth | outline-width | Width of an outline drawn around the glyph paths, as a number in meters or a percentage of the font-size. | 0 | | overflowWrap | overflow-wrap | Controls how text wraps: "normal" to break at whitespace characters, or "break-word" to break within words. | normal | | value | value | The actual content of the text. Line breaks and tabs are supported with \n and \t. | '' | | strokeColor | stroke-color | Color of a stroke drawn inside the glyph paths. | grey | | strokeOpacity | stroke-opacity | Opacity of the stroke, from 0 to 1. | 1 | | strokeWidth | stroke-width | Width of a stroke drawn inside the glyph paths, as a number in meters or a percentage of the font-size. | 0 | | textIndent | text-indent | Width of an indentation space to be added before the first character of a line. | 0 | | whiteSpace | white-space | How whitespace should be handled (i.e., normal, nowrap). | normal (behaves like pre-wrap) |

Note: It does not currently follow how the built-in text component interacts with a geometry component for auto-sizing and anchoring. I think that's a nice feature so it's probably worth adding; in the meantime just use the maxWidth and anchor/baseline attributes to control it manually.

Changing the material

By default the text will render using a MeshBasicMaterial using the color property described in the table above. But you can also change the material to gain more advanced shader features such as physically-based lighting.

If you are using the <a-troika-text> primitive, you can assign it a material component just as you would any other entity.

<a-troika-text
  value="Hello!"
  material="shader: standard; metalness: 0.8;"
></a-troika-text>

If you are using the troika-text="..." component, you must instead give it a troika-text-material="..." attribute to distinguish the text material from the entity's main material. You can pass it anything supported by the built in material component.

<a-entity
  troika-text="value: Hello!"
  troika-text-material="shader: standard; metalness: 0.8;"
></a-entity>

Installation

Browser

Install and use by directly including the browser files:

<head>
  <title>My A-Frame Scene</title>
  <script src="https://aframe.io/releases/1.3.0/aframe.min.js"></script>
  <script src="https://unpkg.com/aframe-troika-text/dist/aframe-troika-text.min.js"></script>
</head>

<body>
  <a-scene>
    <!-- As a component: -->
    <a-entity troika-text="value: Hello world!"></a-entity>
    
    <!-- As a primitive: -->
    <a-troika-text value="Hello world!"></a-troika-text>
  </a-scene>
</body>

npm

Install via npm:

npm install aframe-troika-text

Then require and use.

require('aframe');
require('aframe-troika-text');