Top

Secret Chronicles of the Scripting API documentation

Class LevelPlayer

Parent: MovingSprite

The sole instance of this class, the singleton Player, represents Alex himself. Naturally you can’t instanciate this class (TSC isn’t a multiplayer game), but otherwise this class is your interface to doing all kinds of evil things with Alex. You should, however, be careful, because the powerful methods exposed by this class allow you to control nearly every aspect of Alex--if you exaggerate, the player will get annoyed, probably stopping to play your level.

This class’ documentation uses two words that you’re better off not mixing up:

Alex (or just "the level player")

The sprite of Alex walking around and jumping on enemies.

Player

The actual user sitting in front of some kind of monitor. Don’t confuse him with Alex, because a) he will probably get angry, and b) you’ll get funny meanings on sentences like "the player presses the jump key". The only exception to this rule is the Player constant in Mruby, which obviously represents Alex, not the guy playing the game.

Note that the level player is just a normal sprite all its way up through the class hierarchy. So be sure to check the superclasses’ methods if you don’t find what you’re looking for here.

Events

Die

This event gets fired immediately before Alex is killed by the the game logic. If you call #veto_death from this event handler, the player will not die, but note it is your responsibility to ensure something useful happens. Especially note that Alex would fall down eternally if he dies on the level lower edge and you veto the death (you can check for this using the position information of the player). This event is not emitted when Omega mode or invincibility rescues Alex.

Downgrade

Whenever Alex gets hit (but not killed), this event is triggered. The event handler gets passed Alex’s current downgrade count (which is always 1) and Alex’s maximum downgrade count (which is always 2). As you can see, the arguments passed are not really useful and are just there for symmetry with some enemies’ Downgrade event handlers.

Jewel_100

After Alex has collected 100 jewels, this event is triggered. The event handler isn’t passed anything, but note that it is highly discouraged to alter Alex’s amount of jewels from within the event handler; this may lead to unexpected behaviour such as Alex having more than 100 jewels after all operations regarding the amount of jewels have finished or even endless loops as altering the jewel amount may cause subsequent events of this type to be triggered.

Jump

This event is issued when the Alex does a valid jump, i.e. the player presses the Jump key and Alex is currently in a state that actually allows him to jump. The event is triggered immediately before starting the jump.

Shoot

Fired when Alex executes a valid shoot, either fireball or iceball. As with the Jump event, this is only triggered when the player presses the Shoot key and Alex is currently in a state that allows him to shoot. Likewise, the event is triggered just prior to the actual shot. The event handler gets passed either the string "ice" when the player fired an iceball, or "fire" when it was a fireball.

Instance Methods

add_jewels

add_jewels(num)    → an_integer

Add to the player’s current amount of jewels. If the number of jewels passes 100, a Jewel_100 event is triggered.

Parameter

num

The number of jewels to add. If Alex’s resulting amount of jewels (i.e. the current amount plus num) is greater than 99, Alex gains a life and 100 is subtracted from the resulting amount. This process is repeated until the total resulting amount of jewels is not greater than 99.

Return value

The new amount of jewels (after the 100-rule described above has been applied as often as necessary).

add_lives

add_lives( lives ) → an_integer

Add to the player’s current number of lives.

Parameter

lives

The lives to add. This number may be negative, but note that setting lives to 0 or less doesn’t kill the player immediately as this number is only checked when the player gets killed by some other force.

Return value

The number of lives Alex now has.

add_points

add_points( points ) → an_integer

Adds more points to the amount of points the player already has.

Parameter

points

The number of points to add.

Return value

The new number of points.

get_points

points() → an_integer

Returns the number of points the player currently has.

jewels

jewels() → an_integer

The current amount of jewels Alex has collected so far. This is always smaller than 100.

jewels=

jewels=(num)

Reset the number of collected jewels to the given value. If you set a value greater than 100, a Jewel_100 event is triggered.

Parameter

num

The new number of jewels. This value obeys the same 100-rule as the parameter to #add_jewels.

jump

jump( [ deaccel ] )

Makes Alex jump.

Parameter

deaccel

Negative acceleration to apply, i.e. defines how high Alex will jump. Note that this isn’t necessarily the height in pixels as the force of gravity will be applied to the value while jumping.

kill

kill()

Forcibly kill the level player. This method kills Alex regardless of being big, fire, etc, but still honours star and other invincibility effects. If you urgently want to kill Alex despite of those, use #kill!.

kill!

kill!()

Like #kill, but also ignore any invincibility status that Alex may be in. That is, even kill Alex if he has just been hurt and is thus invincible or despite star being in effect.

lives

lives() → an_integer

Returns the number of lives the player has. Note this may be zero.

lives=

lives=(lives)

Reset Alex’s number of lives to the given value.

Parameter

lives

The new number of lives. This number may be negative, but note that setting lives to 0 or less doesn’t kill the player immediately as this number is only checked when the player gets killed by some other force.

release_item

release_item()

If Alex currently carries something (shell), he will drop it. Otherwise does nothing.

set_points

points=(points)

Reset the player’s points to the given value. You probably don’t want to do this.

type

type() → a_symbol or nil

Returns Alex’s current type. See #type= for a list of possible symbols to be returned. Returns nil if Alex’s state can’t be detected for some reason (and prints a warning on stderr).

type=

type=(type)

Forcibly applies a powerup/powerdown to the level player. Note this method bypasses any Alex state checks, i.e. you can directly apply :ice to small Alex or force Fire Alex back to Normal Big Alex by applying :big. This check bypassing is the reason why you shouldn’t use this method for downgrading or killing the player; there might however be situations in which calling this method is more appropriate.

Using this method never affects the rescue item (that one shown on top of the screen in the box).

Parameter

type

The powerup or powerdown to apply. One of the following symbols:

C<:dead>

Please use the #kill method instead.

C<:small>

Please use the #downgrade method instead.

C<:big>

Apply the normal mushroom.

C<:fire>

Apply the fireplant.

C<:ice>

Apply the ice mushroom.

C<:ghost>

Apply the ghost mushroom.

Specifying an invalid type causes an error.

veto_death

veto_death()

This method is only useful to call inside a Die event handler, in which case it causes the game to not kill Alex although all logical conditions for killing him are fulfilled. The veto only affects this one death case the event was emitted for.

Calling this method outside of the Die event handler has no effect.