Top

Secret Chronicles of the Scripting API documentation

Class MovingSprite

Parent: Sprite

Everything that is moving on the screen is considered by TSC to be a MovingSprite. It is the superclass of most on-screen objects and as such the methods defined here are available to most other objects, e.g. the LevelPlayer or enemies.

This class may not be instanciated directly.

Acceleration and velocity

I hope you didn’t sleep in your physics lessons, because you will need your knowledge now. Remember: Velocity is not the same as acceleration. Velocity means you are currently moving along a given path in a given time. You may for example be moving in your car at 130 km/h, i.e. in average your car makes 130 kilometres in one hour. Acceleration is the process of altering the velocity, either positively or negatively. For example, if you have to brake, your velocity gets reduced. This is an acceleration.

This difference gets really important when you calculate the distance actually passed by a moving object. The first formula below calculates that distance from a constantly moving, non-accelerating object, whereas the second formula assumes a constant acceleration.

s = v * t
s = (1/2)at²

The next thing to know is that you don’t have constant acceleration in TSC. Calling methods like #accelerate! give them a one-time acceleration, just as if you throw something up into the air. While it continues to move upwards after it left your hand, you don’t further accelerate it while it flies. But the gravity does — and does so constantly, always, first eating up the velocity you accelerated the object to, then bringing it to a halt (v = 0), and finally accelerating it in the other direction, i.e. towards the earth’s gravity centre.

Keep this in mind when you call the methods on this class. Accelerating something doesn’t mean to put it at a specific velocity, but rather to add a delta value to its current velocity. TSC however allows you to cheat physics — rather than having to compute the acceleration you need to get an object to a desired velocity you can do magic and call one of the velocity= methods, which skip the acceleration step and directly assign a velocity to an object (no, you can’t do this in reality). After this however, the gravity and other overall forces still apply to the now moving object, deaccelerating and finally stopping it.

I’m too lazy at the moment, but it should be possible to look up the value for g TSC uses and provide a formula that takes the constant negative acceleration it causes into account. The same could be done for the horizontal resistances, finally emitting a formula that allows you to exactly calculate how a once-accelerated object behaves. If you calculate such a formula, please add it in place of this text to the documentation.

Directions

A moving sprite always has one or more directions it is "looking" into. While which directions are valid depends on the exact sprite being in use (e.g. a gee can’t have :left, or :right, but only :horizontal and :vertical), the common method to set these directions is #direction= defined in this class.

As with "bare" sprites and coordinates, moving sprites have two attributes for directions: The normal, current direction; and the "initial direction", which specifys the looking direction at object creation time. Again, most sprites do not care about the initial directions, but those who do are really picky about it. If you try to only specify the current direction for Rokko, but not the initial one, he will just continue looking into the default direction (which is left). If you even activate him in this state, he is flying backwards!

Again as with "bare" sprites, setting the initial direction via the #start_direction= method also sets the current direction, so you most likely don’t need both at once (unless you really want the backward-flying rokko).

Instance Methods

accelerate!

accelerate!( xadd, yadd )

Add to both the horizontal and the vertical velocity at once.

Parameters

xadd

What to add to the horizontal velocity. May include fractions.

yadd

What to add to the vertical velocity. May include fractions.

accelerate_x!

accelerate_x!( val )

Add to the current horizontal velocity.

Parameter

val

The value to add. May include fractions.

accelerate_y!

accelerate_y!( val )

Add to the current vertical velocity.

Parameter

val

The value to add. May include fractions.

direction

direction() → a_symbol

The direction the sprite is "looking" in as a symbol.

Return value

This method may return one of the following, self-explanatory symbols:

:undefined
:left
:right
:up
:down
:up_left
:up_right
:down_left
:down_right
:left_up
:left_down
:horizontal
:vertical
:all
:first
:last

Not all of them are supported by all moving sprites (most only support :left and :right), but usually you can guess which ones are supported by looking at the images a sprite may use. The last five directions are a bit special, namely :horizontal, :vertical and :all may be returned for objects which support "looking" into more than one direction (e.g. a static enemy may return :all), and :first and :last can only be returned by waypoints on the world map, where scripting isn’t supported yet.

direction=

set_direction=( dir )

Set the "looking" direction of the sprite.

Parameter

dir

One of the looking directions supported by this sprite. See #direction for a list of possible symbols.

downgrade

downgrade()

Simulates a hit on this object, downgrading it to the next weaker state. If there is no weaker state, the object dies.

max_gravity

max_gravity() → a_float

Returns the maximum possible velocity gravity may accelerate this object to.

max_gravity=

max_gravity=( val )

Specify the maximum gravity that will be applied to this object. Setting this to 0 will exempt it from gravity, i.e. it will just stay whereever it currently is and not fall down.

Parameters

val

The new maximum gravity.

reset_on_ground

reset_on_ground()

Re-check there's a ground object below this object. If there is none, the object will start falling if it is subject to gravity. Otherwise, nothing happens.

You'll need this method if you made the ground below an object disappear, e.g. if you removed a block below Alex' feet. If you don't call this method, then the lost ground will first be noticed when the object moves the next time.

start_direction

start_direction() → a_symbol

Returns the "initial" looking direction of this sprite. Return values are as per #direction.

start_direction=

start_direction=( dir ) → dir

Like #direction=, but also sets the "initial" looking direction of the sprite. This is e.g. used by Rokko.

turn_around

turn_around()

Make this object turn around and continue moving into the opposite direction.

velocity

velocity  () → [a_float, another_float]

Returns the current horizontal and vertical velocity as a two-element array of form [xvel, yvel]; both values may include fractions.

velocity=

velocity= ( \[ xvel, yvel \] )

Set both the horizontal and vertical velocity at once.

Parameters

xvel

The new horizontal velocity. May include fractions.

yvel

The new vertical velocity. May include fractions.

Example

# Make an object moving very fast towards
# the top-right corner.
UIDS[12].velocity = [200, -200]

velocity_x

velocity_x() → a_float

Returns the current horizontal velocity; the return value may include fractions.

velocity_x=

velocity_x= ( xvel )

Set the horizontal velocity.

Parameter

xvel

The new velocity. May include fractions.

velocity_y

velocity_y() → a_float

Returns the current vertical velocity; the return value may include fractions.

velocity_y=

velocity_y= ( yvel )

Set the vertical velocity.

Parameter

yvel

The new velocity. May include fractions.