Home

LuaRendering

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.

Attributes

object_name

Read: string
Write: unknown
Optional: false

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.

Methods

draw_line

LuaRendering.draw_line{ color: Color, width: float, gap_length?: double, dash_length?: double, dash_offset?: double, from: ScriptRenderTarget, to: ScriptRenderTarget, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, draw_on_ground?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_line{ color=color, width=width, from=from, to=to, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create a line.

Parameters

color: Color
width: float — In pixels (32 per tile).
gap_length?: double — 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.
dash_offset?: double — 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?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
only_in_alt_mode?: boolean — If this should only be rendered in alt mode. Defaults to false.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

draw_text

LuaRendering.draw_text{ text: LocalisedString, surface: SurfaceIdentification, target: ScriptRenderTarget, color: Color, scale?: double, font?: string, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, draw_on_ground?: boolean, orientation?: RealOrientation, alignment?: TextAlign, vertical_alignment?: VerticalTextAlign, scale_with_zoom?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode, use_rich_text?: boolean } -> LuaRenderObject

Call As

rendering.draw_text{ text=text, surface=surface, target=target, color=color }

Call Convention

takes_table: true
table_optional: false

Create a text.

Not all fonts support scaling.

Parameters

text: LocalisedString — 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.
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
orientation?: RealOrientation — The orientation of the text. Default is 0.
alignment?: TextAlign — Defaults to "left".
vertical_alignment?: VerticalTextAlign — 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.
only_in_alt_mode?: boolean — If this should only be rendered in alt mode. Defaults to false.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".
use_rich_text?: boolean — If rich text rendering is enabled. Defaults to false.

Returns

LuaRenderObject

draw_circle

LuaRendering.draw_circle{ color: Color, radius: double, width?: float, filled?: boolean, target: ScriptRenderTarget, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, draw_on_ground?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_circle{ color=color, radius=radius, target=target, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create a circle.

Parameters

color: Color
radius: double — In tiles.
width?: float — 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.
target: ScriptRenderTarget
surface: SurfaceIdentification
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
only_in_alt_mode?: boolean — If this should only be rendered in alt mode. Defaults to false.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

draw_rectangle

LuaRendering.draw_rectangle{ color: Color, width?: float, filled?: boolean, left_top: ScriptRenderTarget, right_bottom: ScriptRenderTarget, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, draw_on_ground?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_rectangle{ color=color, left_top=left_top, right_bottom=right_bottom, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create a rectangle.

Parameters

color: Color
width?: float — 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.
left_top: ScriptRenderTarget
right_bottom: ScriptRenderTarget
surface: SurfaceIdentification
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
only_in_alt_mode?: boolean — If this should only be rendered in alt mode. Defaults to false.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

draw_arc

LuaRendering.draw_arc{ color: Color, max_radius: double, min_radius: double, start_angle: float, angle: float, target: ScriptRenderTarget, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, draw_on_ground?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_arc{ color=color, max_radius=max_radius, min_radius=min_radius, start_angle=start_angle, angle=angle, target=target, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create an arc.

Parameters

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: ScriptRenderTarget
surface: SurfaceIdentification
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
only_in_alt_mode?: boolean — If this should only be rendered in alt mode. Defaults to false.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

draw_polygon

LuaRendering.draw_polygon{ color: Color, vertices: Array<ScriptRenderTarget>, target?: ScriptRenderTarget, orientation?: RealOrientation, orientation_target?: ScriptRenderTarget, use_target_orientation?: boolean, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, draw_on_ground?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_polygon{ color=color, vertices=vertices, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create a triangle mesh defined by a triangle strip.

Parameters

color: Color
vertices: Array<ScriptRenderTarget>
target?: ScriptRenderTarget — 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.
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.
use_target_orientation?: boolean — Only used if orientation_target is a LuaEntity.
surface: SurfaceIdentification
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
only_in_alt_mode?: boolean — If this should only be rendered in alt mode. Defaults to false.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

draw_sprite

LuaRendering.draw_sprite{ sprite: SpritePath, orientation?: RealOrientation, x_scale?: double, y_scale?: double, tint?: Color, render_layer?: RenderLayer, orientation_target?: ScriptRenderTarget, use_target_orientation?: boolean, oriented_offset?: Vector, target: ScriptRenderTarget, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_sprite{ sprite=sprite, target=target, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create a sprite.

Parameters

sprite: SpritePath
orientation?: RealOrientation — The orientation of the sprite. Default is 0.
x_scale?: double — Horizontal scale of the sprite. Default is 1.
y_scale?: double — Vertical scale of the sprite. Default is 1.
tint?: Color
render_layer?: RenderLayer — 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.
use_target_orientation?: boolean — 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.
target: ScriptRenderTarget — Center of the sprite.
surface: SurfaceIdentification
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

draw_light

LuaRendering.draw_light{ sprite: SpritePath, orientation?: RealOrientation, scale?: float, intensity?: float, minimum_darkness?: float, oriented?: boolean, color?: Color, target: ScriptRenderTarget, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_light{ sprite=sprite, target=target, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create a light.

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

Parameters

sprite: SpritePath
orientation?: RealOrientation — The orientation of the light. Default is 0.
scale?: float — Default is 1.
intensity?: float — Default is 1.
minimum_darkness?: float — 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.
color?: Color — Defaults to white (no tint).
target: ScriptRenderTarget — Center of the light.
surface: SurfaceIdentification
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

draw_animation

LuaRendering.draw_animation{ animation: string, orientation?: RealOrientation, x_scale?: double, y_scale?: double, tint?: Color, render_layer?: RenderLayer, animation_speed?: double, animation_offset?: double, orientation_target?: ScriptRenderTarget, use_target_orientation?: boolean, oriented_offset?: Vector, target: ScriptRenderTarget, surface: SurfaceIdentification, time_to_live?: uint32, blink_interval?: uint16, forces?: ForceSet, players?: Array<PlayerIdentification>, visible?: boolean, only_in_alt_mode?: boolean, render_mode?: ScriptRenderMode } -> LuaRenderObject

Call As

rendering.draw_animation{ animation=animation, target=target, surface=surface }

Call Convention

takes_table: true
table_optional: false

Create an animation.

Parameters

animation: string — Name of an AnimationPrototype.
orientation?: RealOrientation — The orientation of the animation. Default is 0.
x_scale?: double — Horizontal scale of the animation. Default is 1.
y_scale?: double — Vertical scale of the animation. Default is 1.
tint?: Color
render_layer?: RenderLayer — Render layer of the animation. Defaults to "arrow".
animation_speed?: double — How many frames the animation goes forward per tick. Default is 1.
animation_offset?: double — 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.
use_target_orientation?: boolean — 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.
target: ScriptRenderTarget — Center of the animation.
surface: SurfaceIdentification
time_to_live?: uint32 — In ticks. Defaults to living forever.
blink_interval?: uint16 — In ticks. Defaults to 0 (no blinking). Game alerts use 30.
forces?: ForceSet — 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.
visible?: boolean — 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.
render_mode?: ScriptRenderMode — Mode which this object should render in. Defaults to "game".

Returns

LuaRenderObject

get_all_objects

LuaRendering.get_all_objects(mod_name?: string) -> Array<LuaRenderObject>

Call As

rendering.get_all_objects()

Call Convention

takes_table: false
table_optional: false

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.

Returns

Array<LuaRenderObject>

clear

LuaRendering.clear(mod_name?: string)

Call As

rendering.clear()

Call Convention

takes_table: false
table_optional: false

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.

get_object_by_id

LuaRendering.get_object_by_id(object_id: uint64) -> LuaRenderObject?

Call As

rendering.get_object_by_id(object_id)

Call Convention

takes_table: false
table_optional: false

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

Parameters

object_id: uint64

Returns

LuaRenderObject?