Creates a new Graphics object.
Optionaloptions: GraphicsContext | GraphicsOptionsOptions for the Graphics.
OptionalaccessibleFlag for if the object is accessible. If true AccessibilityManager will overlay a shadow div with attributes set
OptionalaccessibleSetting to false will prevent any children inside this container to be accessible. Defaults to true.
Optional AdvancedaccessibleSets the aria-label attribute of the shadow div
Optional AdvancedaccessibleSpecify the pointer-events the accessible div will use Defaults to auto.
OptionalaccessibleSets the text content of the shadow
OptionalaccessibleSets the title attribute of the shadow div If accessibleTitle AND accessibleHint has not been this will default to 'container [tabIndex]'
Optional AdvancedaccessibleSpecify the type of div the accessible layer is. Screen readers treat the element differently depending on this type. Defaults to button.
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.
Legacy property for backwards compatibility with PixiJS v7 and below.
Use cacheAsTexture instead.
Caches this container as a texture. This allows the container to be rendered as a single texture, which can improve performance for complex static containers.
If true, enables caching with default options. If false, disables caching. Can also pass options object to configure caching behavior.
// Basic caching
container.cacheAsTexture(true);
// With custom options
container.cacheAsTexture({
resolution: 2,
antialias: true,
});
// Disable caching
container.cacheAsTexture(false);
// Cache a complex UI
const ui = new Container();
// Add multiple children...
ui.cacheAsTexture(true);
ui.updateCacheTexture(); // Update if contents change
ReadonlychildrenThe array of children of this container. Each child must be a Container or extend from it.
The array is read-only, but its contents can be modified using Container methods.
// Access children
const firstChild = container.children[0];
const lastChild = container.children[container.children.length - 1];
OptionalcullableControls whether this object should be culled when out of view. When true, the object will not be rendered if its bounds are outside the visible area.
OptionalcullableControls whether children of this container can be culled. When false, skips recursive culling checks for better performance.
const container = new Container();
// Enable container culling
container.cullable = true;
// Disable child culling for performance
container.cullableChildren = false;
// Children will always render if container is visible
container.addChild(sprite1, sprite2, sprite3);
OptionalcullCustom shape used for culling calculations instead of object bounds. Defined in local space coordinates relative to the object.
Setting this to a custom Rectangle allows you to define a specific area for culling, which can improve performance by avoiding expensive bounds calculations.
const container = new Container();
// Define custom culling boundary
container.cullArea = new Rectangle(0, 0, 800, 600);
// Reset to use object bounds
container.cullArea = null;
OptionalcursorThe cursor style to display when the mouse pointer is hovering over the object. Accepts any valid CSS cursor value or custom cursor URL.
// Common cursor types
sprite.cursor = 'pointer'; // Hand cursor for clickable elements
sprite.cursor = 'grab'; // Grab cursor for draggable elements
sprite.cursor = 'crosshair'; // Precise cursor for selection
sprite.cursor = 'not-allowed'; // Indicate disabled state
// Direction cursors
sprite.cursor = 'n-resize'; // North resize
sprite.cursor = 'ew-resize'; // East-west resize
sprite.cursor = 'nesw-resize'; // Northeast-southwest resize
// Custom cursor with fallback
sprite.cursor = 'url("custom.png"), auto';
sprite.cursor = 'url("cursor.cur") 2 2, pointer'; // With hotspot offset
Whether this object has been destroyed. If true, the object should no longer be used. After an object is destroyed, all of its functionality is disabled and references are removed.
Container#destroy For destroying objects
Optional Advancedeffectstodo Needs docs
OptionaleventEnable interaction events for the Container. Touch, pointer and mouse events are supported.
const sprite = new Sprite(texture);
// Enable standard interaction (like buttons)
sprite.eventMode = 'static';
sprite.on('pointerdown', () => console.log('clicked!'));
// Enable for moving objects
sprite.eventMode = 'dynamic';
sprite.on('pointermove', () => updatePosition());
// Disable all interaction
sprite.eventMode = 'none';
// Only allow child interactions
sprite.eventMode = 'passive';
Available modes:
'none': Ignores all interaction events, even on its children. Best for pure visuals.'passive': (default) Does not emit events and ignores hit testing on itself and non-interactive
children. Interactive children will still emit events.'auto': Does not emit events but is hit tested if parent is interactive. Same as interactive = false in v7.'static': Emit events and is hit tested. Same as interactive = true in v7. Best for buttons/UI.'dynamic': Like static but also receives synthetic events when pointer is idle. Best for moving objects.Performance tips:
'none' for pure visual elements'passive' for containers with some interactive children'static' for standard UI elements'dynamic' only when needed for moving/animated elementsOptionalfilterThe area the filter is applied to. This is used as an optimization to define a specific region for filter effects instead of calculating the display object bounds each frame.
Setting this to a custom Rectangle allows you to define a specific area for filter effects, which can improve performance by avoiding expensive bounds calculations.
// Set specific filter area
container.filterArea = new Rectangle(0, 0, 100, 100);
// Optimize filter region
const screen = app.screen;
container.filterArea = new Rectangle(
screen.x,
screen.y,
screen.width,
screen.height
);
Readonly AdvancedgroupThe group transform is a transform relative to the render group it belongs too. If this container is render group then this will be an identity matrix. other wise it will be the same as the relativeGroupTransform. Use this value when actually rendering things to the screen
OptionalhitDefines a custom hit area for pointer interaction testing. When set, this shape will be used for hit testing instead of the container's standard bounds.
import { Rectangle, Circle, Sprite } from 'pixi.js';
// Rectangular hit area
const button = new Sprite(texture);
button.eventMode = 'static';
button.hitArea = new Rectangle(0, 0, 100, 50);
// Circular hit area
const icon = new Sprite(texture);
icon.eventMode = 'static';
icon.hitArea = new Circle(32, 32, 32);
// Custom hit area with polygon
const custom = new Sprite(texture);
custom.eventMode = 'static';
custom.hitArea = new Polygon([0,0, 100,0, 100,100, 0,100]);
// Custom hit testing logic
sprite.hitArea = {
contains(x: number, y: number) {
// Custom collision detection
return x >= 0 && x <= width && y >= 0 && y <= height;
}
};
OptionalinteractiveWhether this object should fire UI events. This is an alias for eventMode set to 'static' or 'passive'.
Setting this to true will enable interaction events like pointerdown, click, etc.
Setting it to false will disable all interaction events on this object.
OptionalinteractiveControls whether children of this container can receive pointer events.
Setting this to false allows PixiJS to skip hit testing on all children, improving performance for containers with many non-interactive children.
// Container with many visual-only children
const container = new Container();
container.interactiveChildren = false; // Skip hit testing children
// Menu with interactive buttons
const menu = new Container();
menu.interactiveChildren = true; // Test all children
menu.addChild(button1, button2, button3);
// Performance optimization
background.interactiveChildren = false;
foreground.interactiveChildren = true;
ReadonlyisWhether this container is currently cached as a texture.
Determines if the container is interactive or not
Whether the container is interactive or not
import { Sprite } from 'pixi.js';
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
sprite.isInteractive(); // true
sprite.eventMode = 'dynamic';
sprite.isInteractive(); // true
sprite.eventMode = 'none';
sprite.isInteractive(); // false
sprite.eventMode = 'passive';
sprite.isInteractive(); // false
sprite.eventMode = 'auto';
sprite.isInteractive(); // false
The instance label of the object.
ReadonlylocalCurrent transform of the object based on local factors: position, scale, other stuff. This matrix represents the local transformation without any parent influence.
// Basic transform access
const localMatrix = sprite.localTransform;
console.log(localMatrix.toString());
Sets a mask for the displayObject. A mask is an object that limits the visibility of an object to the shape of the mask applied to it.
In PixiJS a regular mask must be a Graphics or a Sprite object.
This allows for much faster masking in canvas as it utilities shape clipping.
Furthermore, a mask of an object must be in the subtree of its parent.
Otherwise, getLocalBounds may calculate incorrect bounds, which makes the container's width and height wrong.
For sprite mask both alpha and red channel are used. Black mask is the same as transparent mask.
// Apply mask to sprite
const sprite = new Sprite(texture);
sprite.mask = graphics;
// Remove mask
sprite.mask = null;
The instance name of the object.
OptionalonclickProperty-based event handler for the click event.
Fired when a pointer device (mouse, touch, etc.) completes a click action.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('click', (event) => {
console.log('Sprite clicked at:', event.global.x, event.global.y);
});
// Using property-based handler
sprite.onclick = (event) => {
console.log('Clicked at:', event.global.x, event.global.y);
};
OptionalonglobalmousemoveProperty-based event handler for the globalmousemove event.
Fired when the mouse moves anywhere, regardless of whether the pointer is over this object.
The object must have eventMode set to 'static' or 'dynamic' to receive this event.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('globalmousemove', (event) => {
// Move sprite to mouse position
sprite.position.copyFrom(event.global);
});
// Using property-based handler
sprite.onglobalmousemove = (event) => {
// Move sprite to mouse position
sprite.position.copyFrom(event.global);
};
OptionalonglobalpointermoveProperty-based event handler for the globalpointermove event.
Fired when the pointer moves anywhere, regardless of whether the pointer is over this object.
The object must have eventMode set to 'static' or 'dynamic' to receive this event.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('globalpointermove', (event) => {
sprite.position.set(event.global.x, event.global.y);
});
// Using property-based handler
sprite.onglobalpointermove = (event) => {
sprite.position.set(event.global.x, event.global.y);
};
OptionalonglobaltouchmoveProperty-based event handler for the globaltouchmove event.
Fired when a touch interaction moves anywhere, regardless of whether the pointer is over this object.
The object must have eventMode set to 'static' or 'dynamic' to receive this event.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('globaltouchmove', (event) => {
sprite.position.set(event.global.x, event.global.y);
});
// Using property-based handler
sprite.onglobaltouchmove = (event) => {
sprite.position.set(event.global.x, event.global.y);
};
OptionalonmousedownProperty-based event handler for the mousedown event.
Fired when a mouse button is pressed while the pointer is over the object.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('mousedown', (event) => {
sprite.alpha = 0.5; // Visual feedback
console.log('Mouse button:', event.button);
});
// Using property-based handler
sprite.onmousedown = (event) => {
sprite.alpha = 0.5; // Visual feedback
console.log('Mouse button:', event.button);
};
OptionalonmouseenterProperty-based event handler for the mouseenter event.
Fired when the mouse pointer enters the bounds of the object. Does not bubble.
OptionalonmouseleaveProperty-based event handler for the mouseleave event.
Fired when the pointer leaves the bounds of the display object. Does not bubble.
OptionalonmousemoveProperty-based event handler for the mousemove event.
Fired when the pointer moves while over the display object.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('mousemove', (event) => {
// Get coordinates relative to the sprite
console.log('Local:', event.getLocalPosition(sprite));
});
// Using property-based handler
sprite.onmousemove = (event) => {
// Get coordinates relative to the sprite
console.log('Local:', event.getLocalPosition(sprite));
};
OptionalonmouseoutProperty-based event handler for the mouseout event.
Fired when the pointer moves out of the bounds of the display object.
OptionalonmouseoverProperty-based event handler for the mouseover event.
Fired when the pointer moves onto the bounds of the display object.
OptionalonmouseupProperty-based event handler for the mouseup event.
Fired when a mouse button is released over the display object.
OptionalonmouseupoutsideProperty-based event handler for the mouseupoutside event.
Fired when a mouse button is released outside the display object that initially
registered a mousedown.
OptionalonpointercancelProperty-based event handler for the pointercancel event.
Fired when a pointer device interaction is canceled or lost.
OptionalonpointerdownProperty-based event handler for the pointerdown event.
Fired when a pointer device button (mouse, touch, pen, etc.) is pressed.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('pointerdown', (event) => {
sprite.position.set(event.global.x, event.global.y);
});
// Using property-based handler
sprite.onpointerdown = (event) => {
sprite.position.set(event.global.x, event.global.y);
};
OptionalonpointerenterProperty-based event handler for the pointerenter event.
Fired when a pointer device enters the bounds of the display object. Does not bubble.
OptionalonpointerleaveProperty-based event handler for the pointerleave event.
Fired when a pointer device leaves the bounds of the display object. Does not bubble.
OptionalonpointermoveProperty-based event handler for the pointermove event.
Fired when a pointer device moves while over the display object.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('pointermove', (event) => {
sprite.position.set(event.global.x, event.global.y);
});
// Using property-based handler
sprite.onpointermove = (event) => {
sprite.position.set(event.global.x, event.global.y);
};
OptionalonpointeroutProperty-based event handler for the pointerout event.
Fired when the pointer moves out of the bounds of the display object.
OptionalonpointeroverProperty-based event handler for the pointerover event.
Fired when the pointer moves over the bounds of the display object.
OptionalonpointertapProperty-based event handler for the pointertap event.
Fired when a pointer device completes a tap action (e.g., touch or mouse click).
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('pointertap', (event) => {
console.log('Sprite tapped at:', event.global.x, event.global.y);
});
// Using property-based handler
sprite.onpointertap = (event) => {
console.log('Sprite tapped at:', event.global.x, event.global.y);
};
OptionalonpointerupProperty-based event handler for the pointerup event.
Fired when a pointer device button (mouse, touch, pen, etc.) is released.
OptionalonpointerupoutsideProperty-based event handler for the pointerupoutside event.
Fired when a pointer device button is released outside the bounds of the display object
that initially registered a pointerdown.
This callback is used when the container is rendered. It runs every frame during the render process, making it ideal for per-frame updates and animations.
In v7 many users used updateTransform for this, however the way v8 renders objects is different
and "updateTransform" is no longer called every frame
// Basic rotation animation
const container = new Container();
container.onRender = () => {
container.rotation += 0.01;
};
// Cleanup when done
container.onRender = null; // Removes callback
Renderer For renderer capabilities
OptionalonrightclickProperty-based event handler for the rightclick event.
Fired when a right-click (context menu) action is performed on the object.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('rightclick', (event) => {
console.log('Right-clicked at:', event.global.x, event.global.y);
});
// Using property-based handler
sprite.onrightclick = (event) => {
console.log('Right-clicked at:', event.global.x, event.global.y);
};
OptionalonrightdownProperty-based event handler for the rightdown event.
Fired when a right mouse button is pressed down over the display object.
OptionalonrightupProperty-based event handler for the rightup event.
Fired when a right mouse button is released over the display object.
OptionalonrightupoutsideProperty-based event handler for the rightupoutside event.
Fired when a right mouse button is released outside the bounds of the display object
that initially registered a rightdown.
OptionalontapProperty-based event handler for the tap event.
Fired when a tap action (touch) is completed on the object.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('tap', (event) => {
console.log('Sprite tapped at:', event.global.x, event.global.y);
});
// Using property-based handler
sprite.ontap = (event) => {
console.log('Sprite tapped at:', event.global.x, event.global.y);
};
OptionalontouchcancelProperty-based event handler for the touchcancel event.
Fired when a touch interaction is canceled, such as when the touch is interrupted.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('touchcancel', (event) => {
console.log('Touch canceled at:', event.global.x, event.global.y);
});
// Using property-based handler
sprite.ontouchcancel = (event) => {
console.log('Touch canceled at:', event.global.x, event.global.y);
};
OptionalontouchendProperty-based event handler for the touchend event.
Fired when a touch interaction ends, such as when the finger is lifted from the screen.
OptionalontouchendoutsideProperty-based event handler for the touchendoutside event.
Fired when a touch interaction ends outside the bounds of the display object
that initially registered a touchstart.
OptionalontouchmoveProperty-based event handler for the touchmove event.
Fired when a touch interaction moves while over the display object.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('touchmove', (event) => {
sprite.position.set(event.global.x, event.global.y);
});
// Using property-based handler
sprite.ontouchmove = (event) => {
sprite.position.set(event.global.x, event.global.y);
};
OptionalontouchstartProperty-based event handler for the touchstart event.
Fired when a touch interaction starts, such as when a finger touches the screen.
OptionalonwheelProperty-based event handler for the wheel event.
Fired when the mouse wheel is scrolled while over the display object.
const sprite = new Sprite(texture);
sprite.eventMode = 'static';
// Using emitter handler
sprite.on('wheel', (event) => {
sprite.scale.x += event.deltaY * 0.01; // Zoom in/out
sprite.scale.y += event.deltaY * 0.01; // Zoom in/out
});
// Using property-based handler
sprite.onwheel = (event) => {
sprite.scale.x += event.deltaY * 0.01; // Zoom in/out
sprite.scale.y += event.deltaY * 0.01; // Zoom in/out
};
ReadonlyparentThe display object container that contains this display object. This represents the parent-child relationship in the display tree.
// Basic parent access
const parent = sprite.parent;
// Walk up the tree
let current = sprite;
while (current.parent) {
console.log('Level up:', current.parent.constructor.name);
current = current.parent;
}
Readonly AdvancedparentThe RenderLayer this container belongs to, if any. If it belongs to a RenderLayer, it will be rendered from the RenderLayer's position in the scene.
Readonly AdvancedrelativeThe relative group transform is a transform relative to the render group it belongs too. It will include all parent transforms and up to the render group (think of it as kind of like a stage - but the stage can be nested). If this container is is self a render group matrix will be relative to its parent render group
If set to true, the container will sort its children by zIndex value
when the next render is called, or manually if sortChildren() is called.
This actually changes the order of elements in the array of children, so it will affect the rendering order.
Also be aware of that this may not work nicely with the addChildAt() function,
as the zIndex sorting may cause the child to automatically sorted to another position.
Sorts children by zIndex value. Only sorts if container is marked as dirty.
OptionaltabSets the tabIndex of the shadow div. You can use this to set the order of the elements when using the tab key to navigate.
Updates the cached texture of this container. This will flag the container's cached texture to be redrawn on the next render.
The zIndex of the container.
Controls the rendering order of children within their parent container.
A higher value will mean it will be moved towards the front of the rendering order.
// Add in any order
container.addChild(character, background, foreground);
// Adjust rendering order
background.zIndex = 0;
character.zIndex = 1;
foreground.zIndex = 2;
The opacity of the object relative to its parent's opacity. Value ranges from 0 (fully transparent) to 1 (fully opaque).
// Basic transparency
sprite.alpha = 0.5; // 50% opacity
// Inherited opacity
container.alpha = 0.5;
const child = new Sprite(texture);
child.alpha = 0.5;
container.addChild(child);
// child's effective opacity is 0.25 (0.5 * 0.5)
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.
The blend mode to be applied to the sprite. Controls how pixels are blended when rendering.
Setting to 'normal' will reset to default blending.
More blend modes are available after importing the pixi.js/advanced-blend-modes sub-export.
// Basic blend modes
sprite.blendMode = 'add'; // Additive blending
sprite.blendMode = 'multiply'; // Multiply colors
sprite.blendMode = 'screen'; // Screen blend
// Reset blend mode
sprite.blendMode = 'normal'; // Normal blending
The local bounds of the graphics object. Returns the boundaries after all graphical operations but before any transforms.
const graphics = new Graphics();
// Draw a shape
graphics
.rect(0, 0, 100, 100)
.fill({ color: 0xff0000 });
// Get bounds information
const bounds = graphics.bounds;
console.log(bounds.width); // 100
console.log(bounds.height); // 100
The underlying graphics context used for drawing operations. Controls how shapes and paths are rendered.
// Create a shared context
const sharedContext = new GraphicsContext();
// Create graphics objects sharing the same context
const graphics1 = new Graphics();
const graphics2 = new Graphics();
// Assign shared context
graphics1.context = sharedContext;
graphics2.context = sharedContext;
// Both graphics will show the same shapes
sharedContext
.rect(0, 0, 100, 100)
.fill({ color: 0xff0000 });
Gets or sets the current fill style for the graphics context. The fill style determines how shapes are filled when using the fill() method.
const graphics = new Graphics();
// Basic color fill
graphics.fillStyle = {
color: 0xff0000, // Red
alpha: 1
};
// Using gradients
const gradient = new FillGradient({
end: { x: 0, y: 1 }, // Vertical gradient
stops: [
{ offset: 0, color: 0xff0000, alpha: 1 }, // Start color
{ offset: 1, color: 0x0000ff, alpha: 1 } // End color
]
});
graphics.fillStyle = {
fill: gradient,
alpha: 0.8
};
// Using patterns
graphics.fillStyle = {
texture: myTexture,
alpha: 1,
matrix: new Matrix()
.scale(0.5, 0.5)
.rotate(Math.PI / 4)
};
Sets the filters for the displayObject. Filters are visual effects that can be applied to any display object and its children.
This is a WebGL/WebGPU only feature and will be ignored by the canvas renderer.
// Add a single filter
sprite.filters = new BlurFilter(2);
// Apply multiple filters
container.filters = [
new BlurFilter(2),
new ColorMatrixFilter(),
];
// Remove filters
sprite.filters = null;
Filter For filter base class
The height of the Container,
Changing the height will adjust the scale.y property of the container while maintaining its aspect ratio. [!NOTE] If you want to set both width and height at the same time, use Container#setSize as it is more optimized by not recalculating the local bounds twice.
AdvancedWhether or not the object should be rendered.
AdvancedReturns true if this container is a render group. This means that it will be rendered as a separate pass, with its own set of instructions
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).
The coordinate of the object relative to the local coordinates of the parent.
Controls whether this object can be rendered. If false the object will not be drawn, but the transform will still be updated. This is different from visible, which skips transform updates.
// Basic render control
sprite.renderable = false; // Skip rendering
sprite.renderable = true; // Enable rendering
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.
Whether or not to round the x/y position of the object.
The scale factors of this object along the local coordinate axes.
The default scale is (1, 1).
The skew factor for the object in radians. Skewing is a transformation that distorts the object by rotating it differently at each point, creating a non-uniform shape.
// Basic skewing
container.skew.set(0.5, 0); // Skew horizontally
container.skew.set(0, 0.5); // Skew vertically
// Skew with point data
container.skew = { x: 0.3, y: 0.3 }; // Diagonal skew
// Reset skew
container.skew.set(0, 0);
// Animate skew
app.ticker.add(() => {
// Create wave effect
container.skew.x = Math.sin(Date.now() / 1000) * 0.3;
});
// Combine with rotation
container.rotation = Math.PI / 4; // 45 degrees
container.skew.set(0.2, 0.2); // Skew the rotated object
Gets or sets the current stroke style for the graphics context. The stroke style determines how paths are outlined when using the stroke() method.
const graphics = new Graphics();
// Basic stroke style
graphics.strokeStyle = {
width: 2,
color: 0xff0000,
alpha: 1
};
// Using with gradients
const gradient = new FillGradient({
end: { x: 0, y: 1 },
stops: [
{ offset: 0, color: 0xff0000, alpha: 1 },
{ offset: 1, color: 0x0000ff, alpha: 1 }
]
});
graphics.strokeStyle = {
width: 4,
fill: gradient,
alignment: 0.5,
join: 'round',
cap: 'round'
};
// Complex stroke settings
graphics.strokeStyle = {
width: 6,
color: 0x00ff00,
alpha: 0.5,
join: 'miter',
miterLimit: 10,
};
The tint applied to the sprite.
This can be any valid ColorSource.
// Basic color tinting
container.tint = 0xff0000; // Red tint
container.tint = 'red'; // Same as above
container.tint = '#00ff00'; // Green
container.tint = 'rgb(0,0,255)'; // Blue
// Remove tint
container.tint = 0xffffff; // White = no tint
container.tint = null; // Also removes tint
The visibility of the object. If false the object will not be drawn, and the transform will not be updated.
// Basic visibility toggle
sprite.visible = false; // Hide sprite
sprite.visible = true; // Show sprite
The width of the Container, setting this will actually modify the scale to achieve the value set.
Changing the width will adjust the scale.x property of the container while maintaining its aspect ratio. [!NOTE] If you want to set both width and height at the same time, use Container#setSize as it is more optimized by not recalculating the local bounds twice.
Current transform of the object based on world (parent) factors.
This matrix represents the absolute transformation in the scene graph.
// Get world position
const worldPos = container.worldTransform;
console.log(`World position: (${worldPos.tx}, ${worldPos.ty})`);
Container#localTransform For local space transform
Adds one or more children to the container. The children will be rendered as part of this container's display list.
The Container(s) to add to the container
The first child that was added
// Add a single child
container.addChild(sprite);
// Add multiple children
container.addChild(background, player, foreground);
// Add with type checking
const sprite = container.addChild<Sprite>(new Sprite(texture));
sprite.tint = 'red';
Adds a child to the container at a specified index. If the index is out of bounds an error will be thrown. If the child is already in this container, it will be moved to the specified index.
The child to add
The index where the child will be placed
The child that was added
// Add at specific index
container.addChildAt(sprite, 0); // Add to front
// Move existing child
const index = container.children.length - 1;
container.addChildAt(existingChild, index); // Move to back
// With error handling
try {
container.addChildAt(sprite, 1000);
} catch (e) {
console.warn('Index out of bounds');
}
Unlike on or addListener which are methods from EventEmitter, addEventListener
seeks to be compatible with the DOM's addEventListener with support for options.
The type of event to listen to.
The listener callback or object.
Optionaloptions: AddListenerOptionsListener options, used for capture phase.
// Tell the user whether they did a single, double, triple, or nth click.
button.addEventListener('click', {
handleEvent(e): {
let prefix;
switch (e.detail) {
case 1: prefix = 'single'; break;
case 2: prefix = 'double'; break;
case 3: prefix = 'triple'; break;
default: prefix = e.detail + 'th'; break;
}
console.log('That was a ' + prefix + 'click');
}
});
// But skip the first click!
button.parent.addEventListener('click', function blockClickOnce(e) {
e.stopImmediatePropagation();
button.parent.removeEventListener('click', blockClickOnce, true);
}, {
capture: true,
});
Optionaloptions: AddListenerOptionsAdds an arc to the current path, which is centered at (x, y) with the specified radius, starting and ending angles, and direction.
The x-coordinate of the arc's center
The y-coordinate of the arc's center
The arc's radius (must be positive)
The starting point of the arc, in radians
The end point of the arc, in radians
Optionalcounterclockwise: booleanOptional. If true, draws the arc counterclockwise. If false (default), draws clockwise.
The Graphics instance for method chaining
// Draw a simple arc (quarter circle)
const graphics = new Graphics();
graphics
.arc(100, 100, 50, 0, Math.PI/2)
.stroke({ width: 2, color: 0xff0000 });
// Draw a full circle using an arc
graphics
.arc(200, 200, 30, 0, Math.PI * 2)
.stroke({ color: 0x00ff00 });
// Draw a counterclockwise arc
graphics
.arc(150, 150, 40, Math.PI, 0, true)
.stroke({ width: 2, color: 0x0000ff });
Adds an arc to the current path that connects two points using a radius. The arc is drawn between the current point and the specified end point, using the given control point to determine the curve of the arc.
The x-coordinate of the control point
The y-coordinate of the control point
The x-coordinate of the end point
The y-coordinate of the end point
The radius of the arc in pixels (must be positive)
The Graphics instance for method chaining
// Draw a simple curved corner
const graphics = new Graphics();
graphics
.moveTo(50, 50)
.arcTo(100, 50, 100, 100, 20) // Rounded corner with 20px radius
.stroke({ width: 2, color: 0xff0000 });
// Create a rounded rectangle using arcTo
graphics
.moveTo(150, 150)
.arcTo(250, 150, 250, 250, 30) // Top right corner
.arcTo(250, 250, 150, 250, 30) // Bottom right corner
.arcTo(150, 250, 150, 150, 30) // Bottom left corner
.arcTo(150, 150, 250, 150, 30) // Top left corner
.fill({ color: 0x00ff00 });
Adds an SVG-style arc to the path, allowing for elliptical arcs based on the SVG spec. This is particularly useful when converting SVG paths to Graphics or creating complex curved shapes.
The x-radius of the ellipse (must be non-negative)
The y-radius of the ellipse (must be non-negative)
The rotation of the ellipse's x-axis relative to the x-axis, in degrees
Either 0 or 1, determines if the larger of the two possible arcs is chosen (1) or not (0)
Either 0 or 1, determines if the arc should be swept in a positive angle direction (1) or negative (0)
The x-coordinate of the arc's end point
The y-coordinate of the arc's end point
The Graphics instance for method chaining
// Draw a simple elliptical arc
const graphics = new Graphics();
graphics
.moveTo(100, 100)
.arcToSvg(50, 30, 0, 0, 1, 200, 100)
.stroke({ width: 2, color: 0xff0000 });
// Create a complex path with rotated elliptical arc
graphics
.moveTo(150, 150)
.arcToSvg(
60, // rx
30, // ry
45, // x-axis rotation (45 degrees)
1, // large arc flag
0, // sweep flag
250, // end x
200 // end y
)
.stroke({ width: 4, color: 0x00ff00 });
// Chain multiple arcs for complex shapes
graphics
.moveTo(300, 100)
.arcToSvg(40, 20, 0, 0, 1, 350, 150)
.arcToSvg(40, 20, 0, 0, 1, 300, 200)
.fill({ color: 0x0000ff, alpha: 0.5 });
Optionalalpha: numbersince 8.0.0 Use Graphics#fill instead
Resets the current path. Any previous path and its commands are discarded and a new path is started. This is typically called before beginning a new shape or series of drawing commands.
The Graphics instance for chaining
const graphics = new Graphics();
graphics
.circle(150, 150, 50)
.fill({ color: 0x00ff00 })
.beginPath() // Starts a new path
.circle(250, 150, 50)
.fill({ color: 0x0000ff });
Adds a cubic Bézier curve to the path, from the current point to the specified end point. The curve is influenced by two control points that define its shape and curvature.
The x-coordinate of the first control point
The y-coordinate of the first control point
The x-coordinate of the second control point
The y-coordinate of the second control point
The x-coordinate of the end point
The y-coordinate of the end point
Optionalsmoothness: numberOptional parameter to adjust the curve's smoothness (0-1)
The Graphics instance for method chaining
// Draw a simple curved line
const graphics = new Graphics();
graphics
.moveTo(50, 50)
.bezierCurveTo(
100, 25, // First control point
150, 75, // Second control point
200, 50 // End point
)
.stroke({ width: 2, color: 0xff0000 });
// Adjust curve smoothness
graphics
.moveTo(50, 200)
.bezierCurveTo(
100, 150,
200, 250,
250, 200,
0.5 // Smoothness factor
)
.stroke({ width: 4, color: 0x0000ff });
Draws a rectangle with chamfered (angled) corners. Each corner is cut off at a 45-degree angle based on the chamfer size.
The x-coordinate of the top-left corner of the rectangle
The y-coordinate of the top-left corner of the rectangle
The width of the rectangle
The height of the rectangle
The size of the corner chamfers (must be non-zero)
Optionaltransform: MatrixOptional Matrix to transform the rectangle
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a basic chamfered rectangle
graphics
.chamferRect(50, 50, 100, 80, 15)
.fill({ color: 0xff0000 });
// Add transform and stroke
const transform = new Matrix()
.rotate(Math.PI / 4); // 45 degrees
graphics
.chamferRect(200, 50, 100, 80, 20, transform)
.fill({ color: 0x00ff00 })
.stroke({ width: 2, color: 0x000000 });
Draws a circle shape at the specified location with the given radius.
The x-coordinate of the center of the circle
The y-coordinate of the center of the circle
The radius of the circle
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a simple filled circle
graphics
.circle(100, 100, 50)
.fill({ color: 0xff0000 });
// Draw a circle with gradient fill
const gradient = new FillGradient({
end: { x: 1, y: 0 },
colorStops: [
{ offset: 0, color: 0xff0000 }, // Red at start
{ offset: 0.5, color: 0x00ff00 }, // Green at middle
{ offset: 1, color: 0x0000ff }, // Blue at end
],
});
graphics
.circle(250, 100, 40)
.fill({ fill: gradient });
Clears all drawing commands from the graphics context, effectively resetting it. This includes clearing the current path, fill style, stroke style, and transformations.
Graphics objects are not designed to be continuously cleared and redrawn. Instead, they are intended to be used for static or semi-static graphics that can be redrawn as needed. Frequent clearing and redrawing may lead to performance issues.
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw some shapes
graphics
.circle(100, 100, 50)
.fill({ color: 0xff0000 })
.rect(200, 100, 100, 50)
.fill({ color: 0x00ff00 });
// Clear all graphics
graphics.clear();
// Start fresh with new shapes
graphics
.circle(150, 150, 30)
.fill({ color: 0x0000ff });
Creates a new Graphics object that copies the current graphics content. The clone can either share the same context (shallow clone) or have its own independent context (deep clone).
Whether to create a deep clone of the graphics object. If false (default), the context will be shared between objects. If true, creates an independent copy of the context.
A new Graphics instance with either shared or copied context
const graphics = new Graphics();
// Create original graphics content
graphics
.circle(100, 100, 50)
.fill({ color: 0xff0000 });
// Create a shallow clone (shared context)
const shallowClone = graphics.clone();
// Changes to original affect the clone
graphics
.circle(200, 100, 30)
.fill({ color: 0x00ff00 });
// Create a deep clone (independent context)
const deepClone = graphics.clone(true);
// Modify deep clone independently
deepClone
.translateTransform(100, 100)
.circle(0, 0, 40)
.fill({ color: 0x0000ff });
Closes the current path by drawing a straight line back to the start point.
This is useful for completing shapes and ensuring they are properly closed for fills.
The Graphics instance for method chaining
// Create a triangle with closed path
const graphics = new Graphics();
graphics
.moveTo(50, 50)
.lineTo(100, 100)
.lineTo(0, 100)
.closePath()
Checks if the object contains the given point. Returns true if the point lies within the Graphics object's rendered area.
The point to check in local coordinates
True if the point is inside the Graphics object
const graphics = new Graphics();
// Draw a shape
graphics
.rect(0, 0, 100, 100)
.fill({ color: 0xff0000 });
// Check point intersection
if (graphics.containsPoint({ x: 50, y: 50 })) {
console.log('Point is inside rectangle!');
}
Applies a cutout to the last drawn shape. This is used to create holes or complex shapes by subtracting a path from the previously drawn path.
If a hole is not completely in a shape, it will fail to cut correctly.
Destroys this graphics renderable and optionally its context.
Optionaloptions: DestroyOptionsOptions parameter. A boolean will act as if all options
If the context was created by this graphics and destroy(false) or destroy() is called
then the context will still be destroyed.
If you want to explicitly not destroy this context that this graphics created, then you should pass destroy({ context: false })
If the context was passed in as an argument to the constructor then it will not be destroyed
AdvancedThis will disable the render group for this container.
Dispatch the event on this Container using the event's EventBoundary.
The target of the event is set to this and the defaultPrevented flag is cleared before dispatch.
The event to dispatch.
Whether the preventDefault() method was not invoked.
since 8.0.0 Use Graphics#circle instead
since 8.0.0 Use Graphics#ellipse instead
since 8.0.0 Use Graphics#poly instead
since 8.0.0 Use Graphics#rect instead
since 8.0.0 Use Graphics#roundRect instead
since 8.0.0 Use Graphics#star instead
Draws an ellipse at the specified location and with the given x and y radii. An optional transformation can be applied, allowing for rotation, scaling, and translation.
The x-coordinate of the center of the ellipse
The y-coordinate of the center of the ellipse
The horizontal radius of the ellipse
The vertical radius of the ellipse
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a basic ellipse
graphics
.ellipse(100, 100, 50, 30)
.fill({ color: 0xff0000 });
// Draw an ellipse with stroke
graphics
.ellipse(200, 100, 70, 40)
.stroke({ width: 2, color: 0x00ff00 });
AdvancedCalling this enables a render group for this container. This means it will be rendered as a separate set of instructions. The transform of the container will also be handled on the GPU rather than the CPU.
since 8.0.0 Use Graphics#fill instead
Fills the current or given path with the current fill style or specified style.
Optionalstyle: FillInputThe style to fill the path with. Can be:
The Graphics instance for chaining
const graphics = new Graphics();
// Fill with direct color
graphics
.circle(50, 50, 25)
.fill('red'); // Red fill
// Fill with texture
graphics
.rect(0, 0, 100, 100)
.fill(myTexture); // Fill with texture
// Fill with complex style
graphics
.rect(0, 0, 100, 100)
.fill({
color: 0x00ff00,
alpha: 0.5,
texture: myTexture,
matrix: new Matrix()
});
// Fill with gradient
const gradient = new FillGradient({
end: { x: 1, y: 0 },
colorStops: [
{ offset: 0, color: 0xff0000 },
{ offset: 0.5, color: 0x00ff00 },
{ offset: 1, color: 0x0000ff },
],
});
graphics
.circle(100, 100, 50)
.fill(gradient);
Draws a rectangle with fillet corners. Unlike rounded rectangles, this supports negative corner radii which create external rounded corners rather than internal ones.
The x-coordinate of the top-left corner of the rectangle
The y-coordinate of the top-left corner of the rectangle
The width of the rectangle
The height of the rectangle
The radius of the corner fillets (can be positive or negative)
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a rectangle with internal fillets
graphics
.filletRect(50, 50, 100, 80, 15)
.fill({ color: 0xff0000 });
// Draw a rectangle with external fillets
graphics
.filletRect(200, 50, 100, 80, -20)
.fill({ color: 0x00ff00 })
.stroke({ width: 2, color: 0x000000 });
Calculates and returns the (world) bounds of the display object as a Rectangle. Takes into account transforms and child bounds.
OptionalskipUpdate: booleanSetting to true will stop the transforms of the scene graph from
being updated. This means the calculation returned MAY be out of date BUT will give you a
nice performance boost.
Optionalbounds: BoundsOptional bounds to store the result of the bounds calculation
The minimum axis-aligned rectangle in world space that fits around this object
// Basic bounds calculation
const bounds = sprite.getBounds();
console.log(`World bounds: ${bounds.x}, ${bounds.y}, ${bounds.width}, ${bounds.height}`);
// Reuse bounds object for performance
const recycleBounds = new Bounds();
sprite.getBounds(false, recycleBounds);
// Skip update for performance
const fastBounds = sprite.getBounds(true);
Returns the child at the specified index.
The index to get the child from
The child at the given index
// Get first child
const first = container.getChildAt(0);
// Type-safe access
const sprite = container.getChildAt<Sprite>(1);
// With error handling
try {
const child = container.getChildAt(10);
} catch (e) {
console.warn('Index out of bounds');
}
Returns the first child in the container with the specified label. Recursive searches are done in a pre-order traversal.
Instance label to search for
Optionaldeep: booleanWhether to search recursively through children
The first child with the specified label, or null if none found
// Basic label search
const child = container.getChildByLabel('player');
// Search with regular expression
const enemy = container.getChildByLabel(/enemy-\d+/);
// Deep search through children
const deepChild = container.getChildByLabel('powerup', true);
Instance name.
Optionaldeep: booleanWhether to search recursively
The child with the specified name.
Returns the index position of a child Container instance.
The Container instance to identify
The index position of the child container
// Basic index lookup
const index = container.getChildIndex(sprite);
console.log(`Sprite is at index ${index}`);
// With error handling
try {
const index = container.getChildIndex(sprite);
} catch (e) {
console.warn('Child not found in container');
}
Returns all children in the container with the specified label. Recursive searches are done in a pre-order traversal.
Instance label to search for
Optionaldeep: booleanWhether to search recursively through children
Optionalout: Container<ContainerChild>[]Optional array to store matching children in
An array of children with the specified label
// Basic label search
const enemies = container.getChildrenByLabel('enemy');
// Search with regular expression
const powerups = container.getChildrenByLabel(/powerup-\d+/);
// Deep search with collection
const buttons = [];
container.getChildrenByLabel('button', true, buttons);
AdvancedComputes an approximate global bounding box for the container and its children. This method is optimized for speed by using axis-aligned bounding boxes (AABBs), and uses the last render results from when it updated the transforms. This function does not update them. which may result in slightly larger bounds but never smaller than the actual bounds.
for accurate (but less performant) results use container.getGlobalBounds
OptionalfactorRenderLayers: booleanA flag indicating whether to consider render layers in the calculation.
Optionalbounds: BoundsThe output bounds object to store the result. If not provided, a new one is created.
The computed bounds.
Returns the global (compound) alpha of the container within the scene.
Performance optimization flag:
The resulting alpha value (between 0 and 1)
Returns the global position of the container, taking into account the container hierarchy.
Optionalpoint: PointThe optional point to write the global value to
OptionalskipUpdate: booleanShould we skip the update transform
The updated point
// Basic position check
const globalPos = sprite.getGlobalPosition();
console.log(`Global: (${globalPos.x}, ${globalPos.y})`);
// Reuse point object
const point = new Point();
sprite.getGlobalPosition(point);
// Skip transform update for performance
const fastPos = container.getGlobalPosition(undefined, true);
Returns the global (compound) tint color of the container within the scene.
OptionalskipUpdate: booleanPerformance optimization flag:
The resulting tint color as a 24-bit RGB number (0xRRGGBB)
Returns the global transform matrix of the container within the scene.
Optional matrix to store the result. If not provided, a new Matrix will be created.
Performance optimization flag:
The resulting transformation matrix (either the input matrix or a new one)
// Accurate but slower - recalculates entire transform chain
const preciseTransform = container.getGlobalTransform();
// Faster but may be outdated - uses cached transform
const cachedTransform = container.getGlobalTransform(undefined, true);
// Reuse existing matrix
const existingMatrix = new Matrix();
container.getGlobalTransform(existingMatrix);
Retrieves the local bounds of the container as a Bounds object. Uses cached values when possible for better performance.
The bounding area
// Basic bounds check
const bounds = container.getLocalBounds();
console.log(`Width: ${bounds.width}, Height: ${bounds.height}`);
// subsequent calls will reuse the cached bounds
const cachedBounds = container.getLocalBounds();
console.log(bounds === cachedBounds); // true
Returns the current transformation matrix of the graphics context. This matrix represents all accumulated transformations including translate, scale, and rotate.
The current transformation matrix.
const graphics = new Graphics();
// Apply some transformations
graphics
.translateTransform(100, 100)
.rotateTransform(Math.PI / 4);
// Get the current transform matrix
const matrix = graphics.getTransform();
console.log(matrix.tx, matrix.ty); // 100, 100
// Use the matrix for other operations
graphics
.setTransform(matrix)
.circle(0, 0, 50)
.fill({ color: 0xff0000 });
Optionalwidth: numberOptionalcolor: ColorSourceOptionalalpha: numbersince 8.0.0 Use Graphics#setStrokeStyle instead
Connects the current point to a new point with a straight line. Any subsequent drawing commands will start from this new point.
The x-coordinate of the line's end point
The y-coordinate of the line's end point
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a triangle
graphics
.moveTo(50, 50)
.lineTo(100, 100)
.lineTo(0, 100)
.fill({ color: 0xff0000 });
// Create a complex shape with multiple lines
graphics
.moveTo(200, 50)
.lineTo(250, 50)
.lineTo(250, 100)
.lineTo(200, 100)
.stroke({ width: 2, color: 0x00ff00 });
Graphics#moveTo For starting a new sub-path
Sets the starting point for a new sub-path.
Moves the "pen" to a new location without drawing a line. Any subsequent drawing commands will start from this point.
The x-coordinate to move to
The y-coordinate to move to
The Graphics instance for method chaining
const graphics = new Graphics();
// Create multiple separate lines
graphics
.moveTo(50, 50)
.lineTo(100, 50)
.moveTo(50, 100) // Start a new line
.lineTo(100, 100)
.stroke({ width: 2, color: 0xff0000 });
// Create disconnected shapes
graphics
.moveTo(150, 50)
.rect(150, 50, 50, 50)
.fill({ color: 0x00ff00 })
.moveTo(250, 50) // Start a new shape
.circle(250, 75, 25)
.fill({ color: 0x0000ff });
// Position before curved paths
graphics
.moveTo(300, 50)
.bezierCurveTo(
350, 25, // Control point 1
400, 75, // Control point 2
450, 50 // End point
)
.stroke({ width: 3, color: 0xff00ff });
Adds another GraphicsPath to this path, optionally applying a transformation.
This allows for reuse of complex paths and shapes across different graphics instances.
The GraphicsPath to add to the current path
The Graphics instance for method chaining
const graphics = new Graphics();
// Create a reusable path
const heartPath = new GraphicsPath()
.moveTo(0, 0)
.bezierCurveTo(-50, -25, -50, -75, 0, -100)
.bezierCurveTo(50, -75, 50, -25, 0, 0);
// Use the path multiple times
graphics
.path(heartPath)
.fill({ color: 0xff0000 })
.translateTransform(200, 200)
.path(heartPath)
.fill({ color: 0xff0000, alpha: 0.5 });
Draws a polygon shape by specifying a sequence of points. This method allows for the creation of complex polygons, which can be both open and closed.
An optional transformation can be applied, enabling the polygon to be scaled, rotated, or translated as needed.
An array of numbers [x1,y1, x2,y2, ...] or an array of point objects [{x,y}, ...] representing the vertices of the polygon in sequence
Optionalclose: booleanWhether to close the polygon path by connecting the last point to the first. Default is true.
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a triangle using array of numbers [x1,y1, x2,y2, x3,y3]
graphics
.poly([50,50, 100,100, 0,100], true)
.fill({ color: 0xff0000 });
// Draw a polygon using point objects
graphics
.poly([
{ x: 200, y: 50 },
{ x: 250, y: 100 },
{ x: 200, y: 150 },
{ x: 150, y: 100 }
])
.fill({ color: 0x00ff00 });
// Draw an open polygon with stroke
graphics
.poly([300,50, 350,50, 350,100, 300,100], false)
.stroke({
width: 2,
color: 0x0000ff,
join: 'round'
});
Adds a quadratic curve to the path. It requires two points: the control point and the end point. The starting point is the last point in the current path.
The x-coordinate of the control point
The y-coordinate of the control point
The x-coordinate of the end point
The y-coordinate of the end point
Optionalsmoothness: numberOptional parameter to adjust the curve's smoothness (0-1)
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a simple curve
graphics
.moveTo(50, 50)
.quadraticCurveTo(100, 25, 150, 50)
.stroke({ width: 2, color: 0xff0000 });
// Adjust curve smoothness
graphics
.moveTo(50, 200)
.quadraticCurveTo(
150, 150, // Control point
250, 200, // End point
0.5 // Smoothness factor
)
.stroke({
width: 4,
color: 0x0000ff,
alpha: 0.7
});
Draws a rectangle shape.
This method adds a new rectangle path to the current drawing.
The x-coordinate of the top-left corner of the rectangle
The y-coordinate of the top-left corner of the rectangle
The width of the rectangle
The height of the rectangle
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a simple filled rectangle
graphics
.rect(50, 50, 100, 75)
.fill({ color: 0xff0000 });
// Rectangle with stroke
graphics
.rect(200, 50, 100, 75)
.stroke({ width: 2, color: 0x00ff00 });
Draws a regular polygon with a specified number of sides. All sides and angles are equal, making shapes like triangles, squares, pentagons, etc.
The x-coordinate of the center of the polygon
The y-coordinate of the center of the polygon
The radius of the circumscribed circle of the polygon
The number of sides of the polygon (must be 3 or more)
Optionalrotation: numberThe rotation angle of the polygon in radians (default: 0)
Optionaltransform: MatrixOptional Matrix to transform the polygon's shape
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a simple triangle (3 sides)
graphics
.regularPoly(100, 100, 50, 3)
.fill({ color: 0xff0000 });
// Draw a hexagon (6 sides) with rotation
graphics
.regularPoly(
250, 100, // center position
40, // radius
6, // sides
Math.PI / 6 // rotation (30 degrees)
)
.fill({ color: 0x00ff00 })
.stroke({ width: 2, color: 0x000000 });
// Draw an octagon (8 sides) with transform
const transform = new Matrix()
.scale(1.5, 1) // stretch horizontally
.rotate(Math.PI/4); // rotate 45 degrees
graphics
.regularPoly(400, 100, 30, 8, 0, transform)
.fill({ color: 0x0000ff, alpha: 0.5 });
Removes one or more children from the container. When removing multiple children, events will be triggered for each child in sequence.
The Container(s) to remove
The first child that was removed
// Remove a single child
const removed = container.removeChild(sprite);
// Remove multiple children
const bg = container.removeChild(background, player, userInterface);
// Remove with type checking
const sprite = container.removeChild<Sprite>(childSprite);
sprite.texture = newTexture;
Removes a child from the specified index position.
The index to remove the child from
The child that was removed
// Remove first child
const removed = container.removeChildAt(0);
// type safe access
const sprite = container.removeChildAt<Sprite>(1);
// With error handling
try {
const child = container.removeChildAt(10);
} catch (e) {
console.warn('Index out of bounds');
}
Removes all children from this container that are within the begin and end indexes.
OptionalbeginIndex: numberThe beginning position
OptionalendIndex: numberThe ending position. Default is container size
List of removed children
// Remove all children
container.removeChildren();
// Remove first 3 children
const removed = container.removeChildren(0, 3);
console.log('Removed:', removed.length); // 3
// Remove children from index 2 onwards
container.removeChildren(2);
// Remove specific range
const middle = container.removeChildren(1, 4);
Unlike off or removeListener which are methods from EventEmitter, removeEventListener
seeks to be compatible with the DOM's removeEventListener with support for options.
The type of event the listener is bound to.
The listener callback or object.
Optionaloptions: RemoveListenerOptionsThe original listener options. This is required to deregister a capture phase listener.
Optionaloptions: RemoveListenerOptionsRemove the Container from its parent Container. If the Container has no parent, do nothing.
// Basic removal
sprite.removeFromParent();
// With validation
if (sprite.parent) {
sprite.removeFromParent();
}
Reparent a child or multiple children to this container while preserving their world transform. This ensures that the visual position and rotation of the children remain the same even when changing parents.
The child or children to reparent
The first child that was reparented
// Basic reparenting
const sprite = new Sprite(texture);
oldContainer.addChild(sprite);
// Move to new parent, keeping visual position
newContainer.reparentChild(sprite);
// Reparent multiple children
const batch = [sprite1, sprite2, sprite3];
newContainer.reparentChild(...batch);
Reparent the child to this container at the specified index while preserving its world transform. This ensures that the visual position and rotation of the child remain the same even when changing parents.
The child to reparent
The index to reparent the child to
The reparented child
// Basic index-specific reparenting
const sprite = new Sprite(texture);
oldContainer.addChild(sprite);
// Move to new parent at index 0 (front)
newContainer.reparentChildAt(sprite, 0);
Resets the current transformation matrix to the identity matrix, effectively removing any transformations (rotation, scaling, translation) previously applied.
The Graphics instance for method chaining
const graphics = new Graphics();
// Apply transformations
graphics
.translateTransform(100, 100)
.scaleTransform(2, 2)
.circle(0, 0, 25)
.fill({ color: 0xff0000 });
// Reset transform to default state
graphics
.resetTransform()
.circle(50, 50, 25) // Will draw at actual coordinates
.fill({ color: 0x00ff00 });
Restores the most recently saved graphics state by popping the top of the graphics state stack. This includes transformations, fill styles, and stroke styles.
The Graphics instance for method chaining
const graphics = new Graphics();
// Save current state
graphics.save();
// Make temporary changes
graphics
.translateTransform(100, 100)
.setFillStyle({ color: 0xff0000 })
.circle(0, 0, 50)
.fill();
// Restore to previous state
graphics.restore();
// Draw with original transform and styles
graphics
.circle(50, 50, 30)
.fill();
Graphics#save For saving the current state
Applies a rotation transformation to the graphics context around the current origin. Positive angles rotate clockwise, while negative angles rotate counterclockwise.
The angle of rotation in radians
The Graphics instance for method chaining
const graphics = new Graphics();
// Rotate 45 degrees clockwise
graphics
.rotateTransform(Math.PI / 4)
.rect(-25, -25, 50, 50)
.fill({ color: 0xff0000 });
Draws a polygon with rounded corners.
Similar to regularPoly but with the ability to round the corners of the polygon.
The x-coordinate of the center of the polygon
The y-coordinate of the center of the polygon
The radius of the circumscribed circle of the polygon
The number of sides of the polygon (must be 3 or more)
The radius of the corner rounding (must be non-negative)
Optionalrotation: numberThe rotation angle of the polygon in radians (default: 0)
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a basic rounded triangle
graphics
.roundPoly(100, 100, 50, 3, 10)
.fill({ color: 0xff0000 });
// Draw a rounded hexagon with rotation
graphics
.roundPoly(
250, 150, // center position
40, // radius
6, // sides
8, // corner radius
Math.PI / 6 // rotation (30 degrees)
)
.fill({ color: 0x00ff00 })
.stroke({ width: 2, color: 0x000000 });
Draws a rectangle with rounded corners. The corner radius can be specified to determine how rounded the corners should be.
The x-coordinate of the top-left corner of the rectangle
The y-coordinate of the top-left corner of the rectangle
The width of the rectangle
The height of the rectangle
Optionalradius: numberThe radius of the rectangle's corners (must be non-negative)
The Graphics instance for method chaining
const graphics = new Graphics();
// Basic rounded rectangle
graphics
.roundRect(50, 50, 100, 75, 15)
.fill({ color: 0xff0000 });
Draws a shape with rounded corners. This function supports custom radius for each corner of the shape. Optionally, corners can be rounded using a quadratic curve instead of an arc, providing a different aesthetic.
An array of RoundedPoint representing the corners of the shape.
Each point can have its own radius or use the default.
A minimum of 3 points is required.
The default radius for corners without a specific radius defined. Applied to any point that doesn't specify its own radius.
OptionaluseQuadratic: booleanWhen true, corners are drawn using quadratic curves instead of arcs, creating a different visual style. Defaults to false.
Optionalsmoothness: numberControls the smoothness of quadratic corners when useQuadratic is true. Values range from 0-1, higher values create smoother curves.
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a custom shape with rounded corners
graphics
.roundShape([
{ x: 100, y: 100, radius: 20 },
{ x: 200, y: 100, radius: 10 },
{ x: 200, y: 200, radius: 15 },
{ x: 100, y: 200, radius: 5 }
], 10)
.fill({ color: 0xff0000 });
// Using quadratic curves for corners
graphics
.roundShape([
{ x: 250, y: 100 },
{ x: 350, y: 100 },
{ x: 350, y: 200 },
{ x: 250, y: 200 }
], 15, true, 0.5)
.fill({ color: 0x00ff00 })
.stroke({ width: 2, color: 0x000000 });
// Shape with varying corner radii
graphics
.roundShape([
{ x: 400, y: 100, radius: 30 },
{ x: 500, y: 100, radius: 5 },
{ x: 450, y: 200, radius: 15 }
], 10)
.fill({ color: 0x0000ff, alpha: 0.5 });
Saves the current graphics state onto a stack. The state includes:
The Graphics instance for method chaining
const graphics = new Graphics();
// Save state before complex operations
graphics.save();
// Create transformed and styled shape
graphics
.translateTransform(100, 100)
.rotateTransform(Math.PI / 4)
.setFillStyle({
color: 0xff0000,
alpha: 0.5
})
.rect(-25, -25, 50, 50)
.fill();
// Restore to original state
graphics.restore();
// Continue drawing with previous state
graphics
.circle(50, 50, 25)
.fill();
Applies a scaling transformation to the graphics context, scaling drawings by x horizontally and by y vertically relative to the current origin.
The scale factor in the horizontal direction
Optionaly: numberThe scale factor in the vertical direction. If omitted, equals x
The Graphics instance for method chaining
const graphics = new Graphics();
// Uniform scaling
graphics
.scaleTransform(2) // Scale both dimensions by 2
.circle(0, 0, 25)
.fill({ color: 0xff0000 });
// Non-uniform scaling
graphics
.scaleTransform(0.5, 2) // Half width, double height
.rect(100, 100, 50, 50)
.fill({ color: 0x00ff00 });
Changes the position of an existing child in the container.
The child Container instance to reposition
The resulting index number for the child
// Basic index change
container.setChildIndex(sprite, 0); // Move to front
container.setChildIndex(sprite, container.children.length - 1); // Move to back
// With error handling
try {
container.setChildIndex(sprite, 5);
} catch (e) {
console.warn('Invalid index or child not found');
}
Sets the current fill style of the graphics context. The fill style can be a color, gradient, pattern, or a complex style object.
The fill style to apply
The Graphics instance for chaining
const graphics = new Graphics();
// Basic color fill
graphics
.setFillStyle({ color: 0xff0000 }) // Red fill
.rect(0, 0, 100, 100)
.fill();
// Gradient fill
const gradient = new FillGradient({
end: { x: 1, y: 0 },
colorStops: [
{ offset: 0, color: 0xff0000 }, // Red at start
{ offset: 0.5, color: 0x00ff00 }, // Green at middle
{ offset: 1, color: 0x0000ff }, // Blue at end
],
});
graphics
.setFillStyle(gradient)
.circle(100, 100, 50)
.fill();
// Pattern fill
const pattern = new FillPattern(texture);
graphics
.setFillStyle({
fill: pattern,
alpha: 0.5
})
.rect(0, 0, 200, 200)
.fill();
Updates the local transform properties by decomposing the given matrix. Extracts position, scale, rotation, and skew from a transformation matrix.
The matrix to use for updating the transform
// Basic matrix transform
const matrix = new Matrix()
.translate(100, 100)
.rotate(Math.PI / 4)
.scale(2, 2);
container.setFromMatrix(matrix);
// Copy transform from another container
const source = new Container();
source.position.set(100, 100);
source.rotation = Math.PI / 2;
target.setFromMatrix(source.localTransform);
// Reset transform
container.setFromMatrix(Matrix.IDENTITY);
Used to set mask and control mask options on a display object. Allows for more detailed control over masking behavior compared to the mask property.
Configuration options for the mask
import { Graphics, Sprite } from 'pixi.js';
// Create a circular mask
const graphics = new Graphics()
.beginFill(0xFF3300)
.drawCircle(100, 100, 50)
.endFill();
// Apply mask with options
sprite.setMask({
mask: graphics,
inverse: true, // Create a hole effect
});
// Clear existing mask
sprite.setMask({ mask: null });
Sets the size of the container to the specified width and height. This is more efficient than setting width and height separately as it only recalculates bounds once.
Sets the current stroke style of the graphics context. Similar to fill styles, stroke styles can encompass colors, gradients, patterns, or more detailed configurations.
The stroke style to apply
The Graphics instance for chaining
const graphics = new Graphics();
// Basic color stroke
graphics
.setStrokeStyle({
width: 2,
color: 0x000000
})
.rect(0, 0, 100, 100)
.stroke();
// Complex stroke style
graphics
.setStrokeStyle({
width: 4,
color: 0xff0000,
alpha: 0.5,
join: 'round',
cap: 'round',
alignment: 0.5
})
.circle(100, 100, 50)
.stroke();
// Gradient stroke
const gradient = new FillGradient({
end: { x: 1, y: 0 },
colorStops: [
{ offset: 0, color: 0xff0000 }, // Red at start
{ offset: 0.5, color: 0x00ff00 }, // Green at middle
{ offset: 1, color: 0x0000ff }, // Blue at end
],
});
graphics
.setStrokeStyle({
width: 10,
fill: gradient
})
.poly([0,0, 100,50, 0,100])
.stroke();
Sets the current transformation matrix of the graphics context.
This method can either take a Matrix object or individual transform values to create a new transformation matrix.
The matrix to set as the current transformation matrix.
The instance of the current GraphicsContext for method chaining.
const graphics = new Graphics();
// Using a Matrix object
const matrix = new Matrix()
.translate(100, 100)
.rotate(Math.PI / 4);
graphics
.setTransform(matrix)
.rect(0, 0, 50, 50)
.fill({ color: 0xff0000 });
// Using individual transform values
graphics
.setTransform(
2, 0, // scale x by 2
0, 1, // no skew
100, 100 // translate x,y by 100
)
.circle(0, 0, 25)
.fill({ color: 0x00ff00 });
Sets the current transformation matrix of the graphics context to the specified matrix or values. This replaces the current transformation matrix.
The value for the a property of the matrix, or a Matrix object to use directly.
The value for the b property of the matrix.
The value for the c property of the matrix.
The value for the d property of the matrix.
The value for the tx (translate x) property of the matrix.
The value for the ty (translate y) property of the matrix.
The instance of the current GraphicsContext for method chaining.
Sets the current transformation matrix of the graphics context.
This method can either take a Matrix object or individual transform values to create a new transformation matrix.
Optionalb: numberOptionalc: numberOptionald: numberOptionaldx: numberOptionaldy: numberThe instance of the current GraphicsContext for method chaining.
const graphics = new Graphics();
// Using a Matrix object
const matrix = new Matrix()
.translate(100, 100)
.rotate(Math.PI / 4);
graphics
.setTransform(matrix)
.rect(0, 0, 50, 50)
.fill({ color: 0xff0000 });
// Using individual transform values
graphics
.setTransform(
2, 0, // scale x by 2
0, 1, // no skew
100, 100 // translate x,y by 100
)
.circle(0, 0, 25)
.fill({ color: 0x00ff00 });
Draws a star shape centered at a specified location. This method allows for the creation of stars with a variable number of points, outer radius, optional inner radius, and rotation.
The star is drawn as a closed polygon with alternating outer and inner vertices to create the star's points. An optional transformation can be applied to scale, rotate, or translate the star as needed.
The x-coordinate of the center of the star
The y-coordinate of the center of the star
The number of points on the star (must be >= 3)
The outer radius of the star (distance from center to point tips)
OptionalinnerRadius: numberOptional. The inner radius of the star (distance from center to inner vertices). If not specified, defaults to half of the outer radius
Optionalrotation: numberOptional. The rotation of the star in radians. Default is 0, which aligns one point straight up
The Graphics instance for method chaining
const graphics = new Graphics();
// Draw a basic 5-pointed star
graphics
.star(100, 100, 5, 50)
.fill({ color: 0xff0000 });
// Star with custom inner radius
graphics
.star(250, 100, 6, 50, 20)
.fill({ color: 0x00ff00 })
.stroke({ width: 2, color: 0x000000 });
Strokes the current path with the current stroke style or specified style. Outlines the shape using the stroke settings.
Optional stroke style to apply. Can be:
The Graphics instance for chaining
const graphics = new Graphics();
// Stroke with direct color
graphics
.circle(50, 50, 25)
.stroke({
width: 2,
color: 0xff0000
}); // 2px red stroke
// Fill with texture
graphics
.rect(0, 0, 100, 100)
.stroke(myTexture); // Fill with texture
// Stroke with gradient
const gradient = new FillGradient({
end: { x: 1, y: 0 },
colorStops: [
{ offset: 0, color: 0xff0000 },
{ offset: 0.5, color: 0x00ff00 },
{ offset: 1, color: 0x0000ff },
],
});
graphics
.rect(0, 0, 100, 100)
.stroke({
width: 4,
fill: gradient,
alignment: 0.5,
join: 'round'
});
Parses and renders an SVG string into the graphics context. This allows for complex shapes and paths defined in SVG format to be drawn within the graphics context.
The SVG string to be parsed and rendered
The Graphics instance for method chaining
const graphics = new Graphics();
graphics
.svg(`
<path d="M 50,50 L 100,50 L 100,100 L 50,100 Z"
fill="blue" />
<circle cx="150" cy="75" r="25"
fill="green" />
`)
.stroke({ width: 2, color: 0x000000 });
Swaps the position of 2 Containers within this container.
// Basic swap
container.swapChildren(sprite1, sprite2);
// With error handling
try {
container.swapChildren(sprite1, sprite2);
} catch (e) {
console.warn('One or both children not found in container');
}
Adds a texture to the graphics context. This method supports multiple ways to draw textures including basic textures, tinted textures, and textures with custom dimensions.
The Texture object to use.
The instance of the current Graphics for chaining.
Extended texture drawing:
const graphics = new Graphics();
// Basic texture drawing
graphics.texture(myTexture);
// Tinted texture with position
graphics.texture(myTexture, 0xff0000); // Red tint
// Texture with custom position and dimensions
graphics
.texture(
myTexture, // texture
0xffffff, // white tint
100, 100, // position
200, 150 // dimensions
);
Basic texture drawing:
Adds a texture to the graphics context. This method supports multiple ways to draw textures including basic textures, tinted textures, and textures with custom dimensions.
The Texture object to use.
Optionaltint: ColorSourceOptionaldx: numberOptionaldy: numberOptionaldw: numberOptionaldh: numberThe instance of the current Graphics for chaining.
Extended texture drawing:
const graphics = new Graphics();
// Basic texture drawing
graphics.texture(myTexture);
// Tinted texture with position
graphics.texture(myTexture, 0xff0000); // Red tint
// Texture with custom position and dimensions
graphics
.texture(
myTexture, // texture
0xffffff, // white tint
100, 100, // position
200, 150 // dimensions
);
Basic texture drawing:
Calculates the global position of a point relative to this container. Takes into account the container hierarchy and transforms.
The global position
// Basic point conversion
const localPoint = { x: 10, y: 20 };
const globalPoint = container.toGlobal(localPoint);
// With point reuse
const reusePoint = new Point();
container.toGlobal(localPoint, reusePoint);
// Performance optimization
const fastPoint = container.toGlobal(
{ x: 50, y: 50 },
undefined,
true // Skip transform update
);
Calculates the local position of the container relative to another point. Converts coordinates from any coordinate space to this container's local coordinate space.
A point object representing the position in local space
// Basic coordinate conversion
const worldPoint = { x: 100, y: 100 };
const localPos = container.toLocal(worldPoint);
// Convert from another container
const fromSprite = new Sprite(texture);
fromSprite.position.set(50, 50);
const pointInSprite = { x: 10, y: 10 };
const localPoint = container.toLocal(pointInSprite, fromSprite);
// With point reuse for performance
const reusePoint = new Point();
container.toLocal(worldPoint, undefined, reusePoint);
// Skip transform update for static objects
const fastLocal = container.toLocal(
worldPoint,
undefined,
undefined,
true
);
Applies a transformation matrix to the current graphics context by multiplying the current matrix with the specified matrix. This allows for complex transformations combining multiple operations.
The matrix to apply to the current transformation.
The instance of the current GraphicsContext for method chaining.
const graphics = new Graphics();
// Using a Matrix object
const matrix = new Matrix()
.scale(2, 1) // Scale horizontally
.rotate(Math.PI/6); // Rotate 30 degrees
graphics
.transform(matrix)
.rect(0, 0, 50, 50)
.fill({ color: 0xff0000 });
// Using individual transform values
graphics
.transform(
1, 0.5, // Skew horizontally
0, 1, // No vertical skew
100, 100 // Translate
)
.circle(0, 0, 25)
.fill({ color: 0x00ff00 });
Applies the specified transformation matrix to the current graphics context by multiplying the current matrix with the specified matrix.
The value for the a property of the matrix, or a Matrix object to use directly.
The value for the b property of the matrix.
The value for the c property of the matrix.
The value for the d property of the matrix.
The value for the tx (translate x) property of the matrix.
The value for the ty (translate y) property of the matrix.
The instance of the current GraphicsContext for method chaining.
Applies a transformation matrix to the current graphics context by multiplying the current matrix with the specified matrix. This allows for complex transformations combining multiple operations.
Optionalb: numberOptionalc: numberOptionald: numberOptionaldx: numberOptionaldy: numberThe instance of the current GraphicsContext for method chaining.
const graphics = new Graphics();
// Using a Matrix object
const matrix = new Matrix()
.scale(2, 1) // Scale horizontally
.rotate(Math.PI/6); // Rotate 30 degrees
graphics
.transform(matrix)
.rect(0, 0, 50, 50)
.fill({ color: 0xff0000 });
// Using individual transform values
graphics
.transform(
1, 0.5, // Skew horizontally
0, 1, // No vertical skew
100, 100 // Translate
)
.circle(0, 0, 25)
.fill({ color: 0x00ff00 });
Applies a translation transformation to the graphics context, moving the origin by the specified amounts. This affects all subsequent drawing operations.
The amount to translate in the horizontal direction
Optionaly: numberThe amount to translate in the vertical direction. If omitted, equals x
The Graphics instance for method chaining
const graphics = new Graphics();
// Basic translation
graphics
.translateTransform(100, 100)
.circle(0, 0, 25)
.fill({ color: 0xff0000 });
Updates the local transform.
Updates the transform properties of the container. Allows partial updates of transform properties for optimized manipulation.
Transform options to update
The x position
The y position
The x-axis scale factor
The y-axis scale factor
The rotation in radians
The x-axis skew factor
The y-axis skew factor
The x-axis pivot point
The y-axis pivot point
This container, for chaining
// Basic transform update
container.updateTransform({
x: 100,
y: 200,
rotation: Math.PI / 4
});
// Scale and rotate around center
sprite.updateTransform({
pivotX: sprite.width / 2,
pivotY: sprite.height / 2,
scaleX: 2,
scaleY: 2,
rotation: Math.PI
});
// Update position only
button.updateTransform({
x: button.x + 10, // Move right
y: button.y // Keep same y
});
StaticmixinMixes all enumerable properties and methods from a source object to Container.
The source of properties and methods to mix in.
The Graphics class is primarily used to render primitive shapes such as lines, circles and rectangles to the display, and to color and fill them. It can also be used to create complex masks and hit areas for interaction.
Example
See