Skip to content

Search

Documentation

render module

What a frame is made of: the shape, sprite, mesh or emitter a node draws, the 2D and 3D cameras, the backdrop, debug lines and screenshots. window holds…

Nesta página

What a frame is made of: the shape, sprite, mesh or emitter a node draws, the 2D and 3D cameras, the backdrop, debug lines and screenshots. window holds the window itself.

70 functions, 46 constants. Scripts reach it as render::.

Acts on boolean3d, multimesh2d, multimesh3d, occluder2d, screen_notifier2d, shape2d, shape3d, tilemap: those functions are also methods on the component's handle, without the node argument.

Functions

Argument kinds are the script values a call passes: node is a node handle, any a table or value of any kind, fn a callback.

function acts on what it does
bounds(node) -> any — The box the node's geometry covers in its own space, as a centre xyz and half-extents xyz, with a z of zero for a 2D node; nil for a node that draws nothing. A solver's body reports where it is now, not where it was built.
buffer(node) -> any multimesh2d, multimesh3d Every instance as one flat list of floats in Godot's MultiMesh.buffer layout: 12 of transform in 3D or 8 in 2D, then 4 of colour and 4 of custom data.
built_mesh(node) -> any boolean3d The triangles the node's boolean settled on, as #{ positions, indices } ready to be written out as a mesh asset; nil when the node draws no built geometry.
camera_2d() -> float, float, float — The 2D camera this frame: centre xy and zoom in logical pixels per world unit; all zeros with no window.
camera_matrix() -> [float] — The camera's projection*view matrix this frame, 16 numbers column-major; all zeros with no window.
camera_pose() -> float, float, float, float, float, float, float, float — The camera the renderer actually used: eye xyz, target xyz, vertical fov in radians, HiDPI scale.
cell(node, int, int) -> int tilemap The tile at a column and row, or -1 for an empty cell or one past the edge.
check_material(string) -> any — Every diagnostic about the material at that path, as [#{ file, line, column, severity, message }]; empty when it links.
debug_view() -> string — Which channel the viewport is drawing instead of the scene's colour, or empty for the scene as it is.
debug_views() -> any — Every channel name set_debug_view accepts, as a list.
draw_arc_2d(float, float, float, float, float, float?, any?, any?) — Stroke an arc between two angles in radians, counter-clockwise from the x axis, for this frame; width is in pixels, and opts takes z_index.
draw_box(float, float, float, float, float, float, any?) — Draw a wireframe box centred at a point, from its three half-extents in world units, for this frame.
draw_capsule(float, float, float, float, float, any?) — Draw a wireframe capsule centred at a point, height being the straight part along y, for this frame.
draw_circle_2d(float, float, float, any?, any?) — Fill a circle in world units for this frame, over everything the scene drew; opts.z_index places it among the nodes of that index instead.
draw_line_2d(float, float, float, float, float, float, float, float?, any?) — Draw one 2D world-space line for this frame; width is in pixels, and opts.z_index places it among the nodes of that index.
draw_line_3d(float, float, float, float, float, float, float, float, float, float?, bool?, bool?) — Draw one 3D world-space line for this frame; the width is in pixels unless perspective scales it with distance.
draw_lines(any) — Draw many 3D lines in one call: eleven numbers a segment, being both ends, an rgb, a width and an on-top flag.
draw_polygon_2d(any, any?, any?) — Fill a convex outline of world-space points for this frame; geometry2d cuts a concave one into triangles first. opts takes z_index.
draw_polyline_2d(any, float?, any?, any?) — Stroke a chain of world-space points for this frame; width is in pixels, and opts takes z_index.
draw_rect_2d(float, float, float, float, any?, any?) — Fill a rectangle centred at a point, in world units, for this frame; opts takes z_index.
draw_sphere(float, float, float, float, any?) — Draw a wireframe sphere centred at a point, as three rings in world units, for this frame.
draw_text_2d(float, float, string, any?) — Draw a line of text in 2D world space for this frame, shaped by the engine's fonts. opts takes the text2d keys (font_size, font_weight, font_style, color, text_align, markup, max_width, font_family, bitmap_font, …), pixels_per_unit and z_index.
draw_text_3d(float, float, float, string, any?) — The same in 3D world space, on a quad that faces the camera. pixels_per_unit sizes it, so text a metre away reads the same whatever the font size.
draw_texture_2d(string, float, float, float, float, any?, any?) — Draw a project image over a rectangle centred at a point, in world units, for this frame; the colour tints it. opts takes z_index, and region_origin and region_size in the image's pixels for part of it.
instance_color(node, int) -> any multimesh2d, multimesh3d The colour one instance draws in.
instance_count(node) -> int multimesh2d, multimesh3d How many instances the node holds.
instance_custom_data(node, int) -> any multimesh2d, multimesh3d One instance's four floats of custom data, as a colour.
instance_region(node, int) -> any multimesh2d One instance's texture rectangle as [x, y, w, h] in pixels, or nil when it draws the whole texture.
instance_transform(node, int) -> any multimesh2d, multimesh3d One instance's transform: a Transform3d, or a Transform2d on a 2D node.
instances(node) -> any multimesh2d, multimesh3d Every instance as the multimesh asset spells it, so assets.save writes a scripted layout into a file.
is_on_screen(node) -> bool screen_notifier2d Whether any of the notifier's box was on screen at the end of the last frame.
material_params(string) -> any — The material's editable rows, one #{ name, type, value } per field its linked shader declares; empty when it will not link.
mouse_ray() -> float, float, float, float, float, float — The picking ray through the mouse position: its origin xyz then its direction xyz, in world units.
mouse_world_2d() -> float, float — The mouse position in 2D world coordinates, for picking.
outline(node) -> [float] occluder2d The outline this node blocks 2D light with, in world space: x then y for each point in turn, with the first repeated at the end when the outline is closed. Empty on a node with no occluder2d.
pick_ray(float, float, float, float, float, float) -> node? — The nearest node with a 3D shape that a world-space ray meets, from its origin xyz and direction xyz.
pick_ray_at(float, float, float, float, float, float) -> any — As pick_ray, but node and at, how far along the ray it was met; nil when the ray meets nothing.
populate(node, any) -> any multimesh2d, multimesh3d Godot's Populate Surface, and a row, a ring or a grid: the instances a layout would write, worked out from seed, returned in the multimesh asset's shape rather than set. kind is render.POPULATE_SURFACE with a surface node, POPULATE_ROW (count, step), POPULATE_RING (count, radius) or POPULATE_GRID (counts, step); rotation, tilt and random_scale vary each instance, as fractions, around scale.
screenshot(string) — Save the next rendered frame as a PNG at a project-relative path. screenshot_written goes to every listener with the path once it is on disk, and screenshot_failed with #{ path, error } when it cannot be, a run with no renderer included.
set_background(float, float, float) — Set the colour the viewport is cleared to behind everything drawn, as r, g, b channel floats.
set_box(node, float, float, float) shape3d Draw the node as a box from its three half-extents, in world units, replacing any other 3D shape.
set_buffer(node, any) multimesh2d, multimesh3d Replace every instance from one flat list in the layout buffer answers in, for a Godot port that sets buffer. Building the list in a script costs more than one set_instance_transform per instance.
set_camera(float, float, float, float, float, float) — Point the 3D camera: the eye position xyz, then the world point it looks at, in world units.
set_camera_2d(float, float, float) — Point the 2D camera: the world centre xy, then the zoom in logical pixels per world unit.
set_cell(node, int, int, int) tilemap Put one tile at a column and row; a tile below zero clears the cell, and a cell outside the map grows it in that direction. The mesh rebuilds on the next frame.
set_debug_view(string) — Draw one channel of the scene (normals, uv, depth or albedo) instead of its colour; an empty name puts the picture back.
set_grid(bool, float?, int?, int?) — Turn the ground grid on or off, and optionally set its step in world units, major-line interval and extent.
set_grid_colors(float, float, float, float, float, float) — Set the ground grid's minor line colour then its major line colour, as r, g, b channel floats.
set_instance_color(node, int, any) multimesh2d, multimesh3d The colour one instance draws in.
set_instance_count(node, int) multimesh2d, multimesh3d How many instances the node holds. Those below the count keep where they were; new ones are plain, at the node.
set_instance_custom_data(node, int, any) multimesh2d, multimesh3d Four floats a material's shader reads for one instance, as a colour or a list.
set_instance_region(node, int, any, any) multimesh2d The rectangle of the texture one instance draws, as an origin and a size in texture pixels; a zero size draws all of it. Not drawn yet: multimesh2d draws through Balaur's own pipeline, which binds no rectangle per instance.
set_instance_transform(node, int, any) multimesh2d, multimesh3d Place one instance with a Transform3d, or a Transform2d on a 2D node. A shear is kept, as the instance's basis.
set_instances(node, any) multimesh2d, multimesh3d Replace every instance with a list in the multimesh asset's shape.
set_rectangle(node, float, float) shape2d Draw the node as a rectangle from its two half-extents, in world units, replacing any other 2D shape.
set_shader_preview(string, int) — Draw the value a shader's line computes for every pixel that reaches it; line 0 puts the picture back.
set_shader_probe(float, float) — Ask what the previewed line computed at one framebuffer pixel; the answer arrives through shader_probe a frame later.
set_sphere(node, float) shape3d Draw the node as a sphere of the given radius in world units, replacing any other 3D shape.
set_terrain(node, int, int, int) tilemap Paint a terrain value at a column and row and let the tileset's rules pick the tiles, for that cell and the ring around it; below zero clears it.
set_visible_instance_count(node, int) multimesh2d, multimesh3d How many instances draw, from the first; -1 draws them all.
shader_probe() -> any — The four channels the previewed line wrote at the probed pixel, or () when nothing has been read yet.
snap_aov(string, string) — Render the 3D scene once more as render.AOV_DEPTH (nearest brightest), AOV_NORMALS (world space), AOV_CAMERA_NORMALS or AOV_SEGMENTATION (a colour per object) and save it as a PNG, announcing it as screenshot does. A read-back of the GPU, as screenshot is.
stats() -> any — What this frame draws: { draws, triangles, texture_bytes, textures, nodes }, where nodes is a row per node that drew, each { node, draws, triangles, texture_bytes, copies }. Presentation, never simulation: nothing in the digest reads it.
terrain(node, int, int) -> int tilemap The terrain value painted at a column and row, or -1 where nothing was painted.
text_size(string, any?) -> float, float — The width and height text shapes to, in font pixels, with the project's own fonts and never a system face — so a headless run and a windowed one answer the same. A width is presentation: writing one into state puts presentation in the digest.
texture_pixels_per_unit(string) -> float — How many of an image's pixels make a world unit when a sprite says 0: its own pixels_per_unit import setting, else 100.
texture_size(string) -> int, int — An image's width and height in pixels, read from the file's own header.
tile_data(node, int, int) -> any tilemap What the tileset says about the tile at a column and row -- its [tiles.<id>.data] table -- or nil where the cell is empty or the tile carries none.
trace_texture(string, any?) -> any — The outline of an image's opaque pixels, as [x, y] points in a node's own space, ready to be a polygon's positions. opts takes threshold (alpha counted as opaque, 0 to 1, default 0.5), tolerance (how many pixels of detail to drop, default 2), pixels_per_unit (default 100) and holes (every loop, largest first: each other island counter-clockwise and each hole clockwise; default false keeps the largest alone). Counter-clockwise with y up, centred on the origin, the way a sprite at the same pixels_per_unit is drawn.
visible_instance_count(node) -> int multimesh2d, multimesh3d How many instances draw; -1 is all of them.

Constants

name value
ALIGN_CENTER center
ALIGN_END end
ALIGN_START start
ALPHA_BLEND blend
ALPHA_MASK mask
ALPHA_OPAQUE opaque
ALPHA_PREMULTIPLIED premultiplied
AOV_CAMERA_NORMALS camera_normals
AOV_DEPTH depth
AOV_NORMALS normals
AOV_SEGMENTATION segmentation
FOG_EXPONENTIAL exponential
FOG_EXPONENTIAL_SQUARED exponential_squared
FOG_LINEAR linear
FOG_NONE none
FONT_ITALIC italic
FONT_NORMAL normal
LIGHT_DIRECTIONAL directional
LIGHT_POINT point
LIGHT_SPOT spot
POPULATE_GRID grid
POPULATE_RING ring
POPULATE_ROW row
POPULATE_SURFACE surface
SHAPE_BOX box
SHAPE_CAPSULE capsule
SHAPE_CIRCLE circle
SHAPE_CONE cone
SHAPE_CYLINDER cylinder
SHAPE_ELLIPSE ellipse
SHAPE_NGON ngon
SHAPE_PLANE plane
SHAPE_POLYLINE polyline
SHAPE_PRISM prism
SHAPE_PYRAMID pyramid
SHAPE_RECTANGLE rectangle
SHAPE_SPHERE sphere
SHAPE_STAR star
SHAPE_TORUS torus
SHAPE_TUBE tube
TONEMAP_ACES aces
TONEMAP_AGX agx
TONEMAP_NEUTRAL neutral
TONEMAP_NONE none
TONEMAP_REINHARD reinhard
TONEMAP_TONY_MCMAPFACE tony_mcmapface