APE COMMANDS

Before you start reading about #windows and #switches, let’s get a few terms (and APE-script formats) straight:

DATA FORMATS

A number between 1 and X, a colon, and another number between 0 and 9999. These are evaluated literally as numbers by the APE compiler.

The same as the above, but in a string format. This allows variables to be used inside it, like:

10:110$whichnum$

(where $whichnum$ is the string-expansion-of-the-variable-value for the numeric variable “whichnum”.) Say whichnum is equal to 5. If this is in a GOTO statement, it will wind up at runtime as: GOTO 10:1105

Either a single command, or a set of commands surrounded by braces ("curly brackets").

Anything you can type in Quake's console.

An expression is a value or comparison:

<variable> true if value non-zero

<variable> > <variable> true if greater than

<variable> < <variable> true if less than

<variable> >= <variable> true if greater than or equal to

<variable> <= <variable> true if less than or equal to

<variable> != <variable> true if not equal to

You can combine any of these simple values or comparisons for a more complex expression, using parentheses, and logical operators.

(<expression> && <expression2>) || <expression3>)

&& means logical "and" (both expressions must be true)

|| means logical "or" (at least one of the expressions must be true)

^^ means logical "exclusive-or" (either the first or the second is true, but not both)

Of course, you may use these in any combination, and group them with parentheses as shown.

A series of text characters, usually inside quotation marks. You can print APE variable values inside a string expression by enclosing them in dollar signs:

body "X = $playerX$ Y = $playerY$ Item = $I[0]$"

Note the array must be concretely indexed--you can't have dollar signs inside dollar signs.

You can use the following character commands:

\n Print a newline character (go to the start of next line)

\\ Print a backslash.

\" Print a double quote.

A simple variable name, which can be made of letters, numbers, and underline characters (though the first character must always be a letter). Stylistically, variable names are usually found in one of two formats: interCaps, and underscore_word_separation. Note, however, that variable names in APE are NOT case-sensitive - that is, the variables “interCaps” and “InTeRcApS” are one and the same.

APE commands (#window)

The #window entry type is used to define an APE “window”. In APE, a window is used for displaying text or images (typically game dialogue) over a sustained period of time. Accordingly, it only allows commands that are useful in describing that window’s appearance (including font, graphics, geometry, etc.) and triggering events that happen upon its opening and closing. Note that windows can also be very useful as “sustained thinking objects” (see thinkswitch, below), even if they have no outward appearance (font, graphics, etc.).

Windows do not possess very much in the way of logical operations and flow branching; these tasks are left to the much-better-suited #switch entry type (see below).

Windows can generally be as large as they want (in terms of command-content, etc). However it is important to note that they are not sequential in their command execution; that is, window command-elements are executed in a fixed order (for instance, the sole “goto” command is always executed last) regardless of the order in which they were defined in the #window. =================================================================== COMMANDS

if (<expression>) <commandblock>

Command block, in a window, can only be one of the following statements: title body style font choice sound

This allows contextual presentation of the window data. Note that, in a #window, “else” is never allowed.

goto <bankentryexpression>

Go to the switch or window specified by when this window becomes closed. Each window may therefore have only one goto statement in it.

BankEntryExpression is usually of the form bbbb:eeee, where bbbb is a number from 1 to ____, and eeee is a number 0 to 9999.

It is called an expression, because you can do things like this:

goto 10:110$choicenum$

…where $choicenum$ is the string-expansion-of-the-variable-value of the APE variable “choicenum”. So, if choicenum = 5 then the statement Becomes “goto 10:1105”.

[set] <variable> = <expression>

Set a variable to the result of an expression's evaluation. Set is actually superfluous, but you can type it if you want. Note that if is followed by a single $ sign, it is considered to be a “string variable” in which case should itself be a string of some kind. (For instance, [set] mystring$ = “hello, world”.)

unset <variable>

Set a variable to zero. Variables equaling zero are removed from memory, so this is a good way to clean up. Likewise with string variables, which get a default (deallocated) value of “”.

title "<stringexpression>"

Title the window with text. The title of a window is printed first, and highlighted. You do not have to have a title for a window. Multiple “title” commands are allowed in a given window, and these are all appended together at run-time to display a single, composite window title.

body "<stringexpression>"

Add text to the body of a window. Multiple “body” commands are allowed in a given window, and these are all appended together at run-time to display a single, composite window text-body.

xyprint "<stringexpression>" <xloc> <yloc>

Print the "<stringexpression>" at that location in the window. The location corresponds to the upper-left pixel of the text, not the baseline. Note that <xloc> and <yloc> are window-relative coordinates, which means 0, 0 is at the upper-left corner of the window. Multiple xyprints per window are allowed.

startconsole "<consolecommandline>"

Execute the listed console command line before the window is presented. The command line can have multiple console commands separated by semi-colons. There may only be one “startconsole” command per window.

finishconsole "<consolecommandline>"

Execute the listed console command line after the window is terminated. The command line can have multiple console commands separated by semi-colons. There may only be one “finishconsole” command per window.

style "<windowstyle>"

style "NULL"

Make the window border of type . See later docs for format of data. For no border, use style "NULL".

font "<fontname>"

Use the proportional font of name . Fonts should be in the Anoxdata\Fonts directory, in the correct format, and saved as a .PCX. (Index 255 color is used as the transparent color.) If you can't figure it out from the PCXs there, it's 256 x 256, 256 color, and each character must fit within a 16 x 16 character tile, starting with ASCII 0 (non-printable characters are usually ones used by the system for special stuff, like the bar drawn in the console). Tiles are arranged by ASCII character value, so the 65th tile (four rows down and one column over) should be a 16x16 picture of the character ‘A’. (Actually this is just exactly like the Quake font format, but nicely proportional.) In the future, 32-bit RGBA Targa images will also be allowed as proportional fonts.

xpos <xposition>

The left side of the window-interior should be at . The border is drawn OUTSIDE of the location of the window. See pos.

ypos <yposition>

The top side of the window-interior should be at . The border is drawn OUTSIDE of the location of the window. See pos.

width <windowwidth>

Set width of window to (duh) <windowwidth>. This is the actual width of the inside of the window frame (in pixels). See size.

height <windowheight>

Set width of window to (doy) <windowheight>. This is the actual height of the inside of the window frame (in pixels). See size.

maxheight <maxwheight>

Set the maximum height the window will automatically expand to <maxwheight>.

pos <xloc>,<yloc>

Set the X,Y position of the upper left corner of the inside of the windowframe (if there is one) to <xloc>,<yloc> . This area is also know as the Content Area. <xloc> and <yloc> are given in screen-pixel-coordinates.

size <xloc>,<yloc>

Set the width and height of the window's Content area at the same time.

image <imagepathname> <xexpression>,<yexpression>,<xsize>,<ysize>

Draw the image file at the given X,Y position, optionally scaled to xsize and ysize. The file can be a BMP, PCX, or TGA. If no path is given, the path "anoxdata\gameflow" is assumed, but don't put it there or you suck. BMPs are opaque, PCXs have transparency (index #255), and TGAs have translucency (8-bit alpha channel).

background "<imagepathname>" [,TILE] [,STRETCH]

Use the image as the background of the window. It will stretch the graphic unless you specify TILE, which, of course, doesn't work yet. STRETCH is what it always does, so Heaven knows why it's a frickin' reserved word. (F you! -squirrel)

flags <flagindex>,TRUE (or FALSE)

Set APE flags to true or false. Right now, you can only use this with one flag...which escapes my mind at the moment. Squirrel? (passive2d) - This flag prevents a 2d window from being closed with a click.

choice "<choicetextexpression>" <bankentrynumber>

Add the text <choicetextexpression> to a bulleted list of choices after the title and body. If this choice is clicked on, then execute the switch or window . I do not believe you can do anything funny with the bank and entry numbers. (Not sure if this is true… -squirbel) The bullet character in the font is character 10, and the highlighted bullet is character 12 (zero-relative).

sound <soundfilepathname>

Play the specified sound file when the window is opened.

startswitch <bankentrynumber>

Before the window is presented, execute this switch.

thinkswitch <bankentrynumber>

Before the first time the window is presented, execute this switch, and execute it every server frame the window is present. This is extremely powerful, and is the basis for almost all APE-based games.

finishswitch <bankentrynumber>

Execute this switch when the window is terminated. (Used for cleaning up variables and such.)

=============================================================================

APE commands (#switch)

A switch is a code block, executed instantaneously. You can do just about anything, except draw stuff to the window. Switches are limited to approximately 30 commands each, for code-efficiency reasons. Here are the commands you can use.

COMMANDS

console [consolecommandline]

Like startconsole, but this command is pushed at the moment this statement is executed. Try to make sure there isn’t a

“better way” of doing something before resorting to using the already-overcrowded console buffer.

extern [command] [arguments]

Use a command defined in another module. It is responsible for the format of the arguments. This is typically used to

expose functions from such modules as AI, Music, and Battle to the APE language.

gosub [bankentryexpression]

Go to the switch or window at [bankentryexpression], then come back here and keep going.

goto [bankentryexpression]

Go to the switch or window at [bankentryexpression]...and DON'T COME BACK! Ya here me!

if ([expression]) [commandblock]

else if [commandblock]

else [commandblock]

If expression is true, then execute [commandblock].

If it is false and there is an else after it, execute the command block after the else. You can keep checking cases by

having if, then an else if, then else if, and so on. An else at the end with no if will terminate the big ol' if statement.

set

Same as in #window.

unset

Same as in #window.

while ([expression]) [commandblock]

While [expression] is true, execute the code in the command block. Usually, the code will do something and

increment a counter, and the complex expression is waiting for that counter to reach a certain value. Alternately, the

code will keep checking something, and set a flag when that something comes about.

A complex expression is simply anything you can also put in an if statement. And, of course, sound SHOULD be okay in a switch too--if Squirrel ever does it. (F you! -squirgel) (F ya back -Tomb)

ALGEBRAIC FUNCTIONS & PSEUDOVARIABLES

(usable wherever an algebraic expression is allowed)

func_mod[number,modval] (integer division remainder)

func_div[number,divby] (integer division, rounded down)

func_ceil[number,divby] (round up)

func_floor[number,divby] (round down)

func_trunc[number,divby] (same as func_floor)

func_round[number,divby] (round to nearest int)

func_drand[low,high] (random integer between LOW and HIGH, inclusive)

func_frand[] (random float from 0.00f to 1.00f)

func_rcos[radians] (cosine, in radians)

func_dcos[degrees] (cosine, in degrees)

func_rsin[radians]

func_dsin[degrees]

func_rtan[radians]

func_dtan[degrees]

func_ratan2[y, x] (arctangent of y,x, in radians)

func_datan2[y, x] (arctangent of y,x, in degrees)

func_abs[number] (absolute value)

func_inventory[itemname] (the amount of the named item in the party inventory - NOT YET INTERFACED TO NOXGAME!)

func_playerstats[charname,stat] (the stat-value of the specified stat for the specified player-character - NOT YET INTERFACED TO NOXGAME!)

func_charinparty[charname] (3=party leader, 2=present in party, 1=joined but not present, 0=never joined, 0.5=retired, or some dumb shit like that.)

func_gamestate[] (returns a different value based on whether we're in combat, stats, shop, etc.)

func_cvar[cvarname] (returns the float-value of the named console variable)

func_pow[num,power] (returns the value when x is raised to the y power)

func_fileexists[filepathname] (returns nonzero if the named file exists in the default APE/gameflow path)

func_gametime (returns the number of milliseconds since the game began (ie: final fantasy, etc.))

func_realtime (returns the system time - milliseconds since midnight, Jan 1, 1970)

func_maptime (returns the number of milliseconds since the map began)

func_timer (high-precision millisecond timer, wraps once per hour)

func_mousex (x screen coordinate of mouse cursor (2d/3d - it's all the same) 0 is left side of screen

func_mousey (y screen coordinate of mouse cursor (2d/3d - it's all the same) 0 is top of screen

func_atof[variable] (text converted to a float number)

func_cursorentity (The edict number of the last entity you clicked on.)

func_lastbattledamage (The amount of damage dealt on the last attack in battle.)

func_lastattacker$ (The targetname of the last attacker in battle.)

func_lastdefender$ (The targetname of the last defender in battle.)

func_LastBattleButtonNumber (The number of the last battle icon clicked.)

func_LastBattleButtonPlayer (???)

func_LastBattleButtonTime (The time when a battle icon was last clicked.)

random (kind of obsolete, but still okay - has a random integer value from 0 to 99)

kidz (1 if "kidz mode" (censored language, etc.), 0 if adult mode)

STRING PSEUDOVARIABLES (this will be changing as soon as strings are finished -squirrel)

partyleadername (the string-name of the partyleader - I'll probably replace this with "partymembername[0]", etc.)

mapname (the string-name of the current map)

username (the anachronox player-user-login-name, or the windows username)


setvar_flexible <varname> <value>

This extern sets the varname you specified as a varaible with the value that you specified. Varname can be either the literal name of the new variable or a string. Value can be a literal number or a variable.


getvar_flexible <varname> <return variable>

This extern looks up the variable name specified and returns the value of it in the variable you specify. The varname can be either the literal name of the variable or a string.


checkgamestate <varname>

This extern returns a 1 for normal walking around gamestate, or a 0 for other gamestates.

AI/ENTITY EXTERN COMMANDS


AI_TalkStop <targetname/sequence>

Force the entity to stop talking or "hanging out" after talking.


AI_AddWaypoint <handlevar> <x> <y> <z>

Add a waypoint to the entity's waypoint queue. The entity will visit them in the order they are added to the queue.


AI_SnapMove <handlevar>

Turn off interpolation for one frame. Use this when you want to "teleport" and entity somewhere else.


AI_FindEntity <return value (handlevar)> <targetname/sequence>

Finds an entity in the map that has a matching targetname or sequence and sets handlevar to the edict number. The return value is -1 if no entity could be found.


AI_Distance3d <return value> <handlevar A> <handlevar B>

Returns the distance in 3d pixels between entity A and entity B.


AI_DistanceSquared3d <return value> <handlevar A> <handlevar B>

Returns the squared distance in 3d pixels between entity A and entity B. This should be used for distance comparisons where efficiency matters, because the function doesn't have to do a square root to find the actual distance in pixels.


AI_Distance2d <return value> <handlevar A> <handlevar B>

Returns the distance between entity A and entity B in the X/Y plane, ignoring the Z values.


AI_GetEdictNumber <targetname/sequence/character (boots,pal...)> <return value (handlevar)>

Does the same thing as AI_GrabEntity, but doesn't actually grab the entity. In other words, gives you a handle for the entity without affecting the entity in any way. BEWARE: make sure you know what you are doing when using this, as an entity that you previously got a handle for could be a different entity now...


AI_GetPlayerLocation <returned x> <returned y> <returned z>

Gets the x,y,z location of the player.


AI_SpawnEntity <return value (handlevar)> <classname> [targetname] [sequence] [targetname of path_corner to spawn at]

Spawns a new entity with the given classname, optionally a targetname and sequence, and optionally at exact location of another specified entity (usually a path_corner).


AI_DestroyEntity <handlevar>

Completely remove the entity from the world and destroy the handle. No, you don't have to call AI_ReleaseEntity after this.


entkey <handlevar> <epair> <value>

Add edicts to entities spawned with APE, (ex: extern entkey door_handle "wsequence" "55:5555")


AI_GrabEntity <targetname/sequence> <return value (handlevar)>

Tries to find an entity in the world with a matching targetname or sequence. If there is one, the entity is frozen and stops what it's doing so that it can execute any future commands you will issue from APE. To put the entity back to normal, you must call AI_ReleaseEntity.


AI_ReleaseEntity <handlevar>

Lets the entity go back to what it was doing before. BEWARE! Do not use a handlevar for an entity that you have already released unless you are positive that it's still valid.


Ent_GetClosestToPoint <X> <Y> <Z> <handlevar>

Get the entity closest to any X Y Z coordinates. GetClosestToPoint will ignore all "func_wall" and "func_areaportal" entities, as well as anything with a non-alpha first character in classname. Returns (-1) if there was nothing found. There is no radius limit. Even if point is at one side of the universe and the only entity is at the other side of the universe, it will find it. Also, when looking for bmodels (triggers, doors, etc), it finds the center point of the entity and uses that to determine distance. So, if you have ONE entity consisting of two brushes that are far apart, the center point will be somewhere between the two brushes and probably not anywhere near either of them... just something to be aware of.


Ent_GetSpecificClosestToPoint <classname> <X> <Y> <Z> <handlevar>

Get an entity of a specific classname closest to any X Y Z coordinates. So for example if you wanted to grab a door, the class name would be "func_door". Returns (-1) if there was nothing found. There is no radius limit. Even if point is at one side of the universe and the only entity is at the other side of the universe, it will find it. Also, when looking for bmodels (triggers, doors, etc), it finds the center point of the entity and uses that to determine distance. So, if you have ONE entity consisting of two brushes that are far apart, the center point will be somewhere between the two brushes and probably not anywhere near either of them... just something to be aware of.


AI_Wait <handlevar> <duration in whole seconds or gamevar with value>

Tells the entity to stop right where it is and wait for some number of seconds. If you tell it to wait -1 seconds, it will stay there forever.


AI_WaitAndFace <handlevar> <duration in whole seconds or gamevar with value> <targetname/sequence of ent to face>

Same as AI_Wait, but the entity will also face the other entity that you specify.


AI_SeekAndTouch <handlevar> <targetname/sequence of destination>

Tells the entity to walk toward the specified entity until their bounding boxes are touching.


AI_SeekAndFace <handlevar> <targetname/sequence of target> [targetname/sequence of ent to face]

Tells the entity to walk to a specific entity (usually a path_corner), then face another entity. If you don't specify another entity to face, it will face the same direction as the target entity (the path_corner).


AI_Seek <handlevar> <targetname/sequence of target ent>

Tells the entity to walk to a specific entity (usually a path_corner).


AI_SetCompletionCallback <handlevar> <sequence number to call>

When the entity is done with whatever command you last gave it, it will invoke the sequence you specify here.


AI_FollowLoose <handlevar> <targetname/sequence of leader> <x offset> <y offset> <z offset>

Don't use it.


AI_FollowRigid_Stop <handlevar>

Force an entity to stop following it's leader, if any.


AI_FollowRigid <handlevar> <targetname/sequence of leader> <distance along trail to follow by>

Make an entity follow a leader, FF8 style.


AI_Path <handlevar> <targetname of path_corner to start at>

Make an entity start walking a path, given a path_corner to start on.


AI_DeSolifity <handlevar>

Make an entity non-solid. Nothing can touch it and it can go through walls.


AI_GetForward <handlevar> <return value X> <return value Y> <return value Z>

Get the unit vector that points in the entity's forward direction.


AI_SpeedMoveTo <handlevar> <speed> <destination X> <destination Y> <destination Z>

Magically float the entity to the desired location, moving at a specific speed.


AI_TimeMoveTo <handlevar> <time in seconds> <destination X> <destination Y> <destination Z>

Magically float the entity to the desired location, arriving in a specific number of seconds.


AI_WaypointPath <handlevar> <targetname of first path_corner in sequence>

The entity will basically start at the path_corner you give it, then walk the entire path to the end, then go back to whatever it was doing before. BEWARE! Make sure the path doesn't loop!


AI_AvoidWorld <handlevar> <"true" or "false">

Toggle whether the entity should try to avoid the world or not.


AI_AvoidEnts <handlevar> <"true" or "false">

Toggle wether the entity should try to avoid other entities or not.


AI_GetXYZ <handlevar> <return value X> <return value Y> <return value Z>
AI_GetX <handlevar> <return value>
AI_GetY <handlevar> <return value>
AI_GetZ <handlevar> <return value>

AI_SetXYZ <handlevar> <new X value> <new Y value> <new Z value>
AI_SetX <handlevar> <new value>
AI_SetY <handlevar> <new value>
AI_SetZ <handlevar> <new value>

AI_SetVelocityXYZ <handlevar> <new X value> <new Y value> <new Z value>
AI_SetVelocityX <handlevar> <value>
AI_SetVelocityY <handlevar> <value>
AI_SetVelocityZ <handlevar> <value>

AI_GetVelocityXYZ <handlevar> <return value X> <return value Y> <return value Z>
AI_GetVelocityX <handlevar> <return value>
AI_GetVelocityY <handlevar> <return value>
AI_GetVelocityZ <handlevar> <return value>

AI_ZeroVelocity <handlevar>

AI_SetYawVelocity <handlevar> <value>
AI_SetPitchVelocity <handlevar> <value>
AI_SetRollVelocity <handlevar> <value>

AI_GetYawVelocity <handlevar> <return value>
AI_GetPitchVelocity <handlevar> <return value>
AI_GetRollVelocity <handlevar> <return value>

AI_GetScale <handle> <return value X> <return value Y> <return value Z>
AI_SetScale <handlevar> <value X> <value Y> <value Z>

AI_SetYaw <handlevar> <value>
AI_SetPitch <handlevar> <value>
AI_SetRoll <handlevar> <value>

AI_GetYaw <handlevar> <return value>
AI_GetPitch <handlevar> <return value>
AI_GetRoll <handlevar> <return value>