Creating new characters
A character in paintown comprises a description file and various resource files (image files and sound files). The description file is a plain text file that must end with a .txt extension. Resource files can be in any format the paintown engine will accept: png, bmp, pcx for images and wav for sounds.
The character description file must use S-expressions to structure the contents. S-expressions are simply parenthesized words of text.
Here is part of the description file for Akuma (paintown/data/players/akuma.txt)
(character (name "Akuma") (health 100) (jump-velocity 6.0) (speed 1.0) (type Player) ... )
The character file starts with an s-expression whose first word is character. The next line is another s-expression that sets the name to be Akuma.
The following are all the attributes that can be put inside the (character) s-expression.
name The name of the character. (name "Akuma")
health The starting health of the character. (health 100)
jump-velocity The starting velocity a character has when jumping. (jump-velocity 6.0)
speed How fast the character can move on the ground. (speed 1.0)
type Player for human controlled characters. (type Player)
shadow The size of the shadow between 1 and 7. (shadow 4)
die-sound The sound to play when the character dies. (die-sound players/ryu/die.wav)
hit-sound The sound to play when this character hits another one. (hit-sound sounds/beat1.wav)
landed The sound to play when the character lands on the ground either due to jumping or from falling. (landed sounds/fall.wav)
icon The icon to show next to the name and health bar in the game. (icon players/akuma/icon.png)
remap Sets up a palette change. (remap players/akuma/idle/18275.png players/akuma/map1.png)
anim Creates an animation / movement the character can use. See the section on animations below. (anim ...stuff..)
The following attributes are for players only, meaning when the character contains (type player).
intro Relative path to a cutscene file which will play after the select screen. (intro players/akuma/intro.txt)
ending Relative path to a cutscene file which will play when all levels have been beaten. (ending players/akuma/ending.txt)
Animations are s-expressions that start with anim or animation and can have a list of attributes in them.
name The name of the animation. (name "idle")
basedir Sets the directory used to find images for frames. (basedir players/akuma/idle)
delay Sets the amount of time to wait for frames that follow before activating the next animation attribute. (delay 10)
offset Sets the x/y coordinates of where the sprite will appear relative to the characters current position. (offset 5 2)
frame Displays a sprite. The frame will stay activated for as long as the current delay time is set for. (frame 18200.png)
move Moves the character in the game. The order of parameters is X, Y, Z. (move 15 0 0)
attack Sets an attack box that will collide with other players. x1, y1 are the upper left corner and x2, y2 are the lower left corner. damage specifies how much damage to the other player this attack will do. force specifies how much velocity to add to a player when they get knocked down.
(attack (box (x1 30) (y1 1) (x2 50) (y2 20) (damage 10) (force 1.2 5.0)))
An empty attack s-expression will disable the attack box. (attack)
next-ticket Normally an attack can only hit once even if the attack box collides with a player multiple times. next-ticket increases an internal counter for the attack so that it can hit again. (next-ticket)
nop Does nothing except wait for the delay time to pass.
trail Generates translucent shadows behind the character. generate is the time between generating a new shadow. length is the amount of time to keep an individual shadow alive for.
(trail (generate 25) (length 20))
range The distance in X coordinates that should specify the maximum distance an enemy can be from this animation for the attack to hit. This is only useful for computer controlled characters as this is what they use to compute a valid set of attacks. (range 50)
type Sets this animation as an attack animation. (type attack)
keys The keys that must be pressed by the player to activate this animation. (keys key_forward key_down key_forward key_attack1)
Valid keys are
Here is a complete example of an animation for Akuma.
(anim (name "strong-punch") (type attack) (sequence "reverse-hand-punch" junk) (keys key_attack1) (range 124) (basedir players/akuma/strong-punch/) (delay 5) (offset 20 1) (frame 18637.png) (offset 24 1) (frame 18638.png) (offset 20 1) (frame 18639.png) (offset 42 1) (attack (box (x1 105) (y1 20) (x2 160) (y2 40) (force 1.7 4.4) (damage 8))) (frame 18640.png) (frame 18641.png) (frame 18642.png) (attack) (offset 30 1) (frame 18643.png) (offset 10 1) (frame 18644.png) (offset 0 1) (frame 18645.png))