Graphics and the Display List - VectorPanic/rune-sdk GitHub Wiki

Rune organizes graphics through a display list: a hierarchy of visual objects that belong to a scene. You build the scene by adding images, sprites, text and containers, then let Rune update and render them.

This approach will feel familiar if you have worked with Flash or ActionScript 3.

The Stage

Every scene has a stage. It is the root of the scene’s display list and contains the visual objects that make up the scene.

To display an object, add it to the stage:

this.stage.addChild(this.background);

A typical display list might look like this:

Stage
├── Background
├── Player
├── Enemies
└── Interface
    ├── Score
    └── Health

The stage holds the scene’s content. Cameras determine which part of that content appears on screen.

Choosing a Graphics Class

Rune provides several classes for different kinds of visual content:

Class	Purpose
rune.display.Graphic	Display a static texture.
rune.display.Sprite	Display a texture with frame-based animation.
rune.display.RepeatedGraphic	Display a repeating texture, such as a scrolling background.
rune.display.TileGraphic	Display a smaller tile-based graphic within the display list.
rune.display.DisplayObjectContainer	Group display objects into a hierarchy.

Choose the simplest class that fits the object. A background image can use Graphic, while an animated character can use Sprite.

Displaying an Image

Before displaying an image, register and load it through the resource system. Once loaded, you refer to its texture by its resource identifier.

The following example assumes that the project has loaded a texture named game_background:

game.scene.Play.prototype.init = function() {
    rune.scene.Scene.prototype.init.call(this);

    this.background = new rune.display.Graphic(
        0,
        0,
        320,
        180,
        "game_background"
    );

    this.stage.addChild(this.background);
};

The arguments describe the object’s position, dimensions and texture identifier.

Adding the graphic to the stage makes it part of the scene’s display list.

Positioning Objects

Display objects expose properties that control their position and appearance. For example, you can move an object by changing its coordinates:

this.player.x = 100;
this.player.y = 60;

You can also change coordinates during the scene’s update:

game.scene.Play.prototype.update = function(step) {
    rune.scene.Scene.prototype.update.call(this, step);

    if (this.keyboard.pressed("RIGHT")) {
        this.player.x += 100 * (step / 1000);
    }
};

Here, the player moves at 100 pixels per second while the right arrow key is held.

Rune renders the object at its updated position. You do not need to draw the texture manually each frame.

Organizing Layers

The display list also determines how graphics overlap. For a simple scene, add the background before objects that should appear in front of it:

this.stage.addChild(this.background);
this.stage.addChild(this.player);
this.stage.addChild(this.interface);

Thinking in layers makes the scene easier to build:

• Background: scenery behind the action.
• World objects: characters, enemies and interactive objects.
• Interface: information such as score and health.

As the scene grows, containers can help keep these groups organized.

Grouping Objects with Containers

A container lets you organize related display objects under a common parent.

For example, a character might consist of a body, a weapon and a visual effect. A menu might contain several buttons and labels.

Stage
└── Character
    ├── Body
    ├── Weapon
    └── Effect

This hierarchy gives related objects a clear place in the display list. It also lets you build reusable visual components instead of placing every object directly on the stage.

For larger projects, create your own classes that extend Rune’s display classes and manage their visual parts internally.

Creating a Repeating Background

RepeatedGraphic is useful for textures that repeat across an area.

This example assumes that game_background_pattern has already been loaded:

this.background = new rune.display.RepeatedGraphic(
    0,
    0,
    320,
    180,
    "game_background_pattern"
);

this.stage.addChild(this.background);

Change its texture offset to create a scrolling effect:

game.scene.Play.prototype.update = function(step) {
    rune.scene.Scene.prototype.update.call(this, step);

    this.background.offsetX += 20 * (step / 1000);
};

The graphic stays in place while its texture scrolls horizontally.

Display Objects and Cameras

Adding an object to the stage places it in the scene. Whether it is visible on screen also depends on the camera.

A camera can show a portion of a larger world, move through the scene or zoom in and out. Multiple cameras can show different views of the same scene.

Keep these responsibilities separate:

• Display objects describe the visual content.
• The display list organizes that content.
• Cameras determine the view.

Removing Objects

When an object should leave the scene, remove it from its parent’s display list.

If it is no longer needed, use the appropriate disposal option to release its resources as well. Removing an object for later reuse and destroying it permanently are different operations.

When a scene is disposed, Rune’s scene implementation also disposes its stage. Always call the base implementation when overriding the scene’s dispose() method.