Player

The Player object is used to control a specific player/character. Player objects are tagged player.

Note: in Open Surge, companion objects can be used to give new abilities to players. Companion objects must be indicated in the character definition files (.chr) and are implemented as regular scripts. The engine will automatically spawn the companions as children of the appropriate Player objects.

Example

object "Display player name" is "companion"
{
    player = parent; // since this object is configured as a
                     // companion, parent is the reference
                     // to the appropriate Player object

    state "main"
    {
        Console.print("I am a companion of " + player.name);
    }
}

Global

Player

Player(playerName)

Gets the Player object associated with a character in the level. If a player with the specified name doesn't exist in the level, there will be an error.

See also: exists.

Arguments

• playerName: string. The name of a character, as defined in a .chr file stored in the characters/ folder.

Returns

A Player object.

Example

using SurgeEngine.Player;

// Gives Surge 1 collectible each second
// Just place it in your level
object "Collectible Giver" is "entity", "awake"
{
    player = Player("Surge");

    state "main"
    {
        if(timeout(1))
            state = "give collectible";
    }

    state "give collectible"
    {
        player.collectibles = player.collectibles + 1;
        state = "main";
    }
}

Player.get

Player[i]

Gets a Player object by its sequence number, as defined in the players entry of the level file.

See also: count.

Arguments

• i: number. An integer between 0 and Player.count - 1, inclusive.

Returns

A Player object.

Player.exists

Player.exists(playerName)

Checks if a player named playerName exists in the level.

Arguments

• playerName: string. The name of a character.

Returns

Returns true if such a player exists in the level.

Player.active

Player.active: Player object.

The player currently in focus.

See also: focus, hasFocus, focusable.

Example

using SurgeEngine.Player;

// Tells the name of the active player
// Just place it in the level
object "Who am I" is "entity", "awake"
{
    state "main"
    {
        player = Player.active;
        Console.print("I am " + player.name);
        destroy();
    }
}

Player.count

Player.count: number, read-only.

The number of players in the level.

Player.initialLives

Player.initialLives: number, read-only.

The initial number of lives set by the engine.

Properties

id

id: number, read-only.

A number that uniquely identifies the player in the Level.

See also: name.

Available since: Open Surge 0.6.1

name

name: string, read-only.

The name of the character.

See also: id.

direction

direction: number, read-only.

This number will be +1 if the player is facing right, or -1 if facing left.

See also: hflip.

Example

// let's check if the player is facing right or left
isFacingRight = (player.direction > 0);
isFacingLeft = (player.direction < 0);

input

input: Input object, read-only.

Reference to the Input object of the Player.

Example

using SurgeEngine.Player;

object "Application"
{
    state "main"
    {
        player = Player.active;

        if(player.input.buttonDown("right"))
            Console.print("Player is holding right");
    }
}

animation

animation: Animation object, read-only.

Reference to the Animation object of the Player.

See also: anim.

anim

anim: number.

A shortcut to animation.id: an integer corresponding to the current animation number.

See also: animation, id.

anchor

anchor: Vector2 object.

A shortcut to animation.anchor.

See also: anchor.

Available since: Open Surge 0.6.0

hotSpot

hotSpot: Vector2 object.

A shortcut to animation.hotSpot.

See also: hotSpot.

Available since: Open Surge 0.6.0.

Note: in versions prior to 0.6.0, you may get the hot spot using the Animation object.

actionSpot

actionSpot: Vector2 object.

A shortcut to animation.actionSpot.

See also: actionSpot.

Available since: Open Surge 0.6.0

actionOffset

actionOffset: Vector2 object, read-only.

A shortcut to animation.actionOffset.

See also: actionOffset.

Available since: Open Surge 0.6.0

attacking

attacking: boolean, read-only.

Is the player attacking, i.e., jumping, rolling, charging or invincible? This flag will be modified if the player is aggressive or inoffensive.

See also: aggressive, inoffensive.

midair

midair: boolean, read-only.

Is the player midair?

stopped

stopped: boolean, read-only.

Is the player stopped?

walking

walking: boolean, read-only.

Is the player walking?

running

running: boolean, read-only.

Is the player running?

jumping

jumping: boolean, read-only.

Is the player jumping?

springing

springing: boolean, read-only.

Is the player playing the "springing" animation, displayed just after hitting a spring?

braking

braking: boolean, read-only.

Is the player braking?

balancing

balancing: boolean, read-only.

Is the player balancing on a ledge?

waiting

waiting: boolean, read-only.

Is the player waiting? (happens after remaining stopped for a few seconds)

rolling

rolling: boolean, read-only.

Is the player rolling?

charging

charging: boolean, read-only.

Is the player charging a rolling movement?

pushing

pushing: boolean, read-only.

Is the player pushing a wall?

hit

hit: boolean, read-only.

Is the player getting hit (i.e., losing collectibles or a shield)?

See also: getHit.

blinking

blinking: boolean, read-only.

Is the player blinking? (happens just after getting hit)

dying

dying: boolean, read-only.

Is the player dying or drowning?

drowning

drowning: boolean, read-only.

Is the player drowning (i.e., dying underwater)?

See also: underwater, dying.

breathing

breathing: boolean, read-only.

Is the player breathing an air bubble that is underwater?

See also: underwater, breathTime.

crouchingDown

crouchingDown: boolean, read-only.

Is the player crouching down?

lookingUp

lookingUp: boolean, read-only.

Is the player looking up?

winning

winning: boolean, read-only.

Is the player displaying the "winning" animation (after clearing a level)?

underwater

underwater: boolean, read-only.

Is the player underwater? Players are considered to be underwater if they are below the water level or if their forciblyUnderwater flag is set to true.

See also: secondsToDrown, drowning, breathing, breathTime, forciblyUnderwater, forciblyOutOfWater, waterlevel.

secondsToDrown

secondsToDrown: number, read-only.

The number of seconds to drown, if underwater.

See also: underwater, drowning, breathTime.

topspeed

topspeed: number, read-only.

The maximum speed that the player can reach when running naturally, without rolling and with no external forces applied. Given in pixels per second.

See also: capspeed.

capspeed

capspeed: number, read-only.

The maximum speed that the player can reach by normal means (e.g., rolling downhill), not considering external forces. Given in pixels per second.

See also: topspeed.

Available since: Open Surge 0.6.1

hlockTime

hlockTime: number, read-only.

The time, in seconds, in which the player will not respond to horizontal input when on the ground. Defaults to zero.

See also: hlock.

Available since: Open Surge 0.6.1

transform

transform: Transform object, read-only.

The transform of the Player.

collider

collider: Collider object, read-only.

A collider associated with this Player.

shield

shield: string | null.

One of the following: "shield", "fire", "thunder", "water", "acid", "wind" or null (if there is no shield).

See also: invulnerable.

invincible

invincible: boolean.

Used to make the player invincible. Defaults to false.

turbo

turbo: boolean.

Turbocharged mode (increases player speed). Defaults to false.

frozen

frozen: boolean.

Disable/enable player movement. Defaults to false.

aggressive

aggressive: boolean.

If set to true, the attacking flag will be true regardless of the state of the player. The player will be able to hit the baddies just by touching them. Defaults to false.

See also: attacking, inoffensive.

Available since: Open Surge 0.5.1

inoffensive

inoffensive: boolean.

If set to true, the attacking flag will be false regardless of the state of the player. The player will be vulnerable to damage even if jumping, rolling or charging. Defaults to false.

Note: if the player is simultaneously aggressive and inoffensive, the aggressive behavior prevails.

See also: attacking, aggressive.

Available since: Open Surge 0.6.1

invulnerable

invulnerable: boolean.

If set to true, the player will be invulnerable to damage. It's like having an invisible shield that is permanent. The player may still be killed if crushed, by falling into a pit, by drowning, or by calling kill.

Available since: Open Surge 0.6.1

immortal

immortal: boolean.

If an immortal player appears to be killed, it will appear to be ressurrected on its spawn point without losing a life.

See also: lives.

Available since: Open Surge 0.6.1

secondary

secondary: boolean.

A secondary player plays a secondary role and interacts with items in different ways. It cannot smash item boxes, activate goal signs, etc. This flag is best used with AI-controlled players. Defaults to false.

Available since: Open Surge 0.6.1

focusable

focusable: boolean.

A focusable player can receive focus. Defaults to true.

See also: focus, hasFocus, Player.active.

Available since: Open Surge 0.6.1

Note: if only a single player exists in the level, then that player will have focus regardless of the value of this flag.

breathTime

breathTime: number.

The maximum number of seconds the player can remain underwater without breathing.

See also: underwater, secondsToDrown.

forciblyUnderwater

forciblyUnderwater: boolean.

If set to true, the underwater flag will be true regardless of the water level. If set to false, the underwater flag will be true only if the player is below the water level. Defaults to false.

See also: underwater, waterlevel, forciblyOutOfWater.

Available since: Open Surge 0.6.1

forciblyOutOfWater

If set to true, the underwater mechanics will be disabled, even if the player is below the water level. If forciblyUnderwater is also true, this flag will do nothing. Defaults to false.

See also: underwater, waterlevel, forciblyUnderwater.

Available since: Open Surge 0.6.1

layer

layer: string.

The current layer of the player. One of the following: "green", "yellow", "default". This property tells you which bricks will be sensed, depending on their layer.

visible

visible: boolean.

Should the player sprite be rendered? Defaults to true.

collectibles

collectibles: number.

The number of collectibles, an integer shared between all player objects.

lives

lives: number.

The number of lives, an integer shared between all player objects.

score

score: number.

The score of the player, an integer value shared between all player objects.

speed

speed: number.

The speed of the player, in pixels per second. This will be mapped automatically to gsp or xsp, depending on whether the player is touching the ground or not.

See also: gsp, xsp.

gsp

gsp: number.

Ground speed, in pixels per second. Prefer using speed instead, since gsp is only meaningful if the player is touching the ground.

See also: speed.

xsp

xsp: number.

Horizontal speed, in pixels per second (useful while midair). Prefer using speed instead.

See also: speed.

ysp

ysp: number.

Vertical speed, in pixels per second.

angle

angle: number.

The angle of the player, in degrees. The same as transform.angle.

See also: slope, transform.

slope

slope: number, read-only.

The angle detected by the physics system, in degrees. Unlike angle, slope is read-only and does not feature any smoothing for visual aesthetics. Its purpose is to be a helper for physics calculations.

See also: angle.

Available since: Open Surge 0.5.2

width

width: number, read-only.

The width of the player sprite, in pixels.

See also: height.

height

height: number, read-only.

The height of the player sprite, in pixels.

See also: width.

hflip

hflip: boolean.

Used to horizontally flip the sprite of the player relative to its direction. Defaults to false. Changing this flag does not change the direction of the player in any way. It only changes the way the sprite is rendered. Also, reading this flag alone does not tell you whether the sprite is facing left or right. Use it in addition to the direction of the player for that.

See also: direction, vflip.

Available since: Open Surge 0.6.1

Example

// make the sprite appear in accordance with player.direction
player.hflip = false;

// make the sprite appear flipped relative to player.direction
player.hflip = true;

// make the sprite appear facing right, regardless of player.direction
player.hflip = (player.direction < 0);

// make the sprite appear facing left, regardless of player.direction
player.hflip = (player.direction > 0);

// spriteDirection is analogous to player.direction
spriteDirection = player.direction * (player.hflip ? -1 : 1);

// let's check if the sprite is facing right or left
isFacingRight = (spriteDirection > 0);
isFacingLeft = (spriteDirection < 0);

vflip

vflip: boolean.

Used to vertically flip the sprite of the player. Defaults to false.

See also: hflip.

Available since: Open Surge 0.6.1

Functions

bounce

bounce(hazard | null)

Makes the player bounce after smashing a hazard. The trajectory of the movement will be computed according to the position of the hazard. If no hazard is present, you may pass null as the argument.

Arguments

• hazard: Actor object. The hazard.

Example

using SurgeEngine.Player;
using SurgeEngine.Actor;
using SurgeEngine.Collisions.CollisionBox;

object "Shield Box" is "entity"
{
    actor = Actor("Shield Box");
    shieldCollider = CollisionBox(32,32);

    state "main"
    {
        player = Player.active;
        if(player.attacking) {
            if(player.collider.collidesWith(shieldCollider)) {
                if(player.midair)
                    player.bounce(actor);
                player.shield = "fire";
                destroy();
            }
        }
    }
}

bounceBack

bounceBack(hazard)

Makes the player bounce after smashing a hazard. If the player comes at the hazard from below, the player is thrown downwards. If not, the player is thrown upwards. The hazard parameter is mandatory.

Arguments

• hazard: Actor object. The hazard.

getHit

getHit(hazard | null)

Makes the player get hit. Call it whenever the player gets hit by a hazard. The hit movement will be calculated according to the position of the hazard. If no hazard is present, you may pass null as the argument.

Arguments

• hazard: Actor object. The hazard.

See also: hit.

kill

kill()

Kills the player.

breathe

breathe()

Makes the player breathe (underwater only).

restore

restore()

Restores the player to a vulnerable state.

Available since: Open Surge 0.6.1

springify

springify()

Activates the "springing" activity.

See also: restore.

roll

roll()

Makes the player roll.

hlock

hlock(seconds)

Locks the horizontal controls of the player for the specified time. Left and right input will be ignored during that time.

See also: hlockTime.

Arguments

• seconds: number. How long the horizontal controls of the player will stay locked? This usually should be set to a value no higher than 0.5.

Note: since Open Surge 0.6.1, the locking will not take place if the player is midair.

focus

focus()

Focuses on the player. The focused player is controlled by the user. Only one player has focus at any given time.

See also: hasFocus, focusable, Player.active.

Returns

Returns true on success, false otherwise.

hasFocus

hasFocus()

Does the player have focus?

See also: focus, focusable, Player.active.

Returns

Returns true if the player has focus, false otherwise.

moveBy

moveBy(dx, dy)

Moves the player by a (dx,dy) offset after the physics update of the current framestep. This is similar to calling player.transform.translateBy(dx, dy) in lateUpdate().

See also: lateUpdate, translateBy.

Available since: Open Surge 0.6.1

Arguments

• dx: number. Horizontal offset in pixels.
• dy: number. Vertical offset in pixels.

Example

// Let's compare player.moveBy() to
// player.transform.translateBy()
dx = 5;
dy = 0;

// this moves the player AFTER the physics update
player.moveBy(dx, dy);

// this moves the player BEFORE the physics update
// (immediately), unless you call it in lateUpdate()
player.transform.translateBy(dx, dy);

move

move(offset)

Moves the player by the given offset after the physics update of the current framestep. Calling player.move(offset) is equivalent to calling player.moveBy(offset.x, offset.y).

See also: moveBy.

Available since: Open Surge 0.6.1

Arguments

• offset: Vector2 object. Offset vector.

transformInto

player.transformInto(characterName)

Transforms the player into the character named characterName. The transformation succeeds only if there is such a character.

Available since: Open Surge 0.6.1

Arguments

• characterName: string. The name of a character, as defined in a .chr file.

Returns

Returns true if the transformation is successful. Transforming a player into itself is considered successful, but nothing happens in this case.

// this player will become Surge
player.transformInto("Surge");

// this player will become Tux
player.transformInto("Tux");

// the following transformation will fail:
if(!player.transformInto("non-existent-character"))
    Console.print("No transformation took place!");

// After a successful transformation:
// - player.name will change;
// - player.id will not change!