ProceduralGenerator2D
Inherits: Spatial2D < CanvasItem < Actor < Object
Generates content over a rectangle of a 2D scene with a procedural graph.
Description
Section titled “Description”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()}Properties
Section titled “Properties”| Type | Name | Default |
|---|---|---|
| Rect2 | bounds | Rect2(0, 0, 1024, 1024) |
| float | cell_size | 512.0 |
| Callable | cleanup_action | Callable() |
| float | cleanup_radius_multiplier | 1.25 |
| Callable | generate_action | Callable() |
| ProceduralGenerator2D.GenerateMode | generate_mode | 0 |
[]u8 | generated_data | PackedByteArray() |
| int | generated_hash | 0 |
| float | generation_radius | 1024.0 |
| ProceduralGraph | graph | |
| Dictionary | managed_tiles | {} |
| float | mask_texel_size | 4.0 |
| Dictionary | masks | {} |
| Dictionary | overrides | {} |
| Dictionary | parameters | {} |
| bool | preview_in_editor | true |
| int | seed | 0 |
| NodePath | spawn_parent | NodePath("") |
| bool | unbounded | false |
| bool | use_camera | true |
| bool | use_online_seed | false |
Methods
Section titled “Methods”| Returns | Method |
|---|---|
| int | add_generated(spawner, position, attributes) |
| void | cleanup() |
| void | clear_overrides() |
| Dictionary | find_generated(position, radius) |
| Error | generate() |
| Vector2i | get_cell_at(position) |
| int | get_effective_seed() |
| int | get_inputs_hash() |
| ProceduralResult | get_last_result() |
| int | get_last_step_usec() |
[]Vector2i | get_loaded_cells() |
| Image | get_mask(name) |
[]String | get_mask_names() |
[]int | get_orphan_overrides() |
| Dictionary | get_override(id) |
| int | get_pending_cell_count() |
| int | get_pending_job_count() |
| int | get_reusable_count() |
| int | get_spawned_id(node) |
[]Actor | get_spawned_nodes() |
| bool | is_cell_loaded(cell) |
| bool | is_generated() |
| bool | is_up_to_date() |
| void | move_generated(id, position) |
| void | paint_mask(name, plane, radius, value, strength) |
| void | remove_generated(id) |
| void | set_generated_attribute(id, name, value) |
| void | set_mask(name, image) |
| void | set_override(id, override) |
| void | set_parameter(name, value) |
Signals
Section titled “Signals”cell_generated
Section titled “cell_generated”cell_generated(cell: Vector2i)At runtime, emitted when everything of cell is in the scene.
cell_removed
Section titled “cell_removed”cell_removed(cell: Vector2i)At runtime, emitted when cell was taken away (it was left far).
generated
Section titled “generated”generated()Emitted after it generated and put what it made in the scene.
masks_changed
Section titled “masks_changed”masks_changed()Emitted when a mask changes (masks).
overrides_changed
Section titled “overrides_changed”overrides_changed()Emitted when what was changed by hand changes (overrides).
prefab_removing
Section titled “prefab_removing”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
Section titled “prefab_spawning”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.
Enumerations and constants
Section titled “Enumerations and constants”enum GenerateMode
Section titled “enum GenerateMode”- 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 withgenerate()(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.
Property descriptions
Section titled “Property descriptions”bounds
Section titled “bounds”Rect2 bounds = Rect2(0, 0, 1024, 1024)
Setter/getter: set_bounds(), get_bounds()
Where it generates, in its own coordinates.
cell_size
Section titled “cell_size”float cell_size = 512.0
Setter/getter: set_cell_size(), get_cell_size()
At runtime, the size of each cell it generates.
cleanup_action
Section titled “cleanup_action”Callable cleanup_action = Callable()
Setter/getter: get_cleanup_action()
The Clear button of the inspector.
cleanup_radius_multiplier
Section titled “cleanup_radius_multiplier”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).
generate_action
Section titled “generate_action”Callable generate_action = Callable()
Setter/getter: get_generate_action()
The Generate button of the inspector.
generate_mode
Section titled “generate_mode”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).
generated_data
Section titled “generated_data”[]u8 generated_data = PackedByteArray()
Setter/getter: set_generated_data(), get_generated_data()
What it made, kept with the scene (compressed).
generated_hash
Section titled “generated_hash”int generated_hash = 0
Setter/getter: set_generated_hash(), get_generated_hash()
What get_inputs_hash() was when it made it.
generation_radius
Section titled “generation_radius”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.
managed_tiles
Section titled “managed_tiles”Dictionary managed_tiles = {}
Setter/getter: set_managed_tiles(), get_managed_tiles()
The cells it changed, as they were before, by layer.
mask_texel_size
Section titled “mask_texel_size”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.
overrides
Section titled “overrides”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.
parameters
Section titled “parameters”Dictionary parameters = {}
Setter/getter: set_parameters(), get_parameters()
Values for the graph’s parameters (see ProceduralGraph.bind_parameter()).
preview_in_editor
Section titled “preview_in_editor”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.
spawn_parent
Section titled “spawn_parent”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.
unbounded
Section titled “unbounded”bool unbounded = false
Setter/getter: set_unbounded(), is_unbounded()
At runtime, generates wherever the sources go, without bounds: a world without end.
use_camera
Section titled “use_camera”bool use_camera = true
Setter/getter: set_use_camera(), get_use_camera()
At runtime, the current camera is a source.
use_online_seed
Section titled “use_online_seed”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).
Method descriptions
Section titled “Method descriptions”add_generated
Section titled “add_generated”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.
cleanup
Section titled “cleanup”void cleanup()
Takes away what it made; tiles go back to how they were.
clear_overrides
Section titled “clear_overrides”void clear_overrides()
Takes away every change made by hand.
find_generated
Section titled “find_generated”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.
generate
Section titled “generate”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.
get_cell_at
Section titled “get_cell_at”Vector2i get_cell_at(position: Vector2) const
The cell a position (in its own coordinates) is in.
get_effective_seed
Section titled “get_effective_seed”int get_effective_seed() const
The seed it generates with: seed, mixed with the world’s when use_online_seed is on.
get_inputs_hash
Section titled “get_inputs_hash”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.
get_last_result
Section titled “get_last_result”ProceduralResult get_last_result() const
The result of the last run (empty when what it made came back from the scene without running).
get_last_step_usec
Section titled “get_last_step_usec”int get_last_step_usec() const
At runtime, how long its work took in the last frame, in microseconds.
get_loaded_cells
Section titled “get_loaded_cells”[]Vector2i get_loaded_cells() const
At runtime, the cells it has generated.
get_mask
Section titled “get_mask”Image get_mask(name: StringName) const
The image of the mask name (null when it has none).
get_mask_names
Section titled “get_mask_names”[]String get_mask_names() const
The names of its masks.
get_orphan_overrides
Section titled “get_orphan_overrides”[]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.
get_override
Section titled “get_override”Dictionary get_override(id: int) const
What changed by hand for the thing id (empty when nothing did).
get_pending_cell_count
Section titled “get_pending_cell_count”int get_pending_cell_count() const
At runtime, how many cells within reach are still to generate.
get_pending_job_count
Section titled “get_pending_job_count”int get_pending_job_count() const
At runtime, how many pieces of generated cells are still to put in the scene.
get_reusable_count
Section titled “get_reusable_count”int get_reusable_count() const
How many prefab instances it keeps out of the tree to use again (ProceduralNodeSpawnPrefab.reuse_instances).
get_spawned_id
Section titled “get_spawned_id”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.
get_spawned_nodes
Section titled “get_spawned_nodes”[]Actor get_spawned_nodes() const
Every node it made (prefabs and sprite groups).
is_cell_loaded
Section titled “is_cell_loaded”bool is_cell_loaded(cell: Vector2i) const
At runtime, whether that cell is generated and everything in it is in the scene.
is_generated
Section titled “is_generated”bool is_generated() const
Whether what it made is in the scene.
is_up_to_date
Section titled “is_up_to_date”bool is_up_to_date()
Whether what it made matches what it depends on now.
move_generated
Section titled “move_generated”void move_generated(id: int, position: Vector2)
Puts the thing id at position (in its own coordinates), also every time it generates again.
paint_mask
Section titled “paint_mask”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.
remove_generated
Section titled “remove_generated”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).
set_generated_attribute
Section titled “set_generated_attribute”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).
set_mask
Section titled “set_mask”void set_mask(name: StringName, image: Image)
Sets the mask name (null takes it away) and generates again where it does so by itself.
set_override
Section titled “set_override”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.
set_parameter
Section titled “set_parameter”void set_parameter(name: StringName, value: Variant)
Sets one value of parameters.