gre.screen_attach_layer(
    layer_name, 
    [zindex]
)
gre.screen_attach_layer(
    layer_name, 
    screen_list, 
    [zindex]
)
            

Attaches a layer to a screen dynamically creating a new layer instance. When used without a screen list this will attach the specified layer to all screens in the application. When used with a list of screens it will bind the specified layer to all of the screens named in the screen list.

If zindex is included, then the layer will be inserted at the specified zindex (0 = backmost). If zindex is not set, then the layer will be inserted at the top of the existing layer stack for the screen (equivalent to specifying a value greater than all of the layers in the project).

If the layer is already present on a screen, then that layers position in the screen z-order will be adjusted to the specified value. If the layer name used is a specific layer instance (ie screen_name.layer_name) then all of the properties of that layer instance (x, y, alpha, hidden) will also be copied to the new layer instance.