Layers

From OrbEdit Wiki

Layers Overview

Each Level in Orb is comprised of 1 - 32 Layers. A Layer contains a single WorldSpace and has several properties that determine how that WorldSpace will be rendered. Layers are arranged into a Layer Stack, or more commonly referred to as a World or Level. All Layers in a Level are drawn in order, meaning Elements in Layer 0 will appear behind Elements in Layer 1 and so on. Generally you will only need 4 or 5 Layers for a Level, but there are plenty more should you need them.

Since each Layer its own WorldSpace, they can each have a different amount of Gravity, Damping, and so on. As such, Elements in different Layers cannot interact with each other.

A good general strategy for Layers is:

• Layer 0: Background, contains mostly Sprites and non-interactive Elements. This is the scenery for your game that is not meant to be interacted with.
• Layer 1: Foreground, where all the action happens. This Layer should contain your player, enemies, buildings, and all other Elements your player might interact with.
• Layer 2: Menu Layer, contains all menus for your game. This Layer should be fixed, that is, resolution-independent, and above your gameplay Layers.
• Layer 3: Special Effects Layer, in which you render your game's special effects. These can be rendered in the Foreground as well, but it is often convenient to separate them into their own Layer to ensure they don't interfere with actual gameplay.
• Layer 4: Overlay, for screen fades and additional text. This Layer is on top of everything else and should be covered with a large Sprite which can be faded in and out for a nice transition effect between your levels.

Layer organization for your game is entirely up to you, but it is highly recommended you start here.

Layer Behavior

Layers have several properties that control how they are rendered:

• Parallax: Controls the scrolling speed of the Layer. As the Renderer's camera pans around the World, each Layer is shifted by the percentage specified by its Parallax value. The default value is 1.0, meaning the Layer will move at the same rate as the camera. However, if the value is set to less than 1.0, the Layer will appear to scroll "slower". Parallax is used to give the perception of depth to your 2D backgrounds, as in real life, objects further away seem to move slower than closer objects. To strengthen the depth effect, you can use multiple background Layers, each with a slightly smaller parallax value.
• ZoomRatio: Similar to Parallax, ZoomRatio controls the zooming speed of the Layer. As the Renderer zooms in and out on the World, each Layer is zoomed by the percentage specified by its ZoomRatio value. For example, if the Renderer zooms in by a factor of 4 and LayerA has a ZoomRatio of 0.5, LayerA's magnification will only increase by a factor of 2. ZoomRatio is meant to further the effects of depth; objects at different distances do not scale by the same amount as the viewer gets closer or further away from them.
• Locked: Similar to Elements, Layers can also be locked. No Elements in a locked Layer can be clicked on and no new Elements can be added to a locked Layer through OrbEdit. Generally you will want to lock all Layers that you are not working on so you don't accidentally modify them.
• Visible: Just like Elements, Layers can also be set visible or invisible. No Elements within an invisible Layer are drawn. Making a Layer invisible is just another way to help focus on the single Layer you are building.

Working with Layers

OrbEdit makes using Layers fairly easy. From the Layers View, you are able to create new Layers, move them around, load them, and delete them. Each Layer is represented as a row in this view, with the Active Layer shaded purple. You can set a Layer's visibility and locked state by clicking on the eye icon and padlock icon respectively. In the diagram to the left, the Menu Layer is locked and the Special Effects Layer is invisible.

Active Layer

Clicking on a Layer row in the Layers View will set that Layer active. The Active Layer is the Layer to which all Elements are added when you select any of the options from OrbEdit's Add Menu. You can access the ID of the Active Layer through the oe.ActiveLayerId variable.

Shared Layers

Layers are usually stored in the Level file itself ( .olvl). However, Layers can also be shared, meaning they are loaded by multiple Levels. If this is the case, they are stored in their own .olay file, which is then referenced from .olvl files. This allows, for example, the same menu Layer to be attached to every Level in your game, without any duplication of the Layer information.

In the diagram to the left, the Menu Layer is a shared Layer. Below the name of a Shared Layer will be the name of an .olay file, which is the file in which that Layer's contents will be saved when you save the Level. You can make a Layer shared or unshared by right-clicking on the Layer row and checking or unchecking "Shared Layer".

You can find out more about the Layers View in the OrbEdit Overview.

Scripting Layers

All Layers are stored in a special table named orb.Layers. You can index this table just like you would index any Lua table to get the Layer you want. Orb also provides several functions for adding and removing Layers, which are covered in more detail in the API.

• orb.addLayer(layer, index): Adds the new Layer layer into the World at index index, shifting up existing Layers if necessary. If no index is given, the new Layer will be placed on top of all existing Layers.
• orb.removeLayer(index): Removes the Layer at the specified index from the World.
• orb.replaceLayer(layer, index): Replaces the Layer at the index index with the new Layer layer.
• orb.clearLayers(): Removes all Layers from the World.

An example of using these functions and accessing their results:

-- First clear any Layers that might exist
orb.clearLayers();
 
-- Create a new Layer
local layer = Layer:new();
 
-- Set the gravity of the new Layer's WorldSpace to 200
layer:getWorldSpace():setGravity(200);
 
-- Add the new Layer to the World
orb.addLayer(layer);
 
-- Now print the gravity value set above, via the orb.Layers table
print(orb.Layers[1]:getWorldSpace():getGravity());      -- Prints "200"