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.
If an entity target of an object is destroyed or changes surface, then the object is also destroyed.
LuaRendering
Create a line.
Create a text.
Create a circle.
Create a rectangle.
Create an arc.
Create a triangle mesh defined by a triangle strip.
Create a sprite.
Create a light.
Create an animation.
Destroy the object with the given id.
Does a font with this name exist?
Gets an array of all valid object ids.
Destroys all render objects.
Reorder this object so that it is drawn in front of the already existing objects.
The surface the object with this id is rendered on.
Get the time to live of the object with this id.
Set the time to live of the object with this id.
Get the forces that the object with this id is rendered to or nil
if visible to all forces.
Set the forces that the object with this id is rendered to.
Get the players that the object with this id is rendered to or nil
if visible to all players.
Set the players that the object with this id is rendered to.
Get whether this is rendered to anyone at all.
Set whether this is rendered to anyone at all.
Get whether this is being drawn on the ground, under most entities and sprites.
Set whether this is being drawn on the ground, under most entities and sprites.
Get whether this is only rendered in alt-mode.
Set whether this is only rendered in alt-mode.
Set the color or tint of the object with this id.
Set the width of the object with this id.
Get from where the line with this id is drawn.
Set from where the line with this id is drawn.
Get where the line with this id is drawn to.
Set where the line with this id is drawn to.
Get the dash length of the line with this id.
Set the dash length of the line with this id.
Get the length of the gaps in the line with this id.
Set the length of the gaps in the line with this id.
Set the length of the dashes and the length of the gaps in the line with this id.
Get where the object with this id is drawn.
Set where the object with this id is drawn.
Get the orientation of the object with this id.
Set the orientation of the object with this id.
Set the scale of the text or light with this id.
Get the text that is displayed by the text with this id.
Set the text that is displayed by the text with this id.
Set the font of the text with this id.
Get the alignment of the text with this id.
Set the alignment of the text with this id.
Get the vertical alignment of the text with this id.
Set the vertical alignment of the text with this id.
Get if the text with this id scales with player 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 if the circle or rectangle with this id is filled.
Set if the circle or rectangle with this id is filled.
Get the radius of the circle with this id.
Set the radius of the circle with this id.
Get where top left corner of the rectangle with this id is drawn.
Set where top left corner of the rectangle with this id is drawn.
Get where bottom right corner of the rectangle with this id is drawn.
Set where top bottom right of the rectangle with this id is drawn.
Set the corners of the rectangle with this id.
Get the radius of the outer edge of the arc with this id.
Set the radius of the outer edge of the arc with this id.
Get the radius of the inner edge of the arc with this id.
Set the radius of the inner edge of the arc with this id.
Get where the arc with this id starts.
Set where the arc with this id starts.
Set the angle of the arc with this id.
Get the vertices of the polygon with this id.
Set the vertices of the polygon with this id.
Get the sprite of the sprite or light with this id.
Set the sprite of the sprite or light with this id.
Get the horizontal scale of the sprite or animation with this id.
Set the horizontal scale of the sprite or animation with this id.
Get the vertical scale of the sprite or animation with this id.
Set the vertical scale of the sprite or animation with this id.
Get the render layer of the sprite or animation with this id.
Set the render layer of the sprite or animation with this id.
The object rotates so that it faces this target.
The object rotates so that it faces this target.
Offsets the center of the sprite or animation if orientation_target
is given.
Offsets the center of the sprite or animation if orientation_target
is given.
Get the intensity of the light with this id.
Set the intensity of the light with this id.
Get the minimum darkness at which the light with this id is rendered.
Set the minimum darkness at which the light with this id is rendered.
Get if the light with this id is rendered has the same orientation as the target entity.
Set if the light with this id is rendered has the same orientation as the target entity.
Get the animation prototype name of the animation with this id.
Set the animation prototype name of the animation with this id.
Get the animation speed of the animation with this id.
Set the animation speed of the animation with this id.
Get the animation offset of the animation with this id.
Set the animation offset of the animation with this id.
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.
In pixels (32 per tile).
Length of the gaps that this line has, in tiles. Default is 0.
Length of the dashes that this line has. Used only if gap_length > 0. Default is 0.
Only used if from
is a LuaEntity.
Only used if to
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should be drawn below sprites and entities.
If this should only be rendered in alt mode. Defaults to false.
Id of the render object
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}
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.
The text to display.
Only used if target
is a LuaEntity.
Name of font to use. Defaults to the same font as flying-text.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should be drawn below sprites and entities.
The orientation of the text. Default is 0.
Defaults to "left". Other options are "right" and "center".
Defaults to "top". Other options are "middle", "baseline" and "bottom".
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.
If this should only be rendered in alt mode. Defaults to false.
Id of the render object
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.
In tiles.
Width of the outline, used only if filled = false. Value is in pixels (32 per tile).
If the circle should be filled.
Only used if target
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should be drawn below sprites and entities.
If this should only be rendered in alt mode. Defaults to false.
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.
Width of the outline, used only if filled = false. Value is in pixels (32 per tile).
If the rectangle should be filled.
Only used if left_top
is a LuaEntity.
Only used if right_bottom
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should be drawn below sprites and entities.
If this should only be rendered in alt mode. Defaults to false.
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.
The radius of the outer edge of the arc, in tiles.
The radius of the inner edge of the arc, in tiles.
Where the arc starts, in radian.
The angle of the arc, in radian.
Only used if target
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should be drawn below sprites and entities.
If this should only be rendered in alt mode. Defaults to false.
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.
Acts like an offset applied to all vertices that are not set to an entity.
Only used if target
is a LuaEntity.
The orientation applied to all vertices. Default is 0.
If given, the vertices (that are not set to an entity) rotate so that it faces this target. Note that orientation
is still applied.
Only used if orientation_target
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should be drawn below sprites and entities.
If this should only be rendered in alt mode. Defaults to false.
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.
The orientation of the sprite. Default is 0.
Horizontal scale of the sprite. Default is 1.
Vertical scale of the sprite. Default is 1.
If given, the sprite rotates so that it faces this target. Note that orientation
is still applied to the sprite.
Only used if orientation_target
is a LuaEntity.
Offsets the center of the sprite if orientation_target
is given. This offset will rotate together with the sprite.
Center of the sprite.
Only used if target
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should only be rendered in alt mode. Defaults to false.
Id of the render object
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}
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.
The orientation of the light. Default is 0.
Default is 1.
Default is 1.
The minimum darkness at which this light is rendered. Default is 0.
If this light has the same orientation as the entity target, default is false. Note that orientation
is still applied to the sprite.
Defaults to white (no tint).
Center of the light.
Only used if target
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should only be rendered in alt mode. Defaults to false.
Id of the render object
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.
Name of an animation prototype.
The orientation of the animation. Default is 0.
Horizontal scale of the animation. Default is 1.
Vertical scale of the animation. Default is 1.
How many frames the animation goes forward per tick. Default is 1.
Offset of the animation in frames. Default is 0.
If given, the animation rotates so that it faces this target. Note that orientation
is still applied to the animation.
Only used if orientation_target
is a LuaEntity.
Offsets the center of the animation if orientation_target
is given. This offset will rotate together with the animation.
Center of the animation.
Only used if target
is a LuaEntity.
In ticks. Defaults to living forever.
The forces that this object is rendered to. Passing nil
or an empty table will render it to all forces.
The players that this object is rendered to. Passing nil
or an empty table will render it to all players.
If this is rendered to anyone at all. Defaults to true.
If this should only be rendered in alt mode. Defaults to false.
Id of the render object
get_all_ids(mod_name?)
→
array[uint64]
Gets an array of all valid object ids.
If provided, get only the render objects created by this mod.
clear(mod_name?)
Destroys all render objects.
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".
bring_to_front(id)
Reorder this object so that it is drawn in front of the already existing objects.
get_surface(id)
→
LuaSurface
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.
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.
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.
set_players(id,
players)
Set the players that the object with this id is rendered to.
Providing an empty array will set the object to be visible to all players.
get_draw_on_ground(id)
→
boolean
Get whether this is being drawn on the ground, under most entities and sprites.
get_only_in_alt_mode(id)
→
boolean
get_color(id)
→
Color?
get_width(id)
→
float?
get_from(id)
→
ScriptRenderTarget?
Get from where the line with this id is drawn.
nil
if this object is not a 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.
get_to(id)
→
ScriptRenderTarget?
Get where the line with this id is drawn to.
nil
if the object is not a 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.
get_dash_length(id)
→
double?
get_gap_length(id)
→
double?
get_target(id)
→
ScriptRenderTarget?
Get where the object with this id is drawn.
nil
if the object does not support target.
Polygon vertices that are set to an entity will ignore this.
set_target(id,
target,
target_offset?)
Set where the object with this id is drawn. Does nothing if this object does not support target.
Polygon vertices that are set to an entity will ignore this.
get_orientation(id)
→
RealOrientation?
Get the orientation of the object with this id.
nil
if the object is not a text, polygon, sprite, light or animation.
Polygon vertices that are set to an entity will ignore this.
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.
Polygon vertices that are set to an entity will ignore this.
get_scale(id)
→
double?
get_text(id)
→
LocalisedString?
Get the text that is displayed by the text with this id.
nil
if the object is not a 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.
get_font(id)
→
string?
get_alignment(id)
→
string?
get_vertical_alignment(id)
→
string?
get_scale_with_zoom(id)
→
boolean?
get_filled(id)
→
boolean?
get_radius(id)
→
double?
get_left_top(id)
→
ScriptRenderTarget?
Get where top left corner of the rectangle with this id is drawn.
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. Does nothing if this object is not a rectangle.
get_right_bottom(id)
→
ScriptRenderTarget?
Get where bottom right corner of the rectangle with this id is drawn.
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. Does nothing if this object is not a 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.
get_max_radius(id)
→
double?
get_min_radius(id)
→
double?
get_start_angle(id)
→
float?
get_angle(id)
→
float?
get_vertices(id)
→
array[ScriptRenderTarget]?
Get the vertices of the polygon with this id.
nil
if the object is not a polygon.
set_vertices(id,
vertices)
Set the vertices of the polygon with this id. Does nothing if this object is not a polygon.
get_sprite(id)
→
SpritePath?
Get the sprite of the sprite or light with this id.
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. Does nothing if this object is not a sprite or light.
get_x_scale(id)
→
double?
get_y_scale(id)
→
double?
get_render_layer(id)
→
RenderLayer?
Get the render layer of the sprite or animation with this id.
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. Does nothing if this object is not a 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.
nil
if no target or if this object is not a polygon, sprite, or animation.
Polygon vertices that are set to an entity will ignore this.
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.
Polygon vertices that are set to an entity will ignore this.
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.
nil
if this object is not a 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.
get_intensity(id)
→
float?
get_minimum_darkness(id)
→
float?
get_oriented(id)
→
boolean?
get_animation(id)
→
string?
get_animation_speed(id)
→
double?
get_animation_offset(id)
→
double?
object_name
:: string
[Read]
This object's name.