Character Def

The "Character Def" file creates most aspects of a player character to be used in the game. Character sprites, movement properties, sound effect IDs, and animations are listed here. There are a set number of player "Constants" that must be used in a particular order. The same applies to sound effects, and Animation functions. Custom data may be added to the end of lists whose size is available in the current Character Def or the "Game Def" script for changing. It is recommended that if the characters have art that is used for status displays, that it be placed at the beginning of the sprite listing, so that it will have the same sprite ID for every character included in the game. Sprites may otherwise be listed in any order. If the sprite listing is modified at any time, Animations and status displays may need to be updated to reflect the changes if frames were inserted or deleted.

Format Description
The following is a detailed description of each of the entries in a Character Def file. For a more practical view, see the example below

-Notes
The "Notes" field may contain any text to describe the file.

-Total Frames
This is the total number of sprite frames listed for this character to load.

-Frame
Each sprite frame for this character is defined by loading, offset, and boundary information. Though the initial data must be defined in this script manually, some of this information may be obtained visually using the Sprite Editor, from which modified settings may be dumped, but those settings must be copied into this file, and are laid out in the following way:

-FileName
This is the name of the art file that contains the image data for this sprite frame. If the file does not exist in this folder, it's path must be included. The path must be "relative", meaning that it must tell how to get to the file from this folder, not the "Root Directory".

-X offset in file
-Y offset in file
These are the X and Y positions of the top-left corner of the sprite in it's image file.

-Width
-Height
These are the size of the sprite frame in width and height.

-X offset for normal draw
-Y offset for normal draw
These values specify how far away from the player position to start drawing this frame on the X and Y axes when it is being drawn forward and right-side up

-X offset for b-ward draw
-Y offset for u-down draw
These values specify how far away from the player position to start drawing this frame on the X and Y axes when it is being drawn backward and upside-down

- Main BoundsX1
- Y1
- X2
- Y2
These values create a boundary box around the sprite that can be used for collision purposes. "Main Bounds" are used automatically for collision against the level, but but may also be used by script commands for collision tests against objects. The values used are based on offsets from the player position

For level collision purposes, "walls" are tested for at the exact X/Y offset of the boundary, while "floors"/"ceilings" are tested for only -between- those offsets. "Walls" are the axis perpendicular to the current path axis, which is determined by the player's current Path Mode

-Num Attack Boxes
This is the number of boundary boxes that will be created for "Attack" collision. Each "Attack" box is listed directly below:

- AttackX1
- Y1
- X2
- Y2
These values create a boundary box around the sprite that can be used for collision purposes. "Attack" bounds are generally used to signal an "Attack" on an object when colliding with it's "Hurt" bounds, an effect created by creating an Object Collision Function that tests for and reacts to the collision. This boundary type may be tested against any of the three boundary types for any purpose. These values are based on offsets from the player position

-Num Hurt Boxes
This is the number of boundary boxes that will be created for "Hurt" collision. Each "Hurt" box is listed directly below:

- HurtX1
- Y1
- X2
- Y2
These values create a boundary box around the sprite that can be used for collision purposes. "Hurt" bounds are generally used to signal an "Attack" on the player when colliding with an object's "Attack" bounds, an effect created by creating an Object Collision Function that tests for and reacts to the collision. This boundary type may be tested against any of the three boundary types for any purpose. These values are based on offsets from the player position

-Num Hotspots
This is the number of "Hotspots" that will be created for the sprite. Each "Hotspot" is listed directly below:

- SpotX
- Y
These values create a Hotspot within the sprite that can be used for collision, positioning of or against other objects, etc. For example, using the proper script commands, a player that must spawn a projectile during a complex animation may use hotspots to align the new object at different places for each frame of animation to achieve the image that the new object spawns perfectly from a certain visual area of the player no matter where it appears to be

-Constants
There must be at least 9 Constants assigned to a player character. These required constants control how the player is initialized when it's player character is set, how the viewport is managed for the character when it is set to automatically update, and how a player follows inclines/declines on level or tiled object paths. If more constants are desired for use with scripts, the number of total Constants available must first be altered in the "Game Def" to reflect the number of user-defined Constants that will be used. All characters in the same game must list the same number of Constants. The user-defined constants should be listed immediately below the required Constants. The 9 required Constants, which must appear first and in this order, are as listed:

0 - Character's Init Function
This value represents the ID number of the function to call when the player character is set. A normal ID value references a player common function, however, prefixing the value with an "F", such as "F0", signifies that the value represents a function from this character's own character def function listing

1 - Character's Viewport Left Limit
2 - Character's Viewport Right Limit
3 - Character's Viewport Upper Limit
4 - Character's Viewport Lower Limit
These values are used for automatic viewport update, and describe at what point on the screen, starting at the top-left corner, the player can be before the viewport automatically pans in any of the four directions by the speeds given below

5 - Character's Viewport X Speed
6 - Character's Viewport Y Speed
These values are used for automatic viewport update, and describe how fast the viewport is allowed to move when attempting to catch up to the player once he has passed any of the offset boundaries described above

7 - Character's Floor Slope Tolerance
8 - Character's Ceiling Slope Tolerance
These values describe how many pixels a path may raise from a "floor" or fall from a "ceiling" before it is considered to be a "wall". If the rise or fall of the path in front of the player is less than or equal to these values, the player will continue to follow the path. If the rise/fall is greater than this value, the solidity in front of the player is considered to be a "wall", and he will not be allowed to move in this direction

-User-defined Constants.....
At this point, any user-defined constants that need to be declared should be listed here in the same way as the required Constants. The number of user-defined Constants that is listed in the Game Def must be equal to the number of Constants that are listed from this point on. All Characters must use the exact same number of Constants (Required and user-defined). These Constants may be accessed as part of the complete listing (beginning with the Required Constants at ID 0), or they may be accessed as their own listing (beginning with the first user-defined Constant at ID 0) if the lower-case "c" tag is used used. (See "Player Variables" Doc)

-Character's Custom Variables
This section isn't an actual entry, but it is suggested that this area be used to enter comments that list the name, ID, and description of any user-defined variables that are used by scripts so that it can be used for reference.

-Sound Effects
This is a listing of ID numbers of the sound effects that this character object can play. This E02 build does not expect any required effects to be listed. If more sound effects are desired for use with scripts, the number of custom sound effects available for character use must be altered below to reflect number of user-defined sound effects that will be used

-There are no sound effects required by this build of E02

-Number of Custom Sound Effects
If the player should use any Sound Effects that aren't required, this value specifies how many. If no extra sound effects are desired, this value should be 0. If it is greater than 0, the IDs for the custom Sound Effect listing should be listed immediately below in the same way as the required Sound Effects. This list may be accessed as part of the full Sound Effect listing (starting with the first required Sound at ID 0), or as a listing of it's own (starting with the first Custom Sound Effect entry at ID 0) if the lower-case "s" tag is used when referencing it's ID in a Script Function (such as "s0" for the first Custom Sound). This list is used by Script Commands that call for Player Sound Effects

-Movement Mode Properties
This section is used to build "Movement Modes" for the character that describes how the player moves, animates, and reacts to input. The behavior is set up by the inclusion of the following data:

-Movement Function
The ID number of a player function that should be called during this character's Movement Phase, immediately after hard-coded path movement. In general, this function is responsible for controlling player velocities, and it's reactions to level collisions, level events, and other player state triggers. A normal ID value references a function from this character's own character def function listing, however, prefixing the value with a "C", such as "C0", signifies that the value represents a player common function

-Update Function
The ID number of a player function that should be called during this character's Update Phase, immediately before the player's animation is processed, and the automatic viewport update is managed. In general, this function is responsible for controlling what animation a player is playing relative to the movement mode and any special states, and to update automatic viewport properties or to manually update the viewport. A normal ID value references a function from this character's own character def function listing, however, prefixing the value with a "C", such as "C0", signifies that the value represents a player common function

-Number of Key Events
The number of different key combinations that can trigger an event during this "Movement Mode". Each combination and it's corresponding event are listed directly below:

-Num of Keys
The number of keypresses that this event requires to be triggered. Each key that must be pressed simultaneously for this event is listed directly below:

-Key
The ID number of the desired key's position in the key state table
-Function
The ID number of the player function that should be called if all keys for this event are pressed. A normal ID value references a function from this character's own character def function listing, however, prefixing the value with a "C", such as "C0", signifies that the value represents a player common function

-Animation Func IDs
This is a listing of ID numbers of the functions that this character should use for animation purposes. Animation is not limited to the functions shown in this list, but the entries in this list can be modified during gameplay to swap animations as needed. There must be at least 1 of these assigned to each character. If more animations are desired for use by scripts, the number of user-defined Animation Functions must be altered below to reflect the number of Animation Function IDs that will be added to the list. The 1 required animation, which must appear first, is:

-Default
This animation will run automatically when the player character is set

-Number of Custom Animation Entries
If more Animation ID entries are desired, this value specifies how many. If none, it should be set to 0. The Custom Animation list can be used to store animation IDs for use by scripts in cases such as when a player's state changes, and it may also contain IDs that may be switched with other entries, so that when that entry is called for, a different animation may be played depending on other aspects of the player's state. The desired Animation ID listing entries should appear immediately below in the same way as the required entries. This list may be accessed as part of the full Animation ID listing (starting with the first required Animation ID Entry at ID 0), or as a listing of it's own (starting with the first Custom Animation ID Entry at ID 0) if the lower- case "l" tag is used when referring to it's ID in a Script Function (such as "l0" for the first Custom Animation ID Entry). This list is used by Script Commands that call for or swap Player Animations

-Number of Player Funcs
This is the number of scripted functions that will be listed for this character to use during animation, motion, etc. The Animation listing refers to the functions found in this listing, as do the player movement, update, and key events. The Functions themselves appear immediately below this line as described in their own documentation



Example Character Def
The following is an example setup for a character def file to better demonstrate how to put the above information into practice. Use the same format and fill in the appropriate values given the information contained throughout the various documents to create a player character for an E02 game

Notes: Example Character Def File

Total Frames: 2

Frame  0-        FileName:   Char1.pcx
         X offset in file:   0
         Y offset in file:   0
                    Width:  29
                   Height:  39
 X offset for normal draw: -16
 Y offset for normal draw: -19
 X offset for b-ward draw: -12
 Y offset for U-Down draw: -20
           Main Bounds X1:  -9
                       Y1: -19
                       X2:   9
                       Y2:  20
           Num Attack Box:   0
             Num Hurt Box:   1
           Hurt 0-     X1:  -8
                       Y1: -19
                       X2:   9
                       Y2:  20
             Num Hotspots:   1
           HotSpot 0-   X:   0
                        Y:   0
Frame  1-        FileName:   Char1.pcx
         X offset in file:  29
         Y offset in file:   0
                    Width:  30
                   Height:  39
 X offset for normal draw: -17
 Y offset for normal draw: -19
 X offset for b-ward draw: -12
 Y offset for U-Down draw: -20
           Main Bounds X1:  -9
                       Y1: -19
                       X2:   9
                       Y2:  20
           Num Attack Box:   0
             Num Hurt Box:   1
           Hurt 0-     X1:  -8
                       Y1: -19
                       X2:   9
                       Y2:  20
             Num Hotspots:   1
           HotSpot 0-   X:   0
                        Y:   0


;-----------------------------------------------------------------;
;----------------Character's Constant Properties------------------;
;-----------------------------------------------------------------;
;Total number is defined in Game Def File

;The 0 Required Constants
  0 - Character's Init Function:                     22 ;Common Func 22, Player Init/Sentry

  1 - Character's Viewport Left Limit:              144
  2 - Character's Viewport Right Limit:             160
  3 - Character's Viewport Upper Limit:              96
  4 - Character's Viewport Lower Limit:              96
  5 - Character's Viewport X Speed:                  16
  6 - Character's Viewport Y Speed:                  16

  7 - Character's Floor Slope Tolerance:              4
  8 - Character's Ceiling Slope Tolerance:            4

;The extra Constants just for this game
  0 - Example User Constant 0:                     $600
  1 - Example User Constant 1:                       $C


;-----------------------------------------------------------------;
;-----------------Character's Custom Variables--------------------;
;-----------------------------------------------------------------;
;These are just comments to document the custom variables used in scripts

; 0 - Example Custom Player Variable 0
; 1 - Example Custom Player Variable 1


;-----------------------------------------------------------------;
;-------------------Character's Sound Effects---------------------;
;-----------------------------------------------------------------;

;The 0 Required sounds
  ;There are currently no required sounds

;The extra sounds just for this game
Number of Custom Sound Effects:   2
  0 - Example Chr SFX 0:     1
  1 - Example Chr SFX 1:     2


;-----------------------------------------------------------------;
;--------------------Movement Mode Properties---------------------;
;-----------------------------------------------------------------;

Number of Movement Modes:   2

Mode 0 - Example Movement Mode 0
        Movement Function:C11  ;Character Common Function 11
          Update Function:C12  ;Character Common Function 12
     Number of Key Events:  2
    Event 0 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PH0  ;Hold Player Button 0
                 Function:C25  ;Character Common Function 25
    Event 1 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PT1  ;Tap Player Button 1
                 Function:C26  ;Character Common Function 26
Mode 1 - Example Movement Mode 1
        Movement Function:C13  ;Character Common Function 13
          Update Function:C14  ;Character Common Function 14
     Number of Key Events:  2
    Event 0 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PH0  ;Hold Player Button 0
                 Function:  2  ;This Character's Function 2
    Event 1 - Num of Keys:  1  ;Example Player Key Event
                    Key 1:PT1  ;Tap Player Button 1
                 Function:  3  ;This Character's Function 3


;-----------------------------------------------------------------;
;-------------------Animation Function Listing--------------------;
;-----------------------------------------------------------------;

;The 1 Required Animations
  0 - Default Animation:                 1 ; Used by this script for standing still

;The extra Animations just for this game
Number of Custom Animation Entries:    25

  1 - Example Custom Animation 1:        7 ;  l0	(This Character Function  7)
  2 - Example Custom Animation 1:       11 ;  l1	(This Character Function 11)
  3 - Example Custom Animation 1:        7 ;  l2	(This Character Function  7)


;-----------------------------------------------------------------;
;-----------Character's Animation and Action Functions------------;
;-----------------------------------------------------------------;

Number of Player Funcs: 2

;===================================================================================
;=======================================
;Function 0 - Example Player Function 0=
;=======================================

	# 137 ;LockPlayer
	:   6 ;All Priorities
	:  r9 ;Current Player

	#  85 ;Chr2 = Const	(Set the player's flags)
	: A36 ;(Chr2) Player_Flags
	:%11101011100 ;(Const) Left/Right stop, VPCenter, FollowPath, UseVector, FollowCurves, RotateBounds

# End	;Terminate Function

;===================================================================================
;=======================================
;Function 1 - Example Player Function 1=
;=======================================
@0
	# 137 ;LockPlayer
	:   6 ;All Priorities
	:  r9 ;Current Player

	# 663 ;Increase Chr2	(Move one pixel)
	:  A3 ;Player_X_Pos

	#  79 ;Break Function	(Break until next frame)
	# 847 ;GoTo		(Re-run the function)
	:  @0

# End	;Terminate Function