BitmapText

Renders a PIXI.BitmapText. Bitmap fonts must be loaded before use.

PIXI.BitmapText description from PixiJS

source

A BitmapText Object will create a line or multiple lines of text.

To split a line you can use '\n' in your text string, or, on the style object, change its wordWrap property to true and and give the wordWrapWidth property a value.

The text is created using a bitmap font (a sprite sheet of characters).

The primary advantage of this render mode over text is that all of your textures are pre-generated and loaded, meaning that rendering is fast, and changing text is much faster than Text.

The primary disadvantage is that supporting character sets other than latin, such as CJK languages, may be impractical due to the number of characters.

Pre-loaded BitmapFonts:

PixiJS enables the loading of BitmapFonts through its Asset Manager, supporting both XML and FNT formats. Additionally, PixiJS is compatible with MSDF (Multi-channel Signed Distance Field) and SDF (Signed Distance Field) fonts. These advanced font types allow for scaling without quality degradation and must be created with specific tools, such as the one available at https://msdf-bmfont.donmccurdy.com/.

Dynamically Generated BitmapFonts:

PixiJS also offers the capability to generate BitmapFonts dynamically. This means that fonts are created in real-time based on specified styles, eliminating the need for pre-loading. This process is initiated simply by assigning a style to a BitmapText object, which then automatically generates the required font.

However, dynamically generating a large number of fonts may lead to significant memory use. To prevent this, PixiJS smartly attempts to reuse fonts that closely match the desired style parameters. For instance, if a text style requires a font size of 80 but a similar font of size 100 has already been generated, PixiJS will scale the existing font to fit the new requirement, rather than creating a new font from scratch.

For those who prefer to manage BitmapFonts manually, PixiJS provides the BitmapFont.install method. This method allows for the pre-generation and preparation of fonts, making them readily available for use by specifying the fontFamily in your text styling.

This approach ensures efficient font management within PixiJS, balancing between dynamic generation for flexibility and manual management for optimized performance.

Usage

Svelte 5

<script>
  import { AssetsLoader, BitmapText } from 'svelte-pixi'
</script>

<AssetsLoader assets={['/assets/desyrel.xml']}>
  <BitmapText
    text={'the fox jumps over\nthe lazy dog'}
    x={380}
    y={200}
    anchor={0.5}
    style={{ fontFamily: 'Desyrel', fontSize: 48, align: 'center' }}
  />
</AssetsLoader>

Svelte 4 (deprecated)

<script>
  import { AssetsLoader, BitmapText } from 'svelte-pixi/svelte-4'
</script>

<AssetsLoader assets={['/assets/desyrel.xml']}>
  <BitmapText
    text={'the fox jumps over\nthe lazy dog'}
    x={380}
    y={200}
    anchor={0.5}
    style={{ fontFamily: 'Desyrel', fontSize: 48, align: 'center' }}
  />
</AssetsLoader>

API

Svelte 5

Props

* denotes required

Name	Description
accessible	boolean Flag for if the object is accessible. If true AccessibilityManager will overlay a shadow div with attributes set
accessibleChildren	boolean Setting to false will prevent any children inside this container to be accessible. Defaults to true.
accessibleHint	nullstring Sets the aria-label attribute of the shadow div
accessiblePointerEvents	"visible""auto""none""visiblePainted""visibleFill""visibleStroke""painted""fill""stroke""all""inherit" Specify the pointer-events the accessible div will use Defaults to auto.
accessibleTitle	nullstring Sets the title attribute of the shadow div If accessibleTitle AND accessibleHint has not been this will default to 'container [tabIndex]'
accessibleType	string Specify the type of div the accessible layer is. Screen readers treat the element differently depending on this type. Defaults to button.
alpha	number
anchor	number[number, number]{ x: number; y: number }PIXI.Point The anchor sets the origin point of the text. The default is (0,0), this means the text's origin is the top left. Setting the anchor to (0.5,0.5) means the text's origin is centered. Setting the anchor to (1,1) would mean the text's origin point will be the bottom right corner. If you pass only single parameter, it will set both x and y to the same value as shown in the example below.
angle	number The angle of the object in degrees. 'rotation' and 'angle' have the same effect on a display object; rotation is in radians, angle is in degrees.
boundsArea	PIXI.Rectangle An optional bounds area for this container. Setting this rectangle will stop the renderer from recursively measuring the bounds of each children and instead use this single boundArea. This is great for optimisation! If for example you have a 1000 spinning particles and you know they all sit within a specific bounds, then setting it will mean the renderer will not need to measure the 1000 children to find the bounds. Instead it will just use the bounds you set.
cacheAsBitmap	boolean Legacy property for backwards compatibility with PixiJS v7 and below. Use cacheAsTexture instead.
cacheAsTexture	PIXI.CacheAsTextureOptionsboolean
cullable	boolean Should this object be rendered if the bounds of this object are out of frame? Culling has no effect on whether updateTransform is called.
cullableChildren	boolean Determines if the children to the container can be culled Setting this to false allows PixiJS to bypass a recursive culling function Which can help to optimize very complex scenes
cullArea	PIXI.Rectangle If set, this shape is used for culling instead of the bounds of this object. It can improve the culling performance of objects with many children. The culling area is defined in local space.
cursor	string The cursor preferred when the mouse pointer is hovering over.
effects	PIXI.Effect[]
eventMode	"auto""none""passive""static""dynamic" The mode of interaction for this object
filterArea	PIXI.Rectangle
filters	PIXI.FilterPIXI.Filter[]
height	number The height of the Container, setting this will actually modify the scale to achieve the value set.
hitArea	nullPIXI.IHitArea The hit-area specifies the area for which pointer events should be captured by this event target.
instance	T
interactive	boolean Whether this event target should fire UI events.
interactiveChildren	boolean Whether this event target has any children that need UI events. This can be used optimize event propagation.
isRenderGroup	boolean
label	string
mask	numberPIXI.Container<PIXI.ContainerChild>Partial<PIXI.MaskOptionsAndMask>
name	string
onadded	() => void Called when the instance is added to its parent or stage
onclick	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'click' event
oncreate	(instance: T) => void Called on creation of the component. You can use this to do any setup on the instance directly
onglobalmousemove	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'globalmousemove' event
onglobalpointermove	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'globalpointermove' event
onglobaltouchmove	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'globaltouchmove' event
onmousedown	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mousedown' event
onmouseenter	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mouseenter' event
onmouseleave	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mouseleave' event
onmousemove	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mousemove' event
onmouseout	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mouseout' event
onmouseover	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mouseover' event
onmouseup	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mouseup' event
onmouseupoutside	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'mouseupoutside' event
onpointercancel	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointercancel' event
onpointerdown	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointerdown' event
onpointerenter	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointerenter' event
onpointerleave	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointerleave' event
onpointermove	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointermove' event
onpointerout	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointerout' event
onpointerover	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointerover' event
onpointertap	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointertap' event
onpointerup	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointerup' event
onpointerupoutside	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'pointerupoutside' event
onremoved	() => void Called when the instance removed from its parent or stage
onrightclick	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'rightclick' event
onrightdown	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'rightdown' event
onrightup	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'rightup' event
onrightupoutside	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'rightupoutside' event
ontap	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'tap' event
ontouchcancel	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'touchcancel' event
ontouchend	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'touchend' event
ontouchendoutside	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'touchendoutside' event
ontouchmove	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'touchmove' event
ontouchstart	nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent> Handler for 'touchstart' event
pivot	number[number, number]{ x: number; y: number }PIXI.Point The center of rotation, scaling, and skewing for this display object in its local space. The position is the projection of pivot in the parent's local space. By default, the pivot is the origin (0, 0).
position	number[number, number]{ x: number; y: number }PIXI.Point The coordinate of the object relative to the local coordinates of the parent.
renderable	boolean Can this object be rendered, if false the object will not be drawn but the transform will still be updated.
rotation	number The rotation of the object in radians. 'rotation' and 'angle' have the same effect on a display object; rotation is in radians, angle is in degrees.
roundPixels	boolean Whether or not to round the x/y position of the sprite.
scale	number[number, number]{ x: number; y: number }PIXI.Point The scale factors of this object along the local coordinate axes. The default scale is (1, 1).
skew	number[number, number]{ x: number; y: number }PIXI.Point The skew factor for the object in radians.
sortableChildren	boolean
style	TEXT_STYLE
tabIndex	number
text	string Set the copy for the text object. To split a line you can use '\n'.
visible	boolean The visibility of the object. If false the object will not be drawn, and the transform will not be updated.
width	number The width of the Container, setting this will actually modify the scale to achieve the value set.
x	number The position of the container on the x axis relative to the local coordinates of the parent. An alias to position.x
y	number The position of the container on the y axis relative to the local coordinates of the parent. An alias to position.y
zIndex	number

Snippets

Name	Type
children	Snippet<[instance: T]>

Svelte 4 (deprecated)

Props

Name	Description
anchor	PointLike The anchor sets the origin point of the text.
instance	PIXI.BitmapText The PIXI.BitmapText instance. Can be set or bound to.
roundPixels	boolean If true PixiJS will Math.floor() x/y values when rendering, stopping pixel interpolation. Advantages can include sharper image quality (like text) and faster rendering on canvas. The main disadvantage is movement of objects may appear less smooth.
style	PIXI.IBitmapTextStyle Sets the style
text	string The text of the BitmapText object.

Additional props are passed on to Container

Slots

Name	Props	Fallback
default	{}

Events

Name	Type	Detail
added	forwarded
click	forwarded
globalmousemove	forwarded
globalpointermove	forwarded
globaltouchmove	forwarded
mousedown	forwarded
mousemove	forwarded
mouseout	forwarded
mouseover	forwarded
mouseup	forwarded
mouseupoutside	forwarded
pointercancel	forwarded
pointerdown	forwarded
pointermove	forwarded
pointerout	forwarded
pointerover	forwarded
pointertap	forwarded
pointerup	forwarded
pointerupoutside	forwarded
removed	forwarded
removedFrom	forwarded
rightclick	forwarded
rightdown	forwarded
rightup	forwarded
rightupoutside	forwarded
tap	forwarded
touchcancel	forwarded
touchend	forwarded
touchendoutside	forwarded
touchmove	forwarded
touchstart	forwarded