Skip to content
Download
API reference

ProceduralGenerator2D

Inherits: Spatial2D < CanvasItem < Actor < Object

Generates content over a rectangle of a 2D scene with a procedural graph.

Runs graph over bounds and puts in the scene what its spawner nodes say: tiles (ProceduralNodeSpawnTiles), sprites (ProceduralNodeSpawnSprites) and prefabs (ProceduralNodeSpawnPrefab). What it makes belongs to it: generating again replaces it, and cleanup() takes it away (tiles go back to how they were). Its graph can read the scene: ProceduralNodeGetTiles, ProceduralNodeGetNodes.

With GENERATE_AT_RUNTIME, it generates in the game the cells of cell_size around its sources, nearest first and within a time budget each frame, and takes away the cells left far; each cell puts only its own points, so the result is the same as generating the whole area at once.

With GENERATE_IN_EDITOR, it generates while you edit (when the graph, the seed, the bounds or the parameters change, or with Generate), and what it made is kept with the scene: when the scene loads, in the editor or in the game, it comes back the same without running the graph, as long as nothing it depends on changed.

use actor::Forest as generator : ProceduralGenerator2D
fn _ready() void {
generator.seed = 7
generator.set_parameter(&"trees", 0.8)
generator.generate()
}
TypeNameDefault
Rect2boundsRect2(0, 0, 1024, 1024)
floatcell_size512.0
Callablecleanup_actionCallable()
floatcleanup_radius_multiplier1.25
Callablegenerate_actionCallable()
ProceduralGenerator2D.GenerateModegenerate_mode0
[]u8generated_dataPackedByteArray()
intgenerated_hash0
floatgeneration_radius1024.0
ProceduralGraphgraph
Dictionarymanaged_tiles{}
floatmask_texel_size4.0
Dictionarymasks{}
Dictionaryoverrides{}
Dictionaryparameters{}
boolpreview_in_editortrue
intseed0
NodePathspawn_parentNodePath("")
boolunboundedfalse
booluse_cameratrue
booluse_online_seedfalse
ReturnsMethod
intadd_generated(spawner, position, attributes)
voidcleanup()
voidclear_overrides()
Dictionaryfind_generated(position, radius)
Errorgenerate()
Vector2iget_cell_at(position)
intget_effective_seed()
intget_inputs_hash()
ProceduralResultget_last_result()
intget_last_step_usec()
[]Vector2iget_loaded_cells()
Imageget_mask(name)
[]Stringget_mask_names()
[]intget_orphan_overrides()
Dictionaryget_override(id)
intget_pending_cell_count()
intget_pending_job_count()
intget_reusable_count()
intget_spawned_id(node)
[]Actorget_spawned_nodes()
boolis_cell_loaded(cell)
boolis_generated()
boolis_up_to_date()
voidmove_generated(id, position)
voidpaint_mask(name, plane, radius, value, strength)
voidremove_generated(id)
voidset_generated_attribute(id, name, value)
voidset_mask(name, image)
voidset_override(id, override)
voidset_parameter(name, value)

cell_generated(cell: Vector2i)

At runtime, emitted when everything of cell is in the scene.

cell_removed(cell: Vector2i)

At runtime, emitted when cell was taken away (it was left far).

generated()

Emitted after it generated and put what it made in the scene.

masks_changed()

Emitted when a mask changes (masks).

overrides_changed()

Emitted when what was changed by hand changes (overrides).

prefab_removing(node: Object, id: int)

Emitted before a prefab it made is taken away: its cell was left far, or it generates again. id is its stable id. The game reads here what changed in it (a tree cut down) to keep it: when the cell comes back, the graph makes it again as it was.

prefab_spawning(node: Object, id: int)

Emitted for each prefab it makes, before it enters the scene tree, so what the game sets on it is there for its Actor._ready(). id is its stable id: the same when its cell comes back, so the game sets again what it kept from prefab_removing.

  • GENERATE_IN_EDITOR = 0 — Generates while you edit; what it made is kept with the scene.

  • GENERATE_ON_READY = 1 — Generates every time it enters the game.

  • GENERATE_MANUALLY = 2 — Only with generate() (what was generated in the editor with Generate still comes back).

  • GENERATE_AT_RUNTIME = 3 — In the game, the cells around its sources (the camera, ProceduralSource2D nodes), a little each frame (Project Settings > Procedural > Runtime > Frame Budget Ms); the cells left far go.

Rect2 bounds = Rect2(0, 0, 1024, 1024)

Setter/getter: set_bounds(), get_bounds()

Where it generates, in its own coordinates.

float cell_size = 512.0

Setter/getter: set_cell_size(), get_cell_size()

At runtime, the size of each cell it generates.

Callable cleanup_action = Callable()

Setter/getter: get_cleanup_action()

The Clear button of the inspector.

float cleanup_radius_multiplier = 1.25

Setter/getter: set_cleanup_radius_multiplier(), get_cleanup_radius_multiplier()

At runtime, a cell goes when it is farther than generation_radius times this from every source (more than 1, so cells at the edge don’t come and go).

Callable generate_action = Callable()

Setter/getter: get_generate_action()

The Generate button of the inspector.

ProceduralGenerator2D.GenerateMode generate_mode = 0

Setter/getter: set_generate_mode(), get_generate_mode()

When it generates: In Editor (and kept with the scene), On Ready (every time the game starts), Manually (generate()), or At Runtime (by cells around the camera and the sources, a little each frame: a big world costs what is near).

[]u8 generated_data = PackedByteArray()

Setter/getter: set_generated_data(), get_generated_data()

What it made, kept with the scene (compressed).

int generated_hash = 0

Setter/getter: set_generated_hash(), get_generated_hash()

What get_inputs_hash() was when it made it.

float generation_radius = 1024.0

Setter/getter: set_generation_radius(), get_generation_radius()

At runtime, how far from each source the cells are generated. Around the camera (use_camera), never less than what it sees and a quarter more, so nothing appears on screen.

ProceduralGraph graph

Setter/getter: set_graph(), get_graph()

The graph it runs.

Dictionary managed_tiles = {}

Setter/getter: set_managed_tiles(), get_managed_tiles()

The cells it changed, as they were before, by layer.

float mask_texel_size = 4.0

Setter/getter: set_mask_texel_size(), get_mask_texel_size()

How big a texel of a new mask is, in its units (pixels in 2D, metres in 3D).

Dictionary masks = {}

Setter/getter: set_masks(), get_masks()

The masks painted by hand, kept with the scene: a name and an image (one channel) over its bounds each. ProceduralNodeMaskToDensity reads them.

Dictionary overrides = {}

Setter/getter: set_overrides(), get_overrides()

What was changed by hand, kept with the scene: the id of each thing (the hex of a prefab’s name) and what changed ("removed", "position", "attributes"; "added" with its spawner’s "path", "position" and "seed"). Applied every time it generates.

Dictionary parameters = {}

Setter/getter: set_parameters(), get_parameters()

Values for the graph’s parameters (see ProceduralGraph.bind_parameter()).

bool preview_in_editor = true

Setter/getter: set_preview_in_editor(), get_preview_in_editor()

At Runtime, in the editor: generates around what the 2D viewport shows, to see the world while you edit (without tiles: the scene’s layers are left as they are).

int seed = 0

Setter/getter: set_seed(), get_seed()

The seed: another seed gives other content.

NodePath spawn_parent = NodePath("")

Setter/getter: set_spawn_parent(), get_spawn_parent()

Where prefabs go (for example the node the player is in, for Y sorting). Empty: under the generator.

bool unbounded = false

Setter/getter: set_unbounded(), is_unbounded()

At runtime, generates wherever the sources go, without bounds: a world without end.

bool use_camera = true

Setter/getter: set_use_camera(), get_use_camera()

At runtime, the current camera is a source.

bool use_online_seed = false

Setter/getter: set_use_online_seed(), get_use_online_seed()

Mixes its seed with the world’s (Online.get_world_seed()), so every game of an online session generates the same, with the same names. It generates again when the world’s seed changes (a player that gets the server’s).

int add_generated(spawner: int, position: Vector2, attributes: Dictionary = {})

Adds a thing by hand at position for the spawner node spawner of the graph, with attributes. Returns its id.

void cleanup()

Takes away what it made; tiles go back to how they were.

void clear_overrides()

Takes away every change made by hand.

Dictionary find_generated(position: Vector2, radius: float) const

The thing it made (a prefab or a sprite) nearest to position within radius, in its own coordinates: a dictionary with id, path and position, empty when there is none.

Error generate()

Runs the graph and puts what it makes in the scene, replacing what it made before.

With GENERATE_AT_RUNTIME it doesn’t make all of it at once: it takes away what it made, and the cells come again around the sources, a little each frame, with the current settings. So a script that sets the parameters and calls generate() works the same in every mode.

Vector2i get_cell_at(position: Vector2) const

The cell a position (in its own coordinates) is in.

int get_effective_seed() const

The seed it generates with: seed, mixed with the world’s when use_online_seed is on.

int get_inputs_hash()

The same while nothing the generation depends on changes: the graph, the seed, the bounds, the parameters and what its nodes read from the scene.

ProceduralResult get_last_result() const

The result of the last run (empty when what it made came back from the scene without running).

int get_last_step_usec() const

At runtime, how long its work took in the last frame, in microseconds.

[]Vector2i get_loaded_cells() const

At runtime, the cells it has generated.

Image get_mask(name: StringName) const

The image of the mask name (null when it has none).

[]String get_mask_names() const

The names of its masks.

[]int get_orphan_overrides() const

The changes whose thing the last generation didn’t make any more (the graph or what it reads changed): remove them, or edit what they are about again. Only a generation without cells knows them.

Dictionary get_override(id: int) const

What changed by hand for the thing id (empty when nothing did).

int get_pending_cell_count() const

At runtime, how many cells within reach are still to generate.

int get_pending_job_count() const

At runtime, how many pieces of generated cells are still to put in the scene.

int get_reusable_count() const

How many prefab instances it keeps out of the tree to use again (ProceduralNodeSpawnPrefab.reuse_instances).

int get_spawned_id(node: Actor) const

The stable id of a prefab it made: the same for the same spawner and point every time it is made (it is also at the end of its name, in hexadecimal). -1 for a node it didn’t make. See prefab_spawning.

[]Actor get_spawned_nodes() const

Every node it made (prefabs and sprite groups).

bool is_cell_loaded(cell: Vector2i) const

At runtime, whether that cell is generated and everything in it is in the scene.

bool is_generated() const

Whether what it made is in the scene.

bool is_up_to_date()

Whether what it made matches what it depends on now.

void move_generated(id: int, position: Vector2)

Puts the thing id at position (in its own coordinates), also every time it generates again.

void paint_mask(name: StringName, plane: Vector2, radius: float, value: float, strength: float = 1.0)

Paints the mask name with a soft round brush of radius at plane (on its ground, in its coordinates), towards value (0 to 1) by strength. It doesn’t generate again: call set_mask() with it at the end of a stroke.

void remove_generated(id: int)

Takes the thing id away by hand: it is not made again when it generates (one added by hand is just not added any more).

void set_generated_attribute(id: int, name: StringName, value: Variant)

Gives the thing id another value of an attribute (one named like a property of a prefab sets it; another value of ProceduralNodeSpawnPrefab.prefab_attribute gives another prefab).

void set_mask(name: StringName, image: Image)

Sets the mask name (null takes it away) and generates again where it does so by itself.

void set_override(id: int, override: Dictionary)

Sets what changed by hand for the thing id (see overrides). An empty override takes the change away: the thing is again as the graph makes it.

void set_parameter(name: StringName, value: Variant)

Sets one value of parameters.