Difference between revisions of "Characters"

From Open Surge Engine Wiki
Jump to: navigation, search
(Structure)
m (Curiosity: regular platformers)
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
  
Characters are human-readable .chr files located in the characters/ folder. They're used to create playable characters.
+
In Open Surge, you can create your own playable characters. To create a playable characrer, first of all you need to create a character file.
  
See also: [[Level_specification#players]]
+
Character files are human-readable configuration files located in the ''characters/'' folder. They have the .chr extension. These files are used to specify the properties of the characters.
 +
 
 +
Each level has one or more playable characters. You can pick which level features which characters. To know how to set the characters, refer to: [[Level_specification#players|Level specification - players]].
  
 
== Structure ==
 
== Structure ==
  
.chr files contain the following information:
+
Character files are used to specify the following data:
  
 
* the '''name of the character''';
 
* the '''name of the character''';
 
* the '''multipliers'''. These values are used to specify how fast a character runs, how high it jumps, how fast it accelerates, etc. For example, if you set the acceleration to one, it will accelerate by the default rate (set by the game engine). If you set it to two, it will accelerate two times faster than that. If you set it to 0.5, it will accelerate by half of the default rate, and so on. By default, all the multipliers are set to 1.0;
 
* the '''multipliers'''. These values are used to specify how fast a character runs, how high it jumps, how fast it accelerates, etc. For example, if you set the acceleration to one, it will accelerate by the default rate (set by the game engine). If you set it to two, it will accelerate two times faster than that. If you set it to 0.5, it will accelerate by half of the default rate, and so on. By default, all the multipliers are set to 1.0;
* the '''animations''' for each action the character performs: walk, run, jump, etc. See also: [[Sprites]];
+
* the '''animations''' for each action the character performs: walk, run, jump, etc., as well as the sprite name. See also: [[Sprites]];
 
* the '''sound effects''' this character uses: jump, brake, etc.;
 
* the '''sound effects''' this character uses: jump, brake, etc.;
* optionally, the name of a '''companion object'''. If specified, the companion object can be used to develop special moves. This object is spawned when the players are spawned.
+
* the '''abilities''' this character has: roll, charge, etc.;
** '''Note 1:''' the companion object should have the [[API_Reference#always_active|always_active]] flag specified;
+
* optionally, the name of one or more '''companion objects'''. If defined, companion objects can be used to give custom abilities to characters.
** '''Note 2:''' you should make the companion object [[API_Reference#Cooperative_play|observe]] its owner character.
+
  
== Example ==
+
== Example: Surge ==
  
// ---------------------------------------------------------------------------
 
// Open Surge Engine
 
// http://opensnc.sourceforge.net
 
 
  //
 
  //
  // File:   characters/surge.chr
+
// Surge (example)
  // Desc:  character definition: Surge
+
  // File: characters/surge.chr
// Author: OS Team
+
  //
// ---------------------------------------------------------------------------
+
 
   
 
   
 
  character "Surge"
 
  character "Surge"
 
  {
 
  {
     companion_object                ".surge_companion"
+
     companions                      "Surge's Light Sneakers" // "Surge's Light Sneakers" is an object created in SurgeScript
   
+
 
     multipliers
 
     multipliers
 
     {
 
     {
         acceleration                1.0
+
         acceleration                1.0   // modifies the acceleration rate
         deceleration                1.0
+
         deceleration                1.0   // used when moving in opposition to the current movement
         topspeed                    1.0
+
        friction                    1.0    // modifies the friction (since version 0.5.0)
         jump                        1.0
+
         topspeed                    1.0   // modifies how fast the character can run
         jumprel                     1.0
+
         jump                        1.0   // modifies how high the character jumps
         gravity                    1.0
+
         gravity                     1.0   // gravity modifier
         rollthreshold              1.0
+
         slope                      1.0   // affects the physics on slopes
         brakingthreshold            1.0
+
         charge                      1.0   // modifies the charge-and-release speed (since version 0.5.0)
 +
         airacceleration            1.0   // the rate at which the horizontal speed can change while midair (since 0.5.0)
 +
        airdrag                    1.0    // air drag / air friction (since version 0.5.0)
 
     }
 
     }
 
      
 
      
 
     animations
 
     animations
 
     {
 
     {
         sprite_name                "SD_SURGE"
+
         sprite_name                "Surge"
 
         stopped                    0
 
         stopped                    0
 
         walking                    1
 
         walking                    1
Line 52: Line 51:
 
         jumping                    3
 
         jumping                    3
 
         springing                  13
 
         springing                  13
         rolling                    3
+
         rolling                    18
 +
        charging                    6
 
         pushing                    14
 
         pushing                    14
 
         gettinghit                  11
 
         gettinghit                  11
Line 63: Line 63:
 
         ducking                    4
 
         ducking                    4
 
         lookingup                  5
 
         lookingup                  5
         winning                    10
+
         winning                    17
 
         ceiling                    16
 
         ceiling                    16
 +
    }
 +
   
 +
    abilities
 +
    {
 +
        roll                        TRUE
 +
        brake                      TRUE
 +
        charge                      TRUE
 
     }
 
     }
 
      
 
      
Line 73: Line 80:
 
         death                      "samples/death.wav"
 
         death                      "samples/death.wav"
 
         brake                      "samples/brake.wav"
 
         brake                      "samples/brake.wav"
 +
        charge                      "samples/charge.wav"
 +
        release                    "samples/release.wav"
 +
    }   
 +
}
 +
 +
'''Compatibility notes:''' animation ''charging'', sounds ''charge'' and ''release'', the ''abilities'' block, as well as some multipliers (indicated above) are available since Open Surge version 0.5.0.
 +
 +
'''Companion objects:''' ''companions'' is available since Open Surge version 0.5.0. It is followed by one or more names of objects surrounded by double quotes ("). These objects should be created in SurgeScript. In older versions of the engine, you'd write ''companion_object'' instead (it supports only one companion).
 +
 +
== Creating custom abilities ==
 +
 +
One of the exciting features of Open Surge is the possibility to create custom abilities (custom moves) for your characters. You can create these abilities by adding companion objects to your characters. These objects are created in SurgeScript.
 +
 +
To understand better how to create your own custom abilities, let's study the case of a dash movement (affectionally called ''"Super Peel Out"''). If your character is endowed with that ability, you can give it instant speed when it's stopped. In Open Surge, character Tux features that ability. Surge does not. To add this custom move to Surge, add the corresponding object to his companions:
 +
 +
companions                      "Surge's Light Sneakers" "Super Peel Out"
 +
 +
The new companion is defined in a script, a .ss file located in the ''scripts/'' folder. The script of this move has been reproduced here for clarity:
 +
 +
using SurgeEngine.Audio.Sound;
 +
 +
//
 +
// This is a dash move that should be configured as a
 +
// companion object in a character definition file (.chr)
 +
//
 +
// When you are stopped, hold up and press jump to charge.
 +
// Release up after 0.3 second and you'll gain a nice boost!
 +
//
 +
object "Super Peel Out" is "companion"
 +
{
 +
    speed = 720;    // dash speed, in pixels/second
 +
 +
    charge = Sound("samples/charge.wav");
 +
    release = Sound("samples/release.wav");
 +
    player = parent; // since this object is configured as a
 +
                      // companion, parent is the reference
 +
                      // to the correct Player object
 +
 +
    // capture the event
 +
    state "main"
 +
    {
 +
        if(player.lookingUp) {
 +
            if(player.input.buttonPressed("fire1")) {
 +
                charge.play();
 +
                state = "charging";
 +
            }
 +
        }
 +
    }
 +
 +
    // charging the dash
 +
    state "charging"
 +
    {
 +
        player.anim = 2; // running animation
 +
        player.animation.speedFactor = 1.85;
 +
        player.frozen = true; // disable physics (temporarily)
 +
 +
        // ready to go?
 +
        if(player.input.buttonReleased("up")) {
 +
            if(timeout(0.3)) {
 +
                player.gsp = speed * player.direction; // dash!!!
 +
                release.play();
 +
            }
 +
            player.frozen = false; // enable physics
 +
            state = "main";
 +
        }
 +
        else if(player.input.buttonPressed("fire1"))
 +
            charge.play();
 
     }
 
     }
 
  }
 
  }
 +
 +
What custom abilities can you add? Whatever you can imagine! Swimming, flying, climbing, wall kicking, you name it! The sky is the limit for those who learn SurgeScript! ;)
 +
 +
== Curiosity: regular platformers ==
 +
 +
Even though Open Surge provides built-in 360º physics (with curvy roads, loops, and so on), careful modification of the character files can make it behave like a regular platformer. Example: if you create a character named ''SuperTux'' without the special abilities listed above (rolling, charging, etc.), set its slope multiplier to zero (and adjust the others), as well as build levels mainly out of rectangular platforms, you'll end up with a platformer like [http://www.supertux.org SuperTux]. Additionally, companion object "Lock Angle" prevents the character from rotating on slopes.
 +
 +
[[File:Supertux051.png|256px|thumb|left|SuperTux, a jump'n run inspired by Mario]]
 +
<br clear="all">
  
 
[[Category:MODs]]
 
[[Category:MODs]]
 
[[Category:Characters]]
 
[[Category:Characters]]

Revision as of 16:11, 9 September 2019

Overview

In Open Surge, you can create your own playable characters. To create a playable characrer, first of all you need to create a character file.

Character files are human-readable configuration files located in the characters/ folder. They have the .chr extension. These files are used to specify the properties of the characters.

Each level has one or more playable characters. You can pick which level features which characters. To know how to set the characters, refer to: Level specification - players.

Structure

Character files are used to specify the following data:

  • the name of the character;
  • the multipliers. These values are used to specify how fast a character runs, how high it jumps, how fast it accelerates, etc. For example, if you set the acceleration to one, it will accelerate by the default rate (set by the game engine). If you set it to two, it will accelerate two times faster than that. If you set it to 0.5, it will accelerate by half of the default rate, and so on. By default, all the multipliers are set to 1.0;
  • the animations for each action the character performs: walk, run, jump, etc., as well as the sprite name. See also: Sprites;
  • the sound effects this character uses: jump, brake, etc.;
  • the abilities this character has: roll, charge, etc.;
  • optionally, the name of one or more companion objects. If defined, companion objects can be used to give custom abilities to characters.

Example: Surge

//
// Surge (example)
// File: characters/surge.chr
//

character "Surge"
{
    companions                      "Surge's Light Sneakers" // "Surge's Light Sneakers" is an object created in SurgeScript

    multipliers
    {
        acceleration                1.0    // modifies the acceleration rate
        deceleration                1.0    // used when moving in opposition to the current movement
        friction                    1.0    // modifies the friction (since version 0.5.0)
        topspeed                    1.0    // modifies how fast the character can run
        jump                        1.0    // modifies how high the character jumps
        gravity                     1.0    // gravity modifier
        slope                       1.0    // affects the physics on slopes
        charge                      1.0    // modifies the charge-and-release speed (since version 0.5.0)
        airacceleration             1.0    // the rate at which the horizontal speed can change while midair (since 0.5.0)
        airdrag                     1.0    // air drag / air friction (since version 0.5.0)
    }
    
    animations
    {
        sprite_name                 "Surge"
        stopped                     0
        walking                     1
        running                     2
        jumping                     3
        springing                   13
        rolling                     18
        charging                    6
        pushing                     14
        gettinghit                  11
        dead                        8
        braking                     7
        ledge                       10
        drowned                     9
        breathing                   12
        waiting                     15
        ducking                     4
        lookingup                   5
        winning                     17
        ceiling                     16
    }
    
    abilities
    {
        roll                        TRUE
        brake                       TRUE
        charge                      TRUE
    }
    
    samples
    {
        jump                        "samples/jump.wav"
        roll                        "samples/roll.wav"
        death                       "samples/death.wav"
        brake                       "samples/brake.wav"
        charge                      "samples/charge.wav"
        release                     "samples/release.wav"
    }    
}

Compatibility notes: animation charging, sounds charge and release, the abilities block, as well as some multipliers (indicated above) are available since Open Surge version 0.5.0.

Companion objects: companions is available since Open Surge version 0.5.0. It is followed by one or more names of objects surrounded by double quotes ("). These objects should be created in SurgeScript. In older versions of the engine, you'd write companion_object instead (it supports only one companion).

Creating custom abilities

One of the exciting features of Open Surge is the possibility to create custom abilities (custom moves) for your characters. You can create these abilities by adding companion objects to your characters. These objects are created in SurgeScript.

To understand better how to create your own custom abilities, let's study the case of a dash movement (affectionally called "Super Peel Out"). If your character is endowed with that ability, you can give it instant speed when it's stopped. In Open Surge, character Tux features that ability. Surge does not. To add this custom move to Surge, add the corresponding object to his companions:

companions                      "Surge's Light Sneakers" "Super Peel Out"

The new companion is defined in a script, a .ss file located in the scripts/ folder. The script of this move has been reproduced here for clarity:

using SurgeEngine.Audio.Sound;

//
// This is a dash move that should be configured as a
// companion object in a character definition file (.chr)
//
// When you are stopped, hold up and press jump to charge.
// Release up after 0.3 second and you'll gain a nice boost!
//
object "Super Peel Out" is "companion"
{
    speed = 720;     // dash speed, in pixels/second

    charge = Sound("samples/charge.wav");
    release = Sound("samples/release.wav");
    player = parent; // since this object is configured as a
                     // companion, parent is the reference
                     // to the correct Player object

    // capture the event
    state "main"
    {
        if(player.lookingUp) {
            if(player.input.buttonPressed("fire1")) {
                charge.play();
                state = "charging";
            }
        }
    }

    // charging the dash
    state "charging"
    {
        player.anim = 2; // running animation
        player.animation.speedFactor = 1.85;
        player.frozen = true; // disable physics (temporarily)

        // ready to go?
        if(player.input.buttonReleased("up")) {
            if(timeout(0.3)) {
                player.gsp = speed * player.direction; // dash!!!
                release.play();
            }
            player.frozen = false; // enable physics
            state = "main";
        }
        else if(player.input.buttonPressed("fire1"))
            charge.play();
    }
}

What custom abilities can you add? Whatever you can imagine! Swimming, flying, climbing, wall kicking, you name it! The sky is the limit for those who learn SurgeScript! ;)

Curiosity: regular platformers

Even though Open Surge provides built-in 360º physics (with curvy roads, loops, and so on), careful modification of the character files can make it behave like a regular platformer. Example: if you create a character named SuperTux without the special abilities listed above (rolling, charging, etc.), set its slope multiplier to zero (and adjust the others), as well as build levels mainly out of rectangular platforms, you'll end up with a platformer like SuperTux. Additionally, companion object "Lock Angle" prevents the character from rotating on slopes.

SuperTux, a jump'n run inspired by Mario