Factorio.com|Forums|Wiki|Mod Portal|API Docs Prototype|Runtime|Auxiliary

# Factorio Runtime Docs Version 2.0.7

## Class LuaRendering changed

Allows rendering of geometric shapes, text and sprites in the game world through the global object named `rendering`. 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.

## Members

draw_line{color=…, width=…, gap_length?=…, dash_length?=…, dash_offset?=…, from=…, to=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create a line.
Create a line.
draw_text{text=…, surface=…, target=…, color=…, scale?=…, font?=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, orientation?=…, alignment?=…, vertical_alignment?=…, scale_with_zoom?=…, only_in_alt_mode?=…, use_rich_text?=…} changed | → LuaRenderObject | Create a text. [...]
Create a text. [...]
draw_circle{color=…, radius=…, width?=…, filled?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create a circle.
Create a circle.
draw_rectangle{color=…, width?=…, filled?=…, left_top=…, right_bottom=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create a rectangle.
Create a rectangle.
draw_arc{color=…, max_radius=…, min_radius=…, start_angle=…, angle=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create an arc.
Create an arc.
draw_polygon{color=…, vertices=…, target?=…, orientation?=…, orientation_target?=…, use_target_orientation?=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create a triangle mesh defined by a triangle strip.
Create a triangle mesh defined by a triangle strip.
draw_sprite{sprite=…, orientation?=…, x_scale?=…, y_scale?=…, tint?=…, render_layer?=…, orientation_target?=…, use_target_orientation?=…, oriented_offset?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create a sprite.
Create a sprite.
draw_light{sprite=…, orientation?=…, scale?=…, intensity?=…, minimum_darkness?=…, oriented?=…, color?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create a light. [...]
Create a light. [...]
draw_animation{animation=…, orientation?=…, x_scale?=…, y_scale?=…, tint?=…, render_layer?=…, animation_speed?=…, animation_offset?=…, orientation_target?=…, use_target_orientation?=…, oriented_offset?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, only_in_alt_mode?=…} changed | → LuaRenderObject | Create an animation.
Create an animation.
get_all_objects(mod_name?) new | → array[LuaRenderObject] | Gets an array of all valid objects.
Gets an array of all valid objects.
clear(mod_name?) |  | Destroys all render objects.
Destroys all render objects.
get_object_by_id(object_id) new | → LuaRenderObject? | Gives LuaRenderObject for given object ID. [...]
Gives LuaRenderObject for given object ID. [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]

## Methods

### draw_line{color=…, width=…, gap_length?=…, dash_length?=…, dash_offset?=…, from=…, to=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} → LuaRenderObject changed

Create a line.

#### Parameters

Table with the following fields:

color | :: Color |
width | :: float | In pixels (32 per tile).
In pixels (32 per tile).
gap_length | :: double? | Length of the gaps that this line has, in tiles. Default is 0.
Length of the gaps that this line has, in tiles. Default is 0.
dash_length | :: double? | Length of the dashes that this line has. Used only if gap_length > 0. Default is 0.
Length of the dashes that this line has. Used only if gap_length > 0. Default is 0.
dash_offset | :: double? | Starting offset to apply to dashes. Cannot be greater than dash_length + gap_length. Default is 0.
Starting offset to apply to dashes. Cannot be greater than dash_length + gap_length. Default is 0.
from | :: ScriptRenderTarget |
to | :: ScriptRenderTarget |
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
draw_on_ground | :: boolean? | If this should be drawn below sprites and entities. Defaults to false.
If this should be drawn below sprites and entities. Defaults to false.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

#### Examples

    -- 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=…, color=…, scale?=…, font?=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, orientation?=…, alignment?=…, vertical_alignment?=…, scale_with_zoom?=…, only_in_alt_mode?=…, use_rich_text?=…} → LuaRenderObject changed

Create a text.

Not all fonts support scaling.

#### Parameters

Table with the following fields:

text | :: LocalisedString | The text to display.
The text to display.
surface | :: SurfaceIdentification |
target | :: ScriptRenderTarget |
color | :: Color |
scale | :: double? |
font | :: string? | Name of font to use. Defaults to the same font as flying-text.
Name of font to use. Defaults to the same font as flying-text.
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
draw_on_ground | :: boolean? | If this should be drawn below sprites and entities. Rich text does not support this option. Defaults to false.
If this should be drawn below sprites and entities. Rich text does not support this option. Defaults to false.
orientation | :: RealOrientation? | The orientation of the text. Default is 0.
The orientation of the text. Default is 0.
alignment | :: TextAlign? | Defaults to "left".
Defaults to "left".
vertical_alignment | :: VerticalTextAlign? | Defaults to "top".
Defaults to "top".
scale_with_zoom | :: boolean? | 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.
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? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.
use_rich_text | :: boolean? | If rich text rendering is enabled. Defaults to false.
If rich text rendering is enabled. Defaults to false.

### draw_circle{color=…, radius=…, width?=…, filled?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} → LuaRenderObject changed

Create a circle.

#### Parameters

Table with the following fields:

color | :: Color |
radius | :: double | In tiles.
In tiles.
width | :: float? | Width of the outline, used only if filled = false. Value is in pixels (32 per tile). Defaults to 1.
Width of the outline, used only if filled = false. Value is in pixels (32 per tile). Defaults to 1.
filled | :: boolean? | If the circle should be filled. Defaults to false.
If the circle should be filled. Defaults to false.
target | :: ScriptRenderTarget |
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
draw_on_ground | :: boolean? | If this should be drawn below sprites and entities. Defaults to false.
If this should be drawn below sprites and entities. Defaults to false.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

### draw_rectangle{color=…, width?=…, filled?=…, left_top=…, right_bottom=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} → LuaRenderObject changed

Create a rectangle.

#### Parameters

Table with the following fields:

color | :: Color |
width | :: float? | Width of the outline, used only if filled = false. Value is in pixels (32 per tile). Defaults to 1.
Width of the outline, used only if filled = false. Value is in pixels (32 per tile). Defaults to 1.
filled | :: boolean? | If the rectangle should be filled. Defaults to false.
If the rectangle should be filled. Defaults to false.
left_top | :: ScriptRenderTarget |
right_bottom | :: ScriptRenderTarget |
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
draw_on_ground | :: boolean? | If this should be drawn below sprites and entities. Defaults to false.
If this should be drawn below sprites and entities. Defaults to false.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

#### Example

    -- Draw a white and 1 pixel wide square outline with the corners {0, 0} and {2, 2}.
    rendering.draw_rectangle{surface = game.player.surface, left_top = {0, 0}, right_bottom = {2, 2}, color = {1, 1, 1}}

### draw_arc{color=…, max_radius=…, min_radius=…, start_angle=…, angle=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} → LuaRenderObject changed

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.
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.
The radius of the inner edge of the arc, in tiles.
start_angle | :: float | Where the arc starts, in radian.
Where the arc starts, in radian.
angle | :: float | The angle of the arc, in radian.
The angle of the arc, in radian.
target | :: ScriptRenderTarget |
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
draw_on_ground | :: boolean? | If this should be drawn below sprites and entities. Defaults to false.
If this should be drawn below sprites and entities. Defaults to false.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

### draw_polygon{color=…, vertices=…, target?=…, orientation?=…, orientation_target?=…, use_target_orientation?=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, draw_on_ground?=…, only_in_alt_mode?=…} → LuaRenderObject changed

Create a triangle mesh defined by a triangle strip.

#### Parameters

Table with the following fields:

color | :: Color |
vertices | :: array[ScriptRenderTarget] |
target | :: ScriptRenderTarget? | Acts like an offset applied to all vertices that are not set to an entity.
Acts like an offset applied to all vertices that are not set to an entity.
orientation | :: RealOrientation? | The orientation applied to all vertices. Default is 0.
The orientation applied to all vertices. Default is 0.
orientation_target | :: ScriptRenderTarget? | If given, the vertices (that are not set to an entity) rotate so that it faces this target. Note that `orientation` is still applied.
If given, the vertices (that are not set to an entity) rotate so that it faces this target. Note that `orientation` is still applied.
use_target_orientation | :: boolean? | Only used if `orientation_target` is a LuaEntity.
Only used if `orientation_target` is a LuaEntity.
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
draw_on_ground | :: boolean? | If this should be drawn below sprites and entities. Defaults to false.
If this should be drawn below sprites and entities. Defaults to false.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

### draw_sprite{sprite=…, orientation?=…, x_scale?=…, y_scale?=…, tint?=…, render_layer?=…, orientation_target?=…, use_target_orientation?=…, oriented_offset?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, only_in_alt_mode?=…} → LuaRenderObject changed

Create a sprite.

#### Parameters

Table with the following fields:

sprite | :: SpritePath |
orientation | :: RealOrientation? | The orientation of the sprite. Default is 0.
The orientation of the sprite. Default is 0.
x_scale | :: double? | Horizontal scale of the sprite. Default is 1.
Horizontal scale of the sprite. Default is 1.
y_scale | :: double? | Vertical scale of the sprite. Default is 1.
Vertical scale of the sprite. Default is 1.
tint | :: Color? |
render_layer | :: RenderLayer? | Render layer of the sprite. Defaults to `"arrow"`.
Render layer of the sprite. Defaults to `"arrow"`.
orientation_target | :: ScriptRenderTarget? | If given, the sprite rotates so that it faces this target. Note that `orientation` is still applied to the sprite.
If given, the sprite rotates so that it faces this target. Note that `orientation` is still applied to the sprite.
use_target_orientation | :: boolean? | Only used if `orientation_target` is a LuaEntity.
Only used if `orientation_target` is a LuaEntity.
oriented_offset | :: Vector? | Offsets the center of the sprite if `orientation_target` is given. This offset will rotate together with the sprite.
Offsets the center of the sprite if `orientation_target` is given. This offset will rotate together with the sprite.
target | :: ScriptRenderTarget | Center of the sprite.
Center of the sprite.
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

#### Examples

    -- 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 = {entity = game.player.character, offset = {0, -2}}, surface = game.player.surface}

### draw_light{sprite=…, orientation?=…, scale?=…, intensity?=…, minimum_darkness?=…, oriented?=…, color?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, only_in_alt_mode?=…} → LuaRenderObject changed

Create a light.

The base game uses the utility sprites `light_medium` and `light_small` for lights.

#### Parameters

Table with the following fields:

sprite | :: SpritePath |
orientation | :: RealOrientation? | The orientation of the light. Default is 0.
The orientation of the light. Default is 0.
scale | :: float? | Default is 1.
Default is 1.
intensity | :: float? | Default is 1.
Default is 1.
minimum_darkness | :: float? | The minimum darkness at which this light is rendered. Default is 0.
The minimum darkness at which this light is rendered. Default is 0.
oriented | :: boolean? | If this light has the same orientation as the entity target, default is false. Note that `orientation` is still applied to the sprite.
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? | Defaults to white (no tint).
Defaults to white (no tint).
target | :: ScriptRenderTarget | Center of the light.
Center of the light.
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

### draw_animation{animation=…, orientation?=…, x_scale?=…, y_scale?=…, tint?=…, render_layer?=…, animation_speed?=…, animation_offset?=…, orientation_target?=…, use_target_orientation?=…, oriented_offset?=…, target=…, surface=…, time_to_live?=…, forces?=…, players?=…, visible?=…, only_in_alt_mode?=…} → LuaRenderObject changed

Create an animation.

#### Parameters

Table with the following fields:

animation | :: string | Name of an AnimationPrototype.
Name of an AnimationPrototype.
orientation | :: RealOrientation? | The orientation of the animation. Default is 0.
The orientation of the animation. Default is 0.
x_scale | :: double? | Horizontal scale of the animation. Default is 1.
Horizontal scale of the animation. Default is 1.
y_scale | :: double? | Vertical scale of the animation. Default is 1.
Vertical scale of the animation. Default is 1.
tint | :: Color? |
render_layer | :: RenderLayer? | Render layer of the animation. Defaults to `"arrow"`.
Render layer of the animation. Defaults to `"arrow"`.
animation_speed | :: double? | How many frames the animation goes forward per tick. Default is 1.
How many frames the animation goes forward per tick. Default is 1.
animation_offset | :: double? | Offset of the animation in frames. Default is 0.
Offset of the animation in frames. Default is 0.
orientation_target | :: ScriptRenderTarget? | If given, the animation rotates so that it faces this target. Note that `orientation` is still applied to the animation.
If given, the animation rotates so that it faces this target. Note that `orientation` is still applied to the animation.
use_target_orientation | :: boolean? | Only used if `orientation_target` is a LuaEntity.
Only used if `orientation_target` is a LuaEntity.
oriented_offset | :: Vector? | Offsets the center of the animation if `orientation_target` is given. This offset will rotate together with the animation.
Offsets the center of the animation if `orientation_target` is given. This offset will rotate together with the animation.
target | :: ScriptRenderTarget | Center of the animation.
Center of the animation.
surface | :: SurfaceIdentification |
time_to_live | :: uint? | In ticks. Defaults to living forever.
In ticks. Defaults to living forever.
forces | :: ForceSet? | The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
The forces that this object is rendered to. Passing `nil` or an empty table will render it to all forces.
players | :: array[PlayerIdentification]? | The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
The players that this object is rendered to. Passing `nil` or an empty table will render it to all players.
visible | :: boolean? | If this is rendered to anyone at all. Defaults to true.
If this is rendered to anyone at all. Defaults to true.
only_in_alt_mode | :: boolean? | If this should only be rendered in alt mode. Defaults to false.
If this should only be rendered in alt mode. Defaults to false.

### get_all_objects(mod_name?) → array[LuaRenderObject] new

Gets an array of all valid objects.

#### Parameters

mod_name | :: string? | If provided, get only the render objects created by this mod. An empty string (`""`) refers to all objects not belonging to a mod, such as those created using console commands.
If provided, get only the render objects created by this mod. An empty string (`""`) refers to all objects not belonging to a mod, such as those created using console commands.

### clear(mod_name?)

Destroys all render objects.

#### Parameters

mod_name | :: string? | If provided, only the render objects created by this mod are destroyed. An empty string (`""`) refers to all objects not belonging to a mod, such as those created using console commands.
If provided, only the render objects created by this mod are destroyed. An empty string (`""`) refers to all objects not belonging to a mod, such as those created using console commands.

### get_object_by_id(object_id) → LuaRenderObject?new

Gives LuaRenderObject for given object ID. May return nil if object does not exist or is invalid.

#### Parameters

object_id | :: uint64 |

## Attributes

### object_name :: Read string

The class name of this object. Available even when `valid` is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.