Dynamic text
Introduction¶
Control position, angle of each character drawn on a canvas.
- Author: Rex
- Game object
Live demos¶
- Wrap
- Page typing
- Align, rotation, drawBelowCallback
- Vertical wrap
- Character's world position
- Child input event
Usage¶
Install plugin¶
Load minify file¶
- Load plugin (minify file) in preload stage
scene.load.plugin('rexdynamictextplugin', 'https://raw.githubusercontent.com/rexrainbow/phaser3-rex-notes/master/dist/rexdynamictextplugin.min.js', true);
- Add dynamic-text object
var txt = scene.add.rexDynamicText(x, y, width, height, config);
Import plugin¶
- Install rex plugins from npm
npm i phaser3-rex-plugins
- Install plugin in configuration of game
import DynamicTextPlugin from 'phaser3-rex-plugins/plugins/dynamictext-plugin.js'; var config = { // ... plugins: { global: [{ key: 'rexDynamicTextPlugin', plugin: DynamicTextPlugin, start: true }, // ... ] } // ... }; var game = new Phaser.Game(config);
- Add dynamic-text object
var txt = scene.add.rexDynamicText(x, y, width, height, config);
Import class¶
- Install rex plugins from npm
npm i phaser3-rex-plugins
- Import class
import DynamicText from 'phaser3-rex-plugins/plugins/dynamictext.js';
- Add dynamic-text object
var txt = new DynamicText(scene, x, y, width, height, config); scene.add.existing(txt);
Create instance¶
var txt = scene.add.rexDynamicText({
x: 0,
y: 0,
width: undefined,
height: undefined,
resolution: 1,
padding: 0, // {left: 0, right: 0, top: 0, bottom: 0}
background: {
color: null,
color2: null,
horizontalGradient: true,
stroke: null,
strokeThickness: 2,
cornerRadius: 0,
cornerIteration: null
},
innerBounds: {
color: null,
color2: null,
horizontalGradient: true,
stroke: null,
strokeThickness: 2
},
style: {
bold: false,
italic: false,
fontSize: '16px',
fontFamily: 'Courier',
color: '#fff',
stroke: '#fff',
strokeThickness: 0,
shadowColor: null,
shadowOffsetX: 0,
shadowOffsetY: 0,
shadowBlur: 0,
backgroundColor: null,
backgroundHeight: undefined,
backgroundBottomY: undefined,
offsetX: 0,
offsetY: 0
},
childrenInteractive: false,
text: '',
wrap: undefined,
testString: '|MÉqgy',
});
x
,y
: Position of this dynamic-text game object.width
: Fixed width.- A number : Width of this dynamic-text game object.
- Wrap-width is
width - padding.left - padding.right
.
- Wrap-width is
undefined
: Width of this dynamic-text game object will be set after invokedrunWordWrap
method.
- A number : Width of this dynamic-text game object.
height
: Fixed height.- A number : Height of this dynamic-text game object.
undefined
: Height of this dynamic-text game object will be set after invokedrunWordWrap
method.
resolution
: The resolution the content is rendered to its internal canvas at. Default value is1
.padding
: Padding of bounds.- A number
padding.left
,padding.right
,padding.top
,padding.bottom
background
: Properties of background round-rectangle.background.color
: Fill color, number or string.null
: No filling.
background.color2
: Gradient fill color, number or string.null
: No gradient filling.
background.horizontalGradient
: Horizontal or vertical gradient filling.true
: Horizontal gradient filling.false
: Vertical gradient filling.
background.stroke
: Stroke color, number or string.null
: No stroke.
background.strokeThickness
: Line width of stroke.background.cornerRadius
: Corner-radius of round rectangle.background.cornerIteration
: Iteration of corner-radius.null
: Draw corner-radius via arc directly.- A number : Draw corner-radius via lines
innerBounds
: Properties of inner-bounds.innerBounds.color
: Fill color, number or string.null
: No filling.
innerBounds.color2
: Gradient fill color, number or string.null
: No gradient filling.
innerBounds.horizontalGradient
: Horizontal or vertical gradient filling.true
: Horizontal gradient filling.false
: Vertical gradient filling.
innerBounds.stroke
: Stroke color, number or string.null
: No stroke.
innerBounds.strokeThickness
: Line width of stroke.
style
: Initial text-style.style.bold
: Boldstyle.italic
: Italicstyle.fontSize
: Font size, number or string.style.fontFamily
: Font familystyle.color
: Fill color, number or string.style.stroke
: Stroke color, number or string.style.strokeThickness
: Line width of stroke.style.shadowColor
: Shadow color, number or string.null
: No shadow.
style.shadowOffsetX
: OffsetX of shadow.style.shadowOffsetY
: OffsetY of shadow.style.shadowBlur
: Blur of shadow.style.backgroundColor
: Background color of a character.style.backgroundHeight
,style.backgroundBottomY
: Background position and height of a character.undefined
, ornull
: Use height of character as background height. Default behavior.
style.offsetX
: OffsetX.style.offsetY
: OffsetY.style.align
: Override default line-alignment setting.0
,'left'
,'top'
: Align remainder lines to left/top.1
,'center'
: Align remainder lines to center.2
,'right'
,'bottom'
: Align remainder lines to right/bottom.undefined
: Use default line-alignment setting.
childrenInteractive
:true
: Fire input events ('child.pointerdown'
,'child.pointerup'
,'child.pointerover'
,'child.pointerout'
) of any child aftertext.setInteractive()
.false
: Won't fire any input events of child. Default behavior.
text
: Content of text.wrap
: Default configuration Horizontal/Vertical wrapping.testString
: Test string to get text ascent and text height with default text style.
or
var txt = scene.add.rexDynamicText(x, y, width, height, config);
or
var txt = scene.add.rexDynamicText(x, y, config);
Add dynamictext from JSON
var txt = scene.make.rexDynamicText({
x: 0,
y: 0,
// origin: {x: 0.5, y: 0.5},
// fill: null,
add: true
});
Custom class¶
- Define class
class MyDynamicText extends DynamicText { constructor(scene, x, y, width, height, config)) { super(scene, x, y, width, height, config)); // ... scene.add.existing(this); } // ... // preUpdate(time, delta) {} }
scene.add.existing(gameObject)
: Adds an existing Game Object to this Scene.- If the Game Object renders, it will be added to the Display List.
- If it has a
preUpdate
method, it will be added to the Update List.
- Create instance
var txt = new MyDynamicText(scene, x, y, config);
Clear content¶
txt.clearContent();
Text¶
Append text¶
txt.appendText(text);
or
txt.appendText(text,
{
// bold: false,
// italic: false,
// fontSize: '16px',
// fontFamily: 'Courier',
// color: '#fff',
// stroke: '#fff',
// strokeThickness: 0,
// shadowColor: null,
// shadowOffsetX: 0,
// shadowOffsetY: 0,
// shadowBlur: 0,
// backgroundColor: null,
// backgroundHeight: undefined,
// backgroundBottomY: undefined,
// offsetY: 0,
// offsetY: 0,
// align: undefined
}
);
To overwrite some properties of text-style.
Each character will be placed at position (0,0), without rotation. Uses word-wrap method to rearrange position of characters.
Set text¶
txt.setText(text);
or
txt.setText(text,
{
// bold: false,
// italic: false,
// fontSize: '16px',
// fontFamily: 'Courier',
// color: '#fff',
// stroke: '#fff',
// strokeThickness: 0,
// shadowColor: null,
// shadowOffsetX: 0,
// shadowOffsetY: 0,
// shadowBlur: 0,
// backgroundColor: null,
// backgroundHeight: undefined,
// backgroundBottomY: undefined,
// offsetY: 0,
// offsetY: 0,
// align: undefined
}
);
Insert text¶
txt.insertText(index, text);
txt.insertText(index, text,
{
// bold: false,
// italic: false,
// fontSize: '16px',
// fontFamily: 'Courier',
// color: '#fff',
// stroke: '#fff',
// strokeThickness: 0,
// shadowColor: null,
// shadowOffsetX: 0,
// shadowOffsetY: 0,
// shadowBlur: 0,
// backgroundColor: null,
// backgroundHeight: undefined,
// backgroundBottomY: undefined,
// offsetY: 0,
// offsetY: 0,
// align: undefined
}
);
Remove text¶
txt.removeText(index);
Get text¶
- Get active characters
or
var text = txt.text;
var text = txt.getText();
- Get all characters
var text = txt.getText(false);
Image¶
Append image¶
txt.appendImage(key, frame, {
// width: ,
// height: ,
// scaleX: ,
// scaleY: ,
// color: ,
})
width
: Scaled-width. Aspect-ratio will be kept if noheight
, orscaleY
is set.height
: Scaled-height. Aspect-ratio will be kept if nowidth
, orscaleX
is set.color
: Tint-fill color. Default isundefined
.
Background¶
- Fill style
txt.setBackgroundColor(color); // txt.setBackgroundColor(color, color2, isHorizontalGradient);
- Stroke style
txt.setBackgroundStroke(color, lineWidth);
- Corner radius
txt.setBackgroundCornerRadius(radius); // txt.setBackgroundCornerRadius(radius, iteration)
Inner bounds¶
- Fill style
txt.setInnerBoundsColor(color); // txt.setInnerBoundsColor(color, color2, isHorizontalGradient);
- Stroke style
txt.setInnerBoundsStroke(color, lineWidth);
Wrap¶
Control characters :
'\n'
: New line'\f'
: Page break
Horizontal wrap¶
var result = txt.runWordWrap({
padding: {
left: 0,
right: 0,
top: 0,
bottom: 0
},
ascent: undefined,
lineHeight: undefined,
useDefaultTextHeight: false,
maxLines: undefined,
wrapWidth: undefined,
wrapMode: 'word', // 1|'word'|2|'char'|'character'|3|'mix'
letterSpacing: 0,
hAlign: 0,
vAlign: 0,
});
padding
:padding.top
,padding.bottom
,padding.left
,padding.right
: Extra space around lines.
ascent
,lineHeight
: Height of first line and remainder linesascent
will set tolineHeight
ifascent
isundefined
butlineHeight
is notundefined
(backward compatible)- Get
ascent
,lineHeight
from default text style and test string, ifascent
,lineHeight
are bothundefined
useDefaultTextHeight
: If parameterlineHeight
is not given,false
: Set line height to (total line height / maxLines), if parametermaxLines
is larger than0
. Default behavior.true
: Set line height to default text height.
maxLines
: Lines number of this page.0
: Wrapping whole content.undefined
: It will be set iflineHeight
andheight
is given
wrapWidth
: Width of wrapping. Use inner width if this parameter isundefined
.wrapMode
:- No wrapping if
wrapWidth
, or inner width is not given. 1
, or'word'
: Word wrapping. Default behavior.2
, or'char'
, or'character'
: Character wrapping.3
, or'mix'
: Word wrapping for ASCII word, Character wrapping for other (unicode) word.
- No wrapping if
letterSpacing
: Space between each character.hAlign
: Horizontal alignment.0
, or'left'
: Align to left bound.1
, or'center'
: Align to center.2
, or'right'
: Align to right bound.3
,'justify'
,'justify-left'
: If remainder space is less or equal than 25%, then justify children. Else align children to left/top side.4
,'justify-right'
: If remainder space is less or equal than 25%, then justify children. Else align children to right/bottom side.5
,'justify-cneter'
: If remainder space is less or equal than 25%, then justify children. Else align children to center.
vAlign
: Vertical alignment.0
, or'top'
: Align to top bound.1
, or'center'
: Align to center.2
, or'bottom'
: Align to bottom bound.
Align¶
- Set vertical align mode
txt.setVAlign(vAlign);
vAlign
: Vertical alignment.0
, or'top'
: Align to top bound.1
, or'center'
: Align to center.2
, or'bottom'
: Align to bottom bound.
- Set horizontal align mode
txt.setHAlign(hAlign);
hAlign
: Horizontal alignment.0
, or'left'
: Align to left bound.1
, or'center'
: Align to center.2
, or'right'
: Align to right bound.
Test string¶
txt.setTestString(text);
Vertical wrap¶
var result = txt.runVerticalWrap({
padding: {
top: 0,
left: 0,
right: 0,
bottom: 0
},
lineWidth: undefined,
maxLines: undefined,
fixedChildHeight: undefined,
charPerLine: undefined,
wrapHeight: undefined,
letterSpacing: 0,
rtl: true,
hAlign: 0,
vAlign: 0,
});
padding
:padding.top
,padding.bottom
,padding.left
,padding.right
: Extra space around lines.
lineWidth
: Line width.undefined
: It will be set ifmaxLines
andfixedWidth
is given.
maxLines
: Lines number of this page.0
: Wrapping whole content.undefined
: It will be set iflineWidth
andfixedWidth
is given.
fixedChildHeight
: Each character has the same fixed height.undefined
: GetfixedChildHeight
according tocharPerLine
parameter. Or use height of each character iffixedChildHeight
andcharPerLine
parameters areundefined
.
charPerLine
: Amount of characters in each line, to getfixedChildHeight
.wrapHeight
: Height of wrappingletterSpacing
: Space between each character.rtl
:true
: Place lines from right to left.false
: Place lines from left to right.
hAlign
: Horizontal alignment.0
, or'left'
: Align to left bound. Default value ifrtl
is set tofalse
.1
, or'center'
: Align to center.2
, or'right'
: Align to right bound. Default value ifrtl
is set totrue
.
vAlign
: Vertical alignment.0
, or'top'
: Align to top bound.1
, or'center'
: Align to center.2
, or'bottom'
: Align to bottom bound.
Result¶
{
children: [],
lines: [],
isLastPage: false
}
children
: Character/Image data in this page.lines
: Array of line data. A line data contains{ children: [], width: 0, // Horizontal-wrapping height: 0, // Vertical-wrapping. }
isLastPage
:false
: Runtxt.runWordWrap(result)
/txt.runVerticalWrap(result)
to get next page of word-wrapping result.true
: No remainder of characters.
Wrap next page¶
var result = txt.runWordWrap(prevResult);
prevResult
: Result of previous word-wraping.result
: Current result of word-wraping.
Default configuration of wrapping¶
txt.setWrapConfig(config);
config
: Default configuration Horizontal/Vertical wrapping.
Scroll content¶
Scroll content by setting textOX
, textOY
members
- Set
or
txt.setTextOXY(x, y).updateTexture(); // txt.setTextOX(x).updateTexture(); // txt.setTextOY(x).updateTexture();
ortxt.addTextOXY(incX, incY).updateTexture(); // txt.addTextOX(incX).updateTexture(); // txt.addTextOY(incY).updateTexture();
txt.textOX = x; txt.textOY = y; txt.updateTexture();
- Get
var ox = txt.textOX; var oy = txt.textOY;
Child¶
General properties¶
- Visible :
- Get
var visible = child.visible;
- Set
or
child.setVisible(); // child.visible = true;
child.setVisible(false); // Set to invisible // child.visible = false;
- Get
- Alpha
- Get
var alpha = child.alpha;
- Set
child.setAlpha(alpha); // child.alpha = alpha;
- Get
- Position :
- Get
var x = child.x; var y = child.y;
- Set
child.setPosition(x, y); // child.x = x; // child.y = y;
- Get
- Angle :
- Get
var degrees = child.angle; // var radians = child.rotation;
- Set
child.setAngle(degrees); child.setRotation(radians); // child.angle = degrees; // child.rotation = radians;
- Get
- Scale
- Get
var scaleX = child.scaleX; var scaleY = child.scaleY;
- Set
child.setScale(scaleX, scaleY); // child.scaleX = scaleX; // child.scaleY = scaleY;
- Get
- Draw callbacks
- Set
child.setDrawBelowCallback(callback); child.setDrawAboveCallback(callback);
callback
:function(child) { var text = child.text; var context = child.context; // ... }
- Set
- World position
or
var worldXY = child.getWorldPosition(); // out = child.getWorldPosition(out);
var worldXY = txt.getCharWorldPosition(char); // out = txt.getCharWorldPosition(char, out);
Character¶
Text-style¶
- Get
var bold = char.style.bold; var italic = char.style.italic; var fontSize = char.style.fontSize; var fontFamily = char.style.fontFamily; var color = char.style.color; var stroke = char.style.stroke; var strokeThickness = char.style.strokeThickness; var shaodwColor = char.style.shadowColor; var shadowBlur = char.style.shadowBlur; var shadowOffsetX = char.style.shadowOffsetX; var shadowOffsetY = char.style.shadowOffsetY; var backgroundColor = char.style.backgroundColor; var backgroundHeight = char.style.backgroundHeight; var backgroundBottomY = char.style.backgroundBottomY; var xOffset = char.style.x; var yOffset = char.style.y;
- Set
or
char.modifyStyle({ // bold: false, // italic: false, // fontSize: '16px', // fontFamily: 'Courier', // color: '#fff', // stroke: '#fff', // strokeThickness: 0, // shaodwColor: null, // shadowBlur: 0, // shadowOffsetX: 0, // shadowOffsetY: 0, // backgroundColor: null, // backgroundHeight: undefined, // backgroundBottomY: undefined, // offsetX: 0, // offsetY: 0 })
char.setBold(); // char.setBold(false);
char.setItalic(); // char.setItalic(false);
char.setFontSize(fontSize); // number, string
char.setFontFamily(fontFamily);
char.setColor(color); // number, string // char.setColor(); // No filling color
char.setStrokeStyle(color, thickness); // char.setStrokeStyle(); // No stroke
char.setShadowColor(color); // char.setShadowColor(); // No shadow
char.setShadowOffset(offsetX, offsetY);
char.setShadowBlur(blur);
char.setBackgroundColor(color); // char.setBackgroundColor(); // No shadow
char.setOffsetX(offsetX); char.setOffsetY(offsetY);
Image¶
- Size
- Get
var width = image.width; var height = image.height;
- Set
image.setWidth(width); // image.setWidth(width, true); // Resize and keep aspect- ratio image.setHeight(height); // image.setHeight(height, true); // Resize and keep aspect- ratio
- Get
For each child¶
- Any child
- For each active child
txt.forEachChild(function(child, childIndex){ }, scope)
- For each character child
txt.forEachChild(function(child, childIndex){ }, scope, false);
- For each active child
- Renderable child
- For each active renderable child
txt.forEachRenderableChild(function(child, charIndex){ }, scope)
- For each renderable child
txt.forEachRenderableChild(function(child, charIndex){ }, scope, false);
- For each active renderable child
- Character child
- For each active character child
txt.forEachCharChild(function(child, charIndex){ }, scope)
- For each character child
txt.forEachCharChild(function(child, charIndex){ }, scope, false);
- For each active character child
Get children¶
- Get all children
var children = txt.getChildren();
- Get last appended children
var children = txt.getLastAppendedChildren();
- Get active children, after wrapping
var children = txt.getActiveChildren();
Get character children¶
- Get active character children
var children = txt.getCharChildren();
- Get all character children
var children = txt.getCharChildren(false);
- Get character child by character index
var child = txt.getCharChild(charIndex);
Move child¶
- Move child to fist
txt.moveChildToFist(child);
- Move child to last
txt.moveChildToLast(child);
- Move child up
txt.movechildUp(child);
- Move child to down
txt.movechildDown(child);
- Move child above another child
txt.movechildAbove(child, baseChild);
- Move child below another child
txt.movechildBelow(child, baseChild);
Size¶
- Resize canvas size
txt.setCanvasSize(width, height)
- Reisze text wrapping size and canvas size.
or
txt.setSize(width, height);
txt.setFixedSize(width, height);
- Resize to minimun size to show all visible characters.
txt.setToMinSize();
Input events of child¶
- Enable input events of child on config of constructor, or via method
txt.setChildrenInteractiveEnable();
- Pointer down/up on child
txt.on('child.pointerdown', function(child, pointer, localX, localY, event) { })
txt.on('child.pointerup', function(child, pointer, localX, localY, event) { })
- Pointer over/out on child
txt.on('child.pointerover', function(child, pointer, localX, localY, event) { })
txt.on('child.pointerout', function(child, pointer, localX, localY, event) { })
Other properties¶
See game object
Create mask¶
var mask = txt.createBitmapMask();
See mask
Shader effects¶
Support preFX and postFX effects
Compare with other kinds of text game object¶
- Built-in text:
- Single color per game object.
- Draw content line by line.
- Best render performance.
- BBCode text:
- Multiple colors, multiple font size per gaem object.
- Draw content segment by segment.
- Slower than built-in text game object.
- Dynamic text:
- Multiple colors, multiple font size per gaem object.
- Draw content character by character.
- Slower than bbcode text game object.