Skip to main content

Graphics

These functions relate to rendering graphics on the screen, such as sprites, particles and text. See Learn > Graphics for a broader overview of how graphics work in Easel.

Position​

Position:AtPointer -> symbol

Returns a special symbol that can be used to attach a sprite to the Pointer. Use this by passing it to the body parameter of PolygonSprite, ImageSprite or TextSprite.

Position:AtCamera -> symbol
Position:CameraTopLeft -> symbol
Position:CameraTop -> symbol
Position:CameraTopRight -> symbol
Position:CameraLeft -> symbol
Position:CameraRight -> symbol
Position:CameraBottomLeft -> symbol
Position:CameraBottom -> symbol
Position:CameraBottomRight -> symbol

Returns a special symbol that can be used to attach a sprite to the center, edge or corner of the camera's view. Use this by passing it to the body parameter of PolygonSprite, ImageSprite or TextSprite.

Resolution​

Resolution:Max -> symbol
Resolution:High -> symbol
Resolution:Low -> symbol

Used to modify the player's resolution using the ResolutionIntent function.

  • Maximum resolution is the highest quality, but may run slower on older devices. If a retina display is detected, the game will be rendered to subpixel resolution.
  • High resolution is a good balance between quality and performance. It only renders to normal pixel resolution and not to subpixels.
  • Low resolution is the fastest option. It renders to half pixel resolution, creating a pixel-art look which can help your game run smoothly on older devices.

FullscreenIntent​

FullscreenIntent(fullscreen) -> intent

Returns an Intent to enter or exit fullscreen mode.

  • fullscreen (Boolean): true to enter fullscreen mode, false to exit.

FullscreenToggle​

FullscreenToggle([ui=]) |use ui:whenFullscreen, use ui:whenWindowed| { }

Creates an element in the user interface that allows the player to switch between fullscreen and windowed mode.

  • ui (UI): The slot in the user interface where the element will be inserted.

Subblock: The subblock will be called immediately to populate the element's content. It is optional as there are defaults for both fullscreen and windowed states. Use the %ui:whenFullscreen { ... } syntax to populate one of the slots, see Multiple Slots for more information.

  • ui:whenFullscreen (UI): populate this slot with the content that should be displayed when fullscreen. If left empty, will display a default button that will exit fullscreen mode.
  • ui:whenWindowed (UI): populate this slot with the content that should be displayed when windowed. If left empty, will display a default button that will enter fullscreen mode.

ImageSpark​

this.ImageSpark<Id = auto>(image, [body, radius=], heading?, face?, billboard?, bodyOffset?, screenOffset?, angleOffset?, scale?, speed?, velocity?, acceleration?, turnRate?, imageAnchor?, repeatX?, repeatY?, [audience?, bodyScale?, camera?, color?, crater?, diminish?, dissipate?, fade?, feather?, flicker?, frameInterval?, frameRepeat?, glare?, glareAlpha?, glaze?, layer?, luminous?, noRotation?, opacity?, owner?, ownerColor?, shading?, shadow?, sharp?, shine?, splatter?, strobe?, taper?])

Creates a spark particle in a given Polygon shape that dissipates over time.

  • this (Entity): Defines the entity the Spark will Strobe with. Unlike other functions, the lifetime of a spark is not tied to its this entity. If this despawns, the spark will continue to exist until it dissipates like normal.
  • Id: The ID for the spark. Sparks with the same this and Id will be rendered together by the engine. This is done to improve performance. Certain fields, such as layer, are shared between all sparks in the same group. The last spark determines the value of these fields for the entire group.

Image:

  • image (Asset or Array): The image to display. Can either be a single asset, e.g. @fireball.png, or an array of frames, e.g. [@fireball1.png, @fireball2.png] or @fireball*.png (see Asset Wildcards). If you are using an array of frames, the sprite will cycle through the frames at the interval specified by frameInterval.

  • radius (Number): The radius of sprite, in game-world coordinates.

  • repeatX (Number): The number of times to repeat the image along the x-axis. Defaults to 1.

  • repeatY (Number): The number of times to repeat the image along the y-axis. Defaults to 1.

  • frameInterval (Number): The number of ticks to wait before switching to the next frame. Defaults to 0.1s.

  • frameRepeat (Boolean): If true, the sprite will loop through the frames. Defaults to true.

  • sharp (Boolean): If true, will preserve the pixelation of the image by using neearest neighbor interpolation. This can be used to make pixel art games. Defaults to false.

Position:

  • body (Entity or Vector): The position of the spark, whether it be spawned at an Entity's body or at a specific Vector position.

  • bodyOffset (Vector): If set, determines the attachment point of the sprite on the body.

  • screenOffset (Vector): If set, offsets the position of the sprite by this Vector. Unlike bodyOffset, this is done in screen space and so does not follow the rotation of the body.

  • glaze (Number or Bool): If true, randomly offsets the position of the graphic to a random position within the Perimeter of the entity. If a Number, should be a proportion between 0 and 1 where 1 spawns the spark at a random point on the edge of the perimeter, while 0 spawns it in the center.

Orientation:

  • noRotation (Boolean): If truthy, stops the sprite from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the sprite, which affects both the sprite's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the sprite will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the sprite such that it points towards the given position. Affects both the sprite's rotation and its bodyOffset.

    • Vector: the sprite will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the sprite will face towards the given entity's position

  • billboard (Boolean): If true, the sprite's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the sprite's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the sprite will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.
  • bodyScale (Number or Vector): The size of the sprite and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Z-order:

  • layer (Number): The layer at which to draw the spark. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.

Color:

  • color (Color): The color of the spark.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the spark should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the spark in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the spark in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter. This can be controlled dynamically to make a sprite flash or glow temporarily.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the sprite brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the sprite.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0. Defaults to 1.

  • shading (Number): A proportion between 0 and 1 controlling the intensity of shading. Shading adds a gradient to the graphic, mixing it with more black as it gets closer to its bottom left corner. This can make flat shapes look more interesting.

Effects:

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the sprite. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a spark look like it is made of light rather than paint.

Dissipation:

  • dissipate (Number): The number of ticks before the spark dissipates. Defaults to 0.25s.

  • fade (Color or Number): If a Color, determines the color the spark will blend towards as it dissipates. If a Number, should be a proportion between 0 and 1 where 1 means the spark will fade to transparent as it dissipates, while 0 means it will not fade at all.

  • diminish (Number): A proportion between 0 and 1 where 1 means its shine, bloomAlpha and glareAlpha will diminish to zero as it dissipates, while 0 means they will remain the same. This can be used to make the line look brighter at one end. Defaults to 1.

  • taper (Number): A proportion between 0 and 1 where 1 means the scale, bloom and glare will reduce to zero as it dissipates, while 0 means it will remain the same radius. Defaults to 1.

Trajectory:

  • velocity (Vector): The spark will move in the speed and direction determined by this parameter. Defaults to @(0, 0).

  • speed (Number): The spark will move at this speed in a random direction. If both velocity and speed are specified, their effects will be added together. Defaults to 0.

  • acceleration (Vector): The spark's velocity will change at this rate per second. Set to acceleration=Gravity to make the spark fall at the speed of gravity. Defaults to @(0, 0).

  • splatter (Number): A proportion between 0 and 1 which controls how much the spark should splatter. Splattering will primarily occur in the direction of velocity of the body Entity. This can be used to create the splatter from a fireball, for example, when it hits.

  • turnRate (Number): The spark will be rotated by this amount per second.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, the spark will only be visible to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the spark.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the spark. Defaults to World (the main camera).

ImageSprite​

this.ImageSprite<Id = auto>(image, [body, radius=], heading?, face?, billboard?, bodyOffset?, screenOffset?, angleOffset?, scale?, color?, overlay?, imageAnchor?, repeatX?, repeatY?, [audience?, bodyScale?, camera?, crater?, feather?, flicker?, frameInterval?, frameRepeat?, glare?, glareAlpha?, layer?, luminous?, noRotation?, opacity?, owner?, ownerColor?, shading?, sharp?, shadow?, shine?, strobe?])
delete this.ImageSprite<Id>

Creates a sprite which will display an image attached to a given body.

  • this (Entity): Defines the lifespan of the sprite. When this despawns, the sprite is deleted.
  • Id: A unique identifier for the sprite. If a sprite already exists on this with the same Id, the previous sprite will be replaced.

Image:

  • image (Asset or Array): The image to display. Can either be a single asset, e.g. @fireball.png, or an array of frames, e.g. [@fireball1.png, @fireball2.png] or @fireball*.png (see Asset Wildcards). If you are using an array of frames, the sprite will cycle through the frames at the interval specified by frameInterval.

  • radius (Number): The radius of sprite, in game-world coordinates.

  • repeatX (Number): The number of times to repeat the image along the x-axis. Defaults to 1.

  • repeatY (Number): The number of times to repeat the image along the y-axis. Defaults to 1.

  • frameInterval (Number): The number of ticks to wait before switching to the next frame. Defaults to 0.1s.

  • frameRepeat (Boolean): If true, the sprite will loop through the frames. Defaults to true.

  • sharp (Boolean): If true, will preserve the pixelation of the image by using nearest neighbor interpolation. This can be used to make pixel art games. Defaults to false.

Position:

  • body (Entity, Vector or Symbol): The position of the sprite, whether it is attached to an Entity's body or fixed at a Vector position. If given the special symbolic value of Position:AtPointer, the sprite will attach itself to the player's pointer. There are also a number of other symbolic values available, see Position for the full list.

  • bodyOffset (Vector): If set, offsets the position of the sprite by this Vector. bodyOffset will be rotated to match the body's current heading.

  • screenOffset (Vector): If set, offsets the position of the sprite by this Vector.

  • imageAnchor (Vector): Designates which point of the image will be placed at the sprite origin. Defaults to @(0, 0), which places the center of the image at the sprite origin. A value of @(-1, -1) would place the top left corner of the image at the sprite origin, whereas @(1, 1) would place the bottom right corner of the image at the sprite origin.

Orientation:

  • noRotation (Boolean): If truthy, stops the sprite from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the sprite, which affects both the sprite's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the sprite will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the sprite such that it points towards the given position. Affects both the sprite's rotation and its bodyOffset.

    • Vector: the sprite will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the sprite will face towards the given entity's position

  • billboard (Boolean): If true, the sprite's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the sprite's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the sprite will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Mirror a sprite around the Y-axis by using @(-1, 1). Defaults to 1.
  • bodyScale (Number or Vector): The size of the sprite and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Z-order:

  • layer (Number): The rendering layer of the sprite. Sprites on higher layers will be drawn over the top of sprites on lower layers. Must be a number between -128 and 127 (inclusive). Defaults to 0.

  • overlay (Number): When multiple sprites are attached to the same body, sprites with higher overlay will be drawn over the top of sprites with a lower overlay. Must be a number between -128 and 127 (inclusive). Defaults to 0.

Color:

  • color (Color): If set, the image is tinted with this color.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the sprite should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the sprite in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the sprite in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter. This can be controlled dynamically to make a sprite flash or glow temporarily.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the sprite brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the sprite.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0. Defaults to 1.

  • shading (Number): A proportion between 0 and 1 controlling the intensity of shading. Shading adds a gradient to the graphic, mixing it with more black as it gets closer to its bottom left corner. This can make flat shapes look more interesting.

Effects:

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the sprite. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a sprite look like it is made of light rather than paint.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, only the specified audience can see the sprite. Defaults to Audience:All. See Audience.

  • owner (Entity): The player or team entity that owns the sprite.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the sprite. Defaults to World (the main camera).

ImageStencil​

this.ImageStencil<Id = auto>(image, [body], heading?=, face?, billboard?, bodyOffset?, screenOffset?, scale?, imageAnchor?, repeatX?, repeatY?, [radius, angleOffset?, audience?, bodyScale?, camera?, crater?, frameInterval?, frameRepeat?, noRotation?, owner?])
delete this.ImageStencil<Id>

Limits rendering to the area inside an image. See Stencils for more information.

  • this (Entity): Defines the lifespan of the stencil. When this despawns, the stencil is deleted.
  • Id: A unique identifier for the stencil. If a stencil already exists on this with the same Id, the previous stencil will be replaced.

Image:

  • image (Asset or Array): The image to display. Can either be a single asset, e.g. @fireball.png, or an array of frames, e.g. [@fireball1.png, @fireball2.png] or @fireball*.png (see Asset Wildcards). If you are using an array of frames, the stencil will cycle through the frames at the interval specified by frameInterval.

  • radius (Number): The radius of stencil, in game-world coordinates.

  • repeatX (Number): The number of times to repeat the image along the x-axis. Defaults to 1.

  • repeatY (Number): The number of times to repeat the image along the y-axis. Defaults to 1.

  • frameInterval (Number): The number of ticks to wait before switching to the next frame. Defaults to 0.1s.

  • frameRepeat (Boolean): If true, the stencil will loop through the frames. Defaults to true.

Position:

  • body (Entity, Vector or Symbol): The position of the stencil, whether it is attached to an Entity's body or fixed at a Vector position. If given the special symbolic value of Position:AtPointer, the stencil will attach itself to the player's pointer. There are also a number of other symbolic values available, see Position for the full list.

  • bodyOffset (Vector): If set, offsets the position of the stencil by this Vector. bodyOffset will be rotated to match the body's current heading.

  • screenOffset (Vector): If set, offsets the position of the stencil by this Vector.

Orientation:

  • noRotation (Boolean): If truthy, stops the stencil from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the stencil, which affects both the stencil's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the stencil will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the stencil such that it points towards the given position. Affects both the stencil's rotation and its bodyOffset.

    • Vector: the stencil will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the stencil will face towards the given entity's position

  • billboard (Boolean): If true, the stencil's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the stencil's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the sprite will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.
  • bodyScale (Number or Vector): The size of the sprite and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Effects:

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the stencil.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, only the specified audience can see the stencil. Defaults to Audience:All. See Audience.

  • owner (Entity): The player or team entity that owns the stencil.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the stencil. Defaults to World (the main camera).

PointerAimingLine​

this.PointerAimingLine<Id = auto>([body], priority?=, lengthMultiplier?, maxLength?, diminish?, fade?, taper?, [radius, owner?, audience?, camera?, flicker?, shadow?, bloom?, bloomAlpha?, color?, crater?, feather?, glare?, glareAlpha?, layer?, luminous?, opacity?, shine?])
delete this.PointerAimingLine<Id>

Creates a behavior which will display a line between a body and the current position of the mouse pointer. It is better to use this function than manually creating a Streak for example, because this will display the aiming line with zero lag.

  • this (Entity): Defines the lifespan of the line. When this despawns, the line is deleted.

  • body (Entity or Vector): Defines the position the line will be drawn from, whether that be from a fixed position Vector, or tracking an Entity's body.

  • audience (Entity, Symbol or Flag): If provided, only the specified audience will see the aiming line. Defaults to owner. See Audience.

  • owner (Entity): The player or team who owns the aiming line. Only used to interpret the audience parameter.

  • priority (Number): Only the highest priority aiming line will be shown. Must be an integer between -128 and 127. Defaults to 0.

  • radius (Number): The width of the line, measured as the distance from the center to the edge.

  • lengthMultiplier (Number): The length of the line will be equal to the distance between body and the player's Pointer, multiplied by this number. Defaults to 3.

  • maxLength (Number): The maximum length of the line, in game-world coordinates. Defaults to 100.

  • layer (Number): The rendering layer of the sprite. Sprites on higher layers will be drawn over the top of sprites on lower layers. Must be a number between -128 and 127 (inclusive). Defaults to 0.

  • diminish (Number): A proportion between 0 and 1 where 1 means its shine, bloomAlpha and glareAlpha will diminish to zero as the line extends away from body, while 0 means they will remain the same. This can be used to make the line look brighter at one end. Defaults to 1.

  • fade (Number or Color): If set to a Number, a proportion between 0 and 1 where 1 means it will fade to transparent as it extends away from the body, while 0 means it will remain fully opaque. If set to a Color, the line will fade to that color as it extends away from body. Defaults to 1.

  • taper (Number): A proportion between 0 and 1 where 1 means it will taper to a point as it extends away from the body, while 0 means it will remain the same width. Defaults to 0.

  • color (Color): The color of the line.

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it, where 1 will add fully and will make the line look like it is made of light rather than paint.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the line, making it look brighter.

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the graphic.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the shape brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the shape.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • bloom (Number): Makes the space outside of the line glow. This number is the maximum distance from the line that the bloom should extend.

  • bloomAlpha (Number): A proportion between 0 and 1 controlling the opacity of the bloom.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the line. Defaults to World (the main camera).

PolygonHotspot​

this.PolygonHotspot<Id = auto>(intent?, [shape, body], heading?=, face?, billboard?, angleOffset?, bodyOffset?, scale?, screenOffset?, growth?, rotate?, shift?, shine?, [bodyScale?, layer?, noRotation?, tolerance?, audience?, owner?, camera?])
delete this.PolygonHotspot<Id>

Creates a hotspot within the game world which the player can click on. This can be used to make things clickable, selectable or hoverable within the game world.

Hotspots do not have any graphics by themselves, but when the player hovers a hotspot with their mouse, the sprites will Strobe. By default, it will act like Strobe(growth=0.05, shine=0.1), but this can be customized, either by passing in parameters directly into this function, or globally in the [graphics] section of easel.toml. The mouse pointer will also be changed to indicate the player can interact with the hotspot.

  • this (Entity): Defines the lifespan of the hotspot. When this despawns, the hotspot is deleted.
  • Id: A unique identifier for the hotspot. If a hotspot already exists on this with the same Id, the previous hotspot will be replaced.

Intent:

  • intent (Intent/Keycode or Array of Intent/Keycodes): The action to take when the hotspot is pressed. null (the default) means no action. The most common intent is a PressIntent. If provided a Keycode, the hotspot will simulate a press of that key when clicked. It is possible to provide an array of multiple intents, which will be executed in order. Unlike a Button, a hotspot cannot accept a String intent to take the player to an external website when clicked, and so if you provide a String intent, it will be ignored. See Intents to learn more.

Shape:

  • shape (Polygon): The shape of the hotspot.

  • tolerance (Number): Some shapes may need to be approximated in order to perform efficient overlap detection. This value determines the maximum allowed distance between the original shape and the approximated shape. Greater tolerance allows of better performance but less accuracy. Defaults to 0.25.

Position:

  • body (Entity, Vector or Symbol): The position of the hotspot, whether it be attached to an Entity's body or fixed at a Vector position. There are also a number of other symbolic values available, see Position for the full list.

  • bodyOffset (Vector): If set, determines the attachment point of the hotspot on the body.

  • screenOffset (Vector): If set, offsets the position of the hotspot by this Vector. Unlike bodyOffset, this is done in screen space and so does not follow the rotation of the body.

Orientation:

  • noRotation (Boolean): If truthy, stops the hotspot from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the hotspot, which affects both the hotspot's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the hotspot will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the hotspot such that it points towards the given position. Affects both the hotspot's rotation and its bodyOffset.

    • Vector: the hotspot will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the hotspot will face towards the given entity's position

  • billboard (Boolean): If true, the hotspot's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the hotspot's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the hotspot will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

  • bodyScale (Number or Vector): The size of the hotspot and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Z-order:

  • layer (Number): The rendering layer of the hotspot. If two hotspots overlap, hotspots on higher layers will be take precedence over hotspots on lower layers. Must be a number between -128 and 127 (inclusive). Defaults to 0.

Strobe:

These parameters decide what should happen when the player hovers over the hotspot. They act like a Strobe, temporarily modifying all graphics on the entity.

  • growth (Number or Vector): A proportion of the growth to apply to all graphics when the hotspot is hovered over. Defaults to 0. A growth of 0.5 would make the graphics grow to 1.5 times their normal size temporarily. Provide a Vector instead of a Number to perform non-uniform scaling, e.g. @(0.5, 0) will make the graphics 50% bigger in the X direction only.

  • rotate (Number): An angle to rotate all the sprites around their body when the hotspot is hovered over. Defaults to 0rev.

  • shift (Vector): All graphics will be offset by this amount on screen when the hotspot is hovered over. Defaults to @(0, 0).

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprites when the hotspot is hovered over, making them look brighter.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, only the specified audience will be able to see and interact with the hotspot. Defaults to owner. See Audience.

  • owner (Entity): The player or team entity that owns the hotspot. Used as the default value for audience.

  • camera (Entity or Array of Entities): Determines the camera(s) for which the hotspot will apply. Defaults to World (the main camera).

PolygonSpark​

this.PolygonSpark<Id = auto>([shape, body], heading?=, face?, billboard?, bodyOffset?, screenOffset?, angleOffset?, scale?, speed?, velocity?, acceleration?, turnRate?, image?, imageAnchor?, imageOffset?, imageRadius?, tile?, [audience?, bloom?, bloomAlpha?, bodyScale?, camera?, color?, crater?, diminish?, dissipate?, fade?, feather?, flicker?, frameInterval?, frameRepeat?, glare?, glareAlpha?, glaze?, layer?, luminous?, noRotation?, opacity?, owner?, ownerColor?, shading?, shadow?, sharp?, shine?, splatter?, strobe?, taper?])

Creates a spark particle in a given Polygon shape that dissipates over time.

  • this (Entity): Defines the entity the Spark will Strobe with. Unlike other functions, the lifetime of a spark is not tied to its this entity. If this despawns, the spark will continue to exist until it dissipates like normal.
  • Id: The ID for the spark. Sparks with the same this and Id will be rendered together by the engine. This is done to improve performance. Certain fields, such as layer, are shared between all sparks in the same group. The last spark determines the value of these fields for the entire group.

Shape:

  • shape (Polygon): The shape of the sprite.

Position:

  • body (Entity or Vector): The position of the spark, whether it be spawned at an Entity's body or at a specific Vector position.

  • bodyOffset (Vector): If set, determines the attachment point of the sprite on the body.

  • screenOffset (Vector): If set, offsets the position of the sprite by this Vector. Unlike bodyOffset, this is done in screen space and so does not follow the rotation of the body.

  • glaze (Number or Bool): If true, randomly offsets the position of the sprite to a random position within the Perimeter of the entity. If a Number, should be a proportion between 0 and 1 where 1 spawns the spark at a random point on the edge of the perimeter, while 0 spawns it in the center.

Orientation:

  • noRotation (Boolean): If truthy, stops the sprite from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the sprite, which affects both the sprite's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the sprite will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the sprite such that it points towards the given position. Affects both the sprite's rotation and its bodyOffset.

    • Vector: the sprite will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the sprite will face towards the given entity's position

  • billboard (Boolean): If true, the sprite's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the sprite's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the sprite will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.
  • bodyScale (Number or Vector): The size of the sprite and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Z-order:

  • layer (Number): The layer at which to draw the spark. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.

Texture:

  • image (Asset or Array): If set, the sprite will be textured with this image. The image will be clipped so it only appears within the shape. Can either be a single asset, e.g. @fireball.png, or an array of frames, e.g. [@fireball1.png, @fireball2.png] or @fireball*.png (see Asset Wildcards). If you are using an array of frames, the sprite will cycle through the frames at the interval specified by frameInterval.

  • frameInterval (Number): The number of ticks to wait before switching to the next frame. Defaults to 0.1s.

  • frameRepeat (Boolean): If true, the sprite will loop through the frames. Defaults to true.

  • imageAnchor (Vector): Designates which point of the image will be placed at the sprite origin. Defaults to @(0, 0), which places the center of the image at the sprite origin. A value of @(-1, -1) would place the top left corner of the image at the sprite origin, whereas @(1, 1) would place the bottom right corner of the image at the sprite origin.

  • imageOffset (Vector): Displaces the image by this amount in world coordinates.

  • imageRadius (Number): Determines the size of the image, in world coordinates. Defaults to the the bounding radius of the shape.

  • tile (Number or Boolean): If a Number, the image will be tiled (repeated horizontally and vertically), with tile determining the radius of each tile. If true, the image will be tiled, using imageRadius as the tile radius.

  • sharp (Boolean): If true, will preserve the pixelation of the image by using neearest neighbor interpolation. This can be used to make pixel art games. Defaults to false.

Color:

  • color (Color): The color of the spark.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the spark should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the spark in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the spark in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter. This can be controlled dynamically to make a sprite flash or glow temporarily.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the shape brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the shape.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0. Defaults to 1.

  • shading (Number): A proportion between 0 and 1 controlling the intensity of shading. Shading adds a gradient to the graphic, mixing it with more black as it gets closer to its bottom left corner. This can make flat shapes look more interesting.

Effects:

  • bloom (Number): Makes the space outside of the polygon glow. This number is the maximum distance from the polygon that the bloom should extend.

  • bloomAlpha (Number): A proportion between 0 and 1 controlling the opacity of the bloom.

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the graphic. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a spark look like it is made of light rather than paint.

Dissipation:

  • dissipate (Number): The number of ticks before the spark dissipates. Defaults to 0.25s.

  • fade (Color or Number): If a Color, determines the color the spark will blend towards as it dissipates. If a Number, should be a proportion between 0 and 1 where 1 means the spark will fade to transparent as it dissipates, while 0 means it will not fade at all.

  • diminish (Number): A proportion between 0 and 1 where 1 means its shine, bloomAlpha and glareAlpha will diminish to zero as it dissipates, while 0 means they will remain the same. This can be used to make the line look brighter at one end. Defaults to 1.

  • taper (Number): A proportion between 0 and 1 where 1 means the scale, bloom and glare will reduce to zero as it dissipates, while 0 means it will remain the same radius. Defaults to 1.

Trajectory:

  • velocity (Vector): The spark will move in the speed and direction determined by this parameter. Defaults to @(0, 0).

  • speed (Number): The spark will move at this speed in a random direction. If both velocity and speed are specified, their effects will be added together. Defaults to 0.

  • acceleration (Vector): The spark's velocity will change at this rate per second. Set to acceleration=Gravity to make the spark fall at the speed of gravity. Defaults to @(0, 0).

  • splatter (Number): A proportion between 0 and 1 which controls how much the spark should splatter. Splattering will primarily occur in the direction of velocity of the body Entity. This can be used to create the splatter from a fireball, for example, when it hits.

  • turnRate (Number): The spark will be rotated by this amount per second.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, the spark will only be visible to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the spark.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the spark. Defaults to World (the main camera).

PolygonSprite​

this.PolygonSprite<Id = auto>([shape, body], heading?=, face?, billboard?, angleOffset?, bodyOffset?, scale?, screenOffset?, overlay?, image?, imageAnchor?, imageOffset?, imageRadius?, tile?, [audience?, bloom?, bloomAlpha?, bodyScale?, camera?, color?, crater?, feather?, flicker?, frameInterval?, frameRepeat?, glare?, glareAlpha?, layer?, luminous?, noRotation?, opacity?, owner?, ownerColor?, shading?, shadow?, sharp?, shine?, strobe?])
delete this.PolygonSprite<Id>

Creates a sprite which will display a polygon attached to a given body.

  • this (Entity): Defines the lifespan of the sprite. When this despawns, the sprite is deleted.
  • Id: A unique identifier for the sprite. If a sprite already exists on this with the same Id, the previous sprite will be replaced.

Shape:

  • shape (Polygon): The shape of the sprite.

Position:

  • body (Entity, Vector or Symbol): The position of the sprite, whether it be attached to an Entity's body or fixed at a Vector position. If given the special symbolic value of Position:AtPointer, the sprite will attach itself to the player's pointer. There are also a number of other symbolic values available, see Position for the full list.

  • bodyOffset (Vector): If set, determines the attachment point of the sprite on the body.

  • screenOffset (Vector): If set, offsets the position of the sprite by this Vector. Unlike bodyOffset, this is done in screen space and so does not follow the rotation of the body.

Orientation:

  • noRotation (Boolean): If truthy, stops the sprite from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the sprite, which affects both the sprite's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the sprite will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the sprite such that it points towards the given position. Affects both the sprite's rotation and its bodyOffset.

    • Vector: the sprite will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the sprite will face towards the given entity's position

  • billboard (Boolean): If true, the sprite's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the sprite's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the sprite will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

  • bodyScale (Number or Vector): The size of the sprite and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Z-order:

  • layer (Number): The rendering layer of the sprite. Sprites on higher layers will be drawn over the top of sprites on lower layers. Must be a number between -128 and 127 (inclusive). Defaults to 0.

  • overlay (Number): When multiple sprites are attached to the same body, sprites with higher overlay will be drawn over the top of sprites with a lower overlay. Must be a number between -128 and 127 (inclusive). Defaults to 0.

Texture:

  • image (Asset or Array): If set, the sprite will be textured with this image. The image will be clipped so it only appears within the shape. Can either be a single asset, e.g. @fireball.png, or an array of frames, e.g. [@fireball1.png, @fireball2.png] or @fireball*.png (see Asset Wildcards). If you are using an array of frames, the sprite will cycle through the frames at the interval specified by frameInterval.

  • frameInterval (Number): The number of ticks to wait before switching to the next frame. Defaults to 0.1s.

  • frameRepeat (Boolean): If true, the sprite will loop through the frames. Defaults to true.

  • imageAnchor (Vector): Designates which point of the image will be placed at the sprite origin. Defaults to @(0, 0), which places the center of the image at the sprite origin. A value of @(-1, -1) would place the top left corner of the image at the sprite origin, whereas @(1, 1) would place the bottom right corner of the image at the sprite origin.

  • imageOffset (Vector): Displaces the image by this amount in world coordinates.

  • imageRadius (Number): Determines the size of the image, in world coordinates. Defaults to the the bounding radius of the shape.

  • tile (Number or Boolean): If a Number, the image will be tiled (repeated horizontally and vertically), with tile determining the radius of each tile. If true, the image will be tiled, using imageRadius as the tile radius.

  • sharp (Boolean): If true, will preserve the pixelation of the image by using neearest neighbor interpolation. This can be used to make pixel art games. Defaults to false.

Color:

  • color (Color): If set, the sprite is tinted with this color.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the sprite should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the sprite in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the sprite in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter. This can be controlled dynamically to make a sprite flash or glow temporarily.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the shape brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the shape.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0. Defaults to 1.

  • shading (Number): A proportion between 0 and 1 controlling the intensity of shading. Shading adds a gradient to the graphic, mixing it with more black as it gets closer to its bottom left corner. This can make flat shapes look more interesting.

Effects:

  • bloom (Number): Makes the space outside of the polygon glow. This number is the maximum distance from the polygon that the bloom should extend.

  • bloomAlpha (Number): A proportion between 0 and 1 controlling the opacity of the bloom.

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the graphic. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a sprite look like it is made of light rather than paint.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, the sprite will only be visible to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player or team entity that owns the sprite.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the sprite. Defaults to World (the main camera).

PolygonStencil​

this.PolygonStencil<Id = auto>([shape, body], heading?=, face?, billboard?, angleOffset?, bodyOffset?, scale?, screenOffset?, image?, imageAnchor?, imageOffset?, imageRadius?, tile?, [audience?, bodyScale?, camera?, crater?, frameInterval?, frameRepeat?, noRotation?, owner?])
delete this.PolygonStencil<Id>

Limits rendering to the area inside a polygon. See Stencils for more information.

  • this (Entity): Defines the lifespan of the stencil. When this despawns, the stencil is deleted.
  • Id: A unique identifier for the stencil. If a stencil already exists on this with the same Id, the previous stencil will be replaced.

Shape:

  • shape (Polygon): The shape of the stencil.

Position:

  • body (Entity, Vector or Symbol): The position of the stencil, whether it be attached to an Entity's body or fixed at a Vector position. If given the special symbolic value of Position:AtPointer, the stencil will attach itself to the player's pointer. There are also a number of other symbolic values available, see Position for the full list.

  • bodyOffset (Vector): If set, determines the attachment point of the stencil on the body.

  • screenOffset (Vector): If set, offsets the position of the stencil by this Vector. Unlike bodyOffset, this is done in screen space and so does not follow the rotation of the body.

Orientation:

  • noRotation (Boolean): If truthy, stops the stencil from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the stencil, which affects both the stencil's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the stencil will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the stencil such that it points towards the given position. Affects both the stencil's rotation and its bodyOffset.

    • Vector: the stencil will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the stencil will face towards the given entity's position

  • billboard (Boolean): If true, the stencil's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the stencil's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the stencil will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

  • bodyScale (Number or Vector): The size of the stencil and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Texture:

  • image (Asset or Array): If set, the stencil will be textured with this image. Opaque parts of the image will allow the camera to be rendered, whereas transparent parts of the image will be stenciled out of the camera. The image will be clipped so it only appears within the shape. Can either be a single asset, e.g. @fireball.png, or an array of frames, e.g. [@fireball1.png, @fireball2.png] or @fireball*.png (see Asset Wildcards). If you are using an array of frames, the stencil will cycle through the frames at the interval specified by frameInterval.

  • frameInterval (Number): The number of ticks to wait before switching to the next frame. Defaults to 0.1s.

  • frameRepeat (Boolean): If true, the stencil will loop through the frames. Defaults to true.

  • imageAnchor (Vector): Designates which point of the image will be placed at the stencil origin. Defaults to @(0, 0), which places the center of the image at the stencil origin. A value of @(-1, -1) would place the top left corner of the image at the stencil origin, whereas @(1, 1) would place the bottom right corner of the image at the stencil origin.

  • imageOffset (Vector): Displaces the image by this amount in world coordinates.

  • imageRadius (Number): Determines the size of the image, in world coordinates. Defaults to the the bounding radius of the shape.

  • tile (Number or Boolean): If a Number, the image will be tiled (repeated horizontally and vertically), with tile determining the radius of each tile. If true, the image will be tiled, using imageRadius as the tile radius.

Effects:

  • crater (Number): A proportion between 0 and 1 which determines the size of a hole in the middle of the polygon shape.

Viewer:

  • audience (Entity, Symbol or Flag): If provided, the stencil will only apply to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player or team entity that owns the stencil. Used to interpret the audience parameter.

  • camera (Entity or Array of Entities): Determines which camera(s) will be affected by the stencil. Defaults to World (the main camera).

ResolutionDropdown​

ResolutionDropdown(width?=, [ui])

Creates a resolution editor dropdown in the user interface that allows the current player to change the resolution of the game. Higher resolutions look better but may run slower on older devices.

  • width (Number): the width of the resolution editor in em units.
  • ui (UI): the slot in the user interface to insert the resolution editor element.

ResolutionIntent​

ResolutionIntent(resolution) -> intent

Returns an Intent to change the resolution to a particular level.

  • resolution (Symbol): The new resolution level. Valid values are Resolution:Max, Resolution:High and Resolution:Low. This function will return undefined if given any other value. See Resolution for more information.

ResolutionToggle​

ResolutionToggle([ui=]) |use ui:whenMax, use ui:whenHigh, use ui:whenLow| { }

Creates a element in the user interface that allows the player to toggle their graphics resolution.

  • ui (UI): The slot in the user interface where the element will be inserted.

Subblock: The subblock will be called immediately to populate the element's content. It is optional to provide this as there are defaults for all three resolution levels. Use the %ui:whenMax { ... } syntax to populate one of the slots, see Multiple Slots for more information.

  • ui:whenMax (UI): populate this slot with the content that should be displayed when resolution is set to maximum. If left empty, will display a default button that will change the resolution to high.
  • ui:whenHigh (UI): populate this slot with the content that should be displayed when resolution is set to high. If left empty, will display a default button that will change the resolution to low.
  • ui:whenLow (UI): populate this slot with the content that should be displayed when resolution is set to low. If left empty, will display a default button that will change the resolution to maximum.

ShadowOffset​

ShadowOffset -> vector

Gets the global shadow offset. Defaults to @(0, 0.5) unless otherwise set. Any sprite that uses the shadow parameter will display a shadow with this screen offset.

The initial shadow offset value is determined by the shadow parameter in the [graphics] section of easel.toml.

ShadowOffset = value

Sets the global shadow offset. Must be a Vector.

await ShadowOffset -> vector

Waits for the global shadow offset to change, then returns its new value.

SolidBackground​

this.SolidBackground<Id = auto>(color, luminous?=, priority?, audience?, [owner?, camera?])

Creates a behavior that sets the background of the screen to a solid color.

  • this (Entity): Defines the lifespan of the background. When this despawns, this behavior is deleted.

  • color (Color): The color of the background.

  • luminous (Number): A proportion between 0 and 1 controlling how much the background adds rather than mixes its color with what is behind it. Setting luminous to 1 will make the background look like it is made of light rather than paint. This parameter is only useful if you have multiple cameras layered on top of each other. Defaults to 0.

  • priority (Number): For each camera, only the highest priority background for that camera will be shown. Must be an integer between -128 and 127. Defaults to 0.

  • audience (Entity, Symbol or Flag): If provided, the background is only visible to the specified audience. Defaults to owner. See Audience.

  • owner (Entity): The player or team who owns the background. Only used to interpret the audience parameter.

  • camera (Entity or Array of Entities): Determines which camera(s) will display this background. Defaults to World (the main camera).

delete this.SolidBackground<Id>

Deletes a previously-assigned solid background behavior from this Entity.

Spark​

this.Spark<Id = auto>([body], bodyOffset?=, screenOffset?, speed?, velocity?, acceleration?, [color, radius, audience?, bloom?, bloomAlpha?, bodyScale?, camera?, crater?, diminish?, dissipate?, fade?, feather?, flicker?, glare?, glareAlpha?, glaze?, layer?, luminous?, opacity?, owner?, ownerColor?, shading?, shadow?, shine?, splatter?, strobe?, taper?])

Creates a spark particle. A spark is a particle in the shape of a circle that dissipates over time. It can be used to create a variety of effects, for example the trail behind a comet or the smoke of an icy whirlwind.

  • this (Entity): Defines the entity the Spark will Strobe with. Unlike other functions, the lifetime of a spark is not tied to its this entity. If this despawns, the spark will continue to exist until it dissipates like normal.

  • Id: The ID for the spark. Sparks with the same this and Id will be rendered together by the engine. This is done to improve performance. Certain fields, such as layer, are shared between all sparks in the same group. The last spark determines the value of these fields for the entire group.

  • radius (Number): The radius of the spark.

Position:

  • body (Entity or Vector): The position of the spark, whether it be spawned at an Entity's body or at a specific Vector position.

  • bodyOffset (Vector): An offset from the body position where the spark should be spawned. This offset will be rotated to match the body's heading.

  • screenOffset (Vector): An offset from the body position where the spark should be spawned.

  • glaze (Number or Bool): If true, randomly offsets the position of the graphic to a random position within the Perimeter of the entity. If a Number, should be a proportion between 0 and 1 where 1 spawns the spark at a random point on the edge of the perimeter, while 0 spawns it in the center.

Scaling:

  • bodyScale (Number): Both the radius and the bodyOffset of the spark will be scaled by this number. Defaults to 1.

Z-order:

  • layer (Number): The layer at which to draw the spark. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.

Color:

  • color (Color): The color of the spark.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the spark should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the spark in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the spark in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter. This can be controlled dynamically to make a sprite flash or glow temporarily.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the shape brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the shape.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0. Defaults to 1.

Effects:

  • bloom (Number): Makes the space outside of the polygon glow. This number is the maximum distance from the polygon that the bloom should extend.

  • bloomAlpha (Number): A proportion between 0 and 1 controlling the opacity of the bloom.

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the graphic. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a spark look like it is made of light rather than paint.

Dissipation:

  • dissipate (Number): The number of ticks before the spark dissipates. Defaults to 0.25s.

  • fade (Color or Number): If a Color, determines the color the spark will blend towards as it dissipates. If a Number, should be a proportion between 0 and 1 where 1 means the spark will fade to transparent as it dissipates, while 0 means it will not fade at all.

  • diminish (Number): A proportion between 0 and 1 where 1 means its shine, bloomAlpha and glareAlpha will diminish to zero as it dissipates, while 0 means they will remain the same. This can be used to make the line look brighter at one end. Defaults to 1.

  • taper (Number): A proportion between 0 and 1 where 1 means the radius, bloom and glare will reduce to zero as it dissipates, while 0 means it will remain the same radius. Defaults to 1.

Trajectory:

  • velocity (Vector): The spark will move in the speed and direction determined by this parameter. Defaults to @(0, 0).

  • speed (Number): The spark will move at this speed in a random direction. If both velocity and speed are specified, their effects will be added together. Defaults to 0.

  • acceleration (Vector): The spark's velocity will change at this rate per second. Set to acceleration=Gravity to make the spark fall at the speed of gravity. Defaults to @(0, 0).

  • splatter (Number): A proportion between 0 and 1 which controls how much the spark should splatter. Splattering will primarily occur in the direction of velocity of the body Entity. This can be used to create the splatter from a fireball, for example, when it hits.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, the spark will only be visible to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the spark.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the spark. Defaults to World (the main camera).

Strand​

this.Strand<Id = auto>([body], to, bodyOffset?=, screenOffset?, toBodyOffset?, toScreenOffset?, [color, radius, audience?, bloom?, bloomAlpha?, bodyScale?, camera?, crater?, dissipate?, fade?, feather?, flicker?, glare?, glareAlpha?, layer?, luminous?, opacity?, owner?, ownerColor?, retract?, shadow?, shine?, strobe?, taper?])
delete this.Strand<Id>

Displays a line that connects two bodies together.

  • this (Entity): Defines the lifespan of the strand. When this despawns, this behavior is deleted.

  • Id (String): The ID for the strand. This is used to distinguish between different strands on the same entity.

  • radius (Number): The radius of the strand.

Position:

  • body (Entity, Vector or Symbol): The origin position of the strand, whether it be attached to an Entity's body, a fixed Vector position or a Position symbol.

  • to (Entity, Vector or Symbol): The end position of the strand, whether it be attached to an Entity's body, a fixed Vector position or a Position symbol.

  • bodyOffset (Vector): An offset from the body position where the strand should be attached. This offset will be rotated to match the body's heading.

  • screenOffset (Vector): An offset from the body position where the strand should be attached.

  • toBodyOffset (Vector): An offset from the to position where the strand should be attached. This offset will be rotated to match the body's heading.

  • toScreenOffset (Vector): An offset from the to position where the strand should be attached.

Scaling:

  • bodyScale (Number): The radius of the strand will be multipled by this factor. Defaults to 1.

Z-order:

  • layer (Number): The layer at which to draw the strand. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.

Color:

  • color (Color): The color of the strand.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the strand should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the strand in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the strand in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the shape brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the shape.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0.

Effects:

  • bloom (Number): Makes the space outside of the polygon glow. This number is the maximum distance from the polygon that the bloom should extend.

  • bloomAlpha (Number): A proportion between 0 and 1 controlling the opacity of the bloom.

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the graphic. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a strand look like it is made of light rather than paint.

Dissipation:

  • dissipate (Number): When the this entity despawns, instead of dissipating immediately, the origin of the strand will retract. This is number of ticks it takes for the strand to retract. If the strand is deleted (using delete Strand), it will disappear immediately.

  • retract (Boolean): If false (the default), the strand will retract to its to position as it dissipates. If true, the strand will retract to its body position as it dissipates.

  • fade (Color or Number): If a Color, determines the color the strand will blend towards as it dissipates. If a Number, should be a proportion between 0 and 1 where 1 means the strand will fade to transparent as it dissipates, while 0 means it will not fade at all.

  • taper (Number): A proportion between 0 and 1 where 1 means the radius, bloom and glare will reduce to zero as it dissipates, while 0 means it will remain the same radius.

Viewer:

  • audience (Entity, Symbol or Flag): If provided, the strand will only be visible to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the strand.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the strand. Defaults to World (the main camera).

Streak​

this.Streak<Id = auto>([body], bodyOffset?=, screenOffset?, [color, radius, audience?, bloom?, bloomAlpha?, bodyScale?, camera?, crater?, diminish?, dissipate?, fade?, feather?, flicker?, glare?, glareAlpha?, layer?, luminous?, opacity?, owner?, ownerColor?, shadow?, shine?, strobe?, taper?])

Displays a streak, which is a rendered line that dissipates over time.

  • this (Entity): Defines the entity that owns the streak. Unlike other functions, if this despawns, streak will continue to exist until it dissipates like normal.

  • Id: The ID for the streak. This is used to distinguish between different streaks on the same entity.

  • radius (Number): The radius of the streak.

Position:

  • body (Entity or Vector): The origin position of the streak, whether it be attached to an Entity's body or at a fixed Vector position. If an Entity, the head of the streak will be extended to the current position of the body. This only occurs once - to make the Streak follow the body, you must call this function again. If a Vector, the head of the streak will be extended to the position of the vector.
  • bodyOffset (Vector): An offset to apply to all new streak points. If body is an Entity with a body, this offset will be rotated to match the current heading of body.
  • screenOffset (Vector): An offset to apply to all new streak points.

Scaling:

  • bodyScale (Number): The radius and bodyOffset will be multiplied by this factor. Defaults to 1.

Z-order:

  • layer (Number): The layer at which to draw the streak. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.

Color:

  • color (Color): The color of the streak.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the streak should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the streak in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the streak in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the streak, making it look brighter.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the shape brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the shape.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this streak should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0.

Effects:

  • bloom (Number): Makes the space outside of the polygon glow. This number is the maximum distance from the polygon that the bloom should extend.

  • bloomAlpha (Number): A proportion between 0 and 1 controlling the opacity of the bloom.

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the graphic.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the streak adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a streak look like it is made of light rather than paint.

Dissipation:

  • dissipate (Number): The number of ticks it takes for the streak to dissipate. Defaults to 0.25s.

  • fade (Color or Number): If a Color, determines the color the streak will blend towards as it dissipates. If a Number, should be a proportion between 0 and 1 where 1 means the streak will fade to transparent as it dissipates, while 0 means it will not fade at all.

  • diminish (Number): A proportion between 0 and 1 where 1 means its shine, bloomAlpha and glareAlpha will diminish to zero as it dissipates, while 0 means they will remain the same. This can be used to make the streak look brighter at one end. Defaults to 1.

  • taper (Number): A proportion between 0 and 1 where 1 means the radius, bloom and glare will reduce to zero as it dissipates, while 0 means it will remain the same radius.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, only the specified audience will see the streak. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the streak.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the streak. Defaults to World (the main camera).

delete this.Streak<Id>

Ends an existing streak. Any new points will begin a new streak, unconnected to the previous streak. The old streak will dissipate as normal.

  • this (Entity): Defines the entity that owns the streak.
  • Id: The ID for the streak. Provide the same ID as the one used to create the streak.

Strobe​

this.Strobe<Id = auto>([dissipate?], swell?=, fade?, growth?, rotate?, scale?, shift?, shine?, taper?)
delete this.Strobe<Id>

Temporarily modifies the graphics attached to this for a short duration. This can be used to create hit flashes, shaking effects, invincibility flashing, or other effects.

  • this (Entity): The entity to strobe.
  • Id: An optional ID to distinguish between multiple strobes on the same entity. If a strobe already exists with the same this and Id, it will be replaced.

Duration:

  • dissipate (Number): The duration of the strobe in ticks. Defaults to 0.25s.

Effects:

  • fade (Number): Reduce the opacity of all graphics by this proportion. Should be a value between 0 and 1. Defaults to 0.

  • growth (Number or Vector): A proportion of the growth to apply to all graphics. Defaults to 0. A growth of 0.5 would make the graphics grow to 1.5 times their normal size temporarily. Provide a Vector instead of a Number to perform non-uniform scaling, e.g. @(0.5, 0) will make the graphics 50% bigger in the X direction only.

  • shift (Vector): Offsets the graphics along the screen axes (like a temporary screenOffset). Defaults to @(0, 0).

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprites, making them look brighter.

  • rotate (Number): An angle to rotate all the sprites around their body. Defaults to 0rev.

Animation:

  • swell (Number): A proportion between 0 and 1 indicating how much time it should take for the strobe to reach its maximum. A value of 0 means it begins at maximum straight away, whereas 1 means it takes its whole duration to grow to maximum. Defaults to 0.

  • taper (Number): A proportion between 0 and 1 indicating how much the strobe should taper off over time. A value of 1 (the default) means the strobe will taper off completely as it dissipates, whereas 0 means it will remain at full strength until the end of its duration.

Swoop​

this.Swoop<Id = auto>([body], heading?=, bodyOffset?, screenOffset?, angleOffset?, [color, length, audience?, bloom?, bloomAlpha?, bodyScale?, camera?, crater?, diminish?, dissipate?, fade?, feather?, flicker?, glare?, glareAlpha?, layer?, luminous?, opacity?, owner?, ownerColor?, shadow?, shine?, strobe?, taper?])

Displays a swoop, which is a sector of a circle that dissipates over time.

  • this (Entity): Defines the entity that owns the swoop. Unlike other functions, if this despawns, swoop will continue to exist until it dissipates like normal.

  • Id (String): The ID for the swoop. This is used to distinguish between different swoops on the same entity.

  • length (Number): The length of the swoop, measured as the distance from the center of the body to the edge of the swoop.

Position:

  • body (Entity, Vector or Symbol): The position of the swoop, whether it be attached to an Entity's body, a fixed Vector position, or a Position symbol.

  • bodyOffset (Vector): Applies an offset to body position. This will be rotated to match the current heading of body, unless noRotation is true.

  • screenOffset (Vector): Applies an offset to the body position.

  • heading (Number or Entity): The heading of the swoop. Normally this is determined from body, but you can use this parameter to override it. Provide either a Number to use a fixed angle, or an Entity to use the heading of that Entity.

  • angleOffset (Number): This is added to the heading of the swoop to calculate the direction of the swoop. Defaults to 0.

Scaling:

  • bodyScale (Number): The length of the swoop and the bodyOffset will be multiplied by this number. Defaults to 1.

Z-order:

  • layer (Number): The layer at which to draw the swoop. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.

Color:

  • color (Color): The color of the swoop.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the swoop should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the swoop in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the swoop in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the swoop, making it look brighter.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the shape brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the shape.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this swoop should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0.

Effects:

  • bloom (Number): Makes the space outside of the polygon glow. This number is the maximum distance from the polygon that the bloom should extend.

  • bloomAlpha (Number): A proportion between 0 and 1 controlling the opacity of the bloom.

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole starting from the origin of the sector and extending to the edge of the swoop.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the swoop adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a swoop look like it is made of light rather than paint.

Dissipation:

  • dissipate (Number): The number of ticks it takes for the swoop to dissipate. Defaults to 0.25s.

  • fade (Color or Number): If a Color, determines the color the swoop will blend towards as it dissipates. If a Number, should be a proportion between 0 and 1 where 1 means the swoop will fade to transparent as it dissipates, while 0 means it will not fade at all.

  • diminish (Number): A proportion between 0 and 1 where 1 means its shine, bloomAlpha and glareAlpha will diminish to zero as it dissipates, while 0 means they will remain the same. This can be used to make the swoop look brighter at one end. Defaults to 1.

  • taper (Number): A proportion between 0 and 1 where 1 means the radius, bloom and glare will reduce to zero as it dissipates, while 0 means it will remain the same radius. Defaults to 0 (no tapering).

Viewers:

  • audience (Entity, Symbol or Flag): If provided, only the specified audience will see the swoop. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the swoop.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the sprite. Defaults to World (the main camera).

delete this.Swoop<Id>

Ends an existing swoop. Any new swoops will begin a new swoop, unconnected to the previous swoop.

  • this (Entity): Defines the entity that owns the swoop.
  • Id (String): The ID for the swoop. Provide the same ID as the one used to create the swoop.

TextSpark​

this.TextSpark<Id = auto>(text, [body], heading?=, face?, billboard?, angleOffset?, bodyOffset?, screenOffset?, scale?, speed?, velocity?, acceleration?, turnRate?, fontSize?, align?, vAlign?, font?, bold?, italic?, stroke?, strokeAlpha?, [audience?, bodyScale?, camera?, color?, crater?, diminish?, dissipate?, fade?, feather?, flicker?, glare?, glareAlpha?, glaze?, layer?, luminous?, noRotation?, opacity?, owner?, ownerColor?, radius?, shading?, shadow?, shine?, splatter?, strobe?, taper?])

Creates a spark particle which displays the given text and dissipates over time.

  • this (Entity): Defines the entity the Spark will Strobe with. Unlike other functions, the lifetime of a spark is not tied to its this entity. If this despawns, the spark will continue to exist until it dissipates like normal.

  • Id: The ID for the spark. Sparks with the same this and Id will be rendered together by the engine. This is done to improve performance. Certain fields, such as layer, are shared between all sparks in the same group. The last spark determines the value of these fields for the entire group.

  • text (String): The text to display.

Font size:

Choose one of the following methods to define the size of the text:

  • radius (Number): Defines the radius (half the height) of the text sprite in world units. This parameter lets you size the text sprite in a similar way to other sprites in your game world.

  • fontSize (Number): The size of the font in em units. This parameter lets you size the text the similar to other UI elements. A font size of 1 is the normal size for body text on the user's screen, whereas 2 would be twice as large.

Font style:

  • font (Font): The font to use.

  • bold (Boolean): If true, the text will be drawn in bold.

  • italic (Boolean): If true, the text will be drawn in italics.

  • stroke (Number or Boolean): Determines the width of the outline around the text. Should be a value between 0 and 1, where 0 means no stroke and 1 is the maximum size. If true is provided, uses the default value of 0.2.

  • strokeAlpha (Number): A proportion between 0 and 1 which controls how dark the stroke color is, where 0 is the same as the text color and 1 means fully black. Defaults to 1.

Text alignment:

  • align (Symbol): Align:Center (the default) centers the text horizontally on the sprite's origin. Align:Left aligns the left of the text with the sprite's origin. Align:Right aligns the right of the text with the sprite's origin.

  • vAlign (Symbol): VAlign:Middle (the default) centers the text vertically on the sprite's origin. VAlign:Top aligns the top of the text with the sprite's origin. VAlign:Bottom aligns the bottom of the text with the sprite's origin.

Position:

  • body (Entity or Vector): The position of the spark, whether it be spawned at an Entity's body or at a specific Vector position.

  • bodyOffset (Vector): If set, determines the attachment point of the sprite on the body.

  • screenOffset (Vector): If set, offsets the position of the sprite by this Vector. Unlike bodyOffset, this is done in screen space and so does not follow the rotation of the body.

  • glaze (Number or Bool): If true, randomly offsets the position of the sprite to a random position within the Perimeter of the entity. If a Number, should be a proportion between 0 and 1 where 1 spawns the spark at a random point on the edge of the perimeter, while 0 spawns it in the center.

Orientation:

  • noRotation (Boolean): If truthy, stops the sprite from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the sprite, which affects both the sprite's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the sprite will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the sprite such that it points towards the given position. Affects both the sprite's rotation and its bodyOffset.

    • Vector: the sprite will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the sprite will face towards the given entity's position

  • billboard (Boolean): If true, the sprite's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the sprite's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the sprite will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

  • bodyScale (Number or Vector): The size of the sprite and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Z-order:

  • layer (Number): The layer at which to draw the spark. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.

Color:

  • color (Color): The color of the spark.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the spark should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the spark in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the spark in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter. This can be controlled dynamically to make a sprite flash or glow temporarily.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the sprite brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the sprite.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0. Defaults to 1.

  • shading (Number): A proportion between 0 and 1 controlling the intensity of shading. Shading adds a gradient to the sprite, mixing it with more black as it gets closer to its bottom left corner. This can make flat shapes look more interesting.

Effects:

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the sprite. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a spark look like it is made of light rather than paint.

Dissipation:

  • dissipate (Number): The number of ticks before the spark dissipates. Defaults to 0.25s.

  • fade (Color or Number): If a Color, determines the color the spark will blend towards as it dissipates. If a Number, should be a proportion between 0 and 1 where 1 means the spark will fade to transparent as it dissipates, while 0 means it will not fade at all.

  • diminish (Number): A proportion between 0 and 1 where 1 means its shine and glareAlpha will diminish to zero as it dissipates, while 0 means they will remain the same. This can be used to make the line look brighter at one end. Defaults to 1.

  • taper (Number): A proportion between 0 and 1 where 1 means the scale and glare will reduce to zero as it dissipates, while 0 means it will remain the same radius. Defaults to 1.

Trajectory:

  • velocity (Vector): The spark will move in the speed and direction determined by this parameter. Defaults to @(0, 0).

  • speed (Number): The spark will move at this speed in a random direction. If both velocity and speed are specified, their effects will be added together. Defaults to 0.

  • acceleration (Vector): The spark's velocity will change at this rate per second. Set to acceleration=Gravity to make the spark fall at the speed of gravity. Defaults to @(0, 0).

  • splatter (Number): A proportion between 0 and 1 which controls how much the spark should splatter. Splattering will primarily occur in the direction of velocity of the body Entity. This can be used to create the splatter from a fireball, for example, when it hits.

  • turnRate (Number): The spark will be rotated by this amount per second.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, the spark will only be visible to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the spark.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the spark. Defaults to World (the main camera).

TextSprite​

this.TextSprite<Id = auto>(text, [body], heading?=, face?, billboard?, angleOffset?, bodyOffset?, screenOffset?, scale?, overlay?, fontSize?, heightPx?, align?, vAlign?, font?, bold?, italic?, stroke?, strokeAlpha?, [audience?, bodyScale?, camera?, color?, crater?, feather?, flicker?, glare?, glareAlpha?, layer?, luminous?, noRotation?, opacity?, owner?, ownerColor?, radius?, shading?, shadow?, shine?, strobe?])
delete this.TextSprite<Id>

Creates a sprite which will display text attached to a given body.

  • this (Entity): Defines the lifespan of the sprite. When this despawns, the sprite is deleted.

  • Id: A unique identifier for the sprite. If a sprite already exists on this with the same Id, the previous sprite will be replaced.

  • text (String): The text to display.

Font size:

Choose one of the following methods to define the size of the text:

  • radius (Number): Defines the radius (half the height) of the text sprite in world units. This parameter lets you size the text sprite in a similar way to other sprites in your game world.

  • fontSize (Number): The size of the font in em units. This parameter lets you size the text the similar to other UI elements. A font size of 1 is the normal size for body text on the user's screen, whereas 2 would be twice as large.

Font style:

  • font (Font): The font to use.

  • bold (Boolean): If true, the text will be drawn in bold.

  • italic (Boolean): If true, the text will be drawn in italics.

  • stroke (Number or Boolean): Determines the width of the outline around the text. Should be a value between 0 and 1, where 0 means no stroke and 1 is the maximum size. If true is provided, uses the default value of 0.2.

  • strokeAlpha (Number): A proportion between 0 and 1 which controls how dark the stroke color is, where 0 is the same as the text color and 1 means fully black. Defaults to 1.

Text alignment:

  • align (Symbol): Align:Center (the default) centers the text horizontally on the sprite's origin. Align:Left aligns the left of the text with the sprite's origin. Align:Right aligns the right of the text with the sprite's origin.

  • vAlign (Symbol): VAlign:Middle (the default) centers the text vertically on the sprite's origin. VAlign:Top aligns the top of the text with the sprite's origin. VAlign:Bottom aligns the bottom of the text with the sprite's origin.

Position:

  • body (Entity, Vector or Symbol): The position of the sprite, whether it is attached to an Entity's body or fixed at a Vector position. If given the special symbolic value of Position:AtPointer, the sprite will attach itself to the player's pointer. There are also a number of other symbolic values available, see Position for the full list.

  • bodyOffset (Vector): If set, offsets the position of the sprite by this Vector. bodyOffset will be rotated to match the body's current heading.

  • screenOffset (Vector): If set, offsets the position of the sprite by this Vector.

Orientation:

  • noRotation (Boolean): If truthy, stops the sprite from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the sprite, which affects both the sprite's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the sprite will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the sprite such that it points towards the given position. Affects both the sprite's rotation and its bodyOffset.

    • Vector: the sprite will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the sprite will face towards the given entity's position

  • billboard (Boolean): If true, the sprite's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the sprite's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the sprite will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

  • bodyScale (Number or Vector): The size of the sprite and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Z-order:

  • layer (Number): The layer of the sprite. Must be an integer between -128 and 127 (inclusive). Graphics on a higher layer will be drawn over the top of graphics on a lower layer. Defaults to 0.
  • overlay (Number): When multiple sprites are attached to the same body, sprites with higher overlay will be drawn over the top of sprites with a lower overlay. Must be a number between -128 and 127 (inclusive). Defaults to 0.

Color:

  • color (Color): The color of the text. Defaults to white.

  • ownerColor (Boolean or Number or Flags): If set to a Number, indicates the amount the sprite should be tinted with the owner's color. The number should be between 0 and 1. If set to a Boolean, true is equivalent to 1 and false is equivalent to 0. If set to a Flag, will be interpreted as an alliance flag, which filters which players will see the sprite in the owner's color. For example Alliance:Friendly will mean only the owner and their allies will see the sprite in their owner color.

  • flicker (Number): A proportion between 0 and 1 which controls how much of a random color should be blended into the color. The random color changes on every frame, creating a flickering effect.

  • shine (Number): A proportion between 0 and 1 controlling how much white to add to the sprite, making it look brighter.

  • glare (Number): A proportion between 0 and 1 which determines the size of the glare. Glare makes the inside of the sprite brighter, as if it is emitting light. A glare of 1 means the glare reaches the edge of the sprite.

  • glareAlpha (Number): A proportion between 0 and 1 controlling the intensity of the glare. A glareAlpha of 1 means the glare becomes fully white.

  • strobe (Number or Boolean): A proportion between 0 and 1 which controls how much this sprite should Strobe with its this entity. true will also be interpreted as 1, and false will be interpreted as 0. Defaults to 1.

  • shading (Number): A proportion between 0 and 1 controlling the intensity of shading. Shading adds a gradient to the graphic, mixing it with more black as it gets closer to its bottom left corner. This can make flat shapes look more interesting.

Effects:

  • crater (Number): A proportion between 0 and 1 which determines the size of a transparent hole in the middle of the sprite. This is useful for creating circular indicators, for example.

  • feather (Number): A proportion which determines the softness of the border of the sprite, where 0 means the border will be hard and 1 means the border will be soft. A positive value (between 0 and 1) will feather the outside of the sprite, while a negative value (between -1 and 0) will feather the inside.

  • shadow (Number): A proportion between 0 and 1 controlling the opacity of the drop shadow, where 1 makes a fully opaque shadow.

Blending:

  • opacity (Number): A proportion between 0 and 1 where 1 means opaque and 0 means transparent.

  • luminous (Number): A proportion between 0 and 1 controlling how much the sprite adds rather than mixes its color with what is behind it. Setting luminous to 1 will make a sprite look like it is made of light rather than paint.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, the sprite will only be visible to the specified audience. Defaults to Audience:All. See Audience.
  • owner (Entity): The player entity that owns the sprite.
  • camera (Entity or Array of Entities): Determines which camera(s) will render the sprite. Defaults to World (the main camera).

Deprecated parameters:

  • heightPx (Number): Use fontSize instead to specify the height in em units, as they are relative to the user's chosen font size and so scale better across different screen sizes and resolutions.

The following parameters have been deprecated in favor of the more flexible vAlign parameter:

  • anchorTop (Boolean): If true, sets vAlign to VAlign:Top.
  • anchorBottom (Boolean): If true, sets vAlign to VAlign:Bottom.

TextStencil​

this.TextStencil<Id = auto>(text, [body], heading?=, face?, billboard?, angleOffset?, bodyOffset?, screenOffset?, scale?, overlay?, fontSize?, align?, vAlign?, font?, bold?, italic?, stroke?, strokeAlpha?, [audience?, bodyScale?, camera?, color?, crater?, feather?, flicker?, glare?, glareAlpha?, layer?, luminous?, noRotation?, opacity?, owner?, ownerColor?, radius?, shading?, shadow?, shine?, strobe?])
delete this.TextStencil<Id>

Limits rendering to the area of a given text shape. See Stencils for more information.

  • this (Entity): Defines the lifespan of the stencil. When this despawns, the stencil is deleted.

  • Id: A unique identifier for the stencil. If a stencil already exists on this with the same Id, the previous stencil will be replaced.

  • text (String): The text to display.

Font size:

Choose one of the following methods to define the size of the text:

  • radius (Number): Defines the radius (half the height) of the text stencil in world units. This parameter lets you size the text stencil in a similar way to other sprites in your game world.

  • fontSize (Number): The size of the font in em units. This parameter lets you size the text the similar to other UI elements. A font size of 1 is the normal size for body text on the user's screen, whereas 2 would be twice as large.

Font style:

  • font (Font): The font to use.

  • bold (Boolean): If true, the text will be drawn in bold.

  • italic (Boolean): If true, the text will be drawn in italic.

  • stroke (Number or Boolean): Determines the width of the outline around the text. Should be a value between 0 and 1, where 0 means no stroke and 1 is the maximum size. If true is provided, uses the default value of 0.2.

  • strokeAlpha (Number): A proportion between 0 and 1 which controls how dark the stroke color is, where 0 is the same as the text color and 1 means fully black. Defaults to 1.

Text alignment:

  • align (Symbol): Align:Center (the default) centers the text horizontally on the stencil's origin. Align:Left aligns the left of the text with the stencil's origin. Align:Right aligns the right of the text with the stencil's origin.

  • vAlign (Symbol): VAlign:Middle (the default) centers the text vertically on the stencil's origin. VAlign:Top aligns the top of the text with the stencil's origin. VAlign:Bottom aligns the bottom of the text with the stencil's origin.

Position:

  • body (Entity, Vector or Symbol): The position of the stencil, whether it is attached to an Entity's body or fixed at a Vector position. If given the special symbolic value of Position:AtPointer, the stencil will attach itself to the player's pointer. There are also a number of other symbolic values available, see Position for the full list.

  • bodyOffset (Vector): If set, offsets the position of the stencil by this Vector. bodyOffset will be rotated to match the body's current heading.

  • screenOffset (Vector): If set, offsets the position of the stencil by this Vector.

Orientation:

  • noRotation (Boolean): If truthy, stops the stencil from rotating with the body. Same as setting heading=0rev.

  • heading (Number, Vector or Entity): Determines the heading of the stencil, which affects both the stencil's rotation and its bodyOffset.

    • Number: specifies the angle, e.g. 0rev, 0.25rev, -0.5rev
    • Vector: derives the angle from the direction of the vector, e.g. @(1, 0), @(-1, 1)
    • Entity: matches the heading of the given entity
    • If not specified, the stencil will follow the heading of the body.

  • face (Vector or Entity): Sets the heading of the stencil such that it points towards the given position. Affects both the stencil's rotation and its bodyOffset.

    • Vector: the stencil will face towards the given world-space position, e.g. @(12, 34), @(-78, 46)
    • Entity: the stencil will face towards the given entity's position

  • billboard (Boolean): If true, the stencil's rotation will locked to the camera's orientation, so it always appears upright.

  • angleOffset (Number): An additional offset to apply to the stencil's rotation, e.g. 0.25rev for a quarter turn. Defaults to 0rev.

Scaling:

  • scale (Number or Vector): The size of the stencil will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.
  • bodyScale (Number or Vector): The size of the stencil and its bodyOffset will be multiplied by this factor. Width and height can be scaled independently by providing a Vector instead of a Number. Defaults to 1.

Effects:

  • crater (Number): A proportion between 0 and 1 which determines the size of a hole in the middle of the stencil.

Viewers:

  • audience (Entity, Symbol or Flag): If provided, the stencil will only be visible to the specified audience. Defaults to Audience:All. See Audience.

  • owner (Entity): The player entity that owns the stencil.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the sprite. Defaults to World (the main camera).

Vignette​

this.Vignette<Id = auto>(color?=, luminous?, opacity?, power?, layer?, priority?, audience?, [owner?, camera?])

Creates a behavior that applies a vignette effect to the screen. This will color the edges of the screen with your specified color.

  • this (Entity): Defines the lifespan of the behavior. When this despawns, this behavior is deleted.

Color and Fill:

  • color (Color): The color of the vignette. Defaults to #000000.

  • power (Number): Controls how quickly the vignette fades away with distance from the edge. Larger numbers make the vignette fade away more quickly. Defaults to 4.

Blending:

  • luminous (Number): A proportion between 0 and 1 controlling how much the vignette adds rather than mixes its color with what is behind it. Setting luminous to 1 will make the background look like it is made of light rather than paint. Defaults to 0.

  • opacity (Number): The opacity of the vignette. Defaults to 1.

Z-order:

  • layer (Number): The rendering layer of the vignette. Sprites on higher layers will be drawn over the top of sprites on lower layers. Must be a number between -128 and 127 (inclusive). Defaults to 127 (draw the vignette on top of everything).

Viewer:

  • priority (Number): Optional. If not provided, the vignette will always be drawn. If provided, it will only be drawn if it is the highest priority vignette for its camera. Must be an integer between -128 and 127. Defaults to null (always draw).

  • audience (Entity, Symbol or Flag): If provided, only the specified audience will see the vignette. Defaults to owner. See Audience.

  • owner (Entity): The player who owns the vignette. Only used to interpret the audience parameter.

  • camera (Entity or Array of Entities): Determines which camera(s) will render the vignette. Defaults to World (the main camera).

delete this.Vignette<Id>

Deletes a previously-assigned vignette behavior.