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.