Player Variables


"Player Variables" store information about each active player character. They store both the player's constants, and his actively changing data. There are four different types:
Main Constants   - Constants required by the program, listed in this documentation
Custom Constants - Constants defined by the user by creating extra Player Constant space
                   with the appropriate option in the Game Def file, which are listed
                   below the "Main Constants" in the Character Def
Main Variables   - Variables required by the program, listed in this documentation
Custom Variables - Variables defined by the user by creating extra Player Variable space
                   with the appropriate option in the Game Def file
When referencing them from a script, the Main Constants can be referenced by simply using their ID number, such as "0" for "Character's Init Function", or with a preceding capital "C", such as "C0". A lower-case "c" (such as "c0") should be used for referencing Custom Constants. To reference an Active Variable, it's ID number should be preceded by a capital "A" (such as "A0" for "Player_Movement_Mode") for the variables listed in this documentation, or by lower-case "a" for Custom Variables. If any variables must be referenced without using the letter symbols, their IDs must be calculated in this manner:
(C) Main Constant   = ID#
(c) Custom Constant = #_of_Main_Constants + ID#
(A) Main Variable   = #_of_Main_Constants + #_of_Custom_Constants + ID#
(a) Custom Variable = #_of_Main_Constants + #_of_Custom_Constants + #_of_Main_Variables + ID#
When using the letter symbols, however, each different type is a list of it's own, each starting at index 0. This method helps compatibility in case the length of any of the lists changes. All references not using the letter symbols must be updated any time a list is lengthened or shortened by using the method described above

While the "Constants" are only for reference purposes (reading and testing), they can be modified, however, recommended use is that Constants that represent values that must change during play are copied to the active variable area, and used from there, so that their original values remain in-tact. Modified constants may be reverted to their initial values, however, by using the "Restore_Chr_Constants" script command

The Main player Constants are loaded from the "Character Def" file, and because they are described in detail in it's documentation, listed here is simply an index:
   0 - Character's Init Function
   1 - Character's Viewport Left Limit
   2 - Character's Viewport Right Limit
   3 - Character's Viewport Upper Limit
   4 - Character's Viewport Lower Limit
   5 - Character's Viewport X Speed
   6 - Character's Viewport Y Speed

   7 - Character's Floor Slope Tolerance
   8 - Character's Ceiling Slope Tolerance
The Main player Variables are stored as folows: (To reference them, either put "A" directly in front of ther ID number, or add the total number of player constants that were loaded from the "Character Def" to it's ID)
   0 - Player_Type
This is the ID value of the character script that this active player object is using. By recommended usage, this value should only be modified with the Set_Player_Character script command
   1 - Player_Movement_Mode
This is the current scripted "Movement Mode" the player is using, which controls how he interacts with the environment, and the effects of input
   2 - Player_Path_Mode
This is the current hard-coded level collision "Path Mode" the player is using, which controls in which direction the player tests for level solidity for path tracing. If the player is flagged to follow a curved path, this value will change as he rounds a 45-degree angle while following a level path or a tiled path object. The value may also be set directly by script commands, and will read or can be set to one of the following:
	0 - Floor Path
	1 - Right Wall Path
	2 - Ceiling Path
	3 - Left Wall Path
	4 - No Collision
	5 - No Collision
	6 - No Collision
	7 - No Collision
	8 - "Debug"
   3 - Player_X_Pos
   4 - Player_Y_Pos
These are the current X and Y coordinates of the player within the level.
   5 - Player_VPX
   6 - Player_VPY
These are the current X and Y positions of the player's "View Port" in the level. These values will be updated automatically if the player is flagged for "Automatic Viewport Update", or the values may be set directly by script commands. These values are copied to the VP?r[?] Game Registers, added with the Player_VP_?Pan offset values, and then clipped to the level boundaries. The final product of this operation is used as the position at which to draw each of the visible player screens
   7 - Player_X_Vel
   8 - Player_Y_Vel
   9 - Player_Path_Vel
These are the current X, Y, and Path velocities of the player. "Path Velocity" is "vector", or actual velocity. It is used to create X and Y velocity when attached to a surface, based on the angle value at the point at which the player is standing on a level path or tiled path object. When the player is not connected to a path, or if the player is flagged not to use vectored movement, or not to follow a path, "Path Velocity" affects X and Y Velocities in the following way:
	Floor:		X =  Path
	Ceiling:	X = -Path
	LWall:		Y =  Path
	RWall:		Y = -Path
  10 - Player_Previous_X_Vel
  11 - Player_Previous_Y_Vel
  12 - Player_Previous_Path_Vel
These values represent the X, Y, and Path velocities that the player had at the start of the current game frame, and can be read in case those velocities are required by a script function, as the current velocities are reset to 0 when the level or a solid object are struck on the corresponding axis
  13 - Player_X_Count
  14 - Player_Y_Count
These values are used for fine-movement with non-whole-value velocities. For every 256 units of velocity, the player will move one pixel across the level. At the beginning of each player's hard-coded movement phase, E02 adds the X and Y velocity values to these counters, and moves the player by one pixel for every 256 units. Remaining units are left in the counters at the end of movement, and added to the velocity when the object is moved again on the next game frame to achieve more fluid movement

They normally shouldn't be modified by script, but can be read or modified when circumstances warrant. Setting these values during Object Collision functions will change the distance that the player moves during that game frame, as the collision tests take place while the counters are being used to move the player
  15 - Player_Leftover_X_Count
  16 - Player_Leftover_Y_Count
These values are set by E02 when the player strikes a solid level plane or solid object during movement. They represent the value remaining in the above-described "count" variables when the player struck the solidity, meaning that this is the amount of potential movement that the player was not allowed to make during this game frame. They are reset at the beginning of the player's hard-coded movement phase each game frame
  17 - Player_X_Dir
  18 - Player_Y_Dir
These values determine in which direction to draw the player. Valid values are 0 for normal, and 1 for flipped/mirrored. They can be reversed by the Player_InvertMirror and Player_InvertMirror settings in cases such as reversing the meaning of player movement direction
  19 - Player_Cant_Go_Up
  20 - Player_Cant_Go_Down
  21 - Player_Cant_Go_Left
  22 - Player_Cant_Go_Right
These values represent whether or not the player is obstructed by the level or a solid object in any of the four directions. If the player is not obstructed, the value would be zero. If the player is obstructed by the level, E02 will set the value equal to the tile plane that the player has collided with, meaning that a positive value is always a tile plane, while solid objects are signified by a negative value, this value being a pointer to the object itself. For an object to be "solid", the object's collision function must use the appropriate script commands to test for a player's collision with it's boundaries, and then use the commands to set the appropriate "Cant_Go" value equal to a pointer to the object
  23 - Player_Path_Angle
When a player is following a path, this value is set equal to the angle that E02 has obtained from the path at the point of collision with the player. This value is only updated while the player is on a level path or tiled path object. If the player is in freespace, or is moving on top of a solid object, it remains unchanged until the player strikes another path
  24 - Player_Motion_Angle
This value represents the angle at which the player is actually moving, whether he is following a path or is in freespace
  25 - Player_Collision_Angle
When a player strikes solidity during movement, this value is set equal to the angle obtained from the point of collision. It is only meaningful during the game frame at which collision has occurred. At the beginning of the player's hard-coded movement during the next game frame, the value is set equal to 256, meaning that no collision has taken place. This value is affected by striking a path while in freespace, but not by a path that is already being followed
  26 - Player_On_Path
This value represents whether or not the player is standing on a path or solid object. The value is set by E02 automatically at the end of the player's hard-coded movement for each game frame, being made equal to the appropriate Player_Cant_Go_??? variable that corresponds with the current Player_Path_Mode setting, and is used to determine what the player is standing on as a "path", rather than what he is colliding with in any specific direction
  27 - Player_Was_On_Path
At the beginning of the player's hard-coded movement for each game frame, E02 sets this value equal to the value of the above-described "Player_On_Path" variable before it is modified. Testing this value allows scripts to determine exactly when the player connects to or disconnects from a "path"
  28 - Player_Solid_Plane
Before the player is allowed to move, this value must be set by script to be equal to the ID number of the tile plane that the player should tests for collisions with. The value can be changed mid-gameplay to cause the player to take alternate paths. If the player's X/Y coordinates move beyond the size of the tile plane, the coordinates at which the player tests for collision will be wrapped-around to the opposite side, preventing game crashes, and allowing proper collision with looped levels
  29 - Player_Collision_Area
This value reflects which of the 9 collision areas the player is being tested for object collision in during the collision testing phase. It is set by E02 and is meant for READ ONLY, as altering it manually will cause collisions to be missed if set between 0 and 8, or cause a crash if set to any other value.
  30 - Player_InvertMirror
  31 - Player_InvertFlip
These values reverse the meaning of the Player_?_Dir variables. Valid settings are 0 for normal, and 1 for reverse
  32 - Player_Curr_Boundary
This value reflects the ID number of the last "Boundary Event" that was triggered by this player, used to ensure that the event is only triggered once when the player or his camera first enters the boundary range. It is set by E02 when the player enters the boundary, but may be set by script to prevent an event from triggering, or to re-trigger an event
  33 - Player_Flash_Timer
This value is used to flicker the player, as in situations such as being invulnerable after taking damage. The player is only drawn when this value is divisible by 4. It is the responsibility of the game scripts to set and manage this value, as it is otherwise meaningless to E02
  34 - Player_Freeze
This value is used to freeze the player in place. Valid settings are:
	0 - Player is allowed to move and update
	1 - Player isn't allowed to move, but still processes his update phase
	2 - Player isn't allowed to move or update
  35 - Player_DebugNum
This value determines which entry in the current zone's debug listing to use for object display and placement when the player is in debug mode. It must be set by script, and must not be set below 0, or in excess of the size of the debug list for the current zone
  36 - Player_Flags
This value acts as a bitfield whose flags determine how E02 handles the player's movement and interaction with the level, and must be set by script before the level starts, or during gameplay, as the situation warrants. The flags represented by this value are as follows:
	 0 - Player_Up_Boundary_Stop
		The upper level boundary acts as solid
	 1 - Player_Down_Boundary_Stop
		The lower level boundary acts as solid
	 2 - Player_Left_Boundary_Stop
		The left level boundary acts as solid
	 3 - Player_Right_Boundary_Stop
		The right level boundary acts as solid
	 4 - Player_VPCenter
		E02 centers the viewport around the
		player using the relevant Player Constants
	 5 - Player_SolidFriction
		When the player strikes solidity on one axis,
		his remaining velocity on the opposite axis
		is ignored during this game frame
	 6 - Player_FollowPath
		The player will attach to and follow paths
		in the direction of his currently-set
		Path Mode
	 7 - Player_WallCollision
		Player tests for collision with "walls"
		(solidity perpendicular to his "path mode")
	 8 - Player_UseVector
		Player uses Path Angle and Path Velocity
		to determine the actual X/Y velocity at
		which to move
	 9 - Player_FollowCurves
		Player automatically changes Path Mode
		upon reaching a 45-degree angle to follow
		a curved path
	10 - Player_RotateBounds
		The "MainBounds" assigned to the player
		that are used for level collision testing
		are rotated 90-degrees when the player is
		using a "wall" Path Mode for a more
		circular effect than rectangular
  37 - Player_VP_XPan
  38 - Player_VP_YPan
These values can be used to "pan" the viewport during gameplay for any reason. They are added to the Player_VP? settings by E02 when they are being applied to the VP?r[?] Game Registers to set the drawn screen position for each player
Variable Index:
   0 - Player_Type
   1 - Player_Movement_Mode
   2 - Player_Path_Mode
   3 - Player_X_Pos
   4 - Player_Y_Pos
   5 - Player_VPX
   6 - Player_VPY
   7 - Player_X_Vel
   8 - Player_Y_Vel
   9 - Player_Path_Vel
  10 - Player_Previous_X_Vel
  11 - Player_Previous_Y_Vel
  12 - Player_Previous_Path_Vel
  13 - Player_X_Count
  14 - Player_Y_Count
  15 - Player_Leftover_X_Count
  16 - Player_Leftover_Y_Count
  17 - Player_X_Dir
  18 - Player_Y_Dir
  19 - Player_Cant_Go_Up
  20 - Player_Cant_Go_Down
  21 - Player_Cant_Go_Left
  22 - Player_Cant_Go_Right
  23 - Player_Path_Angle
  24 - Player_Motion_Angle
  25 - Player_Collision_Angle
  26 - Player_On_Path
  27 - Player_Was_On_Path
  28 - Player_Solid_Plane
  29 - Player_Collision_Area
  30 - Player_InvertMirror
  31 - Player_InvertFlip
  32 - Player_Curr_Boundary
  33 - Player_Flash_Timer
  34 - Player_Freeze
  35 - Player_DebugNum
  36 - Player_Flags
  37 - Player_VP_XPan
  38 - Player_VP_YPan