Contributing a Generator - awesome-llama/procedural-sandbox GitHub Wiki
All texture generators are defined in the generator.gs
file.
A generator has a broadcast receiver hat named "gen.{GENERATOR_NAME}.run". This is how a generator is run. Typically a button in the user interface will trigger this. This script retrieves the settings from the user interface and then calls the custom block of the same name as the generator.
The custom block first resets the canvas. Typically the lowest layer of voxels is then drawn. This is followed by the rest of the generator's behaviour drawing the other voxels. Finally the generator_finished
custom block is called to indicate it is complete.
Have a look at the existing generators such as "Extruded grid" or "Hedge" if you want practical code examples or something to copy or modify.
A generator is not complete without the user interface. This is set up through the python script UI_creator.py
. This script contains classes for the different interface elements, which are eventually written to various text files representing list items for Scratch. You'll find the IDs for these elements to correspond with the broadcast script of the generator. Again, have a look at the existing generators to learn how to do this.
Simple code example
src/generator.gs
)
Generator (The following code creates a canvas with ground and a single sphere in the center...
on "gen.sphere.run" {
delete UI_return;
setting_from_id "gen.sphere.canvas_size";
setting_from_id "gen.sphere.ground_color";
setting_from_id "gen.sphere.sphere_radius";
setting_from_id "gen.sphere.sphere_color";
generate_sphere UI_return[1], UI_return[2], UI_return[3], UI_return[4];
}
proc generate_sphere canvas_size, ground_color, sphere_radius, sphere_color {
reset_generator $canvas_size, $canvas_size, $sphere_radius*2;
set_depositor_from_number $ground_color;
draw_base_layer;
set_depositor_from_number $sphere_color;
draw_sphere $canvas_size/2, $canvas_size/2, $sphere_radius, $sphere_radius;
generator_finished;
}
gen.sphere.run
is the message sent by the user interface button or invoked by command.UI_return
list temporarily stores the values of the UI elements used by the generator.setting_from_id
retrieves the value of a UI element and adds it to theUI_return
list.generate_sphere
is called using the items in theUI_return
list.reset_generator
initialises the generator with a given canvas size. It should be called exactly once at the start of a generator. If you want to clear the canvas after this (without resetting the generator), useclear_canvas
.set_depositor_from_number
sets the depositor to a color represented as a number.draw_base_layer
draws a 1 voxel thick floor along the lowest Z coordinate, using the depositor.draw_sphere
draws a sphere using the depositor.generator_finished
must be called at the end of the generator. You may treat it as a "black box"; you do not need to know what it does. (though as of writing, it resets the camera)
src/UI/UI_creator.py
)
UI (panels['menu.gen'] = Container([
Label.title('Generate'),
Separator(),
# (other buttons omitted for readability)
btn_menu_set_page('Sphere', 'gen.sphere'),
# (other buttons omitted for readability)
])
panels['gen.sphere'] = Container([
Label.title('Sphere'),
Separator(),
Expander('Canvas', '', True, [
Value.canvas_size('Canvas size', 'gen.sphere.canvas_size', 64),
Color('Ground color', 'gen.sphere.ground_col', '#aaaaaa'),
]),
Expander('Sphere', '', True, [
Value('Sphere radius', 'gen.sphere.sphere_radius', 4, 1, 16, 0, 256, snap_frac=1),
Color('Sphere color', 'gen.sphere.sphere_color', '#00ff00'),
]),
Button('Generate', 'gen.sphere.run'),
])
- The side bar as you see it only shows one "panel" (or "page") at a time. To display UI elements on a page, use a
Container
element and add it to thepanels
dictionary. The panel that lists all the generator buttons is under the keymenu.gen
. In the example,gen.sphere
is the page with the settings related to the sphere generator.