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

Generator (src/generator.gs)

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 the UI_return list.
• generate_sphere is called using the items in the UI_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), use clear_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)

UI (src/UI/UI_creator.py)

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 the panels dictionary. The panel that lists all the generator buttons is under the key menu.gen. In the example, gen.sphere is the page with the settings related to the sphere generator.