Skip to content

Scroller Guide

Jump to bottom
Mike Lilligreen edited this page Aug 12, 2013 · 1 revision

Introduction

All scene objects are known engine types that allow instances to be created at runtime. The "Scroller" is slightly different from other game type classes. It is derived from a parent type called "SpriteBase", which itself is derived from "SceneObject". That means it includes all the fields from those types as well as adding its own fields specific to itself.

A Scroller is a sprite-like object that allows you to take a static image and allow it to automatically scroll in both the vertical and horizontal directions. Since the actual image rendering properties are inherited from SpriteBase and all collision and physics properties from SceneObject, there are only a small number of fields and methods that belong to the Scroller itself.

TorqueScript Bindings

Exposed Fields

The Scroller type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

  • RepeatX
  • setRepeatX(float)
  • getRepeatX()
  • RepeatY
  • setRepeatY(float)
  • getRepeatY()
  • ScrollX
  • setScrollX(float)
  • getScrollX()
  • ScrollY
  • setScrollY(float)
  • getScrollY()
  • ScrollPositionX
  • setScrollPositionX(float)
  • getScrollPositionX()
  • ScrollPositionY
  • setScrollPositionY(float)
  • getScrollPositionY()

The following is a complete description of each of these fields.

RepeatX (float)

Sets the number of times to repeat the image texture over the X direction. Normally with a Sprite, the entire image texture or frame is displayed within the specified size of the object. With a Scroller, you can display less or more of the static image over the its width by using this field.

%object = new Scroller();
%object.RepeatX = 0.5;

Depending on the size of the scroller object, the screen resolution and the image size, you can squish or stretch an image along the X axis this way.

RepeatY (float)

Sets the number of times to repeat the image texture over the Y direction. Normally with a Sprite, the entire image texture or frame is displayed within the specified size of the object. With a Scroller, you can display less or more of the static image over the its height by using this field. Depending on the size of the scroller object, the screen resolution and the image size, you can squish or stretch an image this way.

%object.RepeatY = 0.5;

Depending on the size of the scroller object, the screen resolution and the image size, you can squish or stretch an image along the Y axis this way.

ScrollX (float)

This field sets the scroll speed in the X direction. A positive number will scroll the texture from right to left, a negative number from left to right.

%object.ScrollX = 10;

ScrollY (float)

This field sets the scroll speed in the Y direction. A positive number will scroll the texture from top to bottom, a negative number from bottom to top.

%object.ScrollY = -10;

ScrollPositionX (float)

With this property, you can alter the texture's position in the X direction. Values must be specified between 0.0 and 1.0 and are relative to the image size. A value of 0.5 would shift the texture's position by half the image size, for example.

%object.ScrollPositionX = 0.4;

ScrollPositionY (float)

With this property, you can alter the texture's position in the Y direction. Values must be specified between 0.0 and 1.0 and are relative to the image size. A value of 0.5 would shift the texture's position by half the image size, for example.

%object.ScrollPositionY = 0.7;

TAML Format

Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure a Scroller. You can then export this type to a TAML file or even create a TAML file manually and read it into your game at an appropriate time.

Here is an example Scroller TAML file in XML format:

<Scroller
    SceneLayer="31"
    Size="100 75"
    Position="0 -10"
    FixedAngle="1"
    BodyType="Static"
    Image="@asset=ToyAssets:treeBackground1"
    Frame="0"
    repeatX="0.5"
    scrollX="-5"
    scrollPositionX="0.5" />

The same example in JSON format:

{
    "Scroller": {
        "SceneLayer": "31",
        "Size": "100 75",
        "Position": "0 -10",
        "FixedAngle": "1",
        "BodyType": "Static",
        "Image": "@asset=ToyAssets:treeBackground1",
        "Frame": "0",
        "repeatX": "0.5",
        "scrollX": "-5",
        "scrollPositionX": "0.5"
    }
}

Additional API

The following methods are available to further configure and control a Scroller.

setRepeat (float X, float Y)

This method allows you to set both the RepeatX and RepeatY values at once.

setScroll (float X, float Y)

Sets the scroll speed for both X and Y components of the vector.

setScrollPolar (float angle, float scrollSpeed)

Sets the scroll speed using polar coordinates. The angle is specified in degrees.

setScrollPosition (float X, float Y)

With this method you can change the texture's position in both the X and Y direction at once. Values must be specified between 0.0 and 1.0 and are relative to the image size. A value of 0.5 would shift the texture's position by half the image size, for example.

Clone this wiki locally