Factorio » Classes » LuaRenderingFactorio 1.1.39

LuaRendering

Allows rendering of geometric shapes, text and sprites in the game world. Each render object is identified by an id that is universally unique for the lifetime of a whole game.

Note: If an entity target of an object is destroyed or changes surface, then the object is also destroyed.
class LuaRendering - sort
draw_line{color = …, width = …, gap_length = …, dash_length = …, from = …, from_offset = …, to = …, to_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64 Create a line.
draw_text{text = …, surface = …, target = …, target_offset = …, color = …, scale = …, font = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, orientation = …, alignment = …, vertical_alignment = …, scale_with_zoom = …, only_in_alt_mode = …} → uint64 Create a text.
draw_circle{color = …, radius = …, width = …, filled = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64 Create a circle.
draw_rectangle{color = …, width = …, filled = …, left_top = …, left_top_offset = …, right_bottom = …, right_bottom_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64 Create a rectangle.
draw_arc{color = …, max_radius = …, min_radius = …, start_angle = …, angle = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64 Create an arc.
draw_polygon{color = …, vertices = …, target = …, target_offset = …, orientation = …, orientation_target = …, orientation_target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64 Create a triangle mesh defined by a triangle strip.
draw_sprite{sprite = …, orientation = …, x_scale = …, y_scale = …, tint = …, render_layer = …, orientation_target = …, orientation_target_offset = …, oriented_offset = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, only_in_alt_mode = …} → uint64 Create a sprite.
draw_light{sprite = …, orientation = …, scale = …, intensity = …, minimum_darkness = …, oriented = …, color = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, only_in_alt_mode = …} → uint64 Create a light.
draw_animation{animation = …, orientation = …, x_scale = …, y_scale = …, tint = …, render_layer = …, animation_speed = …, animation_offset = …, orientation_target = …, orientation_target_offset = …, oriented_offset = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, only_in_alt_mode = …} → uint64 Create an animation.
destroy(id) Destroy the object with the given id.
is_font_valid(font_name) → boolean Does a font with this name exist?
is_valid(id) → boolean Does a valid object with this id exist?
get_all_ids(mod_name) → array[uint64] Gets an array of all valid object ids.
clear(mod_name) Destroys all render objects.
get_type(id) → string Gets the type of the given object.
bring_to_front(id) Reorder this object so that it is drawn in front of the already existing objects.
get_surface(id) → LuaSurface The surface the object with this id is rendered on.
get_time_to_live(id) → uint Get the time to live of the object with this id.
set_time_to_live(id, time_to_live) Set the time to live of the object with this id.
get_forces(id) → array[LuaForce] Get the forces that the object with this id is rendered to or nil if visible to all forces.
set_forces(id, forces) Set the forces that the object with this id is rendered to.
get_players(id) → array[LuaPlayer] Get the players that the object with this id is rendered to or nil if visible to all players.
set_players(id, players) Set the players that the object with this id is rendered to.
get_visible(id) → boolean Get whether this is rendered to anyone at all.
set_visible(id, visible) Set whether this is rendered to anyone at all.
get_draw_on_ground(id) → boolean Get whether this is being drawn on the ground, under most entities and sprites.
set_draw_on_ground(id, draw_on_ground) Set whether this is being drawn on the ground, under most entities and sprites.
get_only_in_alt_mode(id) → boolean Get whether this is only rendered in alt-mode.
set_only_in_alt_mode(id, only_in_alt_mode) Set whether this is only rendered in alt-mode.
get_color(id) → Color Get the color or tint of the object with this id.
set_color(id, color) Set the color or tint of the object with this id.
get_width(id) → float Get the width of the object with this id.
set_width(id, width) Set the width of the object with this id.
get_from(id) → ScriptRenderTarget Get from where the line with this id is drawn or nil if this object is not a line.
set_from(id, from, from_offset) Set from where the line with this id is drawn.
get_to(id) → ScriptRenderTarget Get where the line with this id is drawn to or nil if the object is not a line.
set_to(id, to, to_offset) Set where the line with this id is drawn to.
get_dash_length(id) → double Get the dash length of the line with this id or nil if the object is not a line.
set_dash_length(id, dash_length) Set the dash length of the line with this id.
get_gap_length(id) → double Get the length of the gaps in the line with this id or nil if the object is not a line.
set_gap_length(id, gap_length) Set the length of the gaps in the line with this id.
set_dashes(id, dash_length, gap_length) Set the length of the dashes and the length of the gaps in the line with this id.
get_target(id) → ScriptRenderTarget Get where the object with this id is drawn or nil if the object does not support target.
set_target(id, target, target_offset) Set where the object with this id is drawn.
get_orientation(id) → RealOrientation Get the orientation of the object with this id or nil if the object is not a text, polygon, sprite, light or animation.
set_orientation(id, orientation) Set the orientation of the object with this id.
get_scale(id) → double Get the scale of the text or light with this id or nil if the object is not a text or light.
set_scale(id, scale) Set the scale of the text or light with this id.
get_text(id) → LocalisedString Get the text that is displayed by the text with this id or nil if the object is not a text.
set_text(id, text) Set the text that is displayed by the text with this id.
get_font(id) → string Get the font of the text with this id or nil if the object is not a text.
set_font(id, font) Set the font of the text with this id.
get_alignment(id) → string Get the alignment of the text with this id or nil if the object is not a text.
set_alignment(id, alignment) Set the alignment of the text with this id.
get_vertical_alignment(id) → string Get the vertical alignment of the text with this id or nil if the object is not a text.
set_vertical_alignment(id, alignment) Set the vertical alignment of the text with this id.
get_scale_with_zoom(id) → boolean Get if the text with this id scales with player zoom or nil if the object is not a text.
set_scale_with_zoom(id, scale_with_zoom) Set if the text with this id scales with player zoom, resulting in it always being the same size on screen, and the size compared to the game world changes.
get_filled(id) → boolean Get if the circle or rectangle with this id is filled or nil if the object is not a circle or rectangle.
set_filled(id, filled) Set if the circle or rectangle with this id is filled.
get_radius(id) → double Get the radius of the circle with this id or nil if the object is not a circle.
set_radius(id, radius) Set the radius of the circle with this id.
get_left_top(id) → ScriptRenderTarget Get where top left corner of the rectangle with this id is drawn or nil if the object is not a rectangle.
set_left_top(id, left_top, left_top_offset) Set where top left corner of the rectangle with this id is drawn.
get_right_bottom(id) → ScriptRenderTarget Get where bottom right corner of the rectangle with this id is drawn or nil if the object is not a rectangle.
set_right_bottom(id, right_bottom, right_bottom_offset) Set where top bottom right of the rectangle with this id is drawn.
set_corners(id, left_top, left_top_offset, right_bottom, right_bottom_offset) Set the corners of the rectangle with this id.
get_max_radius(id) → double Get the radius of the outer edge of the arc with this id or nil if the object is not a arc.
set_max_radius(id, max_radius) Set the radius of the outer edge of the arc with this id.
get_min_radius(id) → double Get the radius of the inner edge of the arc with this id or nil if the object is not a arc.
set_min_radius(id, min_radius) Set the radius of the inner edge of the arc with this id.
get_start_angle(id) → float Get where the arc with this id starts or nil if the object is not a arc.
set_start_angle(id, start_angle) Set where the arc with this id starts.
get_angle(id) → float Get the angle of the arc with this id or nil if the object is not a arc.
set_angle(id, angle) Set the angle of the arc with this id.
get_vertices(id) → array[ScriptRenderTarget] Get the vertices of the polygon with this id or nil if the object is not a polygon.
set_vertices(id, vertices) Set the vertices of the polygon with this id.
get_sprite(id) → SpritePath Get the sprite of the sprite or light with this id or nil if the object is not a sprite or light.
set_sprite(id, sprite) Set the sprite of the sprite or light with this id.
get_x_scale(id) → double Get the horizontal scale of the sprite or animation with this id or nil if the object is not a sprite or animation.
set_x_scale(id, x_scale) Set the horizontal scale of the sprite or animation with this id.
get_y_scale(id) → double Get the vertical scale of the sprite or animation with this id or nil if the object is not a sprite or animation.
set_y_scale(id, y_scale) Set the vertical scale of the sprite or animation with this id.
get_render_layer(id) → RenderLayer Get the render layer of the sprite or animation with this id or nil if the object is not a sprite or animation.
set_render_layer(id, render_layer) Set the render layer of the sprite or animation with this id.
get_orientation_target(id) → ScriptRenderTarget The object rotates so that it faces this target.
set_orientation_target(id, orientation_target, orientation_target_offset) The object rotates so that it faces this target.
get_oriented_offset(id) → Vector Offsets the center of the sprite or animation if orientation_target is given.
set_oriented_offset(id, oriented_offset) Offsets the center of the sprite or animation if orientation_target is given.
get_intensity(id) → float Get the intensity of the light with this id or nil if the object is not a light.
set_intensity(id, intensity) Set the intensity of the light with this id.
get_minimum_darkness(id) → float Get the minimum darkness at which the light with this id is rendered or nil if the object is not a light.
set_minimum_darkness(id, minimum_darkness) Set the minimum darkness at which the light with this id is rendered.
get_oriented(id) → boolean Get if the light with this id is rendered has the same orientation as the target entity or nil if the object is not a light.
set_oriented(id, oriented) Set if the light with this id is rendered has the same orientation as the target entity.
get_animation(id) → string Get the animation prototype name of the animation with this id or nil if the object is not an animation.
set_animation(id, animation) Set the animation prototype name of the animation with this id.
get_animation_speed(id) → double Get the animation speed of the animation with this id or nil if the object is not an animation.
set_animation_speed(id, animation_speed) Set the animation speed of the animation with this id.
get_animation_offset(id) → double Get the animation offset of the animation with this id or nil if the object is not an animation.
set_animation_offset(id, animation_offset) Set the animation offset of the animation with this id.
object_name :: string [R] This object's name.
draw_line{color = …, width = …, gap_length = …, dash_length = …, from = …, from_offset = …, to = …, to_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64

Create a line.

Parameters
Table with the following fields:
  • color :: Color
  • width :: float: In pixels (32 per tile).
  • gap_length :: double (optional): Length of the gaps that this line has, in tiles. Default is 0.
  • dash_length :: double (optional): Length of the dashes that this line has. Used only if gap_length > 0. Default is 0.
  • from :: Position or LuaEntity
  • from_offset :: Vector (optional): Only used if from is a LuaEntity.
  • to :: Position or LuaEntity
  • to_offset :: Vector (optional): Only used if to is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • draw_on_ground :: boolean (optional): If this should be drawn below sprites and entities.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
Example
Draw a white and 2 pixel wide line from {0, 0} to {2, 2}.
rendering.draw_line{surface = game.player.surface, from = {0, 0}, to = {2, 2}, color = {1, 1, 1}, width = 2}
Example
Draw a red and 3 pixel wide line from {0, 0} to {0, 5}. The line has 1 tile long dashes and gaps.
rendering.draw_line{surface = game.player.surface, from = {0, 0}, to = {0, 5}, color = {r = 1}, width = 3, gap_length = 1, dash_length = 1}
draw_text{text = …, surface = …, target = …, target_offset = …, color = …, scale = …, font = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, orientation = …, alignment = …, vertical_alignment = …, scale_with_zoom = …, only_in_alt_mode = …} → uint64

Create a text.

Parameters
Table with the following fields:
  • text :: LocalisedString: The text to display.
  • surface :: SurfaceIdentification
  • target :: Position or LuaEntity
  • target_offset :: Vector (optional): Only used if target is a LuaEntity.
  • color :: Color
  • scale :: double (optional)
  • font :: string (optional): Name of font to use. Defaults to the same font as flying-text.
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • draw_on_ground :: boolean (optional): If this should be drawn below sprites and entities.
  • orientation :: RealOrientation (optional): The orientation of the text. Default is 0.
  • alignment :: string (optional): Defaults to "left". Other options are "right" and "center".
  • vertical_alignment :: string (optional): Defaults to "top". Other options are "middle", "baseline" and "bottom".
  • scale_with_zoom :: boolean (optional): Defaults to false. If true, the text scales with player zoom, resulting in it always being the same size on screen, and the size compared to the game world changes.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
Note: Not all fonts support scaling.
draw_circle{color = …, radius = …, width = …, filled = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64

Create a circle.

Parameters
Table with the following fields:
  • color :: Color
  • radius :: double: In tiles.
  • width :: float (optional): Width of the outline, used only if filled = false. Value is in pixels (32 per tile).
  • filled :: boolean: If the circle should be filled.
  • target :: Position or LuaEntity
  • target_offset :: Vector (optional): Only used if target is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • draw_on_ground :: boolean (optional): If this should be drawn below sprites and entities.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
draw_rectangle{color = …, width = …, filled = …, left_top = …, left_top_offset = …, right_bottom = …, right_bottom_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64

Create a rectangle.

Parameters
Table with the following fields:
  • color :: Color
  • width :: float (optional): Width of the outline, used only if filled = false. Value is in pixels (32 per tile).
  • filled :: boolean: If the rectangle should be filled.
  • left_top :: Position or LuaEntity
  • left_top_offset :: Vector (optional): Only used if left_top is a LuaEntity.
  • right_bottom :: Position or LuaEntity
  • right_bottom_offset :: Vector (optional): Only used if right_bottom is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • draw_on_ground :: boolean (optional): If this should be drawn below sprites and entities.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
draw_arc{color = …, max_radius = …, min_radius = …, start_angle = …, angle = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64

Create an arc.

Parameters
Table with the following fields:
  • color :: Color
  • max_radius :: double: The radius of the outer edge of the arc, in tiles.
  • min_radius :: double: The radius of the inner edge of the arc, in tiles.
  • start_angle :: float: Where the arc starts, in radian.
  • angle :: float: The angle of the arc, in radian.
  • target :: Position or LuaEntity
  • target_offset :: Vector (optional): Only used if target is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • draw_on_ground :: boolean (optional): If this should be drawn below sprites and entities.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
draw_polygon{color = …, vertices = …, target = …, target_offset = …, orientation = …, orientation_target = …, orientation_target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, draw_on_ground = …, only_in_alt_mode = …} → uint64

Create a triangle mesh defined by a triangle strip.

Parameters
Table with the following fields:
  • color :: Color
  • vertices :: array[ScriptRenderVertexTarget]
  • target :: Position or LuaEntity (optional): Acts like an offset applied to all vertices that are not set to an entity.
  • target_offset :: Vector (optional): Only used if target is a LuaEntity.
  • orientation :: RealOrientation (optional): The orientation applied to all vertices. Default is 0.
  • orientation_target :: Position or LuaEntity (optional): If given, the vertices (that are not set to an entity) rotate so that it faces this target. Note that orientation is still applied.
  • orientation_target_offset :: Vector (optional): Only used if orientation_target is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • draw_on_ground :: boolean (optional): If this should be drawn below sprites and entities.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
draw_sprite{sprite = …, orientation = …, x_scale = …, y_scale = …, tint = …, render_layer = …, orientation_target = …, orientation_target_offset = …, oriented_offset = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, only_in_alt_mode = …} → uint64

Create a sprite.

Parameters
Table with the following fields:
  • sprite :: SpritePath
  • orientation :: RealOrientation (optional): The orientation of the sprite. Default is 0.
  • x_scale :: double (optional): Horizontal scale of the sprite. Default is 1.
  • y_scale :: double (optional): Vertical scale of the sprite. Default is 1.
  • tint :: Color (optional)
  • render_layer :: RenderLayer (optional)
  • orientation_target :: Position or LuaEntity (optional): If given, the sprite rotates so that it faces this target. Note that orientation is still applied to the sprite.
  • orientation_target_offset :: Vector (optional): Only used if orientation_target is a LuaEntity.
  • oriented_offset :: Vector (optional): Offsets the center of the sprite if orientation_target is given. This offset will rotate together with the sprite.
  • target :: Position or LuaEntity: Center of the sprite.
  • target_offset :: Vector (optional): Only used if target is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
Example
This will draw an iron plate icon at the character's feet. The sprite will move together with the character.
rendering.draw_sprite{sprite = "item.iron-plate", target = game.player.character, surface = game.player.surface}
Example
This will draw an iron plate icon at the character's head. The sprite will move together with the character.
rendering.draw_sprite{sprite = "item.iron-plate", target = game.player.character, target_offset = {0, -2}, surface = game.player.surface}
draw_light{sprite = …, orientation = …, scale = …, intensity = …, minimum_darkness = …, oriented = …, color = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, only_in_alt_mode = …} → uint64

Create a light.

Parameters
Table with the following fields:
  • sprite :: SpritePath
  • orientation :: RealOrientation (optional): The orientation of the light. Default is 0.
  • scale :: float (optional): Default is 1.
  • intensity :: float (optional): Default is 1.
  • minimum_darkness :: float (optional): The minimum darkness at which this light is rendered. Default is 0.
  • oriented :: boolean (optional): If this light has the same orientation as the entity target, default is false. Note that orientation is still applied to the sprite.
  • color :: Color (optional): Defaults to white (no tint).
  • target :: Position or LuaEntity: Center of the light.
  • target_offset :: Vector (optional): Only used if target is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
Note: The base game uses the utility sprites light_medium and light_small for lights.
draw_animation{animation = …, orientation = …, x_scale = …, y_scale = …, tint = …, render_layer = …, animation_speed = …, animation_offset = …, orientation_target = …, orientation_target_offset = …, oriented_offset = …, target = …, target_offset = …, surface = …, time_to_live = …, forces = …, players = …, visible = …, only_in_alt_mode = …} → uint64

Create an animation.

Parameters
Table with the following fields:
  • animation :: string: Name of an animation prototype.
  • orientation :: RealOrientation (optional): The orientation of the animation. Default is 0.
  • x_scale :: double (optional): Horizontal scale of the animation. Default is 1.
  • y_scale :: double (optional): Vertical scale of the animation. Default is 1.
  • tint :: Color (optional)
  • render_layer :: RenderLayer (optional)
  • animation_speed :: double (optional): How many frames the animation goes forward per tick. Default is 1.
  • animation_offset :: double (optional): Offset of the animation in frames. Default is 0.
  • orientation_target :: Position or LuaEntity (optional): If given, the animation rotates so that it faces this target. Note that orientation is still applied to the animation.
  • orientation_target_offset :: Vector (optional): Only used if orientation_target is a LuaEntity.
  • oriented_offset :: Vector (optional): Offsets the center of the animation if orientation_target is given. This offset will rotate together with the animation.
  • target :: Position or LuaEntity: Center of the animation.
  • target_offset :: Vector (optional): Only used if target is a LuaEntity.
  • surface :: SurfaceIdentification
  • time_to_live :: uint (optional): In ticks. Defaults to living forever.
  • forces :: array[ForceIdentification] (optional): The forces that this object is rendered to.
  • players :: array[PlayerIdentification] (optional): The players that this object is rendered to.
  • visible :: boolean (optional): If this is rendered to anyone at all. Defaults to true.
  • only_in_alt_mode :: boolean (optional): If this should only be rendered in alt mode. Defaults to false.
Return value
Id of the render object
destroy(id)

Destroy the object with the given id.

Parameters
id :: uint64
is_font_valid(font_name) → boolean

Does a font with this name exist?

Parameters
font_name :: string
is_valid(id) → boolean

Does a valid object with this id exist?

Parameters
id :: uint64
get_all_ids(mod_name) → array[uint64]

Gets an array of all valid object ids.

Parameters
mod_name :: string (optional): If provided, get only the render objects created by this mod.
clear(mod_name)

Destroys all render objects.

Parameters
mod_name :: string (optional): If provided, only the render objects created by this mod are destroyed.
get_type(id) → string

Gets the type of the given object. The types are "text", "line", "circle", "rectangle", "arc", "polygon", "sprite", "light" and "animation".

Parameters
id :: uint64
bring_to_front(id)

Reorder this object so that it is drawn in front of the already existing objects.

Parameters
id :: uint64
get_surface(id) → LuaSurface

The surface the object with this id is rendered on.

Parameters
id :: uint64
get_time_to_live(id) → uint

Get the time to live of the object with this id. This will be 0 if the object does not expire.

Parameters
id :: uint64
set_time_to_live(id, time_to_live)

Set the time to live of the object with this id. Set to 0 if the object should not expire.

Parameters
id :: uint64
time_to_live :: uint
get_forces(id) → array[LuaForce]

Get the forces that the object with this id is rendered to or nil if visible to all forces.

Parameters
id :: uint64
set_forces(id, forces)

Set the forces that the object with this id is rendered to.

Parameters
id :: uint64
forces :: array[ForceIdentification]: Providing an empty array will set the object to be visible to all forces.
get_players(id) → array[LuaPlayer]

Get the players that the object with this id is rendered to or nil if visible to all players.

Parameters
id :: uint64
set_players(id, players)

Set the players that the object with this id is rendered to.

Parameters
id :: uint64
players :: array[PlayerIdentification]: Providing an empty array will set the object to be visible to all players.
get_visible(id) → boolean

Get whether this is rendered to anyone at all.

Parameters
id :: uint64
set_visible(id, visible)

Set whether this is rendered to anyone at all.

Parameters
id :: uint64
visible :: boolean
get_draw_on_ground(id) → boolean

Get whether this is being drawn on the ground, under most entities and sprites.

Parameters
id :: uint64
Can only be used if this is Text, Line, Circle, Rectangle, Arc, or Polygon
set_draw_on_ground(id, draw_on_ground)

Set whether this is being drawn on the ground, under most entities and sprites.

Parameters
id :: uint64
draw_on_ground :: boolean
Can only be used if this is Text, Line, Circle, Rectangle, Arc, or Polygon
get_only_in_alt_mode(id) → boolean

Get whether this is only rendered in alt-mode.

Parameters
id :: uint64
set_only_in_alt_mode(id, only_in_alt_mode)

Set whether this is only rendered in alt-mode.

Parameters
id :: uint64
only_in_alt_mode :: boolean
get_color(id) → Color

Get the color or tint of the object with this id.

Parameters
id :: uint64
Return value
or nil if the object does not support color.
Can only be used if this is Text, Line, Circle, Rectangle, Arc, Polygon, Sprite, Light, or Animation
set_color(id, color)

Set the color or tint of the object with this id. Does nothing if this object does not support color.

Parameters
id :: uint64
color :: Color
Can only be used if this is Text, Line, Circle, Rectangle, Arc, Polygon, Sprite, Light, or Animation
get_width(id) → float

Get the width of the object with this id. Value is in pixels (32 per tile).

Parameters
id :: uint64
Return value
or nil if the object does not support width.
Can only be used if this is Line, Circle, or Rectangle
set_width(id, width)

Set the width of the object with this id. Does nothing if this object does not support width. Value is in pixels (32 per tile).

Parameters
id :: uint64
width :: float
Can only be used if this is Line, Circle, or Rectangle
get_from(id) → ScriptRenderTarget

Get from where the line with this id is drawn or nil if this object is not a line.

Parameters
id :: uint64
Can only be used if this is Line
set_from(id, from, from_offset)

Set from where the line with this id is drawn. Does nothing if the object is not a line.

Parameters
id :: uint64
from :: Position or LuaEntity
from_offset :: Vector (optional)
Can only be used if this is Line
get_to(id) → ScriptRenderTarget

Get where the line with this id is drawn to or nil if the object is not a line.

Parameters
id :: uint64
Can only be used if this is Line
set_to(id, to, to_offset)

Set where the line with this id is drawn to. Does nothing if this object is not a line.

Parameters
id :: uint64
to_offset :: Vector (optional)
Can only be used if this is Line
get_dash_length(id) → double

Get the dash length of the line with this id or nil if the object is not a line.

Parameters
id :: uint64
Can only be used if this is Line
set_dash_length(id, dash_length)

Set the dash length of the line with this id. Does nothing if this object is not a line.

Parameters
id :: uint64
dash_length :: double
Can only be used if this is Line
get_gap_length(id) → double

Get the length of the gaps in the line with this id or nil if the object is not a line.

Parameters
id :: uint64
Can only be used if this is Line
set_gap_length(id, gap_length)

Set the length of the gaps in the line with this id. Does nothing if this object is not a line.

Parameters
id :: uint64
gap_length :: double
Can only be used if this is Line
set_dashes(id, dash_length, gap_length)

Set the length of the dashes and the length of the gaps in the line with this id. Does nothing if this object is not a line.

Parameters
id :: uint64
dash_length :: double
gap_length :: double
Can only be used if this is Line
get_target(id) → ScriptRenderTarget

Get where the object with this id is drawn or nil if the object does not support target.

Parameters
id :: uint64
Note: Polygon vertices that are set to an entity will ignore this.
Can only be used if this is Text, Circle, Arc, Polygon, Sprite, Light, or Animation
set_target(id, target, target_offset)

Set where the object with this id is drawn. Does nothing if this object does not support target.

Parameters
id :: uint64
target :: Position or LuaEntity
target_offset :: Vector (optional)
Note: Polygon vertices that are set to an entity will ignore this.
Can only be used if this is Text, Circle, Arc, Polygon, Sprite, Light, or Animation
get_orientation(id) → RealOrientation

Get the orientation of the object with this id or nil if the object is not a text, polygon, sprite, light or animation.

Parameters
id :: uint64
Note: Polygon vertices that are set to an entity will ignore this.
Can only be used if this is Text, Polygon, Sprite, Light, or Animation
set_orientation(id, orientation)

Set the orientation of the object with this id. Does nothing if this object is not a text, polygon, sprite, light or animation.

Parameters
id :: uint64
orientation :: RealOrientation
Note: Polygon vertices that are set to an entity will ignore this.
Can only be used if this is Text, Polygon, Sprite, Light, or Animation
get_scale(id) → double

Get the scale of the text or light with this id or nil if the object is not a text or light.

Parameters
id :: uint64
Can only be used if this is Text or Light
set_scale(id, scale)

Set the scale of the text or light with this id. Does nothing if this object is not a text or light.

Parameters
id :: uint64
scale :: double
Can only be used if this is Text or Light
get_text(id) → LocalisedString

Get the text that is displayed by the text with this id or nil if the object is not a text.

Parameters
id :: uint64
Can only be used if this is Text
set_text(id, text)

Set the text that is displayed by the text with this id. Does nothing if this object is not a text.

Parameters
id :: uint64
Can only be used if this is Text
get_font(id) → string

Get the font of the text with this id or nil if the object is not a text.

Parameters
id :: uint64
Can only be used if this is Text
set_font(id, font)

Set the font of the text with this id. Does nothing if this object is not a text.

Parameters
id :: uint64
font :: string
Can only be used if this is Text
get_alignment(id) → string

Get the alignment of the text with this id or nil if the object is not a text.

Parameters
id :: uint64
Can only be used if this is Text
set_alignment(id, alignment)

Set the alignment of the text with this id. Does nothing if this object is not a text.

Parameters
id :: uint64
alignment :: string: "left", "right" or "center".
Can only be used if this is Text
get_vertical_alignment(id) → string

Get the vertical alignment of the text with this id or nil if the object is not a text.

Parameters
id :: uint64
Can only be used if this is Text
set_vertical_alignment(id, alignment)

Set the vertical alignment of the text with this id. Does nothing if this object is not a text.

Parameters
id :: uint64
alignment :: string: "top", "middle", "baseline" or "bottom"
Can only be used if this is Text
get_scale_with_zoom(id) → boolean

Get if the text with this id scales with player zoom or nil if the object is not a text.

Parameters
id :: uint64
Can only be used if this is Text
set_scale_with_zoom(id, scale_with_zoom)

Set if the text with this id scales with player zoom, resulting in it always being the same size on screen, and the size compared to the game world changes. Does nothing if this object is not a text.

Parameters
id :: uint64
scale_with_zoom :: boolean
Can only be used if this is Text
get_filled(id) → boolean

Get if the circle or rectangle with this id is filled or nil if the object is not a circle or rectangle.

Parameters
id :: uint64
Can only be used if this is Circle or Rectangle
set_filled(id, filled)

Set if the circle or rectangle with this id is filled. Does nothing if this object is not a circle or rectangle.

Parameters
id :: uint64
filled :: boolean
Can only be used if this is Circle or Rectangle
get_radius(id) → double

Get the radius of the circle with this id or nil if the object is not a circle.

Parameters
id :: uint64
Can only be used if this is Circle
set_radius(id, radius)

Set the radius of the circle with this id. Does nothing if this object is not a circle.

Parameters
id :: uint64
radius :: double
Can only be used if this is Circle
get_left_top(id) → ScriptRenderTarget

Get where top left corner of the rectangle with this id is drawn or nil if the object is not a rectangle.

Parameters
id :: uint64
Can only be used if this is Rectangle
set_left_top(id, left_top, left_top_offset)

Set where top left corner of the rectangle with this id is drawn. Does nothing if this object is not a rectangle.

Parameters
id :: uint64
left_top :: Position or LuaEntity
left_top_offset :: Vector (optional)
Can only be used if this is Rectangle
get_right_bottom(id) → ScriptRenderTarget

Get where bottom right corner of the rectangle with this id is drawn or nil if the object is not a rectangle.

Parameters
id :: uint64
Can only be used if this is Rectangle
set_right_bottom(id, right_bottom, right_bottom_offset)

Set where top bottom right of the rectangle with this id is drawn. Does nothing if this object is not a rectangle.

Parameters
id :: uint64
right_bottom :: Position or LuaEntity
right_bottom_offset :: Vector (optional)
Can only be used if this is Rectangle
set_corners(id, left_top, left_top_offset, right_bottom, right_bottom_offset)

Set the corners of the rectangle with this id. Does nothing if this object is not a rectangle.

Parameters
id :: uint64
left_top :: Position or LuaEntity
left_top_offset :: Vector
right_bottom :: Position or LuaEntity
right_bottom_offset :: Vector
Can only be used if this is Rectangle
get_max_radius(id) → double

Get the radius of the outer edge of the arc with this id or nil if the object is not a arc.

Parameters
id :: uint64
Can only be used if this is Arc
set_max_radius(id, max_radius)

Set the radius of the outer edge of the arc with this id. Does nothing if this object is not a arc.

Parameters
id :: uint64
max_radius :: double
Can only be used if this is Arc
get_min_radius(id) → double

Get the radius of the inner edge of the arc with this id or nil if the object is not a arc.

Parameters
id :: uint64
Can only be used if this is Arc
set_min_radius(id, min_radius)

Set the radius of the inner edge of the arc with this id. Does nothing if this object is not a arc.

Parameters
id :: uint64
min_radius :: double
Can only be used if this is Arc
get_start_angle(id) → float

Get where the arc with this id starts or nil if the object is not a arc.

Parameters
id :: uint64
Return value
angle in radian
Can only be used if this is Arc
set_start_angle(id, start_angle)

Set where the arc with this id starts. Does nothing if this object is not a arc.

Parameters
id :: uint64
start_angle :: float: angle in radian
Can only be used if this is Arc
get_angle(id) → float

Get the angle of the arc with this id or nil if the object is not a arc.

Parameters
id :: uint64
Return value
angle in radian
Can only be used if this is Arc
set_angle(id, angle)

Set the angle of the arc with this id. Does nothing if this object is not a arc.

Parameters
id :: uint64
angle :: float: angle in radian
Can only be used if this is Arc
get_vertices(id) → array[ScriptRenderTarget]

Get the vertices of the polygon with this id or nil if the object is not a polygon.

Parameters
id :: uint64
Can only be used if this is Polygon
set_vertices(id, vertices)

Set the vertices of the polygon with this id. Does nothing if this object is not a polygon.

Parameters
id :: uint64
vertices :: array[ScriptRenderVertexTarget]
Can only be used if this is Polygon
get_sprite(id) → SpritePath

Get the sprite of the sprite or light with this id or nil if the object is not a sprite or light.

Parameters
id :: uint64
Can only be used if this is Sprite or Light
set_sprite(id, sprite)

Set the sprite of the sprite or light with this id. Does nothing if this object is not a sprite or light.

Parameters
id :: uint64
sprite :: SpritePath
Can only be used if this is Sprite or Light
get_x_scale(id) → double

Get the horizontal scale of the sprite or animation with this id or nil if the object is not a sprite or animation.

Parameters
id :: uint64
Can only be used if this is Sprite or Animation
set_x_scale(id, x_scale)

Set the horizontal scale of the sprite or animation with this id. Does nothing if this object is not a sprite or animation.

Parameters
id :: uint64
x_scale :: double
Can only be used if this is Sprite or Animation
get_y_scale(id) → double

Get the vertical scale of the sprite or animation with this id or nil if the object is not a sprite or animation.

Parameters
id :: uint64
Can only be used if this is Sprite or Animation
set_y_scale(id, y_scale)

Set the vertical scale of the sprite or animation with this id. Does nothing if this object is not a sprite or animation.

Parameters
id :: uint64
y_scale :: double
Can only be used if this is Sprite or Animation
get_render_layer(id) → RenderLayer

Get the render layer of the sprite or animation with this id or nil if the object is not a sprite or animation.

Parameters
id :: uint64
Can only be used if this is Sprite or Animation
set_render_layer(id, render_layer)

Set the render layer of the sprite or animation with this id. Does nothing if this object is not a sprite or animation.

Parameters
id :: uint64
render_layer :: RenderLayer
Can only be used if this is Sprite or Animation
get_orientation_target(id) → ScriptRenderTarget

The object rotates so that it faces this target. Note that orientation is still applied to the object. Get the orientation_target of the object with this id or nil if no target or if this object is not a polygon, sprite, or animation.

Parameters
id :: uint64
Note: Polygon vertices that are set to an entity will ignore this.
Can only be used if this is Polygon, Sprite, or Animation
set_orientation_target(id, orientation_target, orientation_target_offset)

The object rotates so that it faces this target. Note that orientation is still applied to the object. Set the orientation_target of the object with this id. Does nothing if this object is not a polygon, sprite, or animation. Set to nil if the object should not have an orientation_target.

Parameters
id :: uint64
orientation_target :: Position or LuaEntity
orientation_target_offset :: Vector (optional)
Note: Polygon vertices that are set to an entity will ignore this.
Can only be used if this is Polygon, Sprite, or Animation
get_oriented_offset(id) → Vector

Offsets the center of the sprite or animation if orientation_target is given. This offset will rotate together with the sprite or animation. Get the oriented_offset of the sprite or animation with this id or nil if this object is not a sprite or animation.

Parameters
id :: uint64
Can only be used if this is Sprite or Animation
set_oriented_offset(id, oriented_offset)

Offsets the center of the sprite or animation if orientation_target is given. This offset will rotate together with the sprite or animation. Set the oriented_offset of the sprite or animation with this id. Does nothing if this object is not a sprite or animation.

Parameters
id :: uint64
oriented_offset :: Vector
Can only be used if this is Sprite or Animation
get_intensity(id) → float

Get the intensity of the light with this id or nil if the object is not a light.

Parameters
id :: uint64
Can only be used if this is Light
set_intensity(id, intensity)

Set the intensity of the light with this id. Does nothing if this object is not a light.

Parameters
id :: uint64
intensity :: float
Can only be used if this is Light
get_minimum_darkness(id) → float

Get the minimum darkness at which the light with this id is rendered or nil if the object is not a light.

Parameters
id :: uint64
Can only be used if this is Light
set_minimum_darkness(id, minimum_darkness)

Set the minimum darkness at which the light with this id is rendered. Does nothing if this object is not a light.

Parameters
id :: uint64
minimum_darkness :: float
Can only be used if this is Light
get_oriented(id) → boolean

Get if the light with this id is rendered has the same orientation as the target entity or nil if the object is not a light. Note that orientation is still applied to the sprite.

Parameters
id :: uint64
Can only be used if this is Light
set_oriented(id, oriented)

Set if the light with this id is rendered has the same orientation as the target entity. Does nothing if this object is not a light. Note that orientation is still applied to the sprite.

Parameters
id :: uint64
oriented :: boolean
Can only be used if this is Light
get_animation(id) → string

Get the animation prototype name of the animation with this id or nil if the object is not an animation.

Parameters
id :: uint64
Can only be used if this is Animation
set_animation(id, animation)

Set the animation prototype name of the animation with this id. Does nothing if this object is not an animation.

Parameters
id :: uint64
animation :: string
Can only be used if this is Animation
get_animation_speed(id) → double

Get the animation speed of the animation with this id or nil if the object is not an animation.

Parameters
id :: uint64
Return value
Animation speed in frames per tick.
Can only be used if this is Animation
set_animation_speed(id, animation_speed)

Set the animation speed of the animation with this id. Does nothing if this object is not an animation.

Parameters
id :: uint64
animation_speed :: double: Animation speed in frames per tick.
Can only be used if this is Animation
get_animation_offset(id) → double

Get the animation offset of the animation with this id or nil if the object is not an animation.

Parameters
id :: uint64
Return value
Animation offset in frames.
Can only be used if this is Animation
set_animation_offset(id, animation_offset)

Set the animation offset of the animation with this id. Does nothing if this object is not an animation.

Parameters
id :: uint64
animation_offset :: double: Animation offset in frames.
Can only be used if this is Animation
object_name :: string [Read-only]

This object's name.