Blind Fury Scripting documentation v0.3 for Blind Fury engine beta v0.4

-Introduction

Writing a script for Blind Fury is much like coding a program in basic - so I recommend that you have some elementary programming skills in a language like Basic, Pascal or C (or any languages based on them). Unlike a real programming language, Blind Fury script lacks one major feature: user variables. The only variables you can use/have access to are the variables that are used within the game. These variables are:

 CANCEL				-Not a variable - used when you want to cancel a command (covered later in example)
 PLAYER1_X			-The x co-ordinate of player 1
 PLAYER1_Y			-The y co-ordinate of player 1
 PLAYER1_STATE 			-The action state of player 1
 PLAYER1_ANIM			-The animation state of player 1
 PLAYER2_X 			-See above
 PLAYER2_Y 
 PLAYER2_STATE 
 PLAYER2_ANIM
 MONSTER1_X 
 MONSTER1_Y 
 MONSTER1_STATE 		-The AI decision state of enemy 1
 MONSTER1_ANIM			-The animation state of enemy 1
 MONSTER2_X 
 MONSTER2_Y 
 MONSTER2_STATE 
 MONSTER2_ANIM
 MONSTER3_X 
 MONSTER3_Y 
 MONSTER3_STATE 
 MONSTER3_ANIM
 MONSTER4_X 
 MONSTER4_Y 
 MONSTER4_STATE 
 MONSTER4_ANIM
 MONSTER5_X 
 MONSTER5_Y 
 MONSTER5_STATE 
 MONSTER5_ANIM
 MONSTER6_X 
 MONSTER6_Y 
 MONSTER6_STATE 
 MONSTER6_ANIM
 MONSTER7_X 
 MONSTER7_Y 
 MONSTER7_STATE 
 MONSTER7_ANIM
 MONSTER8_X 
 MONSTER8_Y 
 MONSTER8_STATE 
 MONSTER8_ANIM
 MONSTER9_X 
 MONSTER9_Y 
 MONSTER9_STATE 
 MONSTER9_ANIM
 MONSTER10_X 
 MONSTER10_Y 
 MONSTER10_STATE 
 MONSTER10_ANIM
 BACKGROUND_X 			-The x co-ordinate of the background (how far across it has scrolled)
 BACKGROUND_Y 			-The y co-ordinate of the background (how far up/down it has scrolled)
 FOREGROUND_X 
 FOREGROUND_Y 
 STOPBG 			-Whether or not the foreground should start to disappear

These are constants you can use:

 MONSTER_AMOUNT 		-The amount of monsters on the screen (cannot be changed)
 PLAYER1			-These are character definitions (e.g. used in MOVE_CHAR)
 PLAYER2
 MONSTER1
 MONSTER2
 MONSTER3
 MONSTER4
 MONSTER5
 MONSTER6
 MONSTER7
 MONSTER8
 MONSTER9
 MONSTER10
 LEVEL1X 			-The width of the level 1 image
 LEVEL1Y 			-The height of the level 1 image
 LEVEL1BG1X 			-The width of the level 1 foreground image
 LEVEL1BG1Y	 		-The height of the level 1 foreground image
 BAD1X				-The width of the enemy
 BAD1Y				-The height of the enemy
 PLAYER1X			-The width of the player
 PLAYER1Y			-The height of the player
 STAND				-Animation/state value
 ATTACK				-Animation/state value
 WALK 				-Animation/state value
 PAIN 				-Animation/state value
 JUMP 				-Animation/state value
 NONE				-AI decision define
 CIRCLE				-AI decision define (circle clockwise)
 CIRCLE2			-AI decision define (circle anti-clockwise)
 APPROACH			-AI decision define (approach player and hover/attack)

There is no point in changing the player states, as they will just be reset - all they contain is slightly different details on what animation the player is in. For enemies though, the state contains their current thought (AI decision), so changing that will change the way they act.
To form a command in the script, you group the command words, which are:

 END 				-End of script
 DRAWSKY 			-Draw the background sky
 DRAWBG 			-Draw the background
 DRAWFG 			-Draw the foreground
 DRAWFXFG 			-Draw the hi-detail fx-foreground (hi-detail mode only)
 ADDMONSTER 			-Add a monster
 MOVE 				-Enable player controls
 STOPMOVE 			-Disable player controls
 STOP_UNTIL	 		-Stop the screen from scrolling until...
 CHANGE_VALUE 			-Change the value of any of the variables listed above
 MOVE_CHAR 			-Move a player/monster (makes them walk)
 DRAWTEXT 			-Draw text on the screen
 WAIT_UNTIL 			-Stop executing script commands until...
 GO 				-Allow the screen to scroll
 DRAW_CHARS 			-Draw all the characters on the screen
 STOP 				-Disallow the screen to scroll
 END_LEVEL 			-Indicate end of level
 DRAW_SPRITE 			-Draw a sprite
 DO_UNTIL 			-Execute a command until...
 ADD_TIME 			-Add a number to the time counter
 GOTO				-Goto a place in the code
 ADDTO_VARIABLE			-Add an amount to any of the variables listed above
 IF				-If ... is true then do ...
 END_IF				-Used in conjunction with IF
 ELSE				-Used in conjunction with IF
 END_ELSE			-Used in conjunction with ELSE
 FADEOUT			-Fades the screen out (does not remain faded)
 FADEIN				-Fades the screen in
 EXECUTE_BLOCK			-Starts a multiple execution block
 END_BLOCK			-Used with EXECUTE_BLOCK
 SKIP				-Used to skip a script execution
 PLAY_MUSIC			-Used to start the music playing
 STOP_MUSIC			-Used to stop the music playing

Definitions that have dots after them can be grouped with these operators:

 VALUE_EQUALTO 		- VAR 1 = VAR 2
 VALUE_NOTEQUALTO 	- VAR 1 <> VAR 2
 VALUE_GREATERTHAN 	- VAR 1 > VAR 2

Syntaxes:

FADEOUT - Used on its own (NOTE: The image does not stay faded afterwards, so a fadein is required straight afterwards or in a multiple execution block straight afterwards (see example below)

EXECUTE_BLOCK:
EXECUTE_BLOCK,
...,
...,
END_BLOCK
Where ...'s are, commands can go. All the commands work, but some are uneffective or can cause an infinite loop and effectively halt the system when running under dos. NOTE: Do not use UNTIL commands that are based on variables that only change while the game is running. Also never tell the script to goto a position outside of the block.

SKIP - Used on its own

PLAY_MUSIC:
PLAY_MUSIC, MUSICVAR - Where MUSICVAR is a valid song name

FADEIN - Used on its own

END - Just goes on its own

DRAWSKY - Used on its own

DRAWBG - Used on its own

DRAWFG - Used on its own

DRAWFXFG - Used on its own

ADDMONSTER:
ADDMONSTER, MONSTER_TYPE, X, Y - Where MONSTER_TYPE is a valid monster type, and x and y are where to place the enemy

MOVE - Just goes on its own

STOPMOVE - Just goes on its own

STOP_UNTIL:
STOP_UNTIL, VALUE_GREATERTHAN, VAR1, VAR2 - Where VAR1 and VAR2 are any positive number (including zero) or a game variable

CHANGE_VALUE:
CHANGE_VALUE, VAR, NUMBER - Where VAR is a valid game variable and number is the number to change it to

MOVE_CHAR:
MOVE_CHAR, CHARCODE, X, Y - Where Charcode is the player you want to move (see constants above)

DRAWTEXT:
DRAWTEXT, DATAPOINTER - Due to the limitations of the scripting engines, the text has to be hard-coded into the game (see later example)

WAIT_UNTIL is the same as stop until.

GO - Used on its own

DRAW_CHARS - Used on its own

STOP - Used on its own

END_LEVEL - Used on its own

DRAW_SPRITE:
DRAW_SPRITE, SPRITE, X, Y, DIRECTION - Where SPRITE is a valid game sprite, and x and y are the place to put it and DIRECTION is LEFT or RIGHT

DO_UNTIL:
COMMAND1,
DO_UNTIL, VALUE_GREATERTHAN, VAR1, VAR2 - COMMAND1 will be executed until the statement becomes true

ADD_TIME:
ADD_TIME, NUMBER - Where number is the number to add to the timer (the timer never exceeds 99 seconds)

GOTO:
GOTO, NUMBER - Go to a certain place in the code (a bit useless without the IF statement...)

ADDTO_VARIABLE:
ADDTO_VARIABLE, VAR, NUMBER - Where VAR is a valid game variable and number is the number to add to that variable

IF:
IF, VALUE_GREATERTHAN, VAR1, VAR2, ... , END_IF, ELSE, ..., END_ELSE - If the statement is true, commands between the IF command and the END_IF operator will be executed. If the statement is false, the commands between ELSE and END_ELSE will be operated. Even if there are no else commands, it is compulsary to put all the operators listed above.

After every operator must go a comma. The manual might not be too clear at the moment, so here is an example script. This is used in level 1 of the beta:

 CHANGE_VALUE, LEVELX, 1537,	 			-Level header part 1 (this is executed only once)
 CHANGE_VALUE, LEVELY, 480,				-All these variables are used in the second part
 CHANGE_VALUE, FOREGX, 1088,				-of the level header.
 CHANGE_VALUE, FOREGY, 480,
 CHANGE_VALUE, FOREGSPEED, 2,
 CHANGE_VALUE, FXSPEED, 4,
 CHANGE_VALUE, LEVELIMAGE, L1BACKG1,
 CHANGE_VALUE, FOREGIMAGE, L1FOREG1,
 CHANGE_VALUE, FXIMAGE, FXFOGHI,
 CHANGE_VALUE, SKYIMAGE, NONE,
 CHANGE_VALUE, SKYMOVE, NONE,
 CHANGE_VALUE, PLAYER1_X, 0-PLAYER1X,
 CHANGE_VALUE, PLAYER1_Y, 300,
 PLAY_MUSIC, LEVEL1MUSIC,

 DRAWSKY,						-Level header part 2 (this is executed every frame)
 DRAWBG,
 DRAW_CHARS,
 DRAWFG,
 DRAWFXFG,						-End of header

 SKIP,							-The two skips are to avoid going back to the first script position
 SKIP,							-which causes errors
 MOVE_CHAR, PLAYER1, 100, 300,				-Make player1 walk onto the screen
 GO,							-Go
 WAIT_UNTIL, VALUE_GREATERTHAN, BACKGROUND_X, 90,	-Stop the script until the background has scrolled on 90 pixels

 EXECUTE_BLOCK,						-Open multiple execution block
 ADDMONSTER, 5, 0-BAD1X, 280,				-Add three monsters
 ADDMONSTER, 5, 0-BAD1X, 300,
 ADDMONSTER, 5, 640, 280,
 END_BLOCK,						-Close multiple execution block

 STOP_UNTIL, VALUE_EQUALTO, MONSTER_AMOUNT, 0,		-Stop until there are no more monsters left
 ADD_TIME, 20,						-Add 20 seconds to the counter
 WAIT_UNTIL, VALUE_GREATERTHAN, BACKGROUND_X, 270,

 EXECUTE_BLOCK,
 ADDMONSTER, 5, 0-BAD1X, 280,
 ADDMONSTER, 5, 0-BAD1X, 290,
 ADDMONSTER, 5, 640, 290,
 ADDMONSTER, 5, 640, 300,
 ADDMONSTER, 5, 640, 310,
 ADDMONSTER, 5, 0-BAD1X, 320,
 END_BLOCK,

 STOP,							-Stop the scrolling

 DRAWTEXT, EVERYONE_GET_HIM,				-Draw the text on the screen "Everyone get him!"
 DO_UNTIL, VALUE_GREATERTHAN, 6, MONSTER_AMOUNT,	-Keep drawing the text every frame until there are less than 6
							-monsters on the screen
 WAIT_UNTIL, VALUE_GREATERTHAN, 2, MONSTER_AMOUNT,	-Wait until there is only 1 monster on the screen

 DRAWTEXT, DONT_HURT_ME,
 DO_UNTIL, VALUE_EQUALTO, MONSTER_AMOUNT, 0,

 GO,
 ADD_TIME, 40,

 WAIT_UNTIL, VALUE_GREATERTHAN, BACKGROUND_X, 867,
 FADEOUT,						-Fade to black

 EXECUTE_BLOCK,
 CHANGE_VALUE, PLAYER1_X, 0-PLAYER1X,			-New level header
 CHANGE_VALUE, PLAYER1_Y, 300,
 CHANGE_VALUE, LEVELX, 1024,
 CHANGE_VALUE, LEVELY, 480,
 CHANGE_VALUE, FOREGX, 1024,
 CHANGE_VALUE, FOREGY, 480,
 CHANGE_VALUE, FOREGSPEED, 1,
 CHANGE_VALUE, LEVELIMAGE, L1BACKG2,
 CHANGE_VALUE, FOREGIMAGE, L1FOREG2,
 CHANGE_VALUE, FXIMAGE, NONE,
 CHANGE_VALUE, BACKGROUND_X, 0,
 CHANGE_VALUE, BACKGROUND_Y, 0,
 CHANGE_VALUE, FOREGROUND_X, 0,
 END_BLOCK,

 FADEIN,						-Fade in
 MOVE_CHAR, PLAYER1, 100, 300,				-Make the character walk onto the screen

 WAIT_UNTIL, VALUE_GREATERTHAN, BACKGROUND_X, 90,
 ADDMONSTER, 5, 0-BAD1X, 280,

 WAIT_UNTIL, VALUE_GREATERTHAN, BACKGROUND_X, 200,
 ADDMONSTER, 5, 0-BAD1X, 300,

 WAIT_UNTIL, VALUE_GREATERTHAN, BACKGROUND_X, 350,
 ADDMONSTER, 5, 640, 280,

 WAIT_UNTIL, VALUE_EQUALTO, MONSTER_AMOUNT, 0,
 DRAWTEXT, ENDOFBETATEST,
 DO_UNTIL, VALUE_NOTEQUALTO, MONSTER_AMOUNT, 0,

 END

The second part of the level header is carried out in addition to wherever the script might actually be at, as they define what should be drawn in the level. You should be able to see what this script does, but if you can't, try printing this out and running through it while playing the game.

NB: Don't try to have more than 10 monsters on the screen at the same time - it wont work.

Other operators soon to be added that you may want to consider using:
DRAW_ITEM:
DRAW_ITEM, ITEMCODE, X, Y - Where ITEMCODE is a valid item code and where x and y are the world co-ordinates (background co-ordinates)

Also, if you haven't read the readme file, to activate the debugging mode, press 'p' at the title screen. This shows information about some important variables that control the game and scripting that can be useful. This mode hasn't been finished - later on, I will make two seperate versions - one with development features and one without. The debugging mode in this version is very primitive, but it should help slightly.