# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
# Online Help file for DIV Games Studio 3.0 (Castellano)
# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

# Empty lines are meant to be end of paragraphs.

# Comments can only start or begin by a '#' character
# on first column of line

# List of available commands

# Bold text:
#   {text}

# Terminus definition: (previous line must be an empty one)
#   {.N,title}
#   text ...

# Reference to a terminus:
#   {#N,text}

# Image: (N:code within help.fig (FPG), C:centred 0, 1 or 2)
#   {+N,C}

# End of image (must be signalled or indicated on all images)
#   {-}

# Character '{' o '}':
#   {{} o {}}

# Dividing line
#   {/}

# Simple carriage return
#   ú  (shift+3)

# Text of lenguaje.div:
#   {@N}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
# Bad page reference (the equivalent of http 404)
# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.0,Invalid hypertext link}

Error: There is no help page associated to this link.

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
# Help with using the Help system 
# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1,How to use the help system}{+5,1}{-}

The help system works in a similar way to an internet browser window, each page is
linked using a hyperlink system.

Use the mouse to navigate the help pages, or use the following keys.

{Cursors}  - Move the text a single line at a time.ú
{Page Up/Page Down}  - Go up or down one page.ú
{ESC}  - Exit the help window.ú
{Backspace}  - To return to the previous page.ú

These controls can be used only when the help window is selected
(to select a window you just have to click the mouse over it).

In the lower right part of the screen there is button that you can use to {change the
size of the help window}. Simply click on the button, and whilst holding, drag with the
mouse to change its size.

The words that appear in {#1,white colour} are {hyperlinks to other
help pages} (the mouse cursor will look like a small hand when you are over the words). Click
on these words to jump to the relevant page.

The {examples} are small programs or parts of programs that appear in the Help
to show the user how to use the functions and operations in the DIV language. All
of them begin with a white colour line, as you can see right here:

{#9999,Example program:}
PROGRAM example;

BEGIN
    // ...
END
{-}

To try the example program, just click on the white line.
These programs can be run with the {F10} key and ended by pressing the
{ALT}+{X} keys, the same as any other program.

{/}

In the upper part of the help window you can see a group of buttons to navigate the pages.
({<<} Backwards and {>>} Forwards), ({Index}, {Glossary} and {Functions}),
send the current page to the printer ({Print}), and information on how to use the help
system ({?}).

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
# General Index
# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.3,General index}{+2,1}{-}

{#2000,Introduction to DIV Games Studio 2015}ú

{Help about the program language}ú

  {#4,Glossary of Terms}ú
  {#1000,Syntax of a program}ú
  {#1017,Declaration of statements}ú
  {#1032,List of functions}ú

  {#1202,Predefined constants}ú
  {#1200,Predefined global data}ú
  {#1201,Predefined local data}ú

  {#1035,Arithmetic Expressions}ú
  {#1037,Logical conditions}ú

  {#1176,Key table Codes}ú

  {#2001,Language News}ú

{Help about key table commands}ú

  {#1291,Graphical environment Commands}ú
  {#1292,Normal Commands in the games}ú
  {#1293,Commands in the program debugger}ú
  {#1294,Commands in the program editor}ú
  {#1295,Commands in the graphical editor}ú

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
# Glossary of Terms
# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.4,Glossary of Terms}{+3,1}{-}

{#1046,!=}ú
{#1045,!}ú
{#1047,"}ú
{#1049,%=}ú
{#1048,%}ú
{#1051,&&}ú
{#1052,&=}ú
{#1050,&}ú
{#1047,'}ú
{#1053,(}ú
{#1053,)}ú
{#1002,*/}ú
{#1055,*=}ú
{#1054,*}ú
{#1057,++}ú
{#1058,+=}ú
{#1056,+}ú
{#1059,,}ú
{#1061,--}ú
{#1062,-=}ú
{#1063,->}ú
{#1060,-}ú
{#1064,..}ú
{#1063,.}ú
{#1002,/*}ú
{#1002,//}ú
{#1066,/=}ú
{#1065,/}ú
{#1067,:}ú
{#1068,;}ú
{#1071,<<=}ú
{#1070,<<}ú
{#1072,<=}ú
{#1046,<>}ú
{#1069,<}ú
{#1072,=<}ú
{#1074,==}ú
{#1075,=>}ú
{#1073,=}ú
{#1075,>=}ú
{#1078,>>=}ú
{#1077,>>}ú
{#1076,>}ú
{#1079,[}ú
{#1079,]}ú
{#1081,^=}ú
{#1082,^^}ú
{#1079,^}ú
{#1084,|=}ú
{#1083,||}ú
{#1083,|}ú
{#1176,_a, _b, _c, ...}ú
{#1400,_case_sensitive}ú
{#1400,_extended_conditions}ú
{#1400,_free_sintax}ú
{#0231,_hidden}ú
{#1400,_ignore_errors}ú
{#1400,_max_process}ú
{#1400,_no_check}ú
{#1400,_no_id_check}ú
{#1400,_no_null_check}ú
{#1400,_no_optimization}ú
{#1400,_no_range_check}ú
{#1400,_no_strfix}ú
{#0231,_normal}ú
{#1400,_simple_conditions}ú
{#0231,_subdir}ú
{#0231,_system}ú
{#0231,_volid}ú
{#0100,abs()}ú
{#0246,acos()}ú
{#0101,advance()}ú
{#0250,all_drawing}ú
{#1162,all_sound}ú
{#1161,all_text}ú
{#1051,and}ú
{#1129,angle}ú
{#1409,argc}ú
{#1409,argv[]}ú
{#1109,ascii}ú
{#0245,asin()}ú
{#0247,atan()}ú
{#0248,atan2()}ú
{#1086,begin}ú
{#1120,bigbro}ú
{#1026,break}ú
{#1404,byte}ú
{#1175,c_0 ... c_9}ú
{#1169,c_m7}ú
{#1412,c_m8}ú
{#1167,c_screen}ú
{#1168,c_scroll}ú
{#0254,calculate()}ú
{#1087,case}ú
{#0256,change_channel()}ú
{#0102,change_sound()}ú
{#1416,channel[]}ú
{#0184,char()}ú
{#0235,chdir()}ú
{#0103,clear_screen()}ú
{#1030,clone}ú
{#1134,cnumber}ú
{#0104,collision()}ú
{#1400,compiler_options}ú
{#1171,complete_dump}ú
{#1174,complete_restore}ú
{#0262,compress_file()}ú
{#1004,const}ú
{#1027,continue}ú
{#0105,convert_palette()}ú
{#0243,cos()}ú
{#1122,ctype}ú
{#1031,debug}ú
{#0261,decode_file()}ú
{#1088,default}ú
{#0106,define_region()}ú
{#0250,delete_draw()}ú
{#0107,delete_text()}ú
{#1413,dirinfo (struct)}ú
{#0238,disk_free()}ú
{#0249,draw()}ú
{#1418,draw_z}ú
{#1114,dump_type}ú
{#1089,dup}ú
{#1090,else}ú
{#0259,encode()}ú
{#0260,encode_file()}ú
{#0108,end_fli()}ú
{#1091,end}ú
{#0109,exit()}ú
{#0110,fade()}ú
{#0111,fade_off()}ú
{#0112,fade_on()}ú
{#1107,fading}ú
{#1152,false}ú
{#1104,fast_mixer}ú
{#1117,father}ú
{#0224,fclose()}ú
{#0113,fget_angle()}ú
{#0114,fget_dist()}ú
{#1414,fileinfo (struct)}ú
{#0229,filelength()}ú
{#1131,file}ú
{#0264,find_color()}ú
{#1127,flags}ú
{#0230,flush()}ú
{#0223,fopen()}ú
{#0266,force_pal()}ú
{#1025,for}ú
{#1426,fps}ú
{#0115,frame_fli()}ú
{#1029,frame}ú
{#0225,fread()}ú
{#0258,free()}ú
{#1043,from}ú
{#0227,fseek()}ú
{#0228,ftell()}ú
{#1408,function}ú
{#0226,fwrite()}ú
{#1164,g_height}ú
{#1163,g_width}ú
{#1165,g_x_center}ú
{#1166,g_y_center}ú
{#0116,get_angle()}ú
{#0231,get_dirinfo()}ú
{#0117,get_dist()}ú
{#0118,get_distx()}ú
{#0119,get_disty()}ú
{#0232,get_fileinfo()}ú
{#0120,get_id()}ú
{#0121,get_joy_button()}ú
{#0122,get_joy_position()}ú
{#0123,get_pixel()}ú
{#0124,get_point()}ú
{#0195,get_point_m8()}ú
{#0125,get_real_point()}ú
{#0193,get_sector_height()}ú
{#0198,get_sector_texture()}ú
{#0220,get_song_line()}ú
{#0219,get_song_pos()}ú
{#0200,get_wall_texture()}ú
{#0233,getdrive()}ú
{#1006,global}ú
{#0191,go_to_flag()}ú
{#0126,graphic_info()}ú
{#1126,graph}ú
{#1133,height}ú
{#1092,id}ú
{#1020,if}ú
{#0240,ignore_error()}ú
{#1014,import}ú
{#1402,int} ú
{#0127,is_playing_cd()}ú
{#0222,is_playing_song()}ú
{#0221,is_playing_sound()}ú
{#0255,itoa()}ú
{#1103,joy (struct)}ú
{#1111,joy_filter}ú
{#1112,joy_state}ú
{#0128,key()}ú
{#0129,let_me_alone()}ú
{#0130,load()}ú
{#0131,load_fnt()}ú
{#0132,load_fpg()}ú
{#0174,load_map()}ú
{#0134,load_sound()}ú
{#0133,load_pal()}ú
{#0174,load_pcx()}ú
{#0265,load_screen()}ú
{#0214,load_song()}ú
{#0189,load_wld()}ú
{#1007,local}ú
{#1024,loop}ú
{#0210,lower()}ú
{#1150,m320x200 ... m1024x768}ú
{#1102,m7 (struct)}ú
{#1411,m8 (struct)}ú
{#1424,m8_nextsector}ú
{#1423,m8_sector}ú
{#1425,m8_step}ú
{#1422,m8_wall}ú
{#0257,malloc()}ú
{#0135,map_block_copy()}ú
{#0136,map_get_pixel()}ú
{#0137,map_put()}ú
{#0138,map_put_pixel()}ú
{#0139,map_xput()}ú
{#1178,max_int}ú
{#1115,max_process_time}ú
{#0239,memory_free()}ú
{#1177,min_int}ú
{#0236,mkdir()}ú
{#1048,mod}ú
{#1100,mouse (struct)}ú
{#0251,move_draw()}ú
{#0140,move_scroll()}ú
{#0141,move_text()}ú
{#0142,near_angle()}ú
{#1410,net (struct)}ú
{#0181,net_get_games()}ú
{#0180,net_join_game()}ú
{#0188,new_map()}ú
{#1172,no_restore}ú
{#1045,not}ú
{#1419,num_video_modes}ú
{#1085,offset}ú
{#1083,or}ú
{#0143,out_region()}ú
{#1170,partial_dump}ú
{#1173,partial_restore}ú
{#0185,path_find()}ú
{#0187,path_free()}ú
{#0186,path_line()}ú
{#1179,pi}ú
{#0144,play_cd()}ú
{#1405,pointer}ú
{#0145,pow()}ú
{#1121,priority}ú
{#1008,private}ú
{#1016,process}ú
{#1003,program}ú
{#0146,put()}ú
{#0147,put_pixel()}ú
{#0148,put_screen()}ú
{#0213,qsort()}ú
{#1104,quality_mixer}ú
{#1421,radius}ú
{#0149,rand()}ú
{#0150,rand_seed()}ú
{#0152,refresh_scroll()}ú
{#1130,region}ú
{#0237,remove()}ú
{#1023,repeat}ú
{#1116,reserved}ú
{#0153,reset_fli()}ú
{#0175,reset_sound()}ú
{#1135,resolution}ú
{#1113,restore_type}ú
{#1028,return}ú
{#0154,roll_palette()}ú
{#1160,s_freeze_tree}ú
{#1156,s_freeze}ú
{#1157,s_kill_tree}ú
{#1153,s_kill}ú
{#1159,s_sleep_tree}ú
{#1155,s_sleep}ú
{#1158,s_wakeup_tree}ú
{#1154,s_wakeup}ú
{#0155,save()}ú
{#0241,save_map()}ú
{#0241,save_pcx()}ú
{#1110,scan_code}ú
{#0212,screen_copy()}ú
{#1101,scroll (struct)}ú
{#0227,seek_cur}ú
{#0227,seek_end}ú
{#0227,seek_set}ú
{#0179,set_color()}ú
{#0201,set_env_color()}ú
{#0196,set_fog()}ú
{#0156,set_fps()}ú
{#0157,set_mode()}ú
{#0194,set_point_m8()}ú
{#0192,set_sector_height()}ú
{#0197,set_sector_texture()}ú
{#0218,set_song_pos()}ú
{#0178,set_volume()}ú
{#0199,set_wall_texture()}ú
{#0234,setdrive()}ú
{#1104,setup (struct)}ú
{#1093,setup_program}ú
{#1108,shift_state}ú
{#0158,signal()}ú
{#0242,sin()}ú
{#1094,sizeof()}ú
{#1128,size}ú
{#1119,smallbro}ú
{#0216,song()}ú
{#1118,son}ú
{#0159,sound()}ú
{#1104,sound_bits_16}ú
{#1104,sound_bits_8}ú
{#0160,sqrt()}ú
{#0161,start_fli()}ú
{#0162,start_mode7()}ú
{#0190,start_mode8()}ú
{#0163,start_scroll()}ú
{#1095,step}ú
{#0164,stop_cd()}ú
{#0165,stop_mode7()}ú
{#0182,stop_mode8()}ú
{#0166,stop_scroll()}ú
{#0217,stop_song()}ú
{#0167,stop_sound()}ú
{#0203,strcat()}ú
{#0206,strchr()}ú
{#0205,strcmp()}ú
{#0202,strcpy()}ú
{#0211,strdel()}ú
{#1406,string}ú
{#0204,strlen()}ú
{#0208,strset()}ú
{#0207,strstr()}ú
{#1012,struct}ú
{#1021,switch}ú
{#0168,system()}ú
{#0244,tan()}ú
{#1106,text_z}ú
{#1105,timer[]}ú
{#1096,to}ú
{#1151,true}ú
{#1042,type}ú
{#0263,uncompress_file()}ú
{#1420,drive_size}ú
{#0177,unload_fnt()}ú
{#0169,unload_fpg()}ú
{#0176,unload_map()}ú
{#0170,unload_sound()}ú
{#0176,unload_pcx()}ú
{#0215,unload_song()}ú
{#1097,until}ú
{#0209,upper()}ú
{#1415,video_modes (struct)}ú
{#1417,vsync}ú
{#1022,while}ú
{#1403,word}ú
{#0171,write()}ú
{#0253,write_in_map()}ú
{#0172,write_int()}ú
{#0183,xadvance()}ú
{#1132,xgraph}ú
{#1082,xor}ú
{#0173,xput()}ú
{#1123,x}ú
{#1124,y}ú
{#1125,z}ú

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
# Functions
# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.100,abs()}

{abs(}<expression>{)}

{Returns:}

The {absolute value} of the expression.

{Description:}

Calculates the absolute value of the expression given as parameter.
If the result of the expression is negative it will change the sign,
if it is positive, it won't do anything.

{#9999,Example program:}
PROGRAM example_abs;

GLOBAL
    INT values[15];
    INT n;

BEGIN
    FROM n=0 TO 15;
        values[n]=rand(-1000, 1000);
        write_int(0, 0, n*10,0, offset values[n]);
    END
    write(0, 0, 192, 0, "Press [SPACE] to run the function abs()");
    LOOP
        IF (key(_space))
            FROM n=0 TO 15;

                values[n] = abs(values[n]); // We find the absolute value

            END
        END
        FRAME;
    END
END
{-}

This program will print a list of values on the screen that can be positive or negative, 
when the space bar is pressed it will apply the function {abs()} to all these values, 
making all values positive.

{/}See: {#1035,Expression}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.101,advance()}

{advance(}<distance>{)}

{Description:}

Advances the process in its angle (specified by the local {#1129,angle} variable)
as many points as specified in the {expression} (distance) parameter.

To advance in a different angle to the one specified in this variable, use the
{#183,xadvance()} function instead.

The value can be also a negative number, in this case, the processes' graphic  
will advance in the opposite direction to the angle specified.

{#9999,Example program:}
PROGRAM example_advance;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    graph=101;
    x=160;
    y=100;
    write(0, 0, 0, 0, "Use the cursors (left + right) to change direction.");
    LOOP
        IF (key(_right)) angle-=10000; END
        IF (key(_left)) angle+=10000; END

        advance(2); // We advance 2 points

        FRAME;
    END
END
{-}

This example will draw a triangle on screen that will advance in the specified
direction (2) in the specified local variable {#1129,angle} using this function.

Remember that the angle is specified in thousandths of a degree.

The local {#1129,angle} variable will be changed using the cursor keys
(adding or subtracting 10000, which is equivalent to 10 degrees).

{/}

This function is the same as executing the following two statements:

  {x+=get_distx(angle,} <distance>{);}ú
  {y+=get_disty(angle,} <distance>{);}ú

This function just modifies the coordinates of the process.
It is possible to use the two previous statements when you would like the
process to advance in a different angle to the one which in the local
{#1129,angle} variable. This could be useful if you want to advance without
rotation.  Alternatively you can use the {#183,xadvance()} function.

For example, to make a process advance 8 points in a direction ( 
stored in a private variable called {angle2}) but rotated in another direction,
(the {#1129,angle} variable), you would use:

  {x+=get_distx(angle2, 8);}ú
  {y+=get_disty(angle2, 8);}ú

{/}See: {#183,xadvance()} - {#1044,Use of angles in the language} - {#118,get_distx()} - {#119,get_disty()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.102,change_sound()}

{change_sound(}<channel>{,} <volume>{,} <frequency>{)}

{Description:}

To use this function it is essential to have a sound card installed which is 100%
compatible with {Sound Blaster} (tm) or {Gravis Ultrasound} (tm)
and have the correct drivers installed.

This function only works if it is used after the {#159,sound()} function
is called, which is used to play sounds.

{Change_sound()} modifies one sound that is playing on one of the {channels},
setting the {volume} and {frequency}.

The {channel} is the {channel code} that is returned by the {#159,sound()}
function.  You can play up to 16 channels at the same time, with the same sound
or with different sounds. Each time you play a sound it is quite possible that
it will be played through a different channel.

Each {channel} has its own levels of volume and frequency.

The {volume} is a value between {0} (minimum volume) and {512} (maximum volume)
which determines the noise level that the sound will be heard through this channel.

The {frequency} is a value that affects the speed of the sound through the
channel, it controls how deep or sharp the sound is emitted.
Valid values are between {0} (deep) and {512} (sharp).

{#9999,Example program:}
PROGRAM example_change_sound;

PRIVATE
    freq=256;     // Medium Value (0..512)
    vol=256;        // Medium Value (0..512)

    sound_id;
    chan;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);

    sound_id = load_sound("help/help.pcm", 1);
    chan = sound(sound_id, vol, freq);

    write(0, 0, 0, 0, "Press right or left to change the frequency.");
    write_int(0, 0, 10, 0, offset freq);
    write(0, 0, 20, 0, "Press up or down to change the volume.");
    write_int(0, 0, 30, 0, offset vol);
    LOOP

        // Change the sound
        change_sound(chan, vol, freq);

        IF (key(_right)) freq++; END
        IF (key(_left)) freq--; END
        IF (key(_up)) vol++; END
        IF (key(_down)) vol--; END
        FRAME;
    END

END
{-}

In the example a sound {help.pcm} is loaded and played. Inside the main loop
of the program you can change the frequency and the volume of this sound using the
{change_sound()} function to modify these values using the cursor keys.

{/}See: {#134,load_sound()} - {#159,sound()} - {#170,unload_sound()} - {#1104,STRUCT setup}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.103,clear_screen()}

{clear_screen()}

{Description:}

Delete from the screen all graphics placed on it with the
{#146,put()}, {#173,xput()}, {#147,put_pixel()} & {#148,put_screen()} functions.

{#9999,Example program:}
PROGRAM example_clear_screen;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write(0, 0, 0, 0, "Press [SPACE] to clear the screen.");
    write(0, 0, 10, 0, "Press [ENTER] to view it again.");
    graph=100;
    x=160;
    y=100;
    LOOP
        IF (key (_space))

            clear_screen(); // Deletes the graphic of the screen

        END
        IF (key (_enter)) put_screen(0, 1); END
        FRAME;
    END
END
{-}

In the example a graphic is drawn using the {#148,put_screen()} function.
When the space bar is pressed, the screen is deleted.

Pressing the key {Enter}, you can see the screen again.

You can see how the graphic of the process (a ball that appears in the
centre) doesn't disappear when you use the function {clear_screen()}, because
the function will just delete the screen.

{/}See: {#146,put()} - {#173,xput()} - {#147,put_pixel()} - {#148,put_screen()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.104,collision()}

{collision(}<type of process>{)}

{Returns:}

The {#1039,identifier code} of one process or {0}.

{Description:}

This is the function {to detect collisions} between graphics.

Checks if the current process (the one that executed this function) collides with
one of the indicated parameter types. It checks to see if the graphics
of both processes are overlapped.

If a collision is detected, it returns the {#1039,identifier code}
of the process which is colliding with the current process. If not, the function will return {0}.

If the current process collides with more process of the specified type, the function
{collision()} will return the rest of the identifiers in the successive calls to the
{collision()} function.

To get every {#1039, identifier code} of the process that is in collision with the
current one, you must not use a {#1029,FRAME} statement between successive calls to the
{collision()} function. As soon as a {#1029,FRAME} statement is reached, the function will
start returning collision ID's starting with the first.

Something similar happens if you run a call to the function specifying a different
type of process; if, after this, collisions are still detected with the previous
type, this function will return every code from the first.

If you want to obtain every {#1039,identifier code} of the processes
of one particular type without collision, you must call the function {#120,get_id()}.

If you want to check how near two processes are so that their graphics do not 
collide, then you must use the {#117,get_dist()} function.

{#9999,Example program:}
PROGRAM example_collision;

PRIVATE
    id2;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    graph=100;
    x=160;
    y=100;
    mobile_process(80, 50, 101);
    LOOP
        delete_text(all_text);
        write(0, 160, 0, 1, "Use the cursors to move the triangle");

        id2 = collision(TYPE mobile_process); // Collision detected

        IF (id2<>0)
            write(0, 160, 200, 7, "­ COLLISION DETECTED!");
        END
        FRAME;
    END
END

PROCESS mobile_process(x, y, graph);

BEGIN
    LOOP
        IF (key(_right)) angle-=10000; END
        IF (key(_left)) angle+=10000; END
        IF (key(_up)) advance(4); END
        FRAME;
    END
END
{-}

In this example you can see a ball in the centre of the screen as
the graphic of the main program. After that a process named {mobile_process}
is created with the picture of a controllable triangle with the cursor keys.

The main program will call the function {collision()} to check if its graphic
(the circle) collides with the graphic of the {mobile_process} type (the triangle).
The result of the function is saved in the private variable {id2} of the main program.
This value will be {0} until a collision is detected, and will return the
{#1039,identifier code} of {mobile_process} when it does.

The identifier codes of the processes are always odd numbers, which in the DIV
language are true conditions (the even numbers are associated with the false conditions),
thus, in the example program we could have changed the statement to:

  {IF (id2<>0)} ... {END}

For the next one:

  {IF (id2)} ... {END}

For further information about this, see: {#1037,Definition of a condition.}

{/}

When you can see the mouse pointer in a DIV program (by assigning the code of the
corresponding graphic in the {#1100,mouse structure}), it is possible to see
if it has collided with the current process using this function in the following way:

  {IF (collision(TYPE mouse))}ú
      // The process collides with the mouse pointerú
  {END}ú

When a collision with the mouse pointer is detected, it won't be done with the entire
graphic used as a pointer like a normal graph, but only with the main {#1136,checkpoint}
(the number 0) of the same item, known commonly as the "hotspot" ({hotspot}) of the mouse.

{/}

This function is used to detect collisions between graphics on the screen
or in a window with a scrollbar.

It's not possible to use this function to detect collisions with processes 
that don't have a graphic (a valid code allocated to its variable
{#1126,graph}) or between graphics of a window of mode 7 or mode 8 (with its variable
{#1122,ctype} allocated to the value {#1169,c_m7} o {#1412,c_m8}).

It is {essential} that the particular item of the current process that is the
specified graphic has a defined graphic associated with it.

To detect collisions between graphics of a window of mode 7 or mode 8 you must use
the {#117,get_dist()} function to detect when the distance between the
two processes is smaller than the distance stipulated as a {collision distance}.

{/}See: {#120,get_id()} - {#117,get_dist()} - {#1042,Types of processes} - {#1038,Ways to obtain
the identifier code}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.105,convert_palette()}

{convert_palette(}<file>{,} <graphic>{,} <OFFSET new_palette>{)}

{Description:}

Manipulates a {<graphic's>} map of colour to that of the indicated {<file>}.

The {<}{#1085,offset}{ new_palette>} is the path/address inside the memory of the computer
of a 256-colour table where the new order of colours are located.

{Note:} The table must be (of the {#1402,INT} type, signed 32bit).

If the table is like this:

  new_palette[255]=0, 1, 2, 3, 4, ... , 254, 255;

The graphic will not be changed.

However, if in the 3rd position of the previous table (new_palette[3]) there is a 16 (not a 3),
when the function is called with the {#1085,offset} of the table, 
the colour 3 will be changed for the colour 16 in the graphic.

The graphics loaded with the functions {#174,load_map()} or {#174,load_pcx()}
(or made with {#188,new_map()}) will be used as if they refer to the first file
(the file with the code 0).

If a process wants to change the colours of its graphic, it must build 
a palette with the new order of colours and, after that, call the function with
the parameters:

  {convert_palette(file, graph, }<OFFSET new_palette>{)}

Here is a program that changes the colours of its graphic in this way
using the predefined local variables {#1131,file} and {#1126,graph}.

{#9999,Example program:}
PROGRAM example_convert_palette;

PRIVATE
    new_palette[255];
    counter;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);

    FROM counter=1 TO 255;
        new_palette[counter]=(counter+16) MOD 256;
    END

    graph=100;
    x=160;
    y=100;

    write (0, 160, 0, 1, "Press [SPACE] to change the colours of the ball");
    LOOP
        IF (scan_code==_space)

            // We convert the palette of the graphic number 100 (ball)
            convert_palette(file, graph, offset new_palette);

        END
        FRAME;
    END
END
{-}

First, {a table is created with the new order}
of the palette. The colour number 0 (transparent) never changes
(new_palette[0] will always be 0) and the rest of the colours (from 1 to 255)
will be changed for the colour that is 16 positions further along in the palette
(the 1 for 17, the 2 for 18, etc.). The last 16 colours will be changed
for the first 16 (when the operation {MOD 256} is done the values are truncated, 
256 will be 0, 257 will be 1, etc.).

After that, inside the main loop of the program the function will run 
{convert_palette()} and it will change the colours of the ball each time
that the space bar is pressed.

{/}See: {#133,load_pal()} - {#154,roll_palette()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.106,define_region()}

{define_region(}<region number>{,} <x>{,} <y>{,}<width> {,}<height> {)}

{Description:}

Defines a new region within the screen (like a borderless window).
Regions are rectangular areas inside the screen, in which you will see some kind
of process, scroll windows or mode 7 windows.

The {region number} must be between 1 and 31. Up to 31 different 
regions in the screen can be defined that are assignable, after that, to different processes
(fixing its local variable {#1130,region} to the new number) as its view window
or use it like a border for a scroll window or a mode 7 window, indicating it in the  
parameter of the functions {#163,start_scroll()} or {#162,start_mode7()}.

The {region number 0} can't be redefined, because it will be always be the entire screen,
a window at the coordinates (0, 0) and as wide and as high as the screen.
This is the region in which every process will be displayed,
because its local variable {#1130,region} always has a value 0.

{#9999,Example program:}
PROGRAM example_define_region;

PRIVATE
    counter;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);

    define_region(1, 0, 0, 160, 200);   // We define the region 1
    define_region(2, 160, 0, 160, 200); // We define the region 2

    write(0, 0, 0, 0, "Region 1");
    write(0, 320, 0, 2, "Region 2");

    FROM counter=1 TO 20;
        mobile_process(rand(0, 319), rand(0, 159), rand(-8, 8), rand(-8, 8), rand(1, 2));
    END
END

PROCESS mobile_process(x, y, increment_x, increment_y, region);

BEGIN
    graph=100;
    LOOP
        IF (x<0 OR x>320) increment_x=-increment_x; END
        IF (y<0 OR y>200) increment_y=-increment_y; END
        x+=increment_x;
        y+=increment_y;
        FRAME;
    END
END
{-}

First you define two regions as lateral divisions of the screen.
After that, 20 processes of the type {mobile_process} are created using a loop at random
coordinates and movement, in one of the two regions.

You can see in the execution how each process can be seen in only one of the two halves
of the screen (just in its region).

{/}See: {#143,out_region()} - {#163,start_scroll()} - {#162,start_mode7()} - {#1130,Variable region}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.107,delete_text()}

{delete_text(}<text identifier>{)}

{Description:}

Delete text on the screen that is specified with the {text identifier} parameter,
which is a numeric code returned by the functions {#171,write()} and {#172,write_int()}.

If {#1161,all_text} is specified as the {text identifier} parameter, then all text
on screen will be deleted.

{#9999,Example program:}
PROGRAM example_delete_text;

PRIVATE
    text_id;

BEGIN
    write(0, 160, 10, 1, "Press [ENTER] to make the above text reappear.");
    LOOP
        text_id=write(0, 160, 0, 1, "Press [SPACE] to delete this text.");
        WHILE (NOT key(_space))
            FRAME;
        END

        delete_text(text_id); // Delete the text

        WHILE (NOT key(_enter))
            FRAME;
        END
    END
END
{-}

In this example, two texts appear on screen. When you press
the space bar, one of these texts will be deleted using the {delete_text()} function,
and when you press the Enter key, the text appears again using the {#171,write()} function - 
which returns the new text identifier {text_id}.

{/}See: {#171,write()} - {#172,write_int()} - {#141,move_text()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.108,end_fli()}

{end_fli()}

{Description:}

Finishes an animation {FLI/FLC} shown on screen and frees the memory that was
being used.

The animations {FLI/FLC} are initiated with the {#161,start_fli()} function.

Only one animation can be loaded at a time.

{#9999,Example program:}
PROGRAM example_end_fli;
BEGIN
    LOOP
        start_fli("help/help.fli", 0, 0); // load and play the animation
        WHILE (frame_fli()<>0)
            FRAME;
        END

        end_fli(); // Unload the animation

    END
END
{-}

In this example, the animation is loaded with the {#161,start_fli()} function
and then is displayed via {#115,frame_fli()} until it finishes (when
{#115,frame_fli()} returns 0). At that moment it is unloaded from memory using {end_fli()}.

The program does this sequence of commands (load, play, update  and unload)
of the animation {FLI/FLC}) indefinitely.

It is not necessary for the animation to have finished before it is unloaded from
the memory.

{/}See: {#161,start_fli()} - {#115,frame_fli()} - {#153,reset_fli()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.109,exit()}

{exit(}<message>{,} <return code>{)}

{Description:}

Ends the game, killing all processes and returning to the operating system
(or to the DIV IDE) with a {message} and a {numeric code}.

The message is  text message displayed between quotation marks which will be shown when the game
finishes as an indication to the user that they have left DIV2.

The {return code} is valid for the use of external programs to
DIV Games Studio (like *.BAT files ), to determine the action
that must be done after finishing the game.

When the function {exit()}is used, you do not need to close any resources as this
will be done for you (such as maps, fli, sounds and songs) as the system frees
all resources automatically .

{#9999,Example program:}
PROGRAM example_exit;
BEGIN
    write(0, 160, 0, 1, "Press [SPACE] to finish the program.");
    LOOP
        IF (key (_space))
            fade_off();

            exit("Thanks for using me!", 0); // We exit the program

        END
        FRAME;
    END
END
{-}

In the example you can see a message whilst the program waits for the
space bar to be pressed, then exits with the {exit()} function.
{/}

Every DIV program will finish its execution at any moment if the key combination
{[ALT]+[X]} is pressed. This is similar to calling the {exit()} function, but
without any messages and with the return code 0.

{/}See: {#129,let_me_alone()} - {#111,fade_off()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.110,fade()}

{fade(}<% red>{,} <% green>{,} <% blue>{,} <speed>{)}

{Description:}

Fades the palette until the percentages of colour is reached - (from 0% to 200%
of the {red} (red), {green} (green) and {blue} (blue) components, specified as parameters).

The last parameter indicates the speed at which the fading will occur, 
normally defined as a number from 1 (very slowly) to
10 (Very fast).

If the speed indicates a number bigger or equal to 64, the fade will be done
instantaneously.

The fade will be done gradually in the successive frames of the game.

If all three colour components are 0 you will see a fade to black, if the three components are
set to 200, the fade will be to white, if the components are 100 you will retrieve the 
original colours of the game palette.

A value less than 100 in a component will tone down its colour, meanwhile that a value 
greater than 100, will saturate the colour.

Remember that the fade doesn't happen when the function {fade()} is called, but over 
the next {#1029,FRAME} statements . Whilst the program is executing
a fade command, the predefined global variable {#1107,fading} will have a value of {true}
(1) and when the fade is finished (the required values have been reached), this
variable will be set to {false} (0).

{#9999,Example program:}
PROGRAM example_fade;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write (0, 0, 0, 0, "Press [SPACE] to see the fade() effects.");
    LOOP
        IF (NOT fading AND key(_space))

            fade(rand(0, 200), rand(0, 200), rand(0, 200), 5);

        END
        FRAME;
    END
END
{-}

In the example a screen is loaded and a message appears.
Each time that the space bar is pressed and a fade is not already in
progress ({IF (NOT fading ...)}), a new fade will start with the three random values
chosen between 0% and 200% (with the {#149,rand()} function) at a speed value of 5.

{/}See: {#1107,fading} - {#111,fade_off()} - {#112,fade_on()} - {#133,load_pal()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.111,fade_off()}

{fade_off()}

{Description:}

Creates a fade to black from the colours on screen. The game stays as it is
until the screen is completely black.

To turn on the screen again (undo the fade to black), use the {#112,fade_on()} function.

{#9999,Example program:}
PROGRAM example_fade_off;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write (0, 0, 0, 0, "Press [SPACE] to fade off and fade on the screen.");
    LOOP
        WHILE (NOT key(_space))
            FRAME;
        END

        fade_off(); // We turn off the screen

        WHILE (fading)
            FRAME;
        END

        fade_on();

    END
END
{-}

In this example, a screen appears, and after that, the program waits for the
space bar to be pressed to turn off and turn on the screen.

The {#110,fade()} function can do this without stopping the program
or at different speeds, as well as creating more advanced palette effects.

{/}See: {#110,fade()} - {#112,fade_on()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.112,fade_on()}

{fade_on()}

{Description:}

Creates a fade up of the colours on the screen to their natural saturation (100%).

In the successive {#1029,FRAME} statements of the game, the colours will recover their
visibility until they can be seen perfectly.

To turn off the screen (to do a fade to black) use the {#111,fade_off()} function.

{#9999,Example program:}
PROGRAM example_fade_off;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write (0, 0, 0, 0, "Press [SPACE] to fade off and fade on the screen.");
    LOOP
        WHILE (NOT key(_space))
            FRAME;
        END
        fade_off();

        WHILE (fading)
            FRAME;
        END

        fade_on(); // The screen is faded on

    END
END
{-}

In this example, a screen appears, and after that, the program waits for the
space bar to be pressed to turn off and turn on the screen.

The {#110,fade()} function can do this without stopping the program
or at different speeds, as well as creating more advanced palette effects.

{/}

Every game automatically executes a {fade_on()} at the beginning
of execution.

{/}See: {#110,fade()} - {#111,fade_off()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.113,fget_angle()}

{fget_angle(}<x0>{,} <y0>{,} <x1>{,} <y1>{)}

{Returns:}

The angle between two points.

{Description:}

Returns the angle from the {point 0} (x0, y0) to the {point 1}
(x1, y1).

Remember that the angle is specified in thousandths of a degree. The function
always returns a value between { -180000} and {180000} (an  angle between -180
and 180 degrees).

Coordinates of both points (x0, y0, x1, y1) can be any valid numeric expression.

{#9999,Example program:}
PROGRAM example_fget_angle;

PRIVATE
    coord_x0, coord_y0;
    coord_x1, coord_y1;
    result;
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");
    write(0, 0, 0, 0, "Coordinates point 1");
    write(0, 0, 10, 0, "X:");
    write_int(0, 20, 10, 0, offset coord_x0);
    write(0, 0, 20, 0, "Y:");
    write_int(0, 20, 20, 0, offset coord_y0);
    write(0, 0, 40, 0, "Coordinates point 2");
    write(0, 0, 50, 0, "X:");
    write_int(0, 20, 50, 0, offset coord_x1);
    write(0, 0, 60, 0, "Y:");
    write_int(0, 20, 60, 0, offset coord_y1);
    write(0, 0, 80, 0, "Angle from point 1 to point 2:");
    write_int(0, 0, 90, 0, offset result);
    write(0, 0, 200, 6, "Press [SPACE] to get another two points.");
    LOOP
        clear_screen();
        coord_x0=rand(0, 319);
        coord_y0=rand(0, 199);
        coord_x1=rand(0, 319);
        coord_y1=rand(0, 199);
        put(file1,200,coord_x0, coord_y0);
        put(file1,200,coord_x1, coord_y1);

        //We find the angle between two points
        result = fget_angle(coord_x0, coord_y0, coord_x1, coord_y1);

        scan_code=0;
        WHILE (scan_code<>_space)
            FRAME;
        END
    END
END
{-}

In this example, some text messages are printed on the screen, along with some 
coordinates {x} and {y} of two points set from random values. The angle between
the points is then calculated with the {fget_angle()} function.
Each time that the space bar is pressed the process will repeat.

The {#116,get_angle()} function is used to obtain the {angle between two processes},
instead of between two points.

The {#114,fget_dist()} function is used to obtain the {distance between two
points}, instead of the angle.

{/}See: {#1044,Use of angles in the language} - {#116,get_angle()} - {#114,fget_dist()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.114,fget_dist()}

{fget_dist(}<x0>{,} <y0>{,} <x1>{,} <y1>{)}

{Returns:}

The distance between two points.

{Description:}

Returns the distance between {point 0} (x0, y0) and {point 1}
(x1, y1).

Coordinates of both points (x0, y0, x1, y1) can be specified by any
valid numeric expression.

{#9999,Example program:}
PROGRAM example_fget_dist;

PRIVATE
    coord_x0, coord_y0;
    coord_x1, coord_y1;
    result;
    file1;

BEGIN

    file1=load_fpg("help/help.fpg");
    write(0, 0, 0, 0, "Point 1 Co-ordinates");
    write(0, 0, 10, 0, "X:");
    write_int(0, 20, 10, 0, offset coord_x0);
    write(0, 0, 20, 0, "Y:");
    write_int(0, 20, 20, 0, offset coord_y0);
    write(0, 0, 40, 0, "Point 2 Co-ordinates");
    write(0, 0, 50, 0, "X:");
    write_int(0, 20, 50, 0, offset coord_x1);
    write(0, 0, 60, 0, "Y:");
    write_int(0, 20, 60, 0, offset coord_y1);
    write(0, 0, 80, 0, "Distance between point 1 and point 2");
    write_int(0, 0, 90, 0, offset result);
    write(0, 0, 200, 6, "Press [SPACE] to find another distance.");
    LOOP
        clear_screen();
        coord_x0=rand(0, 319);
        coord_y0=rand(0, 199);
        coord_x1=rand(0, 319);
        coord_y1=rand(0, 199);
        
        put(file1,200,coord_x0, coord_y0);
        put(file1,200,coord_x1, coord_y1);

        //Find the distance between the two points
        result = fget_dist(coord_x0, coord_y0, coord_x1, coord_y1);

        scan_code=0;
        WHILE (scan_code<>_space)
            FRAME;
        END
    END
END
{-}

In this example, the program sets the 2 sets of co-ordinates to random values,
and then obtains the distance between them with the {fget_dist()} function.
Each time that the space bar is pressed, the process is repeated.

The {#116,get_dist()} function is used to obtain the {distance from one process
to another}, instead of from one point to another.

The {#114,fget_angle()} function is used to obtain the {angle between two
points}, instead of the distance.

{/}

This function could be used to detect collisions between processes, but of course,
you would normally use the {#104,collision()} function which detects when two processes 
have their graphics overlapping.

An example of this is when a process exists within a Mode 7 window (See {#162,start_mode7()})
the {#104,collision()} function can't be used, so the distance between the
processes must be obtained (normally with {#116,get_dist()}) to check if they collide
(if their distance is smaller than a specified one).

{/}See: {#117,get_dist} - {#113,fget_angle} - {#104,collision()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.115,frame_fli()}

{frame_fli()}

{Returns:}

{True} if the animation continues and {false} if it has finished.

{Description:}

Shows the next image of an animation {FLI/FLC} that was started with the {#161,start_fli()}
function. This function returns {0} (false) if the animation has finished.

It is only possible to run one {FLI/FLC} animation at a time. It is not possible to
have two animations playing at the same time.

The next frame of animation will be seen in the next {#1029,FRAME} of the game, 
but if a loop is created without a {#1029,FRAME} statement, the animation
will not be seen.

{#9999,Example program:}
PROGRAM example_frame_fli;
BEGIN
    start_fli("help/help.fli", 0, 0);
    LOOP

        frame_fli(); // Show the next frame of animation

        FRAME;
    END
END
{-}

In the example, the animation {FLI/FLC} is loaded and then played repeatedly
with the {frame_fli()} function.

{/}See: {#161,start_fli()} - {#153,reset_fli()} - {#108,end_fli()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.116,get_angle()}

{get_angle(}<identifier code>{)}

{Returns:}

The angle to other process

{Description:}

Returns the angle from the current process (the one which called this function)
to the process which has the {#1039,identifier code}.

See {#1038,Ways to obtain the identifier code}, for further information.

Remember that angle is specified in thousandths of a degree. The function
will always return a value between{ -180000} and {180000} (an angle between -180 and
180 degrees).

{#9999,Example program:}
PROGRAM example_get_angle;

PRIVATE
    resulting_angle;
    process_id;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    graph=100;
    x=160;
    y=100;

    process_id = mobile_object(80, 50, 101);

    write(0, 160, 200, 7, "Use the cursors to move the triangle.");
    write(0, 0, 0, 0, "Angle from the ball to the triangle:");
    write_int(0, 0, 10, 0, offset resulting_angle);
    LOOP

        // We find the angle between the two processes
        resulting_angle = get_angle(process_id);

        FRAME;
    END
END

PROCESS mobile_object(x, y, graph);
BEGIN
    LOOP
        IF (key(_right)) angle-=10000; END
        IF (key(_left)) angle+=10000; END
        IF (key(_up)) advance(4); END
        FRAME;
    END
END
{-}

In this example, a ball is displayed in the centre of the screen. A {mobile_object}
process is created, and its {#1039,identifier code} is stored in the {process_id}
variable. This process can be controlled with the cursor keys.
                
In the main loop of the program, the angle between the two processes is calculated and
shown on screen continuously.

The {#113,fget_angle()} function is used to obtain the {angle between two
points}, instead of between two processes. 

For Example, if the {#1039,identifier code} of the process refers to a variable {id2},
then a function call of:

    {get_angle(id2)}

Would be equivalent to:

    {fget_angle(x, y, id2.x, id2.y)}


The {#117,get_dist()} function is used to obtain the {distance to the other process}
instead of the angle.

{/}See: {#1044,Use of angles in the language} - {#113,fget_angle()} - {#117,get_dist()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.117,get_dist()}

{get_dist(}<identifier code>{)}

{Returns:}

The distance to the other process.

{Description:}

Returns the distance from the current process (the one which called this function) to
the process which has the {#1039,identifier code}.

See {#1038,ways to obtain the identifier code}, for further information.

If the process has defined its local variable {#1135,resolution} then it is important
that the process for which the distance we wish to obtain has the {#1135,resolution}
local variable set to the same value. If both processes have the coordinates in hundredths
instead of whole amounts (with {#1135,resolution}=100), then the distance between both
will be given in hundredths too, but if the value of this variable is different between
processes, then the result of the {get_dist()} function will not make sense.

{#9999,Example program:}
PROGRAM example_get_dist;

PRIVATE
    resulting_distance;
    process_id;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    graph=100;
    x=160;
    y=100;

    process_id = mobile_object(80, 50, 101);

    write(0, 160, 200, 7, "Use the cursors to move the triangle.");
    write(0, 0, 0, 0, "Distance from the ball to the triangle:");
    write_int(0, 0, 10, 0, offset resulting_distance);
    LOOP

        // We find the distance between the two processes
        resulting_distance = get_dist(process_id);

        FRAME;
    END
END

PROCESS mobile_object(x, y, graph)
BEGIN
    LOOP
        IF (key(_right)) angle-=10000; END
        IF (key(_left)) angle+=10000; END
        IF (key(_up)) advance(4); END
        FRAME;
    END
END
{-}

In this example, a ball is displayed in the centre of the screen. A {mobile_object}
process is created, and its {#1039,identifier code} is stored in the {process_id}
variable. This process can be controlled with the cursor keys.
                
In the main loop of the program, the distance between the two processes is calculated and
updated on screen continuously.

The function {#114,fget_dist()} is used to obtain the {distance between two
points}, instead of between two processes. If the {#1039,identifier code}
of the process is contained, for example, in a variable denominated {id2}, then
the call to the function:

    {get_dist(id2)}

Will be equivalent to:

    {fget_dist(x, y, id2.x, id2.y)}

To obtain the distance from the coordinates (x, y) of the current process up to the
coordinates (x, y) of the process for which its {#1039,identifier code} is {id2}.

The function {#116,get_angle()} is used to obtain the {angle to the process}
instead of the distance.

{/}

This function can be used to detect collisions between processes, though of course,
the {#104,collision()} function is normally used which detects when two processes 
graphics overlap.

An example of this is when a process exists within a Mode 7 window (See {#162,start_mode7()})
the {#104,collision()} function can't be used, so the distance between the
processes must be obtained (normally with {#116,get_dist()}) to check if they collide
(if their distance is smaller than a specified one).

{/}See: {#114,fget_dist()} - {#116,get_angle()} - {#118,get_distx()} - {#119,get_disty()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.118,get_distx()}

{get_distx(}<angle>{,} <distance>{)}

{Returns:}

The horizontal distance towards the vector (angle, distance).

{Description:}

Returns the horizontal distance (in the {x} axis) from the angle and {distance} (over this angle) passed as parameters.
It returns the distance that the vector moves horizontally (along the x-axis), made by the
angle and {length} (distance or module of the vector) indicated.

Keep in mind that the angle is specified in thousandths of a degree and
distance can be specified by any valid numeric expression.

The function used to calculate the vertical distance, instead of the
horizontal one is {#119,get_disty()}.

{#9999,Example program:}
PROGRAM example_get_distx;

GLOBAL
    distance;
    horizontal_distance;
    vertical_distance;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 3);
    write(0, 160, 200, 7, "Use the cursors to move the triangle.");
    write(0, 0, 0, 0, "Horizontal distance:");
    write_int(0, 0, 10, 0, offset horizontal_distance);
    graph=101;
    LOOP
        IF (key(_up)) distance+=2; END
        IF (key(_down)) distance-=2; END
        IF (key(_right)) angle-=2000; END
        IF (key(_left)) angle+=2000; END

        // We calculate the horizontal distance
        horizontal_distance= get_distx(angle, distance);

        vertical_distance = get_disty(angle, distance);
        x=160+horizontal_distance;
        y=100+vertical_distance;
        FRAME;
    END
END
{-}

In the example, a circular graphic is placed on screen, then a triangle process is shown, whose angle and distance can be controlled using the cursor keys.

The program calculates the horizontal and vertical distances to the triangle from the coordinates of the centre of the screen
(160, 100), showing the horizontal distance in the upper left corner all the times.

{/}

If the aim is to advance the coordinates of the process a {distance} in a specific angle, the following statements may be used:


  {x+=get_distx(}<angle>{,} <distance>{);}ú
  {y+=get_disty(}<angle>{,} <distance>{);}ú

This would be equivalent to (using the {#183,xadvance()} function).

  {xadvance(}<angle>{,} <distance>{);}

If the angle that you wish to move the process is the one declared in the local variable {#1129,angle}, then you would use the {#101,advance()} function like this:

  {advance(}<distance>{);}

{/}

The {get_distx()} function is the same as calculating the {cosine} of the angle and
multiplying it by the {distance}.

{/}See: {#1044,Use of angles in the language} - {#119,get_disty()} - {#183,xadvance()} - {#101,advance()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.119,get_disty()}

{get_disty(}<angle>{,} <distance>{)}

{Returns:}

The vertical distance towards the vector (angle, distance).

{Description:}

Returns the vertical distance (in the {x} axis) from the angle and {distance} (over this angle) passed as parameters.
It returns the distance that the vector moves vertically (along the y-axis), made by the
angle and {length} (distance or module of the vector) indicated.

Keep in mind that the angle is specified in thousandths of a degree and
distance can be specified by any valid numeric expression.

The function used to calculate the horizontal distance, instead of the
vertical one is {#119,get_distx()}.

{#9999,Example program:}
PROGRAM example_get_disty;

GLOBAL
    distance;
    horizontal_distance;
    vertical_distance;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 3);
    write(0, 160, 200, 7, "Use the cursors to move the triangle.");
    write(0, 0, 0, 0, "Vertical distance:");
    write_int(0, 0, 10, 0, offset vertical_distance);
    graph=101;
    LOOP
        IF (key(_up)) distance+=2; END
        IF (key(_down)) distance-=2; END
        IF (key(_right)) angle-=2000; END
        IF (key(_left)) angle+=2000; END

        // We calculate the horizontal distance
        horizontal_distance= get_disty(angle, distance);

        vertical_distance = get_disty(angle, distance);
        x=160+horizontal_distance;
        y=100+vertical_distance;
        FRAME;
    END
END
{-}

In the example, a circular graphic is placed on screen, then a triangle process is shown, whose angle and distance can be controlled using the cursor keys.

The program calculates the horizontal and vertical distances to the triangle from the coordinates of the centre of the screen
(160, 100), showing the vertical distance in the upper left corner all the times.

{/}

If the aim is to advance the coordinates of the process a {distance} in a specific angle, the following statements may be used:


  {x+=get_disty(}<angle>{,} <distance>{);}ú
  {y+=get_disty(}<angle>{,} <distance>{);}ú

This would be equivalent to (using the {#183,xadvance()} function).

  {xadvance(}<angle>{,} <distance>{);}

If the angle that you wish to move the process is the one declared in the local variable {#1129,angle}, then you would use the {#101,advance()} function like this:

  {advance(}<distance>{);}

{/}

The {get_disty()} function is the same as calculating the {sine} of the angle and
multiplying it by the {distance}.

{/}See: {#1044,Use of angles in the language} - {#119,get_distx()} - {#183,xadvance()} - {#101,advance()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.120,get_id()}

{get_id(}<type of process>{)}

{Returns:}

The {#1039,identifier code} of a process or {0}.

{Description:}

This function checks to see if there are any processes of the specified type.
If any are found, then the function will return the {#1039,identifier code} of the
first occurrence, and if none are found will return a 0.

If there are more processes of the specified type, the function {get_id()}
will return the next {#1039,identifier code} for each successive call.

Once every {#1039,identifier code} has been returned, the function
will return 0, until the next {#1029,FRAME} statement is executed, at which point
the function will be reset, and once again will begin to return every
{#1039,identifier code} of the specified type of process.

If you wish to get all of the {#1039,identifier codes} of the processes of that
type, you should not use the {#1029,FRAME} statement between two successive calls to
{get_id()}. If you execute a {#1029,FRAME} statement between calls to {get_id()} then
the function will again reset and start returning values from the first occurrence of that
type of process.

A similar thing happens if you call {get_id()} with a different process type. Each time a new 
process type is called, the identifiers reset and start with the first process of that type.

{#9999,Example program:}
PROGRAM example_get_id;

PRIVATE
    process_id;
    counter;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    FROM counter=1 TO 20;
        my_process(rand(0, 319), rand(0, 199), 101);
    END
    LOOP
        FROM counter=1 TO 20;

            // Get the Processes ID
            process_id = get_id(TYPE my_process);
    
            // Change the processes LOCAL angle variable using the ID
            process_id.angle+=rand(-5000, 5000);
        END
        FRAME;
    END
END

PROCESS my_process(x, y, graph);
BEGIN
    LOOP
        FRAME;
    END
END
{-}

In the example, after having loaded the file with graphics and set the background screen, 20 {movable_process} type processes are
created with their positions randomly chosen and with a triangle-shaped graphic.

These processes will only execute {#1029,FRAME} statements inside a loop, in order to be displayed.

From the main program, the identifiers of the {movable_process} type processes are taken with the {get_id()} function (storing them in the {process_identifier} variable) and using them to modify their angle (their {#1129,angle} local variable).                                                               
On having the {#1039,identifying code} of a process, it is possible to consult or modify its local variables (like {#1129,angle} in this example) or else, to send signals to the process with the {#158,signal()} function.

{/}

The {#104,collision()} function is used to obtain the {#1039,identifier codes}
of processes of a determined type that collide with the current process.

{/}See: {#1038,Ways to obtain the identifier code} - {#1042,Types of processes} - {#1039,Identifier codes}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.121,get_joy_button()}

{get_joy_button(}<button number>{)}

{Returns:}

{True} (1) if the button is pressed or {False} (0) if it isn't

{Description:}

This function requires the joystick number button (from 0 to 3) as a parameter, and returns {true} (an odd numerical value) if it is pressed at that moment.

If the button is not pressed, the function returns {false}
(an even numeric value).

Some joysticks only have two buttons, and this case they will be mapped to button
numbers 0 and 1. On computers that have two joysticks connected, the second joystick
will have the buttons numbered 2 and 3.

{#9999,Example program:}
PROGRAM example_get_joy_button;

PRIVATE
    counter;
    buttons[3];

BEGIN
    write(0, 160, 200, 7," Press the buttons of the joystick.");
    write(0, 0, 0, 0, "Buttons (0..3):");
    write_int(0, 100, 0, 0, offset buttons[0]);
    write_int(0, 120, 0, 0, offset buttons[1]);
    write_int(0, 140, 0, 0, offset buttons[2]);
    write_int(0, 160, 0, 0, offset buttons[3]);
    LOOP
        FROM counter=0 TO 3;

            // We take the value of the joystick button
            buttons[counter] = get_joy_button(counter);

        END
        FRAME;
    END
END
{-}

An explanatory message is displayed in the lower part of the screen and 
the condition of the four possible buttons is displayed in the upper part of the screen; 
after that, the program stays inside of a loop updating the state of the four buttons
continuously using the {get_joy_button()} function.

{/}

There are other ways to read the joystick. The easiest is to use
the {#1103,joy} structure, because in there are four variables that are
continuously updated with the status of the joystick buttons.

{/}See: {#122,get_joy_position()} - {#1103,Joy Structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.122,get_joy_position()}

{get_joy_position(}<axis number>{)}

{Returns:}

The position of the joystick axis

{Description:}

This function returns the coordinate in which is found the indicated axis
(with a number from {0} to {3}) of the analogic joystick.

Axis {0} - Axis {X} main.ú
Axis {1} - Axis {Y} main.ú
Axis {2} - Axis {X} secondary.ú
Axis {3} - Axis {Y} secondary.ú

The coordinate of the joystick can change due to the type of joystick and
computer in which it is played, in all cases it is a number which changes between
{4} and {200}, more or less.

The axes {main} and {secondary} can be integrated in just one joystick
in some cases (flight joysticks with a {hat}, {pedals}, etc.). In computers
with two joysticks connected, the main axis will be the joystick 1 and the
secondary axis will be the joystick 2.

{#9999,Example program:}
PROGRAM example_get_joy_position;

PRIVATE
    joystick_axis[3];
    counter;

BEGIN
    write (0, 160, 200, 7, "Move the joystick");
    write (0, 0, 0, 0, "Coordinate X main.");
    write_int(0, 0, 10, 0, offset joystick_axis[0]);
    write (0, 0, 40, 0, "Coordinate & main.");
    write_int(0, 0, 50, 0, offset joystick_axis[1]);
    write (0, 0, 80, 0, "Coordinate X secondary.");
    write_int(0, 0, 90, 0, offset joystick_axis[2]);
    write (0, 0, 120, 0, "Coordinate & secondary.");
    write_int(0, 0, 130, 0, offset joystick_axis[3]);
    LOOP
        FROM counter=0 TO 3;

            // We take the value of the joystick axis
            joystick_axis[counter] = get_joy_position(counter);

        END
        FRAME;
    END
END
{-}

Information is printed on the screen, then the program is put into a continuous loop.
The screen updates with the state of each  joystick position, stored in the joystick_axis[]
array, and updated using the get_joy_position() function.

{/}

There are other ways to read the joystick. The easiest is to use
the {#1103,joy} structure when analogue reading of the joystick (its coordinates)
is not required. This tells you the simple directions of the joystick, like the centre,
to the right, down, etc.

{/}See: {#121,get_joy_button()} - {#1103,joy structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.123,get_pixel()}

{get_pixel(}<x>{,} <y>{)}

{Returns:}

The colour value of the pixel (0..255).

{Description:}

Returns the colour of the {background} at the screen coordinates that are
specified in the parameters.

The number returned is a palette index from the active palette
between 0 and 255, because the palettes have 256 colours.

The point refers to only the {background} from the picture, without taking notice
of the graphics of the processes, texts, scroll regions, etc.
Only the images placed on screen by the functions {#146,put()},{#173,xput()}, 
{#147,put_pixel()} & {#148,put_screen()} will be read.

{#9999,Example program:}
PROGRAM example_get_pixel;

PRIVATE
    pixel_colour;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 2);
    mouse.graph=200;
    write (0, 0, 190, 0, "Colour of the background pixel:");
    write_int(0, 256, 190, 0, offset pixel_colour);
    LOOP

        // We take the colour of the point of the background
        pixel_colour = get_pixel(mouse.x, mouse.y);

        FRAME;
    END
END
{-}

In this example, the {#148,put_screen} function is used to display an image on screen,
representing a group of squares in different colours, and a mouse pointer displayed as a cross.

In the lower part of the screen a message is displayed, along with a variable that is updated
from the {get_pixel()} command.

By using the mouse, you can obtain the colour of any pixel on the screen.


{/}See: {#147,put_pixel()} - {#136,map_get_pixel()} - {#138,map_put_pixel()} - {#124,get_point()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.124,get_point()}

{get_point(}<file>{,} <graphic>{,} <number>{,} <OFFSET x>{,} <OFFSET y>{)}

{Returns:}

The position of the checkpoint (placed into the variables which {#1085,offset} is
declared in the last two parameters).

{Description:}

This function will place the coordinate values of a map point into the variable you specify
from an indicated graphic.

A {#1136,checkpoint} is a point that can be defined in the graphic editor
(draw tool), in the checkpoints function.

The function needs the {address} (which is obtained with the {#1085,offset} operator)
in memory {of two variables} in which the {x} and {y} values of the checkpoint will
be stored.

Graphics loaded with the {#174,load_map()} or {#174,load_pcx()} functions
(or created with {#188,new_map()}) will be used as if they were from the first
file (the one with the code 0).

{#9999,Example Program:}
PROGRAM example_get_point;

GLOBAL
    file1;
    point=1;
    x_point;
    y_point;

BEGIN
    file1=load_fpg("help/help.fpg");
    put_screen(0, 4);
    graph=101;
    LOOP
        IF (fget_dist(x, y, x_point, y_point)<6)
            IF (point++==50) point=1; END
        END

        // Store the checkpoint coordinate values in x_point and y_point
        get_point(file1, 4,point, offset x_point, offset y_point);

        angle=fget_angle(x, y, x_point, y_point);
        advance(6);
        FRAME;
    END
END
{-}

In this example, an image of a circuit is displayed on the screen. On this map there are
50 {#1136,checkpoints} defined {from 1 to 50) in the circuit.

The main process appears as a triangle that travels throughout the circuit.

The number of the checkpoint is stored in the local variable {point}
which at the beginning is set to 1.

The coordinates of each checkpoint, obtained with the {get_point()} function,
are saved in the {x_point} and {y_point} variables and are used to make the process
move to that position with the {#113,fget_angle()} functions (to obtain the local {angle}
variable) and {#101,advance()} (to advance 6 points in that direction).

The distance to the next checkpoint is checked using the {#114,fget_dist()} function,
if that point number is detected as being less than 6 pixels away, then
the triangle is directed onto the next point.
When point number 50 is reached it will reset back to point 1.

{/}

This function returns the exact coordinates that the checkpoints were placed
inside the graphic, without regard to how the graphic is displayed (zoomed,rotated,etc).
To obtain the position of a checkpoint in an graphic that is zoomed or rotated,
and relative to the coordinates of screen (and not of the original graphic) you must use the 
{#125,get_real_point()} function.

{/}See: {#1136,Checkpoints} - {#125,get_real_point()} - {#123,get_pixel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.125,get_real_point()}

{get_real_point(}<number>{,} <OFFSET x>{,} <OFFSET y>{)}

{Returns:}

Sets the coordinates of the checkpoint to the variables which
{#1085,offset} indicated as the two last parameters.

{Description:}

This function returns where a checkpoint of the main processes graphic
is at a particular moment in the coordinates system used by
the process (See local variable {#1122,ctype}), evaluating the
original location of the point, the current coordinates of the
process, its size, angle, etc.

A {#1136,checkpoint} is a point that can be defined in the graphics 
editor (drawing tool), in the options given to the function.

The function needs the {address} (which is obtained with the {#1085,offset} operator)
in memory {of two variables} in which the {x} and {y} values of the checkpoint will
be stored.

Graphics loaded with the {#174,load_map()} or {#174,load_pcx()} functions
(or created with {#188,new_map()}) will be used as if they were from the first
file (the one with the code 0).

{#9999,Example program:}
PROGRAM example_get_real_point;

PRIVATE
    point;
    x_point;
    y_point;

BEGIN
    load_fpg("help/help.fpg");
    graph=4;
    x=160;
    y=100;
    LOOP
        FROM point=1 TO 50;

            // We take the coordinates where there at this moment the checkpoint is
            get_real_point(point, offset x_point, offset y_point);

            cross(x_point, y_point, 200);
        END
        angle+=1000;
        FRAME;
    END
END

PROCESS cross(x, y, graph);
BEGIN
    FRAME;
END
{-}

In the example a circuit that rotates on the screen is defined as the graphic of the 
main process . This graphic has 50 defined {#1136,checkpoints} numbered from 1 to 50.

The program stays inside of a loop, rotates this graphic
with the angle command,and creating 50 processes
of a cross type, one for each of the 50 checkpoints of the graphic.

You can check how the relative position of two points doesn't change
though the graphic of the circuit rotates.

{/}

This function is usually used to locate some important key points of a graphic.
For example, in a process in which the graphic is a man with a gun that can
be escalated, rotated or that has some animations, a checkpoint could be defined
in the cannon of the gun to know at each moment where the bullets must go the case
of gun being fired.

If the original graphic was inside of a scroll region 
(See{#163,start_scroll()}) the given coordinates will be relative to
to the scroll region.

{/}

The {#124,get_point()} function returns the position where a checkpoint of
the graphic was placed initially, instead of its current position
like {get_real_point()}.

{/}See: {#1136,Checkpoints} - {#124,get_point()} - {#123,get_pixel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.126,graphic_info()}

{graphic_info(}<file>{,} <graphic>{,} <information>{)}

{Returns:}

The information that was requested about the graphic.

{Description:}

It returns the information of a {graphic} for in a {file} that was requested.

Information:

The returned value will depend on the third parameter {information} that is passed
to the function as follows:

{g_wide} - The {original width} of the graphic
{g_height} - The {original height} of the graphic.
{g_x_center} - The (x coordinate} of the centre of the graphic.
{g_y_center} - The {y coordinate} of the centre of the graphic.

Graphics loaded with the {#174,load_map()} or {#174,load_pcx()} functions
(or created with {#188,new_map()}) will be treated as if they were loaded from the first
file (code 0).

{#9999,Example program:}
PROGRAM example_graphic_info;

PRIVATE
    file1;
    myheight;
    mywidth;
    x_centre;
    y_centre;

BEGIN
    file1=load_fpg("help/help.fpg");
    put_screen(file1, 1);
    graph=100;
    x=160;
    y=100;

    // We take the information about the height of the graphic
    myheight = graphic_info(file1, 100, g_height);

    // We take the information about the width of the graphic
    mywidth = graphic_info(file1, 100, g_wide);

    // We take the information about the coordinate x of the centre of the graphic
    x_centre = graphic_info(file1, 100, g_x_center);

    // We take the information about the coordinate & of the centre of the graphic
    y_centre = graphic_info(file1, 100, g_y_center);

    write(0, 0, 0, 0, "Height of the graphic:");
    write_int(0, 0, 10, 0, offset myheight);
    write(0, 0, 20, 0, "Width of the graphic:");
    write_int(0, 0, 30, 0, offset mywidth);
    write(0, 0, 40, 0, "Horizontal centre of the graphic:");
    write_int(0, 0, 50, 0, offset x_centre);
    write(0, 0, 60, 0, "Vertical centre of the graphic:");
    write_int(0, 0, 70, 0, offset y_centre);
    LOOP
        FRAME;
    END
END
{-}

In this example, the program fetches the information about graphic number 100 in the
{help.fpg} file, which is a ball of 32 pixels square and has a centre of (16, 16).

To obtain this information, it makes 4 calls to the {graphic_info()} function, each
time passing a different (<information>) argument (g_wide, g_height, etc) to get the
required values.

{/}See: {#1163,g_width} - {#1164,g_height} - {#1165,g_x_center} - {#1166,g_y_center}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.127,is_playing_cd()}

{is_playing_cd()}

{Returns:}

{True} (1) if the CD is playing, or {false} (0) if it isn't.

{Description:}

This function is used to determine if the CD is playing a track.
                
Returns {True} (an odd number) if the CD is playing, or {False} (an even number) if
no track is playing.

Normally this is used to play a song in a continuous loop as shown in this example.

{#9999,Example program:}
PROGRAM example_is_playing_cd;
BEGIN
    play_cd(1, 0);
    LOOP

        IF (NOT is_playing_cd()) // Checks if the song has finished

            play_cd(1, 0);
        END
        FRAME;
    END
END
{-}

In this example (which you need to have an audio {Compact disk} inserted in your {CD-ROM} drive),
The {#144,play_cd()} function is used to play the first song of the CD.

In a loop, a check is made to see if the song has finished so it can
restart it.

{/}

The volume of the cd-audio can be controlled with the
{#1104,setup} structure and the {#178,set_volume()} function.
                                            
{/}See: {#144,play_cd()} - {#164,stop_cd()} - {#178,set_volume()} - {#1104,Setup structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.128,key()}

{key(}<key code>{)}

{Returns:}

{True} (1) if the key is pressed and {false} (0) if it is not.

{Description:}

Returns {true} (an odd number) if the key (indicated as the {<key code>} parameter)
is pressed, and returns {false} if not.

The parameter is usually specified by the key name proceeded by the {_} symbol.
For example, to read the [{A}] key, the command used would be {key(_a)}.

View the {#1176,key codes} to see the complete list of keytable codes that
can be used as the parameter of the {key()} function.

{#9999,Example program:}
PROGRAM example_key;
BEGIN
    LOOP
        delete_text(all_text);

        IF (key(_space)) // Check if the space bar is being pressed

            write(0, 0, 0, 0, "You are pressing the [SPACE] key.");
        ELSE
            write(0, 0, 0, 0, "You are not pressing the [SPACE] key.");
        END
        FRAME;
    END
END
{-}

In this example, a message is displayed, dependant on whether the {SPACE} key is being pressed
or not.

{/}

There are three predefined global variables that can be used 
to control the keytable. These are:

{#1110,scan_code} - Gets the Code of the last key that has been pressed. This
is a numeric value that corresponds directly with the constants
of {#1176,key codes} used as parameters of the {key()} function.

{#1109,ascii} - the ASCII code of the last key pressed.

{#1108,shift_state} - Variable that indicates a number in the function for the 
special keys (shift, alt, control, ...) which are pressed at that moment.

{/}See: {#1176,key codes} - {#1110,scan_code} - {#1109,ascii} - {#1108,shift_state}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.129,let_me_alone()}

{let_me_alone()}

{Description:}

Sends a {#1153,s_kill} signal to every process (except the one that called
this function) to stop processing.

This function is normally called from the main process when a game has finished, 
to eliminate every process (shots,enemies, etc.) that still remain active 
and recover the control of the program.

A call to {let_me_alone()} could always  be swapped for a group of calls to the 
{#158,signal()} function with the {#1153,s_kill} signal, but to do this
you need to know the types of the processes that you wish to eliminate
or their {#1039,identifier codes}.

{#9999,Example program:}
PROGRAM example_let_me_alone;
BEGIN
    load_fpg("help/help.fpg");
    ball (160, 100, 100);
    write (0, 160, 0, 1, "Press [SPACE] to eliminate the process");
    WHILE (NOT key (_space))
        FRAME;
    END

    let_me_alone(); // The other processes are eliminated

    LOOP
        FRAME;
    END
END

PROCESS ball(x, y, graph)
BEGIN
    LOOP
        FRAME;
    END
END
{-}

In this example a {ball} process is created, and the program waits for the space bar to
be pressed. At this point, the {let_me_alone()} function is called, which eliminates
every process except the main one, which kills the ball process.

{/}

If you wish to check the processes that are active in a program at any given
moment, the debugger may be accessed by pressing the [{F12}] key.

{/}

The {#109,exit()} function is used to finish a program instantly, returning
to the operating system.

{/}See: {#109,exit()} - {#158,signal()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.130,load()}

{load(}<name of the file>{,} <OFFSET data>{)}

{Description:}

Loads the raw data from a file into the computer memory.

To do this, the function requires the {name of the file} and the address
of the data within the program, this can be a variable, array or structure
and can be obtained by using the {#1085,OFFSET}) operator.

The address of the data must be the same as was used to save the data using the
{#155,save()} function.

The name of the file can be any legal MS-DOS 8:3 filename (the same limitations as fpg
and PRG filenames).

It is important that the file you wish to read data from exists, as an
error will occur if you try to load a nonexistent file (even if this can be ignored,
continuing the program's execution).

{#9999,Example program:}
PROGRAM example_load;

PRIVATE
    table[9];
    counter;

BEGIN
    write (0, 0, 0, 0, "Press [ENTER] to delete the data from memory.");
    write (0, 0, 10, 0, "Press [SPACE] to load the data from disk.");
    write (0, 0, 30, 0, "Current values of the data:");
    FROM counter=0 TO 9;
        table[counter]=rand(0, 100);
        write_int(0, 0, 40+(counter*10), 0, offset table[counter]);
    END
    save("help.dat", offset table, sizeof(table));
    LOOP
        IF (key(_enter))
            FROM counter=0 TO 9;
                table[counter]=0;
            END
        END
        IF (key(_space))

            load("help.dat", offset table); // The disk data are loaded

        END
        FRAME;
    END
END
{-}


In this example, an array of 10 values are created, and filled with random values.
This array is then saved to disk using the {#155,save()} function.

When the ENTER key is pressed, the values in the array are reset to 0.

When the SPACE key is pressed, the values are recovered into the array using
the {load()} function.

{/}See: {#155,save()} - {#1094,sizeof()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.131,load_fnt()}

{load_fnt(}<name of the file>{)}

{Returns:}

The {code} of the loaded font.

{Description:}

Loads a font file (*.FNT) from the disk.

The function returns the {font code} that can be used by the
{#171,write()} and {#172,write_int()} functions to write to the screen.

The path can be specified with the font. However, it is not necessary to do so if the
file resides in the same directory as the executable or the default font directory ({\FNT}).

The new font must have the same palette as the game is currently using for it to be
displayed correctly. Otherwise, the colours may appear incorrectly.

{#9999,Example program:}
PROGRAM example_load_fnt;

PRIVATE
    font1;

BEGIN

    font1=load_fnt("help/help.fnt"); // The font for the text is loaded

    write(0, 160, 0, 1, "Text written with the system font.");
    write(font1, 160, 10, 1, "FONT LOADED FROM DISK");
    LOOP
        FRAME;
    END
END{-}

In this example, a font is loaded with the {load_fnt()} function and then two messages
are written with different fonts. The first one with the system font, and the
second one loaded from the {help.fnt} file.

{/}

To unload the font from memory (freeing up the space that the font occupies), the
{#177,unload_fnt()} function must be called, using the {font code} as the parameter.

{It is not necessary} to unload the font unless you need the space to load other
graphics or fonts, since the system will automatically free up the font when the
program has terminated.

{/}See: {#177,unload_fnt()} - {#171,write()} - {#171,write_int()} - {#133,load_pal()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.132,load_fpg()}

{load_fpg(}<name of the file>{)}

{Returns:}

The {code} of the fpg file that was loaded.

{Description:}

Loads an {*.FPG} file from disk.

An FPG file may contain anywhere from 0 to 999 graphic images. Every image in
in the file will have a numeric code, this is the {graphic code} (a number that ranges from
{1} to {999}) that is used to identify the graphic inside the file.

It is possible to load as many graphics {FPG} files as necessary, as long as there is available
memory (this function has to be called several times to load several files).

The function returns the {file code} that can be used by many functions that require a graphic.
For that, it is necessary to indicate the {file code} in which the graphic is and the
{graphics code} inside the file.

The path can be specified with the graphics file. However, it is not necessary to do so if the
file resides in the same directory as the executable or the default {FPG} directory ({\FPG}).
{/}

When different files have been loaded, take into account that if they have different palettes,
every palette has to be activated previously with the {#133,load_pal()} function, indicating
the (FPG) file name as a parameter before using its graphics.

{#9999,Example program:}
PROGRAM example_load_fpg;

PRIVATE
    file1;

BEGIN

    file1 = load_fpg("help/help.fpg"); // The graphics' file is loaded

    put_screen(file1, 1); // We use graphic 1 of the file
    write(0, 160, 0, 1, "Graphics' file successfully loaded");
    LOOP
        FRAME;
    END
END
{-}

In this example, the {FPG} file that is going to be used in the program is loaded using
the {load_fpg()} function. Then, graphic number 1 is put as a screen background
(with the {#148,put_screen()} function).

{/}

To unload the graphics file ({FPG}) from memory (freeing up the space that the graphics file
occupies), the {#177,unload_fpg()} function must be called, using the {file code}
as the parameter.

{It is not necessary} to unload file unless you need the space to load other
graphics or fonts, since the system will automatically unload the file when the
program has terminated.


{/}See: {#169,unload_fpg()} - {#174,load_map/pcx()} - {#133,load_pal()} - {#1131,file}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.133,load_pal()}

{load_pal(}<name of the file>{)}

{Description:}

Loads a colour palette from disk (from a PAL, FPG, MAP or FNT file) defining the
{256 colours} displayed on the screen.

From that moment, the game will be seen with the colours set indicated by that palette.

If when the palette was loaded, the program had already another one assigned, a fading
of the screen colours to black will be carried out. Then, the new
colour palette will gradually appear in the following frames of the game.

The file path may be specified with the palette, although this is not necessary if the
file is in the same directory as the executable, or in the default directory (depending on
file type) ({\PAL, \FPG, \MAP or \FNT}).

The program will automatically read the palette of the first of these types of files loaded
in the program, even if the {load_pal()} function is not used. Then, this function will be
used when the program uses several different palettes to change from one to another.

{#9999,Example program:}
PROGRAM example_load_pal;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write(0, 160, 0, 1, "Press [SPACE] to load a different palette.");
    write(0, 160, 10, 1, "Press [ENTER] to load the original palette.");
    LOOP
        IF (key(_space))

            load_pal("help/help.pal"); // The palette of a .pal file is loaded

        END
        IF (key(_enter))

            load_pal("help/help.fpg");  // The palette of a .fpg file is loaded

        END
        FRAME;
    END
END
{-}

In this example, a graphics file is loaded ({FPG}) and an image is placed on the background,
along with the necessary text messages.

The main program is a small loop, testing for the space and enter keys. When a key is pressed,
a palette is loaded. The {help2.pal} file is loaded when the spacebar is pressed, and the
original palette is loaded (from the {help.fpg} file) when the ENTER key is pressed.

{/}

A palette can not be unloaded from the computer's memory, since only one palette can be loaded
at any time.

{/}See: {#174,load_map/pcx()} - {#132,load_fpg()} - {#131,load_fnt()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.134,load_sound()}

{load_sound(}<name of the file>{,} <loop>{)}

{Returns:}

The {sound code} loaded.

{Description:}

Loads a PCM, WAV or OGG sound effect from disk. The filename must be specified as the first
parameter, and the second parameter {<loop>} replaced by either a {1} if the sound must
indefinitely be repeated (looped), or {0} if it should played only once (this 
refers to the sound when played using the {#159,sound()} function).

The function returns the {sound code} that is required by the {#159,sound()} function to
play the sound through a channel.

The path can be specified with the sound file. However, it is not necessary to do so if the
file resides in the same directory as the executable or the default sounds directory ({\PCM}, {\WAV} or {\OGG}).

{#9999,Example program:}
PROGRAM example_load_sound;

PRIVATE
    id_sound;

BEGIN

    id_sound = load_sound("help/help.pcm", 0); // Loads a sound of the hard disk

    write(0, 160, 0, 1, "Press [SPACE] to play the sound.");
    LOOP
        IF (scan_code==_space)
            sound(id_sound, 100, 256);
        END
        FRAME;
    END
END
{-}

In this example, a sound is loaded with the {load_sound()} function. Then,
every time the spacebar is pressed, that sound is played using the {#159,sound()}
function.

{/}

The {#170,unload_sound()} functions allow us to free up the computer's
memory occupied by the sound when it is not going to be used any longer. For that, you require
the {sound code} in order to know which sound we want to unload from the memory.

{It is not necessary to unload the sound from memory} before finishing the program,
since the system will do it automatically.

{/}See: {#170,unload_sound()} - {#159,sound()} - {#102,change_sound()} - {#1104,Setup structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.135,map_block_copy()}

{map_block_copy(}<file>{,} <destination graphic>{,} <x destination>{,} <y destination>{,}
                 <origin graphic>{,} <x>{,} <y>{,} <width>{,} <high>{)}

{Description:}

The {map_block_copy()} function allows us to transfer a rectangular block from a graphic to another one.

The graphic from which the rectangular region is taken is called the {<origin graphic>} and
the graphic in which the block will be copied to is called the {<destination graphic>}.

The parameters are the following ones, in order:

{<file>} - Both graphics must come from the same graphics file {FPG}. The {file code} must be
specified as first parameter (see {#132,load_fpg()}). The graphics loaded with the
{#174,load_map()} or {#174,load_pcx()} functions (or created with {#188,new_map()} function)
will be used as if they were from the first file (file code 0).

{<destination graphic>} - {graphic code} in which the block is going to be put.

{<x destination>, <y destination>} - {x} and {y} coordinates at which the copied block is
to be placed inside the destination graphic.

{<origin graphic>} - {graphic code} from which the copied block is going to be taken.

{<x>, <y>} - {starting} coordinates of the block inside the origin graphic.

{<width>, <height>} - {dimensions} of the block that is going to be copied.

This function will modify the indicated graphic, but only the copy that has been loaded
into memory. The original graphic that is stored in the {FPG}, {MAP} or (PCX) files on disk
{will remain unchanged}. If you wish to recover the original graphics, then you must unload
the graphic (with {#169,unload_fpg()}, {#176,unload_map()} or {#176,unload_pcx()})
and then, load it in again to obtain the unchanged version.

{#9999,Example program:}
PROGRAM example_map_block_copy;

PRIVATE
    x_destination, y_destination;
    x_origin, y_origin;
    map_width, map_height;
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");
    graph=1;
    x=160;
    y=100;
    LOOP
        x_destination=rand(0, 320);
        y_destination=rand(0, 200);
        map_width=rand(1, 32);
        map_height=rand(1, 32);
        x_origin=rand(0, 32-map_width);
        y_origin=rand(0, 32-map_height);

        map_block_copy(file1, 1, x_destination, y_destination, 100, x_origin, y_origin, map_width, map_height);

        FRAME;
        angle+=1000;
    END
END
{-}

In this example, an {FPG} graphics file is loaded, and a graph (graphic number 1) is placed in
the centre of the screen and continuously rotated. Within the main loop, a ball graphic
(graphic number 100) is copied inside the destination graphic (number 1)
at some randomly chosen coordinates.

{/}

When a graphic is put inside another one that is being used as a scroll region's background,
it will not automatically appear on screen unless the {#152,refresh_scroll()} function is used.

{/}See: {#139,map_xput()} - {#137,map_put()} - {#138,map_put_pixel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.136,map_get_pixel()}

{map_get_pixel(}<file>{,} <graphic>{,} <x>{,} <y>{)}

{Returns:}

The colour of the point (0..255).

{Description:}

This function allows us to obtain the colour of a graphic's specific pixel.
For this, the <file code> in which the graphic is stored, the <graphic code>
inside the file and the {x} and {y} coordinates of the graphic where you wish to
obtain the colour are needed to be passed as parameters.

Graphics loaded with the {#174,load_map()} or {#174,load_pcx()} functions
(or created with {#188,new_map()} function) are treated as if they were loaded from
the first {FPG} file (code 0).

{#9999,Example program:}
PROGRAM example_map_get_pixel;

PRIVATE
    file1;
    figure;

BEGIN
    file1=load_fpg("help/help.fpg");
    put_screen(0, 7);
    mouse.graph=200;
    write(0, 0, 0, 0, "FIGURE:");
    write_int(0, 42, 0, 0, offset figure);
    LOOP

        // We take the colour of the bitmap's pixel
        figure = map_get_pixel(file1, 8, mouse.x, mouse.y);

        FRAME;
    END
END
{-}

In this example, 6 different geometrical figures are drawn on the screen in the same colour.
The mouse graphic is defined as a little cross.

The image displayed on screen directly corresponds to another graphic (graphic number 8
in the {FPG} file), which has the same figures but every one is in a different colour
(the first one of colour 1, the second one of colour 2, etc.).

In the main loop, the {map_get_pixel()} function is used to get a colour from graph 8, at the
mouse's x and y coordinates.

This value will be shown in the upper left corner of the screen and when the mouse is over
one of the shapes, will show a value from 1 to 6.

{/}

This function is normally used to detect zones inside a graphic.
This technique is called using {hardness maps} and allows us to use two different graphics, one
with the picture and the second with the zones to detect, painted using colours.

{/}See: {#123,get_pixel()} - {#138,map_put_pixel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.137,map_put()}

{map_put(}<file>{,} <destination graphic>{,} <origin graphic>{,} <x>{,} <y>{)}

{Description:}

Puts a graphic inside another one. The graphic that is going to be copied is called <origin graphic>
and the graphic in which the <origin graphic> is to be copied is called the {<destination graphic>}.
The function allows us to copy a graphic (origin) inside another one (destination).

Both graphics must be in the same {FPG} file. The parameters are as follows, in order:

{<file>} - The {file code} of the {FPG} file that contains both graphics. Graphics
loaded with the {#174,load_map()} or {#174,load_pcx()} function (or created with {#188,new_map()}
function) will be used as if they were loaded from the first file (code 0).

{<destination graphic>} - {code of the graphic} inside which the other one is going to be copied.

{<origin graphic>} - {code of the graphic} that is going to be copied into the destination.

{<x>, <y>} - {coordinates inside the destination graphic} where the origin graphic is going to be copied.
The centre (or {#1136,control point} number 0) of the origin graphic will be located at these
coordinates.

This function will modify the <destination graphic>, but only the copy of it in memory. The original graphic
that is stored in the {FPG} or {MAP} files on the disk {will remain unchanged}.

If you wish to recover the original unchanged graphic you should unload the file from memory (using
{#169,unload_fpg()} {#176,unload_map()} or {#176,unload_pcx()} functions) and then load it back again.


{#9999,Example program:}
PROGRAM example_map_put;

PRIVATE
    x_destination;
    y_destination;
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");
    graph=1;
    x=160;
    y=100;
    LOOP
        x_destination=rand(0, 320);
        y_destination=rand(0, 200);

        map_put(file1, 1, 100, x_destination, y_destination);

        angle+=1000;
        FRAME;
    END
END
{-}

In the example, graphic number 1 is put at the centre of the screen.

In every step of the main loop, this graphic rotates and a graphic number 100 (a ball) is put
inside the graphic 1 (the central graphic) with the {map_put()} function.

{/}

The {#139,map_xput()} function is a version a little more complex than the {map_put()}
function, but with much more utilities. Thus, the latter allows us, moreover, to put rotated,
scaled, mirror and transparent graphics.

The {#135,map_block_copy()} function must be used to put a part of a graphic (instead of the
full graphic) inside another one.

{/}

{Note:} When the {map_put()} function (or any other similar) is used to modify a graphic that
is being used as background of a {scroll} window, it is possible that the graphic you have put
does not immediately appear on screen. To solve this problem, you must use the {#152,refresh_scroll()} function.

{/}See: {#139,map_xput()} - {#138,map_put_pixel()} - {#152,refresh_scroll()} - {#135,map_block_copy()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.138,map_put_pixel()}

{map_put_pixel(}<file>{,} <graphic>{,} <x>{,} <y>{,} <colour>{)}

{Description:}

Allows us to modify the colour of a specific pixel of a graphic.
For that, the <file code> where the graphic is stored, the <graphic's code> inside the file
and the ({x}, {y}) coordinates of the pixel whose <colour> is intended to set are required.

The graphics loaded with the {#174,load_map()} or {#174,load_pcx()}
(or created with {#188,new_map()}) function will be used as if they belonged to the first
file (the file with the code 0).


This function will modify the indicated graphic, but only its copy that has been loaded
in the computer's memory. The original graphic, that is stored in the {FPG} or {MAP} files
of the disk, {will remain unchangeable}.
For that, if at a specific moment of the game the aim is to recover the original state of
the graphic, it will be necessary to unload it from the memory (with {#169,unload_fpg()},
{#176,unload_map()} or {#176,unload_pcx()} functions) and then, load it again.


{#9999,Example program:}
PROGRAM example_map_put_pixel;
PRIVATE
    file1;
    coord_x;
    coord_y;
    colour;

BEGIN
    file1=load_fpg("help/help.fpg");
    graph=5;
    x=160;
    y=100;
    size=180;
    LOOP
        coord_x=rand(0, 199);
        coord_y=rand(0, 199);
        colour=rand(0, 15);

        // Points are placed in the graphic number 5 of the file1
        map_put_pixel(file1, 5, coord_x, coord_y, colour);

        angle+=2000;
        FRAME;
    END
END
{-}

In the example, graphic number 5 is put at the centre of the screen, continuously
rotating. This graphic is a completely black background. For that reason, nothing
will initially be seen on screen.

But then, in every step of the loop, pixels of a colour randomly chosen between 0
and 15 (greys) are put in this graphic, at a pair of coordinates randomly chosen too.

These pixels are put using the {map_put_pixel()} function.

Notice how it seems that there are more and more pixels rotating on screen, when
the only thing that really rotates is graphic number 5.

{/}

The {#137,map_put()} or {#139,map_xput()} functions may be used to put a full
graphic inside another one (and not only at one pixel). The {#135,map_block_copy()}
function may be used to put just a part of a graphic inside another one.

{/}

{Note:} When the {map_put_pixel()} function is used to put a pixel in a graphic that
is being used as background of a {scroll} window, it is possible that this pixel does
not immediately appear on screen. To solve this problem, you must use the {#152,refresh_scroll()}
function.

{/}See: {#137,map_put()} - {#139,map_xput()} - {#152,refresh_scroll()} - {#135,map_block_copy()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.139,map_xput()}

{map_xput(}<file>{,} <graphic destination>{,} <graphic origin>{,} <x>{,} <y>{,}
           <angle>{,} <size>{,} <flags>{)}

{Description:}

Extended version of the function {#137,map_put()}.

Puts a graphic inside another one. The graphic that is going to be copied is called
<origin graphic> and the {destination graphic} is that inside which the origin will
be copied. This function allows us to copy a graphic (origin) inside
another one (destination).

Both graphics must be in the same file. The parameters are the following ones, in order:

{<file>} - {file code} with the graphics library that contains both graphics. The
graphics loaded with the {#174,load_map()} or {#174,load_pcx()}
(or created with {#188,new_map()}) function will be used as if they belonged to
the first file (the file with the code 0).

{<destination graphic>} - {code of the graphic} inside which the other one is going to be put.

{<origin graphic>} - {code of the graphic} that is going to be copied in the destination.

{<x>, <y>} - coordinates inside the destination graphic where the aim is to put the
origin graphic. The origin graphic is going to be copied at these coordinates, from
its upper left corner.

{<angle>} - angle (in degree thousandths) in which the origin graphic is going to be
copied; the normal angle is {0}.

{<size>} - size (in percentages) in which the original graphic is going to  be copied
(the normal size is {100}).

{<flags>} - Indicates the mirrors and transparencies with which the original graphic will
be copied in the destination; the values are the following ones:

 {0}-Normal graphic.ú
 {1}-Horizontal mirror.ú
 {2}-vertical mirror.ú
 {3}-Horizontal and vertical mirror (180ø).ú
 {4}-Transparent graphic.ú
 {5}-Horizontal transparencies and mirror.ú
 {6}-vertical transparencies and mirror.ú
 {7}-Transparencies, horizontal and vertical mirror.ú

This function will modify the indicated graphic, but only its copy that has been loaded
in the computer's memory. The original graphic, that is stored in the {FPG} or {MAP} or
(PCX) files of the disk, {will remain unchangeable}.
For that, if at a specific moment of the game the aim is to recover the original state
of the graphic, it will be necessary to unload it from the memory (with {#169,unload_fpg()},
{#176,unload_map()} or {#176,unload_pcx()}) and then, load it again.


{#9999,Example program:}
PROGRAM example_map_xput;
PRIVATE
    x_destination;
    y_destination;
    file1;
    angle1;
    size1;
    flags1;

BEGIN
    file1=load_fpg("help/help.fpg");
    graph=1;
    x=160;
    y=100;
    LOOP
        x_destination=rand(0, 319);
        y_destination=rand(0, 199);
        angle1=rand(-pi, pi);
        size1=rand(10, 200);
        flags1=rand(0, 7);

        map_xput(file1, 1, 101, x_destination, y_destination, angle1, size1, flags1);

        angle+=2000;
        FRAME;
    END
END
{-}

In the example, graphic 1 is put at the centre of the screen,
continuously rotating (this graphic is a decorative background in grey tonalities).

In every step of the loop, a triangle-shaped graphic (with number 100) will be put inside
graphic 1. This new graphic will be put with coordinates,
angle, size and flags (see {#1127,flags} variable) randomly chosen.

Notice how brown triangles with different applied effects are continuously appearing in
the background graphic.

{/}

The {map_xput()} function is a version a little more complex than the {#137,map_put()}
function, which is easier to use when it is not required to put rotated, scaled, mirror
and transparent graphics.

The {#135,map_block_copy()} function must be used to put a part of a graphic (instead of
the full graphic) inside another one.

{/}

{Note:} When the {map_put()} function (or any other similar) is used to modify a graphic
that is being used as background of a {scroll} window, it is possible that the graphic you
have put does not immediately appear on screen. To solve this problem, you must use the
{#152,refresh_scroll()} function.

{/}See: {#137,map_put()} - {#138,map_put_pixel()} - {#152,refresh_scroll()} - {#135,map_block_copy()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.140,move_scroll()}

{move_scroll(}<number of scroll>{)}

{Description:}

Forces to scroll automatically and immediately. This function is rather advanced and,
for that reason, it could be difficult to understand its purpose.

As a parameter, the function requires the <scroll number> from 0 to 9 that was indicated
in the {#163,start_scroll()} function as first parameter when the scroll started.

This function is used when a scroll region is automatically controlled, as the {camera}
field of the {#1101,scroll structure} corresponding to the identifier of a process has been defined.

The purpose is to force the ({x0}, {y0}, {x1} and {y1}) values of that structure to be
updated. If this function is not used, these values won't be updated until the following game's frame.

This means that when a scroll is automatically controlled and another process needs
to know the value of the coordinates of that scroll before the next frame (normally
to be located in a position in keeping with the background movement), do as follows:

{1} - The scroll starts with {#163,start_scroll()}.

{2} - The process that will be used as camera is created and its {#1039,identifying code}
is put in the {camera} field of the {#1101,scroll structure}.

{3} - A very high priority must be set for this process, for it to run before the rest
of the processes (putting in its {#1121,priority} local variable a positive whole value
like, for instance, 100).

{4} - The {move_scroll()} function will be called just before the {#1029,FRAME} statement
of the process' loop used as camera.

Thus, you will guarantee the previous execution of this process and, just at the end, the
updating of the values ({x0}, {y0}, {x1} and {y1}) of the
{#1101,scroll structure}, so the rest of the processes may use these variables already updated.

The most widespread use of this function is when you want to have more than two backgrounds
in a scroll window. For that, a series of processes simulating a third or fourth plane are
created. The position of their coordinates will depend on the exact position of the scroll
in every frame. A program doing so is shown below.

{#9999,Example program:}
PROGRAM example_move_scroll;

PRIVATE
    file1;
    counter;

BEGIN
    set_fps(100, 0);
    file1=load_fpg("help/help.fpg");
    start_scroll(0, file1, 103, 102, 0, 15);
    scroll.camera=id;
    priority=100;

    write(0, 160, 0, 1, "Use the right and left cursors to move");
    graph=101;
    ctype=c_scroll;
    LOOP
        if (key(_right))
            x+=2;
            flags=0;
        END
        if (key(_left))
            x-=2;
            flags=1;
        END

        move_scroll(0); // Updates the scroll structure[]

        FRAME;
    END
END
{-}
This example starts a scroll at full screen with two planes. Then, it moves a triangle to the
right and left with the cursors. This process will function as a scroll camera, automatically
focusing the vision on it (by putting {scroll.camera=}{#1092,id}{;}).

But, at the same time, it creates a total of 40 processes (from -2000 to 2000, every 100 pixels)
with the picture of a vertical band with moving colours as if they were a third scroll plane
(processes of the type {movable_process}).

For that, it is important that their {z} coordinate is greater than the rest of the processes
({z=100;}) and that the priority of the process that controls the camera is higher than
({priority=100;}) and that the latter uses the {move_scroll()} function before every frame ({FRAME;}).

The processes simulated by the third plane ({movable_process}), place their {x} coordinate
at a point depending on the {scroll's x} and its original position.

The difference lies in the fact that, if {move_scroll()} had not been used, the processes,
by using the {scroll.x0} variable without being updated, would move with a certain slowness
that detracted from the credibility  of the game.

{/}See: {#163,start_scroll()} - {#1101,Scroll structure} - {#1121,Priority} - {#1125,Z}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.141,move_text()}

{move_text(}<text identifier>{,} <x>{,} <y>{)}

{Description:}

Moves a text towards other screen coordinates. The { text identifier} and the ({x}, {y})
screen coordinates towards which the text must be moved are specified as parameters. The
identifier of the text is a numeric code returned by the {#171,write()} and {#172,write_int()}
functions when they are required to write a text.

The {centreing code} specified in the {#171,write()} or {#172,write_int()} functions will
remain when this function is used.

The specified coordinates always dealt with the screen and may be inside it or out from it.
It is necessary to use the {#1106,text_z} global variable to modify the {z coordinate of the
texts} (the depth plane in which they appear).

{#9999,Example program:}
PROGRAM example_move_text;

PRIVATE
    id_text1;
    id_text2;
    coord_x;
    coord_y;
    angle1;

BEGIN
    id_text1=write(0, 160, 100, 4, "MOVING TEXT");
    id_text2=write(0, 160, 100, 4, "MOVE THE MOUSE");
    LOOP
        coord_x=160+get_distx(angle1, 100);
        coord_y=100+get_disty(angle1, 90);

        // We move the texts
        move_text(id_text1, coord_x, coord_y);
        move_text(id_text2, mouse.x, mouse.y);

        angle1+=1000;
        FRAME;
    END
END
{-}

In the example, two texts are displayed at the centre of the screen with the {#171,write()}
function. This function returns the identifiers of those texts, that are stored in the {id_text1}
and {id_text2} variables.

In every step of the loop, the first text moves along a circular path obtained by increasing an angle
({angle1}) and using the {#118,get_distx()} and {#119,get_disty()} functions. The second text will be
placed at the coordinates of the mouse pointer.

Both texts move in every frame with the {move_text()} function.

{/}

To delete a text definitively, the {text identifier} is also required, and the {#107,delete_text()}
function must be used for that.

{/}See: {#171,write()} - {#172,write_int()} - {#107,delete_text()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.142,near_angle()}

{near_angle(}<angle>{,} <final angle>{,} <increment>{)}

{Returns:}

A new angle nearer to the final angle.

{Description:}

Brings an angle nearer another one at the given increment. The function returns the new angle.

It is used when the aim is that an angle (<angle>) gradually varies
until it becomes another angle (<final angle>). For that, the  function needs the original angle,
the {final angle} and the angular {increment} that is going to be added to or subtracted from the
original angle.

Keep in mind that all the angles are specified in degree thousandths. The angular {increment}
is but a small angle (such as one degree ({1000}) or five ({5000}).

{#9999,Example program:}
PROGRAM example_near_angle;

PRIVATE
    angle2;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    mouse.graph=200;
    graph=101;
    write(0, 160, 200, 7, "Move the mouse cursor");
    LOOP
        angle2=fget_angle(x, y, mouse.x, mouse.y);

        // Brings the current angle closer to the final one in 10 degrees at the most
        angle = near_angle(angle, angle2, 10000);

        advance(6);
        FRAME;
    END
END
{-}

In the example, the mouse cursor is defined as a little cross that can be moved by the user.

The main program defines its graphic as a triangle ({graph=101;})
that, in every loop's iteration, obtains the angle towards the mouse cursor with the {#113,fget_angle()}
function. Then, it modifies its angle
to move 10 degrees (10000) at the most towards the cursor angle, using the {near_angle()} function.
Finally, it advances 6 points
in that direction by using the {#101,advance()} function.

Notice how the triangle continuously pursues the mouse cursor without making any abrupt turn (bigger
than 10 degrees).

{/}See: {#1044,Use of the angles in the language} - {#1129,angle} - {#116,get_angle()} - {#113,fget_angle()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.143,out_region()}

{out_region(}<identifier code>{,} <number of region>{)}

{Returns:}

{True} if the process is outside of the region or {False} in the opposite case.

{Description:}

This function determines whether a process is out of a screen region. For that, the function
requires the {#1039,identifying code} of the process and a region number.

The screen regions can be defined with the {#106,define_region()} function and they are simply
rectangular zones of screen.

Region number {0} can not be defined, as it will always be equivalent to the entire screen.
Therefore, if {0} is specified as a second parameter, this function determines whether a process
is out of the screen (if it is not seen).

In case that the process' graphic is out of the specified region, the function returns {True}
(an odd number). Otherwise, if the graphic is seen in that region, even partially, the function
returns {False} (any even number).

The process whose {#1039,identifying code} is indicated must have its graphic correctly defined
(normally in its {#1026,graph} variable). Otherwise, the system will produce an error,
since it is not possible to calculate the dimensions of a graphic if the process lacks it.

{#9999,Example program:}
PROGRAM example_out_region;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    y=100;
    x=160;
    graph=101;
    LOOP
        advance(8);

        IF (out_region(id, 0)) // Check for off screen

            x=160;
            y=100;
            angle=rand(-pi, pi);
        END
        FRAME;
    END
END
{-}

In the example, a background graphic is put and the main program creates a triangle-shaped
graphic at the centre of the screen with an angle randomly chosen.

In every step of the loop, the triangle advances and it is checked whether it is still present on
the screen (region 0) with the {out_region()} function. If so, it is put once again at the centre
of the screen with another angle, also randomly chosen.

{/}See: {#106,define_region()} - {#1130,region} - {#1039,codes identifiers}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.144,play_cd()}

{play_cd(}<number of track>{,} <mode>{)}

{Description:}

Starts playing a cd-audio track. The track number (from 1 to the number of songs contained on the cd)
must be indicated. The way to do it is as follows:

{Mode.}

 {0} - Play the song and then stop.ú
 {1} - Play this song and then the following ones.ú

{#9999,Example program:}
PROGRAM example_play_cd;
BEGIN
    write(0, 160, 0, 1, "Press [SPACE] to turn the CD on.");
    LOOP
        IF (scan_code==_space)

            play_cd(1, 1); // It plays the 1st. song followed by all remaining tracks.

        END
        FRAME;
    END
END
{-}

In the previous example (for which it is necessary to have a music {Compact disc} inside
the {CD-ROM} device) an information message is displayed and in every iteration of the loop
it is checked whether the spacebar was pressed to play the first song with the {play_cd()} function.

{/}

To have a song indefinitely playing, a loop must be implemented, using 
the {#127,is_playing_cd()} function to determine when the song is over.

The cd-audio reproduction volume can be controlled with the {#1104,setup} structure and the
{#178,set_volume()} function.

{/}See: {#127,is_playing_cd()} - {#164,stop_cd()} - {#178,set_volume()} - {#1104,Setup structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.145,pow()}

{pow(}<expression>{,} <expression>{)}

{Returns:}

The first expression {raised} to the second.

{Description:}

Calculates the result when the first expression is raised to the second one.

For instance, {pow(3, 2)} will return {9}, which is {3} squared, {3ý}, or {3*3}.

{#9999,Example program:}
PROGRAM example_pow;
GLOBAL
    values[15];
    n;
BEGIN
    FROM n=0 TO 15;
        values[n]=rand(-100, 100);
        write_int(0, 0, n*10, 0, offset values[n]);
    END
    write(0, 0, 192, 0, "Press [SPACE] to square these numbers");
    LOOP
        IF (scan_code==_space)
            FROM n=0 TO 15;

                values[n] = pow(values[n], 2); // Square the values (valueý or value ^ 2)

            END
        END
        FRAME;
    END
END
{-}

This program will display a list of numbers randomly chosen between -100 and 100 on the screen.
When the spacebar is pressed, these numbers will square.

Take into account that in the language {it is only possible to use integers within the}
({#1177,min_int} ... {#1178,max_int}) {range}. Therefore, when the result of the function exceeds
this range, {incorrect results will be shown}. In this case, the system won't produce an error,
so care must be taken.

{/}See: {#1035,Expression}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.146,put()}

{put(}<file>{,} <graphic>{,} <x>{,} <y>{)}

{Description:}

Puts a graphic in the screen background. The function requires the {file code} in which
the graphic is stored, the {graphic code} inside the same file and the ({x}, {y}) coordinates at
which the graphic is intended to be put.

The graphics loaded with the {#174,load_map()} or {#174,load_pcx()}
(or created with {#188,new_map()}) function will be used as if they belonged to the first file
(the file with the code 0).

If the centre graphic was not specified (setting its {#1136,control point}
number 0 from the painting tool), the coordinates will be referred to the position on the screen in
which the graphic {centre} will be located.

The graphics displayed on the screen background like this will be within the game's display
{under all the processes, scroll regions, texts, etc.}

If the aim is to have a graphic over some others, it must be {created as a new process} and
its {#1125,z} variable must be established, indicating the priority of its display.

The {#103,clear_screen()} function must be used to clear the screen background.

{#9999,Example program:}
PROGRAM example_put;

PRIVATE
    file1;
    coord_x;
    coord_y;

BEGIN
    file1=load_fpg("help/help.fpg");
    LOOP
        coord_x=rand(0, 319);
        coord_y=rand(0, 199);

        put(file1, 100, coord_x, coord_y); // The graphic 100 is "put".

        FRAME;
    END
END
{-}

In the example, the file with the graphics is loaded and in every iteration
of the loop graphic number 100 (a ball) is put, with the {put()} function, at random coordinates
(randomly chosen with the {#149,rand()} function).

{/}

If the graphic that is intended to be put is merely a background screen, it is easier to use the
{#148,put_screen()} function, since it does not require the screen coordinates, because it will
automatically centre the graphic on the screen.

{/}

The {#173,xput()} function is a version a little more complex than the {put()} function, but
with much more utilities since, at the same time, it allows us to put rotated, scaled, mirror
and transparent graphics.

To put a graphic inside another one (instead of in the screen background), the {#137,map_put()}
or {#139,map_xput()} functions must be used.

{/}See: {#148,put_screen()} - {#173,xput()} - {#137,map_put()} - {#139,map_xput()} - {#147,put_pixel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.147,put_pixel()}

{put_pixel(}<x>{,} <y>{,} <colour>{)}

{Description:}

Plots a pixel of the specified {colour} at the indicated coordinates ({x}, {y}) on the background screen.

The pixels put with this function in the background screen will be displayed in the game {below
all the processes, scroll regions, texts, etc.}

If the aim is to see a pixel over other graphics, you must create a new process, assigning the
picture of a point (in its {#1126,graph} variable) as a graphic and fixing its {z} variable
with the priority of its printing.

To clear the background screen, the {#103,clear_screen()} function must be used.

{#9999,Example program:}
PROGRAM example_put_pixel;

PRIVATE
    x_pixel;
    y_pixel;
    colour;

BEGIN
    LOOP
        x_pixel=rand(0, 319);
        y_pixel=rand(0, 199);
        colour=rand(0, 15);

        // The pixels are put in the background screen at random
        put_pixel(x_pixel, y_pixel, colour);

        FRAME;
    END
END
{-}

In the example, in every step of the loop the pixels are put with the
{put_pixel()} function, with coordinates and colour chosen at random with the {#149,rand()} function.

{/}

To read the colour of a specific background screen colour, the {#123,get_pixel()} function must be used, returning a number between 0 and 255 corresponding to the order of the colour inside the palette.

The {#146,put()} function must be used to set a graphic on the screen, instead of a simple pixel.

It is also possible to set the colour of a pixel in a specific graphic, instead of in the background screen, by using the {#138,map_put_pixel()} function.

{/}See: {#123,get_pixel()} - {#146,put()} - {#138,map_put_pixel()} - {#136,map_get_pixel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.148,put_screen()}

{put_screen(}<file>{,} <graphic>{)}

{Description:}

Establishes the background screen. The function requires the {file code} in which the graphic is, and the own {code of the graphic} intended to be displayed in the background screen inside the file.

The graphics loaded with the {#174,load_map()} or {#174,load_pcx()}
(or created with {#188,new_map()}) function will be used as if they belonged to the first file (the file with the code 0).

The function does not require any coordinate as a parameter since, if the graphic size (in pixels) is different from that of the screen, the former will simply be displayed centred in the latter.

The {#103,clear_screen()} function must be used to clear the screen background.

{#9999,Example program:}
PROGRAM example_put_screen;

PRIVATE
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");

    put_screen(file1, 1); // Graphic 1 is established as background.

    LOOP
        FRAME;
    END
END
{-}

In the example, the graphics' file is loaded and a background graphic (contained in the file with the graphic code number 1) is set with the {#148,put_screen()} function.

{/}

If the aim is to display a graphic on a specific part of the screen or a graphic {that is not centred}, the {#146,put()} may be used. Moreover, the {#173,xput()} function allows us to display rotated, scaled, mirror and/or transparent graphics in any screen region.

{/}See: {#146,put()} - {#173,xput()} - {#147,put_pixel()} - {#103,clear_screen()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.149,rand()}

{rand(}<minimum value>{,} <maximum value>{)}

{Returns:}

A random numeric value.

{Description:}

Returns a random number (chosen at random) between the {minimum value} and the {maximum value}, both included.

This function is normally used to set all the parameters intended to be varied in a game when it is restarted. For instance, the coordinates of an enemy may be initialised with random numbers, so it may appear in a different position in every game.

This function has another utility. Thus, if we want that an action does not always occur, but that it has a certain probability to occur, we normally use a statement of the following type:

  {IF (rand(0, 100)<25)}ú
     { // Action ...}ú
  {END}ú

In this case, the {action} will take place, on average, 25 per cent of the times the {#1020,IF} statement would be executed. The reason for that is that, on obtaining a random number between 0 and 100, this number would be less than 25 in a fourth of times, approximately.

{#9999,Example program:}
PROGRAM example_rand;

PRIVATE
    table[15];
    counter;

BEGIN
    write (0, 0, 192, 0, "Press [SPACE] to calculate random values.");
    FROM counter=0 TO 15;
        write_int(0, 0, counter*10, 0, offset table[counter]);
    END
    LOOP
        IF (scan_code==_space)
            FROM counter=0 TO 15;

                // Random values between -100 and 100 are chosen
                table[counter] = rand(-100, 100);

            END
        END
        FRAME;
    END
END
{-}

In the example, a table with 16 data (from 0 to 15) is created. In every
iteration of the main loop it is checked whether the spacebar has been pressed.
If so, the 16 data of the table will be filled with random values between -100 and 100,
chosen with the {rand()} function.

{/}

By default, the values returned by the {rand()} function will completely be different in every execution of the program. If we want to have always the same series of numbers, we may use the {#150,rand_seed()} function, specifying a number behind which the series of numbers returned by the {rand()} function will always be predetermined.

{/}See: {#150,rand_seed()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.150,rand_seed()}

{rand_seed(}<numeric value>{)}

{Description:}

This function sets a seed for the generator of random numbers
(the numbers generated by the {#149,rand()} function).

The seed can be any integer within the range ({#1177,min_int} ... {#1178,max_int}).
If the seed is set, all the numbers generated by the {#149,rand()} function will be
the same in every execution of the program.
After having been established an origin seed, the {#149,rand()}
function will return a series of numbers predetermined for this seed.

{#9999,Example program:}
PROGRAM example_rand_seed;

PRIVATE
    table[15];
    counter;

BEGIN
    write (0, 0, 184, 0, "Press [ENTER] to set 1234 as a seed.");
    write (0, 0, 192, 0, "Press [SPACE] to calculate random values.");
    FROM counter=0 TO 15;
        write_int(0, 0, counter*10, 0, offset table[counter]);
    END
    LOOP
        IF (scan_code==_space)
            FROM counter=0 TO 15;
                table[counter] = rand(-100, 100);
            END
        END
        IF (scan_code==_enter)

            rand_seed(1234); // A seed is set to generate the random numbers.

        END
        FRAME;
    END
END
{-}

In the example, a table with 16 bits of data (from 0 to 15) is created. In every iteration
of the main loop,  the data will be filled with random values from -100 and 100 (chosen with the {#149,rand()} function) every time the spacebar is pressed.

And when the ENTER key is pressed, then the seed of the random numbers will be defined as 1234 with the {rand_seed()} function.

Notice how, every time the ENTER key is pressed and then, by pressing the space bar, the same series of random numbers (17, 94, -38, ...) is obtained. This series will be different for every possible seed.

{/}See: {#149,rand()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.152,refresh_scroll()}

{refresh_scroll(}<number of scroll>{)}

{Description:}

This function is used when a graphic that is being used as a {background of a scroll region} has been modified with the {#137,map_put()}, {#139,map_xput()}, {#135,map_block_copy()} or {#138,map_put_pixel()} functions, in order to update it.

The parameter required by the function is the <scroll number> that was specified when the scroll started with the {#163,start_scroll()} function.

When a graphic that is being used as background of a scroll is modified, it is not automatically updated on the screen. On the contrary, it is necessary to call this function for that purpose.

Once the graphic has been modified, it will remain like this during the rest of the program execution, unless the graphic is unloaded from the memory (with {#169,unload_fpg()}, 
{#176,unload_map()} or {#176,unload_pcx()} functions) and loaded again. In this case, the original state of the graphic will be restored.


{#9999,Example program:}
PROGRAM example_refresh_scroll;

BEGIN
    load_fpg("help/help.fpg");
    start_scroll(0, 0, 103, 102, 0, 15);
    scroll.camera=id;
    write(0, 160, 192, 7, "Press [ENTER] to put a graphic in the scroll.");
    write(0, 160, 200, 7, "Press [SPACE] to update scroll.");
    LOOP
        IF (scan_code==_enter)
           map_put(0, 103, 100, rand(16, 48), rand(16, 48));
        END
        IF (scan_code==_space)

            refresh_scroll(0); // We refresh the scroll 0.

        END
        x+=2;
        y+=1;
        FRAME;
    END
END
{-}

In the example, a scroll (number 0) is created as a scroll of two planes:
the foreground with graphic number 103 and the background with graphic number 102.

Inside the main loop, a ball will be displayed over graphic 103 (foreground of the scroll)
when the ENTER key is pressed. But it won't appear on-screen, unless we await until the
scroll gradually appears on-screen (with graphic 103 already modified), or until the spacebar
is pressed. In this case, the call to the {refresh_scroll()} function will update the scroll
window with the graphic already modified.

If, in the previous example, the {refresh_scroll()} function had been called just after
the {#137,map_put()} one, the graphics displayed on the foreground would instantaneously
appear by pressing the spacebar.

In the example, every time that a ball is displayed, many of them appear. The reason for
this is that graphic 103 used as a foreground in the scroll
is a small graphic and it is shown on many occasions tile, to fill all the scroll zone.

{/}

{Note:} It can be noticed that, if the displaying graphic is at some coordinates out
of the screen, it won't be necessary to call this function, because the parts of the
scroll that are gradually appearing on-screen are automatically refreshed.

{/}See: {#163,start_scroll()} - {#140,move_scroll()} - {#1101,Structure scroll}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.153,reset_fli()}

{reset_fli()}

{Description:}

This function {rewinds} an {FLI/FLC} animation to the beginning. This animation
started with the {#161,start_fli()} function.

After having called this function, the animation will entirely be displayed again
from the beginning (to display every frame of the animation, you must call the {#115,frame_fli()} function).

The utility of this function deals with the possibility of stopping an animation
and repeating it again from the beginning, without unloading it ({#108,end_fli()}) and loading it again.

If the aim is to perform an animation indefinitely, restarting when it is over, then
{it is not necessary to use this function}, since it will automatically be done
with {#115,frame_fli()}, if you keep on calling once the animation is over.

Only one animation can exist at the same time. Thus, it is not necessary to specify
any parameter for this function.

{#9999,Example program:}
PROGRAM example_reset_fli;
BEGIN
    start_fli("help/help.fli", 0, 0);
    write(0, 160, 0, 1, "Press [SPACE] to restart the animation.");
    LOOP
        frame_fli();
        IF (scan_code==_space)

            reset_fli(); // The animation is initialised

        END
        FRAME;
    END
END
{-}

In the example, an animation is loaded with the {#161,start_fli()} function and
then, it is indefinitely performed with the {#115,frame_fli()} function.

In the loop, it is checked whether the spacebar has been pressed. If so, the animation
is reinitialised with the {reset_fli()} function.

{/}See: {#161,start_fli()} - {#115,frame_fli()} - {#108,end_fli()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.154,roll_palette()}

{roll_palette(}<initial colour>{,} <number of colours>{,} <increment>{)}

{Description:}

Rotates a range of palette colours. This function is used to create movement
effects in static graphics, like the effect of flowing water.

To use this function, it is first necessary to create graphics that use a
range of consecutive colours of the original palette, in a perpetual cycle
(for instance, colours ranging from {0} to {15}, painting something with
the colours 0, 1, 2, 3, ... , 14, 15, 0, 1, 2, ...).

Then, it is necessary to take care that those colours are not used by other graphics that are going to appear on the screen at the same time, if you do not want to implement the effects on them.

The {increment} (third parameter) is normally {1} to perform the rotation in a direction and{ -1} to perform it in the opposite direction, but other values may be used to perform the colours cycle at higher speed.

To perform a cycle of colours from {0} to {15}, it would be necessary to specify {0} as <initial colour> and {16} as <number of colours>.

{#9999,Example program:}
PROGRAM example_roll_palette;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 2);
    write(0, 160, 0, 1, "Press [SPACE] to rotate the entire palette.");
    LOOP
        IF (scan_code==_space)

            roll_palette(0, 256, 1); // The 256 colours rotate.

        END
        FRAME;
    END
END
{-}

In the example, a multicolour screen is put as background and, inside the program's main loop, the 256 colours of the palette will rotate every time that the spacebar is pressed.

{/}

To determine the palette which is going to realise the circle
of colour, this must be loaded from an file with the function 
{#133,load_pal()}.

{/}

To perform other palette effects without replacing some colours by other ones in cycles, the {#110,fade()} function must be used. This function allows us to perform many colours fading and saturations at different speeds.

There are two simplified versions of this last function that allow us to carry out a fading to black ({#111,fade_off()}) and undo it ({#112,fade_on()}).

{/}See: {#179,set_color()} - {#133,load_pal()} - {#110,fade()} - {#111,fade_off()} - {#112,fade_on()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.155,save()}

{save(}<name of the file>{,} <OFFSET data>{,} <sizeof(data)>{)}

{Description:}

Saves a data block from the program memory to a file in the disk, to recover it later, when it is required, with the {#130,load()} function.

For that, the function requires the {file name}, the offset (inside
the computer memory) of the variable, table or structure stored in
the disk (the variable offset is obtained with {#1085,OFFSET}  
{<variable name>}) and the number of memory positions that this variable occupies (which may be obtained with {#1094,sizeof}{(<file name>)}).

It is possible to save several data (variables, tables or structures) if they have consecutively been defined inside the same section ({#1006,GLOBAL}, {#1007,LOCAL} or {#1008,PRIVATE}). In this case, the {#1085,OFFSET} of the first variable must be indicated as a {second parameter}, and the addition of the {#1094,sizeof()} of all the data must be indicated as a {third parameter}.

It is not necessary to specify a path together with the file name.

{#9999,Example program:}
PROGRAM example_load;

PRIVATE
    table[9];
    counter;

BEGIN
    write (0, 0, 0, 0, "Press [ENTER] to reset the data.");
    write (0, 0, 10, 0, "Press [SPACE] to load the disk data");
    write (0, 0, 30, 0, "Current values of the data:");
    FROM counter=0 TO 9;
        table[counter]=rand(0, 100);
        write_int(0, 0, 40+(counter*10), 0, offset table[counter]);
    END

    save("help/help.dat", offset table, sizeof(table)); // The file is saved.

    LOOP
        IF (key(_enter))
            FROM counter=0 TO 9;
                table[counter]=0;
            END
        END
        IF (key(_space))
            load("help/help.dat", offset table);
        END
        FRAME;
    END
END
{-}

At the beginning of the example, a table of 10 positions (from 0 to 9) is created with random values. This table is saved in the disk with the {save()} function.

When the ENTER key is pressed, the table values are reset (the 10 positions are put at 0).

When the spacebar is pressed, the table's values stored in the disk are loaded with the {#130,load()} function.

{/}

To save the {table[9]} and the {counter} variable in the same file, the {save()} function should have been called in the following way:

  {save("help/help.dat", offset table, sizeof(table)+sizeof(counter));}

Do not vary the load statement ({load("help.dat", offset table);}), as it does not require the number of data.

The value returned by {#1094,sizeof()} for any variable (like {counter})
will always be 1. For a table, this function returns the number of positions that it has. Then, considering that 11 data (10 of the table and 1 of the variable) are going to be saved, the statement to save them could be as follows:

{save("help/help.dat", offset table, 11);

{/}See: {#130,load()} - {#1085,OFFSET} - {#1094,sizeof()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.156,set_fps()}

{set_fps(}<number of frames per second>{,} <number of allowed jumps>{)}

{Description:}

This function regulates the speed of the game; it defines how many frames per second will be
displayed during the game.

By default, the display will be regulated at 18 frames per second, which means
that if a process moves a pixel per every ({FRAME}),
it will move on-screen at a speed of 18 pixels per second.

This function may establish the number of Frames Per Second ({FPS}) from a minimum of {4} to a maximum of {200}; in general, no more than
24 frames per second are necessary to obtain a fluid and slight movement.

The second parameter, {maximum number of allowed omissions}, is referred to how the program must preferably work when it is executed on a computer fast enough to calculate the required number of frames per second. It works as follows.

{Number of allowed omissions.}

{0} - The game will go at a slower speed when it is executed on a computer that is too slow
to keep the required frame rate - It will only display the frames per second that the computer
has had time to calculate.

{1} - If the computer cannot calculate all the frames, it is allowed to occasionally
skip a frame to try to keep the game's relative speed. The game movements will become
a little more abrupt, but faster.

{2 or more} - The game is allowed to skip as many consecutive frames as is indicated
in this parameter to maintain the original relative speed of the game. For instance,
if the number of omissions is set at {4} and in the game a process moved one pixel
at a time, in a very slow computer it could move four pixels at a time.

{#9999,Example program:}
PROGRAM example_set_fps;

PRIVATE
    frames=24;
    omissions=4;

BEGIN
    load_fpg("help/help.fpg");
    graph=1;
    x=160;
    y=100;
    write(0, 0, 0, 0, "Frames per second: Up(+) / Down(-)");
    write_int(0, 0, 10, 0, offset frames);
    write(0, 0, 20, 0, "Allowed omissions: Right(+) / Left(-)");
    write_int(0, 0, 30, 0, offset omissions);
    write(0, 160, 200, 7, "Use the CURSORS to change the values.");
    LOOP

        // The number of frames per second is chosen
        set_fps(frames, omissions);

        IF (key(_up) AND frames<200) frames++; END
        IF (key(_down) AND frames>4) frames--; END
        IF (key(_right) AND omissions<20) omissions++; END
        IF (key(_left) AND omissions>0) omissions--; END
        angle+=4000;
        FRAME;
    END
END
{-}

In the example, the necessary messages are displayed and the main process
creates a graphic, which is indefinitely rotating at the centre of the screen.

In every step of the loop the cursor keys are detected, the number of frames per second ({frames}) is changed with {up/down} and
the maximum number of allowed {omissions} is changed with {right/left}.

At the beginning of every iteration of the loop, the speed is set with the  {set_fps()} function, according to the values of both variables.

{/}

{Note:} The global variable {#1426,fps} monitors the number of 
frames per second which is being reached in the program.

{/}See: {#1029,FRAME} - {#1115,max_process_time} - {#157,set_mode()} - {#1426,fps}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.157,set_mode()}

{set_mode(}<new video mode>{)}

{Description:}

Establishes a new video mode for the game execution. The allowed videomodes that may be specified as a parameter are the following ones:

  {m320x200}  - VGA standardú
  {m320x240}  - X Modeú
  {m320x400}  - X Modeú
  {m360x240}  - X Modeú
  {m360x360}  - X Modeú
  {m376x282}  - X Modeú
  {m640x400}  - SVGA VESAú
  {m640x480}  - SVGA VESAú
  {m800x600}  - SVGA VESAú
  {m1024x768} - SVGA VESAú

When a change of the videomode in the program is made, a fading to black (of the program's colours palette) will automatically be performed and in the following displays, the colours palette will gradually be restored. That is to say, {set_mode()} always performs a {#111,fade_off()} just before changing the videomode and a {#112,fade_on()} just after having changed it.

By default, all the programs start with the 320 by 200 pixel activated mode ({set_mode(m320x200)}).

{#9999,Example program:}
PROGRAM example_set_mode;

PRIVATE
    modes[]=
        m320x240, m640x480, m800x600, m1024x768;
    videomode=0;

BEGIN
    load_fpg("help/help.fpg");
    write (0, 0, 0, 0, "Press [SPACE] to change the videomode");
    LOOP
        IF (scan_code==_space)
            videomode=videomode+1;
            IF (videomode==4) videomode=0; END

            set_mode(modes[videomode]);

        END
        FRAME;
    END
END
{-}

In the example, a screen background and an explanatory text are displayed.

In the iteration of the main loop, if the space bar is pressed, a new videomode will be activated with the {set_mode()} function.

{/}

{Important:} By using the {set_mode()} function, all the scroll and mode 7 windows that were activated in the game, as well as all the processes displayed inside them, will be deleted.

{/}See: {#156,set_fps()} - {#1115,max_process_time} - {#1150,m320x200 ... m1024x768} - {#1415,STRUCT video_modes}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.158,signal()}

{signal(}<id>{,} <signal>{)}

{Description:}

Sends a signal to a process (an object of the game). This function is used mainly to 
destroy (kill) a process from other, sending it a signal {#1153,s_kill}.

If you don't know the meaning of process father, son,
{brother}, of an {orphaned} process, etc., then see {#1041,Hierarchy of processes}.

If you don't know the terms live, {dead}, {slept}, etc., referred to processes
, then see {#1040,Process state}

{#9999,Example:}
PROGRAM my_game;
PRIVATE id2;
BEGIN
    id2=my_process();
    // ...
    signal(id2, s_kill);
END
PROCESS my_process()
BEGIN
    // ...
    LOOP
        FRAME;
    END
END
{-}

This program would create a {my_process} type process and then it would delete it with the {signal(id2,s_kill)} statement (id2 is a variable of the main program that contains the {#1039,identifying code} of the process that is going to be deleted).

Any process may send a signal to another one, provided that the former has the {#1039,identifying code} of the latter. See:

  {#1039,Identifying codes of processes}ú
  {#1038,Ways to obtain the identifying code of a process}ú

Nevertheless, there are other {signal types} that may be sent to a process,
and they are the following ones:

{#1153,s_kill} - Order to {kill} the process. The process will not appear in the following frames of the game any longer.

{#1155,s_sleep} - Order to {make} the process {dormant}. The process will remain paralyzed, without executing its code and without being displayed on screen (nor being detected by the rest of the processes), as if it had been killed. But the process will continue to exist in the computer's memory (see {s_wakeup}).

{#1156,s_freeze} - Order to {freeze} the process. The process will remain motionless without running its code. But it will continue being displayed on screen and it will be possible to detect it (in the collisions) by the rest of the processes. The process will continue to exist in the computer's memory, even if its code is not executed (see {s_wakeup}).

{#1154,s_wakeup} - Order to {wake up} the process. It returns a {slept} or {frozen} process to its normal state. The process will be executed and displayed again from the moment that it receives this signal normally.
A process that has been deleted (killed) can not be returned to its normal state, since it does not exist in the computer's memory any longer.

A process can also send these signals to itself, taking into account that the {#1039,identifying code} of a process is always {#1092,ID} (word reserved in the  language to this purpose). The statement would be as follows:

{signal(}{#1092,id}{,} <signal>{)}

Self-deleting a process in this way, sending a {#1153,s_kill} signal to itself, will not instantaneously destroy the process, but in the following ({#1029,FRAME}) display. The {#1028,RETURN} statement can be used to immediately delete a process.

{All the signals sent to processes will be implemented just before the next display of the game}, in the next {#1029,FRAME} of the game (not instantaneously).

Together with these four signals, there are other four signals that directly correspond to the previous ones. They are: {#1157,s_kill_tree}, {#1158,s_sleep_tree}, {#1160,s_freeze_tree} and {#1159,s_wakeup_tree}.

These signals are sent not only to the indicated process, but also {to all the processes that it has created}. That is to say, if a {#1157,s_kill_tree} signal is sent to a process, the latter and all its descendants (sons, grandsons, ...) will be deleted as well as all the processes created by it and the processes created by the latter.

An exception to these last four signals is when there is an {orphan process}, a process whose father (the process that called it) is already dead. The orphan processes will not receive the signal when it is sent to a process from which they are descended as, on having disappeared their father, it won't be able to send the signal to the processes it created.

{#9999,Example program:}
PROGRAM example_signal;
PRIVATE
    id_text;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write(0, 0, 0, 0, "1 - create the process");
    write(0, 0, 10, 0, "2 - kill the process");
    write(0, 0, 20, 0, "3 - sleep the process");
    write(0, 0, 30, 0, "4 - freeze the process");
    write(0, 0, 40, 0, "5 - wake up the process");
    id_text=write(0, 0, 190, 0, "There is no process");
    LOOP
        IF (key(_1) AND NOT son)
            delete_text(id_text);
            my_process();
            id_text=write(0, 0, 190, 0, "Process alive");
        END
        IF (key(_2) AND son)
            delete_text(id_text);
            signal(son, s_kill);
            id_text=write(0, 0, 190, 0, "There is no process");
        END
        IF (key(_3) AND son)
            delete_text(id_text);
            signal(son, s_sleep);
            id_text=write(0, 0, 190, 0, "Process slept");
        END
        IF (key(_4) AND son)
            delete_text(id_text);
            signal(son, s_freeze);
            id_text=write(0, 0, 190, 0, "Process frozen");
        END
        IF (key(_5) AND son)
            delete_text(id_text);
            signal(son, s_wakeup);
            id_text=write(0, 0, 190, 0, "Process alive");
        END
        FRAME;
    END
END

PROCESS my_process()
BEGIN
    graph=100;
    LOOP
        x=160+get_distx(angle, 140);
        y=100+get_disty(angle, 80);
        angle+=5000;
        FRAME;
    END
END
{-}

With the {1} key, this program will create a process ({my_process}) that rolls around the screen; with the keys from {2} to {5}, different signals will be sent to this process, by using this function. The {#1039,identifying code}
of {my_process} is located in the {son} local variable of the main program by default.

When a process is created, the system defines the {#1118,son} variable of the father with the {#1039,identifying code} of the son, and the {#1117,father} variable of the son with the identifying code of the father.

{/}

{signal(}{#1042,TYPE} <name of the process>{,} <signal>{)}

{Description:}

This second meaning of the {signal} function is similar to the previous one, with the exception that, instead of sending a signal to a process from its {#1039,identifying code}, it allows us to send a signal {to all the processes
of a specific type} or to them and their descendants, when the used signals are
of the type {s_kill_tree} (see: {#1042,Types of processes}).

For instance, if several processes of the {enemy} type exist or may exist in a game, and the aim is to freeze these processes (without freezing their descendants), the following statement will be used:

  {signal(TYPE enemy, s_freeze);}

As it can be noticed, it is necessary to have the {#1039,identifying code} of a specific process in order to send a signal to it. To delete a group of processes, it is necessary either that they are of the same kind, that this group is made up of a process and its descendants, or that all their identifiers are known ( in order to send them the signal one by one).

It is possible to send a signal to a type of processes, even if no process of this type is being executed in the game. But if a signal is sent to a process that has already been killed, with its {#1039,identifying code} (first meaning of the {signal} statement), there is a risk that the {#1039,identifying code} is now used by another process, which is going to receive the signal. This happens, for instance, when the aim is to kill a process that has already been killed, as it is possible that another different one is being killed.

{/}

{Note:} If the aim is to delete all the processes except the current one, the {#129,let_me_alone()} function may be used. This function sends a {s_kill} signal  to all the processes, except the one that executed this function.

{/}See: {#129,let_me_alone()} - {#1039,Identifier codes} - {#1042,Types of processes}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.159,sound()}

{sound(}<code of the sound>{,} <volume>{,} <frequency>{)}

{Returns:}

The {channel number} through which the sound is played.

{Description:}

Plays the effect whose {sound code} is specified as first parameter.
At first, the sound must have been loaded from an audio file with the
{#134,load_sound()} function. This function returns the {sound code} corresponding to this effect.


As a second parameter, it is necessary to specify the {volume} at which the sound is intended to be reproduced, taking into account that {0} is the minimum volume, and {256} the maximum volume.

As third parameter, you must specify the {frequency} (speed) at which the sound is intended to be reproduced, being {256} the standard frequency that will reproduce the original sound. With lesser values, the sound will be reproduced with more accentuated bass. On the contrary, with higher frequency values, it will be reproduced with more accentuated treble.

The function returns the {channel number} that can be used by the
{#167,stop_sound()} function to stop the sound and by the {#102,change_sound()} function to modify its volume or frequency.

There are 16 sound channels. Thus, up to 16 sounds may simultaneously be played.

{#9999,Example program:}
PROGRAM example_sound;

PRIVATE
    volume=128;        // Average value (0..256)
    frequency=256;     // Average value (0..512)
    id_sound, channels;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write(0, 0, 0, 0, "Volume: Up(+) / Down(-)");
    write_int(0, 0, 10, 0, offset volume);
    write(0, 0, 20, 0, "Frequency: Right(+) / Left(-)");
    write_int(0, 0, 30, 0, offset frequency);
    write(0, 160, 180, 1, "Press [SPACE] to play the sound.");
    write(0, 160, 190, 1, "Use the cursors to change the values.");

    id_sound = load_sound("help/help.pcm", 0);

    LOOP
        IF (scan_code==_space)

            // Plays it
            channels = sound(id_sound, volume, frequency);

        END
        IF (key(_up) AND volume<256) volume++; END
        IF (key(_down) AND volume>0) volume--; END
        IF (key(_right) AND frequency<512) frequency++; END
        IF (key(_left) AND frequency>0) frequency--; END
        FRAME;
    END
END
{-}

In the example, a background screen and an explanatory text are displayed,
and a sound is loaded with the {#134,load_sound()} function. This function returns the {identifier of the sound}, that is stored in the {id_sound} variable.

In the main loop, at every keystroke of the spacebar, the sound is played with the {sound()} function with the parameters defined in the {volume} and {frequency} variables.

These values can be manipulated with the cursors keys, in order to understand better how it works.

The {channel number} returned by {sound()}, that is stored in the {channel} variable, could have been used to modify the sound with {#102,change_sound()}
or to stop it with {#167,stop_sound()}.

{/}See: {#134,load_sound()} - {#102,change_sound()} - {#167,stop_sound()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.160,sqrt()}

{sqrt(}<expression>{)}

{Returns:}

The entire square root of the expression.

{Description:}

Calculates the square root of the expression passed as a parameter, {truncated to an integer}.

For instance, as a result, {sqrt(10)} will return {3} and not {3.1623}, which is the real value (approximately) of the square root of ten.

{#9999,Example program:}
PROGRAM example_sqrt;

GLOBAL
    values[15];
    n;

BEGIN
    FROM n=0 to 15;
        values[n]=rand(0, 100000);
        write_int(0, 0, n*10, 0, offset values[n]);
    END
    write(0, 0, 192, 0, "Press [SPACE] to calculate its square root");
    LOOP
        IF (scan_code==_space)
            FROM n=0 TO 15;

                values[n] = sqrt(values[n]);

            END
        END
        FRAME;
    END
END
{-}

This program will display a list of randomly chosen values on-screen. When the spacebar is pressed, the program will apply the {sqrt()} function to all these values, calculating their square root.

{/}See: {#1035,Expression}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.161,start_fli()}

{start_fli(}<name of the file>{,} <x>{,} <y>{)}

{Returns:}

The animation's number of frames.

{Description:}

Starts a {FLI/FLC} animation contained in the specified {file}, in the
coordinates ({x}, {y}) (the upper left coordinate of the display window
must be specified).

The path can be specified in the <file name>. The path is not necessary if the file is in the DIV Games Studio directory or in a subdirectory whose name coincides with file extension (for instance, "fli\anima.fli").

The screen must hold the whole animation. That is to say, if the animation
occupies the whole screen, the videomode must be fixed at first with the
{#157,set_mode()} function, starting then the animation at the (0, 0) coordinate with the {start_fli()} function.

For your information, the function returns the number of frames that the whole animation comprises.

The system will automatically activate the colour palettes that the {FLI/FLC} animation could have. This can cause problems dealing with the representation
of other graphics or fonts of the program, if they had been drawn with a different palette.

If the aim is to combine other graphics with animation on-screen, the latter must have just one colour palette (which is normally called "{palette low FLI/FLC}")
and the graphics must have been drawn with that same palette.

Once the animation has started, its frames will gradually be shown with respective calls to {#115,frame_fli()}.

{It is possible to have but one active animation at every time}. Therefore, after having started an animation with {start_fli()} and having been displayed with {#115,frame_fli()}, this animation must finish with the {#108,end_fli()} function before starting another different animation.

{#9999,Example program:}
PROGRAM example_start_fli;
BEGIN

    start_fli("help/help.fli", 0, 0); // An animation begins.

    LOOP
        frame_fli();
        FRAME;
    END
END
{-}

In the example an animation which is inside of the file {help/help.fli} begins with
the function {start_fli()} in the coordinates (0, 0) and the animation
is played indefinitely.

{/}

The {#115,frame_fli()} function, used to show every frame, will return 0 when the animation is over. Therefore, to show the animation just one time you should have done as follows:

{#9999,Example program:}
PROGRAM example_start_fli;

PRIVATE
    fli_frames;

BEGIN
    start_fli("help/help.fli", 0, 0);
    REPEAT
        fli_frames=frame_fli();
        FRAME;
    UNTIL (fli_frames==0);
    end_fli();
END
{-}

The {#153,reset_fli()} function allows us {to rewind} the animation, so that the {#115,frame_fli()} function continues to execute it from the beginning.

{/}See: {#108,end_fli()} - {#153,reset_fli()} - {#115,frame_fli()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.162,start_mode7()}

{start_mode7(}<number of m7>{,} <file>{,} <graphic>{,} <exterior graphic>{,}
              <number of region>{,} <height of the horizon>{)}

{Description:}

This is an advanced function whose use requires special skill of its user.

Creates a mode-7 display window. That is to say, it displays a {three-dimensional} graphic in a folded plane. In order to obtain this effect, this function will be called with the following parameters:

{<m7 number>} - Up to 10 mode-7 windows can be created on-screen,
numbered from {0} to {9}. If the aim is to create but one, the best thing to do is to define window number {0}. This number will be necessary later to modify the window parameters, as the system will need to know which one of the possible {10} mode-7 windows is intended to modify.

{<file>} - The graphics intended to be folded in the window must be in a file whose {file code} must be specified here, as a second parameter of the function. The graphics loaded with the{#174,load_map()} or {#174,load_pcx()} (or created with {#188,new_map()}) function will be used as if they belonged to the first file (the file with the code 0).


{<graphic>} - The third parameter must be the main {code of the graphic}
which is going to be brought down in the window and must belong to the file
previously indicated.

{<external graphic>} - Here, it is possible to indicate either a {0}, if the aim is not to see any graphic beyond the graphic folded in the perspective, or a {graphic code} of the same file that will be shown in the perspective beyond the {main graphic}, until it gets the horizon. The height and width of this graphic must be powers of two, not higher than {8192} (these powers of two are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 & 8192). For instance, it can be a 64 pixel width by 32 pixel height graphic. This graphic will also be shown folded.

{<region number>} - Here, the rectangular screen region in which the mode-7 is going to be shown, will be indicated. If {0} is indicated as a region number,
this region will be shown on the whole screen. The rest of regions must previously be defined with the {#106,define_region()} function (a {region} is but a rectangular zone of the screen).

{<Height of the horizon>} - The last parameter to indicate will be the distance, in pixels, from the upper part of the window, where the horizon line is intended to be put. If the camera is placed above the folded plane, then nothing will be displayed above the horizon line (this space is normally filled with another  scroll or mode-7 window). Otherwise, if the camera is placed below the plane, then nothing will be shown below this horizon line. 

{/}

{Besides the call to the function, some values of the} {#1102,global structure m7} {must be initialised} {for the correct window's working}.
This is a structure of 10 records (one for every possible mode-7 window)
and every record has the following fields:

  {camera}   - {#1039,Identifying code} of the cameraú
  {height}   - Height of the cameraú
  {distance} - Distance of the cameraú
  {horizon}  - Height of the horizonú
  {focus}    - Focus of visionú
  {z}        - Depth planeú
  {colour}    - Exterior colourú

{Important:} In order to activate the mode 7 window it is {indispensable}  to start the {camera} field as, without this field, the window can not determine from where the folded plane must  {be seen}.

The camera will be placed in the folded plane, at the indicated {distance} of the process whose {#1039,identifying code} has been set in {camera}, orientated at its angle itself (the one indicated by its {#1129,angle} local variable). The height at which the camera is located with respect to the bottom will be that indicated in the {height} field.

See the help about the {#1102,m7 structure} for further information about these issues, or about how to access them.

{/}

{#9999,Example program:}
PROGRAM example_start_mode7;

PRIVATE
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");

    start_mode7(0, file1, 4, 0, 0, 64);

    m7.height = 64;
    m7.distance = 32;
    m7.color = 162;
    m7.camera = id;

    write(0, 160, 0, 1, "Use the cursors to move");
    LOOP
        IF (key(_right)) angle-=8000; END
        IF (key(_left)) angle+=8000; END
        IF (key(_up)) advance(6); END
        FRAME;
    END
END
{-}

In the example, the graphics file is loaded and then, a three-dimensional mode 7 is created with the {start_mode7()} function. This function is passed the following parameters:

{0} - Number of mode 7 window (the first one, as just one window of this kind will be created).

{file1} - Code of the file from which the graphics must be taken. This is the code of the {help.fpg} file, that was loaded with the {#132,load_fpg()} function.

{4} - Code of the main graphic to fold inside the mode 7. To see this graphic, the file must be loaded with the {Files menu}. Thus, it is possible to observe which one is the graphic with {code 4}
{0} - Code of the secondary graphic. A 0 indicates that no secondary (external) graphic will appear in the mode 7, so the external graphic will be displayed in the colour indicated by the {m7[0].colour} variable. In order to observe the effect of putting an {external graphic}, this parameter can be replaced, for instance, by  {100} (that is the code of a 32 by 32 pixel brown ball stored in the {help.fpg} file).

{0} - Region number of the screen on which the mode 7 must be {placed}.
A 0 indicates that it must be placed on the entire screen.

{64} - Height of the horizon. This last parameter indicates that the horizon line will be placed at 64 pixels from the upper part of the window.

After having called the {start_mode7()} function, the program defines the following values of the {#1102,global structure m7}:

{m7.height=64;} - To show that the camera must be placed at 64 pixels from the bottom.

{m7.distance=32;} - To show that the camera must be placed at 32 pixels behind the camera process.

{m7.colour=162;} - To indicate that the external part must be displayed in colour number 162 of the palette.

{m7.camera=}{#1092,id}{;} - To indicate that the current process will be the camera process.

The camera will be placed 32 pixels behind the main process, at 64 pixels height, orientated at the angle indicated by its {#1129,angle} variable.

After these initialisations, the sample program will remain in a loop that simply controls the {#1129,angle} of the main process with the cursors. This angle will be that of the camera and, when the {up cursor} key is pressed, the {#101,advance()} function will be called for the main process (and, consequently, the mode 7 camera) to advance 6 pixels.

{/}{How to visualise processes graphics in mode 7.}{/}

To create a process whose graphic is displayed in the mode 7, its {#1122,ctype} local variable must be defined as {#1169,c_m7} ({type of coordinate}
as {mode 7 coordinate}), which will be done with the following statement:

  {ctype=c_m7;}

After this, the process will be displayed in the mode 7 with its graphic ({#1126,graph}) scaled depending on the distance at which it is. The process must only modify its {#1123,x} and {#1124,y} variables to move through the folded plane.

{/}

{When a process belongs to the mode-7 (the value c_m7 has been assigned to its local variable} {#1122,ctype}{):} 

  - Its {#1123,x} and {#1124,y} variables will  be referred to the folded main graphic's point above which the process graphic will be placed.

  - Its {#1125,z} variable will lose its effect, as the graphics will appear in strict order of depth. This variable will only be useful to indicate display priorities in graphics exactly placed in the same depth plane.

  - The process will automatically be deleted when the mode 7 window, to which the process belongs, is deleted with the {#165,stop_mode7()} function,
or when the videomode is changed with the {#157,set_mode()} function as, by doing so, the mode 7 windows will also be deleted.

{/}

If there were several {mode 7} windows, the process would be displayed in all of them by default. If the process had to be displayed just in one of them, its {#1134,cnumber} local variable should be then defined. For instance, if there were 6 mode 7 windows (from number 0 to number 5) and the aim was to display a process only in windows 0 and 2, the following statement should be included in it:

  {cnumber=c_0+c_2;}

{/}

For a process to have several graphics (several views), depending on the
angle from which it is observed, its graphic must be defined with the {#1132,xgraph} local variable (instead of the {#1126,graph} variable).
To define this variable, it is necessary, at first, to create a table (of any name), first indicating the graphic's {number of views} and then the {graphics codes} for these views, starting with {angle 0} and in an anticlockwise direction. For instance:

  {GLOBAL}ú
    {views_car[]=4, 100, 101, 102, 103;}ú

The table {views_car} would define 4 views: graphic 100 for angles
near 0 degrees, graphic 101 for angles near 90 degrees,
graphic 102 for angles near 180 degrees, etc.

And then, the {#1132,xgraph} variable must be initialised in the process code with the following statement:

  {xgraph=OFFSET views_car;}

To get an example about what we have just seen, examine some of the DIV Games Studio's sample games that use this technique. Thus, read the comments about these programs (for instance, see {Speed for dummies}).

{/}See: {#165,stop_mode7()} - {#1102,Structure m7}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.163,start_scroll()}

{start_scroll(}<number of scroll>{,} <file>{,} <graphic>{,} <background graphic>{,}
               <number of region>{,} <indicator of blocking>{)}

{Description:}

This function has a certain complexity, requiring a special skill of the user, who (should have previously programmed) to use it.

Creates a scroll window, in which it will perform a view against a background graphic. That is to say, by using a graphic bigger than the display window as a game background, a part of this graphic can be showed and shifted in any direction.

To obtain this effect, this function will be called with the following parameters:

{<scroll number>} - Up to 10 scroll windows can be created on screen,
numbered from {0} to {9}. If the aim is to create only one, the best thing is to define window number {0}. This name will later be necessary to modify the parameters of the window, as the system will need to know which one of the {10} possible scroll windows is intended to change.

{<file>} - The graphics that are intended to be shown as a background in that window must be in a file whose {file code} must be specified here, as a second parameter of the function. The graphics loaded with the
{#174,load_map()} or {#174,load_pcx()} (or created with {#188,new_map()}) 
functions will be used as if they belonged to the first file (the file with the code 0).

{<graphic>} - The third parameter must be the {code of the} main {graphic} that is going to be displayed as a background in the window and that must belong to the file previously indicated. This graphic
is normally the main window of the game on which the action will be developed. It is a graphic bigger than the display window, that will be shifted in one or several directions and on which the graphics of the game will be placed.

The scroll window will be initially placed with the {#1136,control point}
number {0} of this graphic in the upper left corner, when this point has been defined in the {graphic editor}.

{<background graphic>} - Here, {0} will be indicated if the aim is to obtain a single scroll plane (a single background graphic), or another {graphic code} if it is intended that it appears as scroll background (deeper),
behind the foreground. In order to see this background plane, it is indispensable that the {main graphic} (foreground) has parts painted in colour number 0 of the palette, as these transparent zones will allow us to see the {background graphic} through them.

{<region number>} - The rectangular screen region in which the scroll is going to be shown will be here indicated. If {0} is indicated as a region number,
it will be shown on full screen. The rest of regions must previously be defined with the {#106,define_region()} function (a {region} is but a rectangular zone of the screen).

{<locking indicator>} - A value defining whether each of the two scroll planes is horizontally and vertically cyclical will be here indicated. For instance,
a plane is horizontally cyclical when, on leaving the picture on the right, the picture appears on the left. To obtain this value, the following quantities must be added:

 { + 1} - If the foreground is horizontally cyclical.ú
 { + 2} - If the foreground is vertically cyclical.ú
 { + 4} - If the background is horizontally cyclical.ú
 { + 8} - If the background is vertically cyclical.ú

This means that {0} if none of the two planes must be cyclical, {15} ({1}+{2}+{4}+{8})
if both planes must be cyclical in both axes, {12} ({4}+{8}) if only the background must be cyclical, etc.

When a (foreground or background) graphic is smaller than the display window,
the system will force it to have a cyclical scroll plane. Otherwise, the scroll window could not be completely filled, without {cyclically} repeating
the graphic (tile).

{/}

{Besides the call to the function, some values of the} {#1101,scroll global structure} {must be initialised} {for the correct working of the window}.
This is a structure of 10 records (one for each possible scroll window)
and every record has the following fields:

  {x0, y0}  - Foreground coordinatesú
  {x1, y1}  - Background coordinatesú
  {z}       - Depth planeú
  {camera}  - {#1039,identifying code} of the cameraú
  {ratio}   - Background's relative speedú
  {speed}   - Foreground's maximum speedú
  {region1} - First screen regionú
  {region2} - Second screen regionú

There are two ways to program the movement of the scroll windows:

- Manually, modifying in each frame of the game the fields {x0}, {y0},
{x1} and {y1} of this structure (the scroll planes' coordinates).

- Automatically, for what the {#1038,identifying code} of a process is needed in the field {camera} of this structure. From then, the system will be in charge of following the graphic of this process in the scroll window.

See the help about the {#1101,scroll structure} either for further information about these fields, or to know how to access them.

{/}

{#9999,Example of AUTOMATIC scroll:}
PROGRAM example_start_scroll;

PRIVATE
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");

    start_scroll(0, file1, 103, 102, 0, 15);

    scroll.camera=id;

    ctype=c_scroll;
    graph=100;
    write(0, 160, 0, 1, "Use the cursors to move the ball");
    LOOP
        IF (key(_right)) x+=2; END
        IF (key(_left)) x-=2; END
        IF (key(_down)) y+=2; END
        IF (key(_up)) y-=2; END
        FRAME;
    END
END
{-}

In the example, the graphics file is loaded and then, a scroll window is created with the {start_scroll()} function. The latter is passed the following parameters:

{0} - Number of scroll window (the first one, as only a window of this kind will be created).

{file1} - Code of the file from which the graphics must be taken. This is the code of the file {help.fpg} loaded with the {#132,load_fpg()} function.

{103} - Code of the main graphic (foreground) of the scroll. In order to see this graphic, the file must be loaded with the {Files menu}, being then possible to observe which is the graphic with {code 103}.

{102} - Code of the secondary graphic (background). This graphic will be shown in the scroll window {behind} the main graphic.

{0} - Number of the screen's region in which the scroll must {be placed}. 0 indicates that it must be put on the entire screen.

{15} - Lock indicator; 15 (1+2+4+8) indicates that the foreground as well as the background will be cyclical in both axes (horizontal and vertical).

After having called the {start_scroll()} function, the program defines the field {camera} of the {#1101,scroll structure}, assigning the {#1039,identifying code}
of the main process to it (with the {scroll.camera=}{#1092,id}{;} statement). Thus, the scroll becomes {automatic}, following the graphic of the main process from that moment.

The program continues to define its {type of coordinate} as a {scroll coordinate} (with the {ctype=c_scroll;} statement), defining its graphic as number 100, that is a brown ball (with {graph=100;}), and displaying a message. Then, it will stay in a loop in which the coordinates of this process (the {#1123,x} and {#1124,y} variables) may vary with the cursor keys.

{/}

{#9999,Example of scroll MANUAL:}
PROGRAM example_start_scroll;

PRIVATE
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");

    start_scroll(0, file1, 103, 102, 0, 15);

    write(0, 160, 0, 1, "Use the cursors to move the scroll");
    LOOP
        IF (key(_right))
            scroll.x0+=2;
            scroll.x1+=1;
        END
        IF (key(_left))
            scroll.x0-=2;
            scroll.x1-=1;
        END
        IF (key(_down))
            scroll.y0+=2;
            scroll.y1+=1;
        END
        IF (key(_up))
            scroll.y0-=2;
            scroll.y1-=1;
        END
        FRAME;
    END
END
{-}

In the example the file of graphics is loaded and then a scroll window
is created with the function {start_scroll()}. The same parameters of the previous
example are given to this last one.

After this, the program will stay in a loop inside of which, when the cursor  
keys are detected, the fields {x0}, {y0}, {x1} and {y1} of the 
{#1101,global scroll structure} will change, and these define the coordinates of
the two scroll planes ({x0}, {y0} for the first plane and {x1}, {y1}
for the second).

It can be seen the difference between both methods; this last one, as it hasn't
beginning the field {camera} of the structure, will be able to manipulate
the coordinates of both planes.

{/}{How to visualise the process graphics in the scroll}{/}

To create a process which graphic is seen in the scroll window, its local
variable {#1122,ctype} must be defined as {#1168,c_scroll} ({coordinate of type}
as {coordinate of scroll}), what will be done with the following statement:

  {ctype=c_scroll;}

Once this is done, the process will be seen in the scroll with its graphic
(defined in the local variable {#1126,graph}). The process just must modify
its variables {#1123,x} and {#1124,y} to move over the scroll.

{/}

In the example, the graphics file is loaded and then, a scroll window is created with the {start_scroll()} window. The latter is passed exactly the same parameters as in the previous example.

After that, the program will stay inside a loop in which, on detecting the cursor keys, the fields {x0}, {y0}, {x1} and {y1} of the {#1101,scroll global structure} will vary. These fields define the coordinates of the two planes of the scroll ({x0}, {y0} are the coordinates of the foreground and {x1}, {y1} those of the background).

The difference between both methods can be noticed. The latter can directly manipulate the coordinates of both planes, as it has not initialised the field {camera} of the structure.

{/}{How to display processes' graphics in the scroll.}{/}

In order to create a process whose graphic is displayed in the scroll window, it is necessary to define its {#1122,ctype} local variable as {#1168,c_scroll} ({type of coordinate} as {scroll coordinate}), which will be done with the following statement:

  {ctype=c_scroll;}

After that, the process will be displayed in the scroll with its graphic (defined in the {#1126,graph} local variable). The process must modified only its {#1123,x} and {#1124,y} variables to scroll.

{/}

{When a process belongs to the scroll (assigning the value c_scroll to its
local variable} {#1122,ctype}{):}

  - Its {#1123,x} and {#1124,y} variables will be referred to the point of the foreground's graphic on which the graphic of the process will be placed.

  - Its {#1125,z} variable will be now referred to the {variables z} of the
processes that also belong to the same scroll window. This means that
each time that a scroll window is displayed, all the graphics that belong to it (ranged by their {z}) will be displayed just after it. Then, the processes that {don't belong to that scroll window} will continue to be displayed.

  - The process will be automatically eliminated when the scroll window to which the process belongs is eliminated with the {#166,stop_scroll()} function.
Or when the videomode is changed with the {#157,set_mode()} function as, on doing so, the scroll windows will be also eliminated.

{/}

If there were several {scroll} windows, the process would be displayed by default in all of them. If it had to be displayed only in some of them, its {#1134,cnumber} local variable should be defined. For instance, if there were 6 scroll windows (numbered from 0 to 5) and the aim was to display a process only in windows 0 and 2, the following statement should be included in it:

  {cnumber=c_0+c_2;}

In order to observe an example of what it has been said, the best thing is to examine some of the sample games of DIV Games Studio that use this technique. Thus, the reader is directly referred to the comments of these programs (for instance, see the example {Helioball}).

{/}See: {#166,stop_scroll()} - {#152,refresh_scroll()} - {#140,move_scroll()} - {#1101,Scroll structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.164,stop_cd()}

{stop_cd()}

{Description:}

Stops the CD-Audio reproduction, stopping the song which were playing.
The songs are reproduced with the function {#144,play_cd()}.

{#9999,Example program:}
PROGRAM example_stop_cd;
BEGIN
    write(0, 160, 0, 1, "Press [ENTER] to turn on the CD.");
    write(0, 160, 10, 1, "Press [SPACE] to stop the CD.");
    LOOP
        IF (scan_code==_space)

            stop_cd(); // Para el CD

        END
        IF (scan_code==_enter)
            play_cd(2, 0);
        END
        FRAME;
    END
END
{-}

In the example are placed the necessary messages. In each step of the
loop, if the space bar is pressed, the CD will be stopped with the
function {stop_cd()}.

If the ENTER key is pressed, it will be turned on with the function
{#144,play_cd()}.

The volume of reproduction of cd-audio can be controlled with the
{#1104,setup} structure and the function {#178,set_volume()}.

{/}See: {#144,play_cd()} - {#127,is_play_cd()} - {#178,set_volume()} - {#1104,setup structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.165,stop_mode7()}

{stop_mode7(}<number of m7>{)}

{Description:}

Eliminates the mode 7 window which number (from 0 to 9) is given as parameter.
This <number of m7> is the one indicated as first parameter in the function
{#162,start_mode7()}, is necessary due to that can be up to 10 different mode 7
windows, and the system needs to know which of them is ending.

When a mode 7 window is eliminated, every process which belongs exclusively to
this window will die automatically, so, every process which has its
variable {#1122,ctype} with the value {#1169,c_m7} and they are not being 
seen in any other mode 7 window.

{Important:} When the video mode is changed with the function {#157,set_mode()}
every mode 7 window (and its processes) will be eliminated, without being in this
case, necessary to use this function ({stop_mode7()}).

{#9999,Example program:}
PROGRAM example_stop_mode7;
BEGIN
    load_fpg("help/help.fpg");
    write(0, 160, 0, 1, "Press [ENTER] to start the mode 7 display.");
    write(0, 160, 10, 1, "Press [SPACE] to stop the mode 7 display.");
    write(0, 160, 190, 1, "Use the mouse to move the mode 7 display.");
    angle=90000;
    LOOP
        IF (scan_code==_space)

            stop_mode7(0); // The mode 7 is stopped

        END
        IF (scan_code==_enter)
            start_mode7(0, 0, 4, 0, 0, 64);
            m7.camera=id;
        END
        x=mouse.x;
        y=mouse.y;
        FRAME;
    END
END
{-}

In the example a file of graphics is loaded, and the instructions of the program
appear on screen, after this, the coordinates of the main process, which will be
the camera of the mode 7, will be controlled with the mouse (through the
statements {x=mouse.x;} and {y=mouse.y}).

When the ENTER key is pressed, a mode 7 window is created with a graphic
of a circle, controlled by the main process.

When the space bar is pressed, the function {stop_mode7()} will be called,
eliminating this window of the mode 7 visualisation.

{/}

To Create a mode 7 window is a bit complex procedure and requires to
begin some parameters, as in this case the camera, some of them required
by the function {#162,start_mode7()} and other variables in the global
structure {#1102,m7} (as the variable {m7.camera} used in the example).

{/}See: {#162,start_mode7()} - {#1102,m7 structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.166,stop_scroll()}

{stop_scroll(}<number of scroll>{)}

{Description:}

Eliminates the scroll window which number (from 0 to 9) is given as parameter.
This <number of scroll> is the one indicated as first parameter in the function
{#163,start_scroll()} and it is necessary due to can be up to 10 different scroll
windows, and the system needs to know which one is ending.

When a scroll window is eliminated, every process which belongs exclusively to this
window will die automatically, so, every process which has its
variable {#1122,ctype} with the value {#1168,c_scroll} and they are not being 
seen in any other scroll window.

{Important:} When the video mode is changed with the function {#157,set_mode()}
every scroll window (and its processes) will be eliminated, without being in this
case, necessary to use this function ({stop_scroll()}).

{#9999,Example program:}
PROGRAM example_stop_scroll;
BEGIN
    load_fpg("help/help.fpg");
    write(0, 160, 0, 1, "Press [ENTER] to activate the scroll window.");
    write(0, 160, 10, 1, "Press [SPACE] to end the scroll.");
    LOOP
        IF (scan_code==_space)

            stop_scroll(0); // The scroll is quit.

        END
        IF (scan_code==_enter)
            start_scroll(0, 0, 103, 102, 0, 15);
        END
        scroll.x0+=1;
        scroll.y0+=1;
        scroll.x1-=1;
        FRAME;
    END
END
{-}

In the example a file of graphics is loaded and the instructions of the program
appear on screen.

When the ENTER key is pressed, a scroll window will be created and when the
space bar is pressed, the function {stop_scroll()} is called, eliminating
this scroll window.

Inside of the main loop, the coordinates of the scroll are accessed, being contained
in the {#1101,global scroll structure} to move manually the scroll window
({scroll.x0+=1; ...}).

{/}

To create a scroll window is a bit complex procedure and requires to start some
parameters, some of them, required by the function {#163,start_scroll()} 
and other contained in the {#1101,global scroll structure}
(as the variable {scroll.x0} used in the example).

{/}See: {#163,start_scroll()} - {#1101,scroll structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.167,stop_sound()}


{stop_sound(}<channel number>{)}

{Description:}

Stops the sound that is being played through the channel, passed as a parameter.

The required <channel number> is the value returned by the {#159,sound()} function when the reproduction of a sound effect starts.

There are 16 sound channels. Thus, up to 16 sounds may simultaneously be played.

{#9999,Example program:}
PROGRAM example_stop_sound;

PRIVATE
    id_sound;
    channels;
    playing=FALSE;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    write(0, 160, 0, 1, "Press [SPACE] to start the reproduction.");
    write(0, 160, 10, 1, "Press [ENTER] to stop the sound channel.");
    id_sound = load_sound("help/help.pcm", 1);
    LOOP
        IF (scan_code==_space AND NOT playing)
            channels = sound(id_sound, 128, 256);
            playing=TRUE;
        END
        IF (scan_code==_enter)

            stop_sound(channels); // The sounds stops playing

            playing=FALSE;
        END
        FRAME;
    END
END
{-}

In the example, a background graphic is put and the necessary messages are displayed. At the same time, the sound effect stored in the {help.pcm} file is loaded with the {#134,load_sound()} function, that returns the sound identifier that is stored in the {id_sound} variable. Notice that, in this example, {1} is passed to this function as a second parameter. That is done to indicate that the loaded sound effect must indefinitely be repeated every time it is initialised (stressing thus the effect of the {stop_sound()} function).

In every step of the loop, it is checked whether the spacebar is pressed. In this case, the reproduction of the sound effect will start with the {#159,sound()} function, which will return the channel number that will be stored in the {channel} variable.

If the ENTER key is pressed, the sound will be stopped with the {stop_sound()} function.

{/}

To gradually stop a sound, turning its volume down little by little, several calls to the {#102,change_sound()} function must be made to slightly reduce the channel volume until it reaches level 0. Then, the {stop_sound()} can be called to definitively stop the sound.

{/}See: {#159,sound()} - {#102,change_sound()} - {#134,load_sound()} - {#170,unload_sound()}

# -----------------------------------------------------------------------------

{.168,system()}


{system(}<"external command">{)}

{Description:}

Executes the operative system's command passed as a parameter.

{#9999,Example program:}
PROGRAM example_system;
BEGIN
    write(0, 160, 0, 1, "Press [SPACE] to execute a DIR.");
    LOOP
        IF (scan_code==_space)

            system("dir"); // A command of MS-DOS is executed.

        END
        FRAME;
    END
END
{-}

In the example, after the display of a text, you enter inside the main loop in which the {DIR} command of the MS-DOS operative system will be executed every time the spacebar is pressed.

{/}

One of the utilities of this command is, for instance, to delete a temporary file that has been created in the program, calling the command of the
system {DEL <}file name{>}.

{/}

{Note:} The system can be blocked depending of the executed commands. In these cases you must reset the computer. There is no guarantee dealing with this function running, due to the multiple incompatibilities that can appear between the external commands and the manager of internal processes of DIV Games Studio.

{/}

{system("COMMAND.COM")}

{Description:}

Executes a session of the MS-DOS operative system from the program itself.
On typing EXIT from it, you will return to the program at the point in which this statement was executed.

{/}See: {#109,exit()}

# -----------------------------------------------------------------------------

{.169,unload_fpg()}

{unload_fpg(}<file code>{)}

{Description:}

Unloads the graphics file whose code is passed as parameter from the memory. This <file code> is the value returned by the {#132,load_fpg()} function when a new graphics file is loaded in the memory.

After having unloaded a graphics' file, {much care must be taken} not to go on using in the program any graphic that was in that file. Otherwise, the program could become blocked.

{It is not necessary to unload the file from the memory} before finishing the program, as the system will do it automatically.

Therefore, a file must be unloaded from the memory only when it is not going to be used for a while and when the aim is to free up space occupied in the computer's memory in order to load other resources (other graphics files, sounds, fonts, etc.).

{#9999,Example program:}
PROGRAM example_unload_fpg;

PRIVATE
    file1;

BEGIN
    file1=load_fpg("help/help.fpg");
    put_screen(file1, 1);
    write(0, 160, 0, 1, "Press [ENTER] to unload the file and finish");
    REPEAT
        FRAME;
    UNTIL (key(_enter));

    unload_fpg(file1); // The file is loaded.

END
{-}

The example loads the graphics file contained in the {help.fpg} file
with the {#132,load_fpg()} function, storing the {file code} in the
{file1} private variable.

The program will remain in a loop until the ENTER key is pressed. At that moment, the file will be unloaded from the memory with {unload_fpg()}
and the program will finish.

{/}

The graphics individually loaded with the {#174,load_map()} or {#174,load_pcx()} (or created with {#188,new_map()}) functions will not be unloaded when file number 0 (with code 0) is loaded , even if they were used as if they belonged to it. These graphics will have to be unloaded by using the {#176,unload_map()} or {#176,unload_pcx()} functions.

{/}See: {#132,load_fpg()} - {#174,load_map/pcx()} - {#176,unload_map/pcx ()}

# -----------------------------------------------------------------------------

{.170,unload_sound()}


{unload_sound(}<sound id>{)}

{Description:}

Unloads the sound with the passed id from memory.
This <sound id> is the value returned by the {#132,load_sound()} function when a new sound effect is loaded in the memory.

After unloading a sound effect, {much care must be taken} to not continute to use this sound id in the program for the {#159,sound()} or {unload_sound()} functions. Otherwise, the program could become blocked.

{It is not necessary to unload the sound from the memory} before finishing the program, as the system will do it automatically.

A sound need only be unloaded from memory when it is not going to be used for a while and when the aim is to free up space occupied in the computer's memory to load other resources (other graphics files, sounds, fonts, etc.), this is logical for large sounds or sounds only played once, for example an intro sound or music, in other words big enough so as to be worth freeing up the space they occupy.

{#9999,Example program:}
PROGRAM example_unload_sound;

PRIVATE
    sound1;

BEGIN
    sound1=load_sound("help/help.pcm",0);
    write(0, 160, 0, 1, "Press [ENTER] to unload the sound and finish");
    REPEAT
        FRAME;
    UNTIL (key(_enter));

    unload_sound(sound1); // The sound is unloaded.

END
{-}

The example loads the sound effect stored in the {help.pcm} file
with the {#134,load_sound()} function, storing the {sound code} in the
{sound1} private variable.

The program will remain in a loop until the ENTER key is pressed. At that moment, the file will be unloaded from the memory with {unload_sound()} and the program will finish.

{/}

The {#167,stop_sound()} function must be used to stop a sound effect, but keeping it in the memory in order to be played again when desired.

{/}See: {#134,load_sound()} - {#159,sound()} - {#102,change_sound()} - {#167,stop_sound()}

# -----------------------------------------------------------------------------

{.171,write()}

{write(}<font>{,} <x>{,} <y>{,} <centreing code>{,} <text>{)}

{Returns:}

The identifying code of the text that has been written.

{Description:}

This function is used to show an alphanumeric text on-screen. For that, it requires the following parameters:

{<font>} - The {font code} or {type of letter} that is going to be used.
Here, you must put either 0 when the aim is to use the system's font
(white, small font, 6 by 8 pixels), or the {font code} returned by the {#131,load_fnt()} function when a new font is loaded in the program.

{<x>}, {<y>} - The coordinates referred to the screen in which the text is going to be displayed, first in the horizontal axis and then in the vertical one.

{<centreing code>} - This code determines the position of the text specified by the previous coordinates. Its values are:

  {0}-Up left {1}-Up {2}-Up rightú
  {3}-Left        {4}-centre {5}-Rightú
  {6}-Down left  {7}-Down  {8}-Down rightú

For example, if a text is written at the 160, 0 coordinates and with the centreing code 1 (Up), then the text will c entre in the column 160 and it will be displayed from line 0 downwards. Or, if the aim is to have a text in the upper left corner, it must be displayed at the 0, 0 coordinates and with centreing code 0 (Up left).

{<text>} - The text to be written as a literal (a text in inverted commas) will be specified as last parameter (see the {#1047,literals' specifying symbols}).

{/}

The displayed text will remain on-screen until it is deleted with the {#107,delete_text()} function, that requires as parameter the {identifying code} returned by {write()}.

The {#172,write_int()} function must be used to display the numeric value of a variable (such as the score of the player).

The texts will remain unchangeable on screen even if graphics are displayed on it or processes' graphics pass before or behind them.

{#9999,Example program:}
PROGRAM example_write;

PRIVATE
    font1;

BEGIN
    font1 = load_fnt("help/help.fnt");

    write(0, 160, 100, 4, "Sample text with the system font.");
    write(font1, 0, 0, 0, "LEFT UP");
    write(font1, 320, 200, 8, "RIGHT DOWN");

    LOOP
        FRAME;
    END
END
{-}

In the previous example, the font contained in the {help.fnt} file is loaded
with the {#131,load_fnt()} function (whose font code is stored in the {font1} variable), and then three texts are written:

The first one with the system font (0), being placed at the 160, 100 coordinates
(screen centre) the {centre} of the text (centreing code 4).

The second one with the loaded font (whose {font identifier} is stored in the {font1} variable), being placed at the 0, 0 coordinates the
upper left corner of the text (centreing code 0).

And finally, the third text, also with the loaded font, being placed at the 320, 200 coordinates the lower right corner of the text (centreing code 8).

After that, the program will indefinitely remain expecting inside a loop.

{/}

The depth plane in which the written texts appear is controlled through the {#1106,text_z} global variable, that is useful to regulate which graphics must be seen above the texts and which ones must be seen below them.

Then, it will be possible to move the texts towards another position if necessary, by using the {#141,move_text()} function, which also requires the {identifying code} returned by {write()} as parameter.

{/}

When fonts loaded from {files FNT} are used, the colours palette used to generate these fonts must be activated (see {#133,load_pal()}). Otherwise, the colours may appear changed, and the text will be incorrectly displayed.

{/}See: {#172,write_int()} - {#141,move_text()} - {#107,delete_text()} - {#131,load_fnt()} - {#1106,text_z}

# -----------------------------------------------------------------------------

{.172,write_int()}
    
{write_int(}<font>{,} <x>{,} <y>{,} <centreing code>{,} <OFFSET variable>{)}

{Returns:}

The identifying code of the text that has been written.

{Description:}

This function is used to show the numeric value of a variable. For that, it requires the following parameters:

{<font>} - The {font code} or {type of letter} that is going to be used.
Here, it is necessary to put either 0 when the aim is to use the system's font
(white, small font, 6 by 8 pixels), or the {font code} returned by the {#131,load_fnt()} function when a new font is loaded in the program.

{<x>}, {<y>} - The coordinates referred to the screen in which the numeric value is going to be displayed, first in the horizontal axis and then in the vertical one.

{<centreing code>} - This code determines the position of the numeric value specified by the previous coordinates. Its values are:

  {0}-Up left     {1}-Up     {2}-Up rightú
  {3}-Left        {4}-centre     {5}-Rightú
  {6}-Down left      {7}-Down      {8}-Down rightú

For example, if a numeric value is written at the 160, 0 coordinates and with the centreing code 1 (Up), then the numeric value will be centred in the column 160 and it will be displayed from line 0 downwards. Or, if the aim is to have a numeric value in the upper left corner, it must be displayed at the 0, 0 coordinates and with centreing code 0 (Up left).

{<OFFSET variable>} - The offset inside the computer's memory of the variable whose value is intended to be displayed, must be specified as last parameter (the offset of the data is obtained with the {#1085,OFFSET} operator).

{/}

The displayed numeric value will remain on-screen until it is deleted with the {#107,delete_text()} function, that requires as parameter the {identifying code} returned by {write_int()}.

{Important:} During the time that the value of the variable appears on screen, this value will automatically be updated every time the variable is modified. For that, new calls to {write_int()} are not necessary.

The {#171,write()} function must be used to display any kind of alphanumeric text (a fixed text).

The texts will remain unchangeable on screen even if graphics are displayed on it or processes graphics pass before or behind them.

{#9999,Example program:}
PROGRAM example_write_int;

PRIVATE
    variable;

BEGIN
    write(0, 160, 190, 1, "Press [SPACE] to change the value of the variable.");

    write_int(0, 160, 100, 4, OFFSET variable); // A variable is displayed.

    LOOP
        IF (scan_code==_space) variable=rand(-100, 100); END
        FRAME;
    END
END
{-}

In the example, a text is displayed by using {#171,write()} and the value of a variable with the {write_int()} function. This last function is passed the following
parameters:

  {0} - As {font} (0 is the system font).ú
  {0, 10} - As screen coordinates.ú
  {0} - As centreing code (Up/Left).ú
  {OFFSET variable} - As the offset of the variable in the memory.ú

In every step of the loop, if the spacebar is pressed, the value of the variable is changed, assigning it one randomly chosen with the {#149,rand()} function.

{/}

The depth plane in which the written texts appear is controlled through the {#1106,text_z} global variable, that is useful to regulate which graphics must be seen above the texts and which ones must be seen below them.

Then, it will be possible to move the texts towards another position if necessary, by using the {#141,move_text()} function, which also requires the {identifying code} returned by {write()} as parameter.

{/}

When fonts loaded from {files FNT} are used, the colour palette used to generate these fonts must be activated (see {#133,load_pal()}). Otherwise, the colours may appear changed, being the text incorrectly displayed.

{/}

{Warning:}

It is not possible to display an expression, as it is shown below:

  {write_int(0, 0, 0, 0, offset variable + 1);}

To display the value of the variable plus 1. That is to say, if the aim was to display this value, it would be necessary either to add 1 to the variable or to create another variable, assigning it the value of the original variable plus 1, for
instance:

  {variable2 = variable + 1;}ú
  {write_int(0, 0, 0, 0, offset variable2);}ú

In this case, you should take into account that you had to update the value of the {variable2} at least once per every {#1029,FRAME} of the game, as by changing {variable} the value of {variable2} will not automatically be updated unless the {variable2 = variable + 1;} statement is again executed.

{/}See: {#171,write()} - {#141,move_text()} - {#107,delete_text()} - {#131,load_fnt()} - {#1106,text_z}

# -----------------------------------------------------------------------------

{.173,xput()}

{xput(}<file>{,} <graphic>{,} <x>{,} <y>{,} <angle>{,} <size>{,} <flags>{,} <region>{)}

{Description:}

Advanced version of the {#146,put()} function to put a graphic on the screen background. This function requires the following parameters, in order:

{<file>} - {file code} with the graphics library that contains both graphics. The graphics loaded with the {#174,load_map()} or {#174,load_pcx()}(or created with {#188,new_map()}) functions will be used as if they belonged to the first file (the file with the code 0).

{<graphic>} - {code of the graphic} inside the file that is going to be displayed on screen.

{<x>, <y>} - coordinates dealing with the screen where the graphic is intended to be put. These coordinates reveal the position in which the graphic centre (or the {#1136,control point} number 0, if it is defined) will be placed. 

{<angle>} - angle (in degree thousandths) in which the graphic is going to be displayed; the normal angle is {0}.

{<size>} - size (in percentage) in which the graphic is going to  be displayed; the normal size is {100}.

{<flags>} - Indicates the mirrors and transparencies with which the graphic will be displayed; the possible values are the following ones:

 {0}-Normal graphic.ú
 {1}-Horizontal mirror.ú
 {2}-Vertical mirror.ú
 {3}-Horizontal and vertical (180ø) mirror.ú
 {4}-Transparent graphic.ú
 {5}-Horizontal transparent and mirror.ú
 {6}-Vertical transparent and mirror.ú
 {7}-Horizontal and vertical transparent, mirror.ú

{<region>} - Number of region (window inside the screen) in which the graphic must be displayed. This value will normally equal {0} to display the graphic at any position of the screen. The {#106,define_region()} function must be used to define a region.

{/}

The graphics displayed in this way on the background screen will be in the game display {below all the processes, scroll regions, texts, etc.}

If the aim is that a graphic is above others, it is necessary to {create it as a new process}  and fix its {#1125,z} variable with the priority of its display.

The {#103,clear_screen()} function must be used to clear the screen background.

{#9999,Example program:}
PROGRAM example_put;

PRIVATE
    file1;
    coord_x;
    coord_y;
    angle1;
    size1;
    flags1;

BEGIN
    file1=load_fpg("help/help.fpg");
    LOOP
        coord_x=rand(0, 319);
        coord_y=rand(0, 199);
        angle1=rand(-pi, pi);
        size1=rand(10, 200);
        flags1=rand(0, 7);

        // The graphic 101 is put
        xput(file1, 101, coord_x, coord_y, angle1, size1, flags1, 0);

        FRAME;
    END
END
{-}

In the example, the file is loaded with the graphics and, in every iteration of the loop, graphic number 101 (a triangle) is put with the {xput()} function at coordinates randomly chosen with the {#149,rand()} function, with random angle, size and value of {flags}, and in region number 0 (entire screen).

{/}

The {#146,put()} function is a simplified version of the {xput()} function, and it is useful when you do not want to rotate, scale, mirror or display the graphic with transparencies.

The {#137,map_put()} or {#139,map_xput()} functions must be used to put a graphic inside another one (instead of the screen background).

{/}

If the graphic intended to be put is just a screen background,
it is easier to use the {#148,put_screen()} function, as it does not require the screen coordinates because it will automatically centre the graphic on screen.

{/}See: {#146,put()} - {#137,map_put()} - {#139,map_xput()} - {#148,put_screen()}

# -----------------------------------------------------------------------------

{.174,load_map() / load_pcx()}

{load_map(}<name of file>{)}

{load_pcx(}<name of file>{)}

{Returns:}

The loaded {graphic code}.

{Description:}

Loads a {MAP or PCX file} with a graphic in the computer's memory . The function requires the file name as a parameter, in inverted commas.

The {graphic code} is returned as return value, which is a numeric value that must be specified to use the graphic, in the {#1126,graph} variable or, in general, in all the functions requiring a {graphic code} among their parameters.

It is possible to load as many graphics as necessary. Every time one is loaded, the function will return the corresponding code (the first graphic loaded will have the code {1000}, the following one the code {1001}, etc.)

It is possible to specify the path to the file with the graphics' file. Nevertheless, if the file is in the directory by default (\MAP or \PCX), it won't be necessary.

{/}

{Important:}

When the {file code} to which that graphic belongs is required inside a function, the code {0} (which is the code of the first {file FPG} that is loaded in the program) must be indicated.

{/}

When different graphics have been loaded, keep in mind that if they have different palettes, every one of them must previously be activated with the {#133,load_pal()} function, indicating the name of the file (MAP / PCX) as a parameter, before using the graphic.

Graphics created with different palettes can not simultaneously be used.

{#9999,Example program:}
PROGRAM example_load_map;

PRIVATE
    map1;

BEGIN

    map1 = load_map("help/help.map"); // A graphic map's file is loaded.

    put_screen(0, map1);
    LOOP
        FRAME;
    END
END
{-}

In the example, a graphic map is loaded with the {load_map()} function, storing the {graphic code} that returns in the {map1} private variable.

This code is later used as a parameter of the {#148,put_screen()} function
to put the graphic on the background screen.

{/}

The {#176,unload_map()} and {#176,unload_pcx()} functions allows us to free up the computer's memory used by the graphic when it is not going to be used for a specific time. For that purpose, it also requires the {graphic code} to know which is the graphic to be unloaded from the memory.

{It is not necessary to unload the graphic from the memory} before finishing the 
program, as the system will do it automatically.

{/}

To load several graphics all at once in a program, they must be included inside a graphics file (FPG) and loaded with the {#132,load_fpg()} function.

{/}

The function {#188,new_map()} allows you to create a new graphic map of
any size and colour, without loading it from an file.

{/}See: {#188,new_map()} - {#176,unload_map/pcx()} - {#132,load_fpg()} - {#133,load_pal()} - {#1126,graph}

# -----------------------------------------------------------------------------

{.175,reset_sound()}


{reset_sound(}{)}

{Description:}

Advanced function, only for very expert users. Resets the sound system.

This function is used to activate new parameters of the sound hardware.

The following values of the {#1104,setup global structure} must be established:

    {setup.card}ú
    {setup.port}ú
    {setup.irq}ú
    {setup.dma}ú
    {setup.dma2}ú

This function is normally used inside the sound setup programs (see {#1093,setup_program}).

{/}

To activate the rest of the values of the setup structure, those referred to the {mixer} volume, the {#178,set_volume()} function must be called. The values to establish the volume are the following ones:

    {setup.master}ú
    {setup.sound_fx}ú
    {setup.cd_audio}ú

{/}See: {#178,set_volume()} - {#1104,Setup structure} - {#1093,setup_program}

# -----------------------------------------------------------------------------

{.176,unload_map() / unload_pcx()}

{unload_map(}<code of the graphic>{)}

{unload_pcx(}<code of the graphic>{)}

{Description:}

Unloads the graphic whose code is passed as a parameter from the memory.
This <graphic code> is the value returned by the {#174,load_map()} {#174,load_pcx()}
or {#188,new_map()} function by loading a new graphic stored in an {file MAP or PCX} in 
the computer's memory.

After having unloaded a graphic, {much care must be taken} not to go on using this graphic in the program. Otherwise, the program would risk to become blocked.

{It is not necessary to unload the graphic} before finishing the 
program, as the system will do it automatically.

Then, a graphic must be unloaded from the memory only when it is not going to be used for a specific time and when the aim is to free up the occupied space in the computer's memory to load other resources (other graphics files, sounds, fonts, etc.), which will make sense only with graphics of a certain size, big enough so as to be worth freeing up the space they occupy.

{#9999,Example program:}
PROGRAM example_unload_map;

PRIVATE
    map1;

BEGIN
    map1=load_map("help/help.map");
    put_screen(0, map1);
    write(0, 160, 0, 1, "Press [ENTER] to unload the graphic and finish");
    REPEAT
        FRAME;
    UNTIL (key(_enter));

    unload_map(map1); // The graphic is unloaded.

END
{-}

In the example, a graphic map is loaded with the {#174,load_map()} function, storing the {graphic code} returned by it in the {map1} private variable.

This code is later used as a parameter of the {#148,put_screen()} function
to put the graphic on the background screen.

Then, the program will display a message and wait in a loop for the ENTER key to be pressed. At that moment, the graphic will be unloaded by using the {unload_map()} function.

{/}

The graphics individually loaded with the {#174,load_map()} or {#174,load_pcx()}(or created with the
{#188,new_map()}) functions will not be unloaded when file number 0 (with code 0) is unloaded
with the {#169,unload_fpg()} function, even if these graphics are used as if they belonged to it.

{/}See: {#174,load_map/pcx()} - {#169,unload_fpg()}

# -----------------------------------------------------------------------------

{.177,unload_fnt()}

{unload_fnt(}<font code>{)}

{Description:}

Unloads from the memory the {font} (the {kind of letter} or the {set of graphic characters}) whose code is passed as a parameter.

This <font code> is the value returned by the {#131,load_fnt()} function by 
loading a new letter font stored in a {file FNT} in the computer's memory.

After having unloaded a font, {much care must be taken} not to go on using this font in the program. Otherwise, the program could crash.

{It is not necessary to unload the font} before finishing the 
program, as the system will do it automatically.

Then, a font must be unloaded from the memory only when it is not going to be used for a specific time and when the aim is to free up the occupied space in the computer's memory to load other resources (other graphics files, sounds, fonts, etc.).  

{#9999,Example program:}
PROGRAM example_unload_fnt;

PRIVATE
    font1;

BEGIN
    font1=load_fnt("help/help.fnt");
    write(font1, 160, 0, 1, "FONT LOADED FROM DISK");
    write(0, 160, 190, 1, "Press [ENTER] to unload the font and finish");
    REPEAT
        FRAME;
    UNTIL (key(_enter));

    unload_fnt(font1); // The font is unloaded
END
{-}

In the example, the font stored in the {help.fnt} file is loaded with the {#131,load_fnt()} function, storing the {font code} returned by it in the {font1} private variable.

This code is later used as a parameter of the {#171,write()} function
to put a text on screen with that font.

Then, the program will wait in a loop for the ENTER key to be pressed. At that moment the font will be unloaded by using the {unload_fnt()} function and the program will finish.

{/}

Font number 0, (the system font having 0 as font code),
{can not be unloaded}.

{/}See: {#131,load_fnt()} - {#171,write()} - {#172,write_int()}

# -----------------------------------------------------------------------------

{.178,set_volume()}

{set_volume(}{)}

{Description:}

Advanced function, only for very experienced users.
Adjusts the different volume controls managed by the {mixer} of the system sound.

To adjust the volume, the following values of the {#1104,setup global structure} must be set:

    {setup.master}   - General volumeú
    {setup.sound_fx} - Sound effects volumeú
    {setup.cd_audio} - CC-audio music volumeú

This function is normally used inside the sound setup programs (see {#1093,setup_program}), or even in the rest of the programs, normally to adjust the CD_Audio music volume.

{/}

To activate the rest of the values of the setup structure (those referring to the sound card's parameters) the {#175,reset_sound()} function must be called with the following defined values of the structure:
 
    {setup.card}ú
    {setup.port}ú
    {setup.irq}ú
    {setup.dma}ú
    {setup.dma2}ú

{/}See: {#175,reset_sound()} - {#1104,Setup structure} - {#1093,setup_program}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.179,set_color()}

{set_volume(}<colour>{,} <red>{,} <green>{,} <blue>{)}

{Description:}

Redefines a colour of the palette. This function is used to modify the components
of a colour of the game palette.

You must be very cautious with it, because all the graphics on the screen
that use this colour will be affected, to modify the colours of just one graphic
use the function {#105,convert_palette()} .

The <colour> must be a number between {0} and {255}. The {components of the colour}
will be specified as a number between {0} (minimum) and {63} (maximum).

  {<red>}   - red Component of the colour.ú
  {<green>} - green Component of the colour.ú
  {<blue>}  - blue Component of the colour.ú

Now a program is shown which modifies randomly the colours of the palette.

{#9999,Example program:}
PROGRAM example_set_colour;
GLOBAL colour,r,g,b;
BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 2);
    LOOP
        colour=rand(1,255);
        r=rand(0,63);
        g=rand(0,63);
        b=rand(0,63);

        set_color(colour, r, g, b); // A colour of the palette is redefined.

        FRAME;
    END
END
{-}

In the example a multicolour screen is placed as background and inside of the program 
main loop, the component colours of the palette are modified randomly when the
space bar is pressed. To obtain random numbers use the function {#149,rand()}.

{/}

To modify the entire palette, it is better to load a wholly different file palette with the
function {#133,load_pal()}.
{/}

To realise other palette effects, the function {#154,roll_palette()} can be used, which 
allows you to make loops of changing colours, or the function {#110,fade()} which allows you to realise
multiple fades and saturations of colour at different speeds.

{/}See: {#154,roll_palette()} - {#133,load_pal()} - {#110,fade()} - {#111,fade_off()} - {#112,fade_on()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.180,net_join_game()}

{net_join_game(}<name of the game>{,} <OFFSET structure>{,} <SIZEOF(structure)>{)}

{Returns:}

Number of players in the game (0, 1, 2, ...). If there is an error, a negative
number is returned, which is the error code:

 { -1} : Connection aborted by the user.ú
 { -2} : Can't start the connection.ú
 { -3} : The number of players doesn't fit.ú
 { -4} : There were errors of synchronisation.ú

{Description:}

The net functions are of an extremely advanced level, so could be difficult to understand
for users with not enough experience in programming.

First the predefined global structure {#1410,net} must be initialised with the parameters
that define the type of connection which is going to be established.

Then, a call to the function {net_join_game()} will be enough to create a new game or to join
a game (if it is already created).

The name of the game (a literal, as {"MyGame"}), is used to differentiate a game from other games
running at the same time on one local net. 

>From that moment, every computer connected to the game will send and receive data from 
the others automatically, through the net structure, indicated by the parameters.

{The structure of data.}

This must be a global structure of the program with as many registers as players
that are connected at the same time.

In the fields of the structure the sent data can be read and written to; each player
must input their values in their own register. The number which corresponds
to the total number of players is returned by this function.

The system will automatically send their register values to the other players, and the registers
of the others players to them.

{#1410,The predefined structure net}

In this structure are established the parameters which define the type of connection. The fields
of this structure are :

{net.device} - Type of Connection Port  (1-IPX, 2-Serial link or 3-Modem).

{net.com} - Nº of COM Port, from 1 to 4 (just for serial and modem).

{net.speed} - Connection Speed (in bauds), up to 115000 (just for serial and modem).

{net.number} - Telephone number (just modem), for example {net.number="913040622";}.

{net.init} - Initialising string of the modem, for example {net.init="ATZ";}.

{net.mode} - 0 or 1 depending on whether the signals are pulses or tones (only for modem).

{net.server} - Indicates if it is the server (just reading, can't be modified).

{net.max_players} - Maximum number of players, from 2 to 16 (it must be the same as the number of registers to the global structure).

{net.num_players} - Current number of players, from 1 to 16 (players can connect and disconnect at any moment).

When the connection is made by a serial link or modem, you may only connect {2 players}.

{/}

It's important that the register number of the structure used for the data transfer
has as many registers as that indicated in {net.max_players}.

For example, if a game is created and the maximum number of players is 8,
and the information which must be given to the players is just their coordinates (x,y),
then it could be done as is shown in the following program (supposing a IPX connection
for a local net).

{#9999,Example program:}
PROGRAM example_net_join_game;

GLOBAL
  STRUCT player[7] // 8 players as maximum (from 0 to 7).
    x,y;
  END

  id_red;

BEGIN

  net.device=1;
  net.max_players=8; // Here, the number of registers is indicated.

  // ...

  id_red=net_join_game("xxx",OFFSET player, sizeof(player));

  IF (id_red<0)

    // An error has been produced ...

  END

  // The register of this player is "player[id_red]"

  player[id_red].x=x; // I Define my fields
  player[id_red].y=y;

  FRAME; // Sending / Reception of data

  // Now there are connected "net.num_players", and their data has also been passed to 
  // the other registers of the structure player[].

  // ...

END
{-}

{Note:} Further information can be found about how to structure a game over the internet in
the user's manual of DIV Games Studio.

{/}See: {#181,net_get_games()} - {#1410,STRUCT net}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.181,net_get_games()}

{net_get_games()}

{Returns:}

Activated games of this game currently running.

{Description:}

returns the number of live games currently being played of a particular game
(to connections over local net).
This function is used to see if there is any live game at a determined moment.

To establish a connection, the function {#180,net_join_game()} is used, to create
a game or to connect to them.

{#9999,Example program:}
PROGRAM example_net_get_games;

GLOBAL
  n;  // Active games.

BEGIN
  net.device=1; // set device to local LAN
  // ...

  n=net_get_games();

  IF (n>0)
    // ...
  END

  //...

END
{-}

Just is useful to IPX connections, it has no meaning in serial link or modem connections  
(because in these cases there can be just one game).

{/}See: {#180,net_join_game()} - {#1410,,STRUCT net}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.182,stop_mode8()}

{stop_mode8(}<number of m8>{)}

{Description:}

Eliminates the mode 8 window which number (from 0 to 9) is given as the parameter.
This <number of m8> is the one indicated as the first parameter in the function
{#190,start_mode8()}, it is necessary to define the mode 8 window number as there 
can be up to 10 different mode 8 windows, and the system needs to know which of them 
is being terminated.

{/}

{Note:} To create a mode 8 window is an advanced procedure and requires
some parameters to be set, as in this case the camera, some of them required
by the function {#190,start_mode8()} and others are contained in the
{#1411,global m8 structure} (such as the variable {m8.camera}).

{/}

{#9999,Example program:}
PROGRAM example_stop_mode8;

BEGIN
  load_fpg("help/WLD_VIEW.FPG");
  load_wld("help/WLD_VIEW.WLD",0);
  start_mode8(id,0,0);
  ctype=c_m8;
  go_to_flag(0);
  write(0,0,0,0,"Press ESC to finish ...");
  REPEAT
      FRAME;
  UNTIL (key(_esc));

  stop_mode8(0); // Eliminates the region number 0 of mode 8

END
{-}

This program shows an initiation example of a mode 8 region,
loading the map contained in the file {wld_view.prg}, and starting a
region (the number {0}) with {#190,start_mode8()} function.

This program waits in a loop until it detects the {ESC} key has been pressed,
at which point it leaves the loop and then eliminates this region with the {stop_mode8(0)} function.

{/}See: {#190,start_mode8()} - {1411,STRUCT m8} - {#189,load_wld()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.183,xadvance()}

{xadvance(}<angle>{,} <distance>{)}

{Description:}

Advances the process {the indicated angle} as many points as {the indicated distance} shows as parameter.

This function is equivalent to the function {#101,advance()}, if the {#1129,angle} is used as its first
parameter.

The distance can be a negative number too, so the graphic of the process
will advance  (its coordinates {#1123,x} and {#1124,y}) in the opposite direction
to this angle.

{#9999,Example program:}
PROGRAM example_xadvance;

PRIVATE
  angle2;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    graph=101;
    x=160;
    y=100;
    write(0, 0, 0, 0, "Use the cursors to change the direction.");
    LOOP
        angle+=5000;
        IF (key(_right)) angle2-=10000; END
        IF (key(_left)) angle2+=10000; END

        xadvance(angle2,4); // We advance the process to points

        FRAME;
    END
END
{-}

This example will draw a triangle on screen which will rotate in the selected direction
chosen with the cursors, independent of the orientation of the graphic on the screen
(of visible angle). The program advances 5 degrees per frame in the direction
selected by the cursors. 

Remember that the angle is specified in thousandths of a degree.

{/}See: {#1044,Use of the angles in the language} - {#101,advance()} - {#118,get_distx()} - {#119,get_disty()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.184,char()}

{char(}<literal>{)}

{Returns:}

The {ASCII} value of the (first) character contained in the literal parameter.

{Description:}

This function {char()} is used to obtain the ordinal value of a character.

{#9999,Example program:}
PROGRAM example_char;
PRIVATE value;
BEGIN
  // ..
  value="A";       // The address of the literal "A" is assigned in memory.
  // ..
  value=char("A"); // The ASCII value of "A" is assigned (65 in decimal).
  // ..
END
{-}

In a program, the literals (texts between quotation marks) are translated as the
memory address which they have been allocated. To assign to one variable
a character (its ordinal value), instead of the address of the string,
use this function.

See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.185,path_find()}

{path_find(}<mode>{,} <file>{,} <graphic>{,} <square size>{,} <x>{,} <y>, <OFFSET structure>{,} <sizeof(structure)>{)}

{Returns:}

Number of route points, or 0 if it doesn't find any.

{Description:}

Finds a route from the current coordinates of the process to a determined
point, dodging the defined obstacles in a searching map
(in the user's manual, can be found information about these maps).

{The mode.}

Defines the type of route searching mode, depending on the {<mode>} indicated
as first parameter of the function.

  {0} - Searching less precise and faster.ú
  {1} - Searching more precise, but slower.ú

{The searching map.}

The {<file>} and {<graphic>} codes, are related to the searching map. This
is a simplified version of the real scenario, where the free zones appear as
a {black colour}(the number 0 of the palette) and the obstacles appear as a 
{white colour} shape.

The {<square size>} indicates the reduction factor of the searching map,
how much the width and height of the map must be multiplied to be shown 
at real size. For example, if a searching map of 160x100 is generated for
a 320x200 screen, the square size will be 2.

{The route points.}

Now must be indicated the coordinates {<x>} and {<y>} where the process must
go (the origin is taken as the initial coordinates of the process which
executes the function {path_find()}).

This function returns a group of structure points, which are the
points that form the route from the origin to the destination point.

To do this, a structure must be declared which contains two fields (x,y),
and as many registers as points that comprise the calculated route.

The two last parameters of the function contain, the address ({#1085,OFFSET}) of
this structure and its size ({#1094,SIZEOF()}), so the coordinates contained in this 
structure can be passed back to the function as the results.

{/}

{#9999,Example program:}
PROGRAM example_path_find;

GLOBAL
    num_points;
    STRUCT points[100]
      x,y;
    END
    index;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 7);
    graph=200;
    mouse.graph=200;
    LOOP

        // Obtains the route to the mouse's coordinates

        num_points=path_find(0,0,201,2,mouse.x,mouse.y,OFFSET points,sizeof(points));

        // If a route was obtained, it shows the route and advances to the destination

        IF (num_points>0)
            FOR (index=0;index<num_points-1;index++)
                draw(1,24,15,0,points[index].x,points[index].y,points[index+1].x,points[index+1].y);
            END
            IF (fget_dist(x,y,points[0].x,points[0].y)>4)
                xadvance(fget_angle(x,y,points[0].x,points[0].y),4);
            ELSE
                x=points[0].x;
                y=points[0].y;
            END
            draw(1,24,15,0,x,y,points[0].x,points[0].y);
        END

        FRAME;
        delete_draw(all_drawing);
    END
END
{-}

In this example the {graphic number 7} of the file {help.fpg} is used as the
scenario, and the {graphic number 201} of the same file as its {searching map}.

The square size of the searching map is {2}

The main process is continuously finding a route to the mouse cursor
with the function {path_find()}.

The different segments of this route are shown with lines using the
function {#249,draw()}, and the coordinates are incremented
with the function {#183,xadvance()}.

To obtain the distance and the angle to the next point of the route the 
functions {#114,fget_dist()} and {#113,fget_angle()} are used.

{/}

To see if it's possible to go directly in a straight line between two points (without
passing through any obstacle) the function {#186,path_line()} can be used.

The function {#187,path_free()} determines if a particular point of the map
is an obstacle or if it is a free point (accessible).

{/}See: {#186,path_line()} - {#187,path_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.186,path_line()}

{path_line(}<file>{,} <graphic>{,} <square size>{,} <x>{,} <y>{)}

{Returns:}

{#1151,True (1)}, if it is possible to go from one point to another without
going through any obstacle, or {#1152,false (0)} if not.

{Description:}

It determines if, inside of a searching map, you can go in a straight line up to a point
(starting from the current coordinates of the process), without passing through any 
obstacle of the searching map (in the user's handbook you can find information about
these maps).

In case of wanting to obtain a path between two points that dodges all the obstacles ,
use the function {#185,path_find()}, and to see if the destination point
is inside of an obstacle, use the function {#187,path_free()}.

{The searching map.}

The {<file>} and {<graphic>} codes, are related to the searching map. This
is a simplified version of the real scenario, where the free zones appear as
a {black colour}(the number 0 of the palette) and the obstacles appear as a 
{white colour} shape.

The {<square size>} indicates the reduction factor of the searching map,
how much the width and height of the map must be multiplied to be shown 
at real size. For example, if a searching map of 160x100 is generated for
a 320x200 screen, the square size will be 2.

{The route points.}

Now must be indicated the coordinates {<x>} and {<y>} where the process must
go (the origin is taken as the initial coordinates of the process which
executes the function {path_find()}).

{/}

{#9999,Example program:}
PROGRAM example_path_line;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 7);
    graph=200;
    mouse.graph=200;
    LOOP

        // It checks if you can go in a straight line to the mouse

        IF (path_line(0,201,2,mouse.x,mouse.y))

            IF (fget_dist(x,y,mouse.x,mouse.y)>4)
                xadvance(fget_angle(x,y,mouse.x,mouse.y),4);
                draw(1,24,15,0,x,y,mouse.x,mouse.y);
            ELSE
                x=mouse.x;
                y=mouse.y;
            END
        END

        FRAME;
        delete_draw(all_drawing);
    END
END
{-}

In this example the {graphic number 7} of the file {help.fpg}is used as the
scenario, and the {graphic number 201} of the same file is used  as its {searching map}.

The square size in the searching map is {2}.

The main process is continuously checking if you can go in a straight line
to the mouse coordinates with the function {path_line()}. If this is
possible, a line is traced with the function {#249,draw()}, and the process 
coordinates advance in this direction with the function {#183,xadvance()}.

To obtain the distance and the angle to the mouse cursor the
functions {#114,fget_dist()} and {#113,fget_angle()} are used.

{/}See: {#185,path_find()} - {#187,path_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.187,path_free()}

{path_free(}<file>{,} <graphic>{,} <square size>{,} <x>{,} <y>{)}

{Returns:}

{#1151,True (1)}, if the point in a searching map is free (is not an obstacle), or
{#1152,false (0)} if not.

{Description:}

Determines if, inside of a searching map, the coordinates are placed
in an accessible zone, not overlapping with any obstacle (in the user's manual
can be found information about these searching maps).

In case of wanting to obtain a route to dodge the obstacles between two points
the function {#185,path_find()} must be used, and to see if it can go to a
point in a straight line without passing through any obstacle use the function {#186,path_line()}.

{The searching map.}

The {<file>} and {<graphic>} codes, are related to the searching map. This
is a simplified version of the real scenario, where the free zones appear as
a {black colour}(the number 0 of the palette) and the obstacles appear as a 
{white colour} shape.

The {<square size>} indicates the reduction factor of the searching map,
how much the width and height of the map must be multiplied to be shown 
at real size. For example, if a searching map of 160x100 is generated for
a 320x200 screen, the square size will be 2.

Now the coordinates {<x>} and {<y>} to be referenced must be indicated .

{/}

{#9999,Example program:}
PROGRAM example_path_free;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 7);
    mouse.graph=200;
    mouse.size=400;
    LOOP

        // Checks if the mouse is in an accessible zone

        IF (path_free(0,201,2,mouse.x,mouse.y))
            mouse.angle+=5000;
        END

        FRAME;
    END
END
{-}

In this example the {graphic number 7} of the file {help.fpg} is used as
the scenario, and the {graphic number 201} of the same file as its {searching map}.
the square size of the searching map is {2}

The main process is continuously checking, with the function {path_free()},
if the mouse cursor is in a free zone, or over an obstacle.

When the cursor is in a free zone, out of any obstacle, the cursor graphic
will rotate.

{/}See: {#185,path_find()} - {#186,path_find()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.188,new_map()}

{new_map(}<width>{,} <height>{,} <centre x>{,} <centre y>{,} <colour>{)}

{Returns:}

The {code of the graphic} created.

{Description:}

Creates a new map in memory (without loading it from an file of the disk).

To do this, the function requires the {<width>} and {<height>} (in pixels) of the map
that must be created, a central point (of the same) in {<centre x>} and {<centre y>},
and the colour with which the map will be initially filled (the number of the colour
inside of the active palette, from 0 to 255).

This function acts similarly to the function {#174,load_map()}, except that an file
graphic from the disk is not loaded, and the graphic created is a solid graphic of just one
colour.

The value returned is the {code of the graphic}, which is a numeric value
which must be specified to use the graphic, in the variable
{#1126,graph} or, in general, in every function which requires a {code of graphic}
in its parameters.

{/}

{Important:}

When, inside of a function, the {code of file} which belongs
to the graphic is required , you must be indicate the code {0} (which is the code of the
first {file FPG} that is loaded in the program).

{/}

{#9999,Example program:}
PROGRAM example_new_map;

BEGIN

    // Is created a map of 16x32 points
    // with its centre in the point (0,0)
    // and with the colour 15 of the palette

    mouse.graph = new_map(16,32,0,0,15); // Is assigned as mouse cursor

    REPEAT
        FRAME;
    UNTIL (key(_esc));

    unload_map(mouse.graph); // And finally the graphic is deleted 
END
{-}

In the example a map is created with the function {new_map()} and is saved as 
the {code of the graphic} which is returned in the variable {#1100,mouse.graph}, as 
the mouse cursor.

Pressing the {ESC} key takes you out of the loop of the program and
the graphic will be deleted with the function {#176,unload_map()} (exactly the same
as if it were loaded from an file).

{/}

The function {#176,unload_map()} frees up the computer memory used
by the graphic when it is used no more, and due to that
the {code of the graphic} is also required to know which graphic is the one
that is to be deleted from memory.

{It is not necessary to delete the graphic from memory} before exiting the
program, because the system will do that automatically.

{/}See: {#174,load_map/pcx()} - {#176,unload_map/pcx()} - {#1126,graph}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.189,load_wld()}

{load_wld(}<Archive number>{,} <file>{)}

{Description:}

It loads a {mode 8 map} in a program. These maps are saved in the files
with the extension WLD, and are created with the map's 3D menu (in the user's manual
can be found further information on how to construct these maps).

The parameters required are the {<name of file>} which contains the map in
WLD format, and the code of the {<file>} which contains the file's textures.
This file with the textures of the map needs to be previously loaded in 
the program with the function {#132,load_fpg()}.

Once the map is loaded, a region of mode 8 screen must be initiated with
the function {#190,start_mode8()}. The functioning is quite similar to the mode 7
which shows a graphic in a folded plane (see {#162,start_mode7()}).

{#9999,Example program:}
PROGRAM example_load_wld;

GLOBAL
    fpgfile;

BEGIN
  set_mode(m640x480);
  set_fps(70,0);
  fpgfile = load_fpg("help/WLD_VIEW.FPG");

  load_wld("help/WLD_VIEW.WLD",file); // Loads a file WLD

  start_mode8(id,0,0);
  ctype=c_m8;
  height=64;
  radius=64;
  m8.height=32;
  go_to_flag(0);
  LOOP
    IF (key(_right)) angle-=5000; END
    IF (key(_left))  angle+=5000; END
    IF (key(_up))    advance(24); END
    IF (key(_down))  advance(-9); END
    IF (key(_q))     z+=16;       END
    IF (key(_a))     z-=16;       END
    IF (key(_w))     m8.angle+=8; END
    IF (key(_s))     m8.angle-=8; END
    FRAME;
  END
END
{-}

This program shows an initiation example of a mode 8 region,
loading the map contained in the file {wld_view.prg}, and whose texture is
found in the file {wld_view.fpg}.

{/}See: {#190,start_mode8()} - {#191,go_to_flag()} - {#132,load_fpg()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.190,start_mode8()}

{start_mode8(}<camera identifier>{,} <number of m8>{,} <number of region>{)}

{Description:}

This is an advanced function that requires the user to have a certain
amount of experience to use it.

It creates a window with a mode 8, which generates a three-dimensional map.
{First the map must be loaded with the {#189,load_wld()} function} and then,
the following parameters of this function need defining.

{<camera identifier>} - {#1039,Identifier code} of the process
in which the mode 8 camera will be placed, the camera will be placed
at the coordinates {(x,y)}, at height {(z)} and looking in the indicated
direction  defined by {(angle)} (these are {#1201,local data predefined} for the
process).

{<number of m8>} - Up to 10 mode 8 windows can be created on screen, 
numbered from {0} to {9}; if just one is created, then define this as 
number {0}. This number will be needed to modify
the parameters of the window, because the system needs to know which one
of the {10} possible mode 8 windows you wish to modify.

{<number of region>} - Here will be indicated the rectangular region of the screen
where the mode 8 is going to be shown. If the number of the region indicated is {0} , 
it will be shown full screen. Other regions must be defined
previously with the function {#106,define_region()} (a {region} is just a
rectangular zone of the screen).

{Note:} The functioning is very similar to the mode 7 which shows a folded plane 
(see {#162,start_mode7()}).

{/}

{Apart from the call to the function, some values of the} {#1411,global m8 structure} 
must be initiated {for the window to function correctly}.
This is a structure of 10 registers (one for each possible mode 8 window)
and each register has the following fields:

  {camera}   - {#1039,Identifier code} of the cameraú
  {height}   - Height of the camera in relation to the processú
  {angle}    - Vertical angle of the camera (-128,128)ú
  {z}        - Plane of depth (priority of impression of the region)ú

The field {camera} is {essential},as that is asked as one of the calling parameters
of the function {start_mode8()} because, without this field, the window can't determine 
the viewpoint from which the map will be initially viewed.

{/}

{#9999,Example program:}
PROGRAM example_start_mode8;

GLOBAL
    fpgfile;

BEGIN
  set_mode(m640x480);
  set_fps(70,0);
  fpgfile = load_fpg("help/WLD_VIEW.FPG");
  load_wld("help/WLD_VIEW.WLD",file);

  start_mode8(id,0,0); // Starts a mode 8 region

  ctype=c_m8;
  height=64;
  radius=64;
  m8.height=32;
  go_to_flag(0);
  LOOP
      IF (key(_right)) angle-=5000; END
      IF (key(_left))  angle+=5000; END
      IF (key(_up))    advance(24); END
      IF (key(_down))  advance(-9); END
      IF (key(_q))     z+=16;       END
      IF (key(_a))     z-=16;       END
      IF (key(_w))     m8.angle+=8; END
      IF (key(_s))     m8.angle-=8; END
      FRAME;
  END
END
{-}

This program shows an initiation example of a mode 8 region, loading
the file {wld_view.prg}, and whose textures are found in the
file {wld_view.fpg}.

{/}

To create a process where a graphic is displayed in the mode 8 region, 
its local variable {#1122,ctype} must be defined as well as {#1412,c_m8}
({type of coordinate} as the {coordinate of mode 8}).

When a process is in a mode 8 region its variables {#1123,x} and {#1124,y}
will be related to the point inside of the map sector (WLD), and the variable
{#1125,z} will indicate the height.

If there are several {mode 8} windows, the process will by default be seen 
in all of them, if the process is wanted to be seen in just some of them, the local
variable {#1134,cnumber} must be defined.

For a process to have many graphics (many views), depending on the
angle from which it is going to be viewed, you must define 
the local variable of the graphic {#1132,xgraph} (instead of the variable {#1126,graph}).

{/}

{Note:} To eliminate a mode 8 region you must be use the function
{#182,stop_mode8()}, indicating the {number of m8}.

{/}See: {#1411,STRUCT m8} - {#189,load_wld()} - {#191,go_to_flag()} - {#182,stop_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.191,go_to_flag()}

{go_to_flag(}<number of flags>{)}

{Description:}

Places a process in a mode 8 region in a position indicated by a flag, the process
 calling  the function is the one placed in that position, 
the only parameter needed is the {<number of flag>}, as a mode 8 region can
have more than one predefined flag position.

After the function has been called, in the next {#1029,FRAME} the process will be placed
at the flag coordinates. The height of the flag will always be understood
to be the minimum height of the sector where it is going to be found.

The flags are placed in the editor of the three-dimensional maps, control
of which is explained in the user's manual.

{Note:} This function is equivalent to giving the process the coordinates
a flag ({x},{y},{z}). 

{#9999,Example program:}
PROGRAM example_go_to_flag;

BEGIN
  load_fpg("help/WLD_VIEW.FPG");
  load_wld("help/WLD_VIEW.WLD",0);
  start_mode8(id,0,0);
  ctype=c_m8;

  go_to_flag(0); // Places the process camera at flag 0

  LOOP
      FRAME;
  END
END
{-}

This example program initialises a mode 8 region, loading the map contained in the
{wld_view.prg} file using the {#189,load_wld()} function, and starts a region 
with {#190,start_mode8()}.

Then, it places the process (which acts as the camera of the window) in the
position indicated by the flag number 0 of the map sector.

{/}See: {#190,start_mode8()} - {#1411,STRUCT m8} - {#189,load_wld()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.192,set_sector_height()}

{set_sector_height(}<number of sector>{,} <height of the ground>{,} <height of the ceiling>{)}

{Description:}

Modifies the height of the {ground} or {ceiling} of a mode 8 sector. The following
parameters are required:

{<number of sector>} - Number of sector of the map for which the height is wished
to be modified. This number can be obtained from three-dimensional maps editor,
as explained in the user's manual.

{<height of the ground>} - The new sector height of the ground must be indicated
(a value from 0 to 4096), if { -1} is indicated as the parameter, 
the current sector height of the ground will remain (useful to ascertain the
height of the ground).

{<height of the ceiling>} - The new sector height of the ceiling must be indicated
(a value from 0 to 4096), if { -1} is indicated as the parameter, the current sector 
height of the ceiling will remain (useful to ascertain the height of the ceiling).

To start a mode 8 region, the function {#190,start_mode8()} must be called.

{/}

{Note:} If the height of the ceiling is the same as the ground's height this
sector won't be accessible (if this one is inside of another, it will appear as a
column). The height of the ceiling must be smaller than the height of the ground.

{/}

{#9999,Example program:}
PROGRAM example_set_sector_height;

GLOBAL
    sector=255;
    altitude;
    angle1;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    start_mode8(id,0,0);
    ctype=c_m8;
    go_to_flag(1);
    FRAME;
    z+=64;
    LOOP
        altitude=1000+get_distx(angle1,64);
        angle1+=5000;

        set_sector_height(sector,altitude,-1);

        FRAME;
    END
END
{-}

This small example starts a mode 8 region, loading the map
{wld_view.wld}, and places it at the predetermined coordinates with
the function {#191,go_to_flag()}.

Then, inside of the program main loop, the height of the ground of the
sector {255} is fixed with the function {set_sector_height()}.

{/}

The function {#193,get_sector_height()} allows you to find the ground
and ceiling heights in a mode 8 sector.

{/}See: {#193,get_sector_height()} - {#190,start_mode8()} - {#1411,STRUCT m8}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.193,get_sector_height()}

{get_sector_height(}<number of sector>{,} <OFFSET ground>{,} <OFFSET ceiling>{)}

{Returns:}

The {height of the ground and ceiling} of a mode 8 sector (in the variables which
{#1085,offset} are indicated as the two last parameters).

{Description:}

This function allows you to determine in a program, the height of the ground
and ceiling of a determined sector, inside of a mode 8 sector.

To do this, the {<number of sector>} is required , and the {#1085,OFFSET} (address
of memory) of the two variables where the result will be returned.

This information also can be obtained inside of the editor of three-dimensional maps
as explained in the user's manual.

{#9999,Example program:}
PROGRAM example_get_sector_height;

GLOBAL
    ceiling_height;
    floor_height;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    // ...

    // Obtain the heights of a sector

    get_sector_height(255,OFFSET floor_height,OFFSET ceiling_height);

    // ...
END
{-}

This small example shows how the function {get_sector_height()} must be called
to obtain the heights of a sector (in this case, in the variables {ceiling_height}
and {floor_height} these values are obtained for the sector number {255}).

{/}

To establish the height of a sector, the function {#192,set_sector_height()} must
be used.

{/}See: {#192,set_sector_height()} - {#190,start_mode8()} - {#1411,STRUCT m8}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.194,set_point_m8()}

{set_point_m8(}<number of vertex>{,} <x>{,} <y>{)}

{Description:}

Modifies the coordinates of a three-dimensional map's vertex on a mode 8 sector.
The following parameters are required:

{<number of vertex>} - Number of vertices of the map which position is wanted to
modified. This number can also be obtained from the editor of the three-dimensional maps,
as is explained in the user's manual.

{<x>}, {<y>} - The new coordinates of the vertex must be defined. The
coordinates inside of a three-dimensional map are placed with the rank ({0} ..
{30200}).

To create a mode 8 region, the function {#190,start_mode8()} must be called.

{/}

{Note:} This is a function which can give rise to multiple
{errors of visibility}. For that reason, it is not recommended for use by inexperienced users.

The vertices can only move {inside of the sector} in which they started,
{sector boundaries can't be crossed} (not the vertex, nor the lines which these make) and, besides,
all sectors which can't contain processes may not be moved.

{/}

{#9999,Example program:}
PROGRAM example_set_point_m8;

GLOBAL
    position1;
    position2;
    angle1;
    angle2;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    start_mode8(id,0,0);
    ctype=c_m8;
    go_to_flag(1);
    FRAME;
    z+=64;
    LOOP
        position1=3400+get_distx(angle1,150);
        angle1+=5000;
        position2=3400+get_distx(angle2,150);
        angle2+=7000;

        set_point_m8(1620,position1,9280); // Fixes the vertex 1620

        set_point_m8(1621,position2,9456); // Fixes the vertex 1621

        FRAME;
    END
END
{-}

This small example initialises a mode 8 region, loading the map
{wld_view.wld}, and places it in the predetermined coordinates with
the function {#191,go_to_flag()}.

Then, inside of the program's main loop, the position of the vertex
{1620} and {1621} is fixed with the function {set_point_m8()}.

{/}

The function {#195,get_point_m8()} allows you to find the coordinates of a vertex
of a three-dimensional map in a mode 8 region.

{/}See: {#195,get_point_m8()} - {#190,start_mode8()} - {#1411,STRUCT m8}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.195,get_point_m8()}

{get_point_m8(}<number of vertex>{,} <OFFSET x>{,} <OFFSET y>{)}

{Returns:}

The {coordinates of a vertex} of a mode 8 map (in the variables which
{#1085,offset}, indicated as the two last parameters).

{Description:}

This function allows you to determine inside of a program, the coordinates of
a specific vertex, inside of a mode 8 region.

To do this, the {<number of vertex>} is required, and the {#1085,OFFSET} (pointer) 
of the two variables where the result is stored.

This information can also be obtained from the three-dimensional
maps editor, which is explained in the user's manual.

{#9999,Example program:}
PROGRAM example_get_point_m8;

GLOBAL
    position_x;
    position_y;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    // ...

    // Obtains a vertex's coordinates

    get_point_m8(1620,OFFSET position_x,OFFSET position_y);

    // ...
END
{-}

This small example shows how the function {get_point_m8()} is called 
to obtain the position of a sector vertex (in this case, in the variables {position_x}
and {position_y}).

{/}

To set or establish the positions of a vertex, the function {#194,set_point_m8()} must
be used.

{/}See: {#194,set_point_m8()} - {#190,start_mode8()} - {#1411,STRUCT m8}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.196,set_fog()}

{set_fog(}<Initial position>{,} <Final position>{)}

{Description:}

Modifies the fog of a mode 8 region initiated with the function {#190,start_mode8()},
to do this, the following parameters are required:

{<Initial position>} - Percentage or initial distance of the fog (from 0 to 100),
in this way, the point from which the effect is applied is determined.

{<Final position>} - Percentage or final distance of the fog (from 0 to 100),
in this way, the point from which the fog is solid/completely opaque is determined.

Normally the position or final percentage is established as the double
of the initial, the further apart the values are, the more slowly the fog
will appear.

{#9999,Example program:}
PROGRAM example_set_fog;

GLOBAL
    fogpos;
    angle1;

BEGIN
  load_fpg("help/WLD_VIEW.FPG");
  load_wld("help/WLD_VIEW.WLD",0);
  start_mode8(id,0,0);
  ctype=c_m8;
  go_to_flag(0);
  FRAME;
  z+=128;
  LOOP
      fogpos=25+get_distx(angle1,20);
       angle1+=5000;

      set_fog(fogpos,fogpos*2); // Establishes the fog level of the mode 8

      FRAME;
  END
END
{-}

This small example shows how the function {set_fog()} must be called 
to modify the fog of a mode 8 region.

The variable {position} varies from {5} to {45} (using the function
{#118,get_distx()}), this will be the initial position, the final one
will be fixed as double the initial one.

{/}

{Note:} The function {#201,set_env_color()} allows you to fix the ambience colour
or the fog colour of a mode 8 region.

{/}See: {#201,set_env_color()} - {#190,start_mode8()} - {#1411,STRUCT m8}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.197,set_sector_texture()}

{set_sector_texture(}<number of sector>{,} <ground texture>{,} <ceiling texture>{,} <luminosity>{)}

{Description:}

Modifies the {textures of ground and ceiling} of a mode 8 sector. The following
parameters are required:

{<number of sector>} - Number of the map sector for which textures are to be
modified. This number can be obtained from the three-dimensional maps editor,
as is explained in the user's manual of the program.

{<ground texture>} - The code of the new texture graphic to be used as the 
{ground texture} of the sector (ie: the number of the graphic
inside of the FPG which contains every texture of the mode 8 region). If a { -1} is
indicated as parameter the current texture will remain (to modify just
the ceiling texture).

{<ceiling texture>} - The code of the new texture graphic to be used as the 
{ceiling texture} of the sector (ie: the number of the graphic
inside of the FPG which contains every texture of the mode 8). If a { -1} is
indicated as parameter the current texture will remain (to modify just
the ground texture).

{<luminosity>} - Luminosity of the texture, from {0} (ambience colour, which
is normally black) up to {15} (texture with the original colours).
If a { -1} is indicated, the current level of luminosity in the sector will remain
unchanged.

{/}

{Note:} every texture must be contained in the same file FPG,
this is the file which is loaded with {#132,load_fpg()} function and which number is
given as the parameter of the function {#189,load_wld()}.

{/}

{#9999,Example program:}
PROGRAM example_set_sector_texture;

GLOBAL
    texture=94;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    start_mode8(id,0,0);
    ctype=c_m8;
    go_to_flag(1);
    FRAME;
    z+=128;
    m8.angle=-64;
    LOOP
        IF (texture++==103) texture=94; END

        set_sector_texture(255,texture,-1,15);

        FRAME;
    END
END
{-}

This small example starts a mode 8 region, loading the map
{wld_view.wld}, which is placed at the predetermined coordinates with
the function {#191,go_to_flag()}.

Then, inside of the program main loop, the ground texture of the sector
{255} is set with the function {set_sector_texture()}.

{/}

The function {#198,get_sector_texture()} allows one to find the textures
(and luminosity) that are assigned to a mode 8 sector.

The function {#199,set_wall_texture()} allows you to establish the texture of a wall.

{/}See: {#198,get_sector_texture()} - {#199,set_wall_texture()} - {#192,set_sector_height()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.198,get_sector_texture()}

{get_sector_texture(}<number of sector>{,} <OFFSET ground texture>{,} <OFFSET ceiling texture>{,} <OFFSET luminosity>{)}

{Returns:}

The {luminosity, and the textures of the ground and ceiling} of a mode 8 sector
(stored in the variables which {#1085,offset} are indicated as the parameters).

{Description:}

This function allows you to determine which are the textures in a program 
for the ground and the ceiling and/or the luminosity of a determined sector, inside of a
mode 8 region.

To do this, the {<number of sector>} is required , and the {#1085,OFFSET} (pointer) for the
variables where the results will be stored are also required.

{#9999,Example program:}
PROGRAM example_get_sector_texture;

GLOBAL
    ceiling_texture;
    floor_texture;
    luminosity;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    // ...

    // Obtains the luminosity and textures of a sector

    get_sector_texture(255,OFFSET ceiling_texture,OFFSET floor_texture,OFFSET luminosity);

    // ...
END
{-}

This small example shows how the function {get_sector_texture()} must be called 
to obtain the textures and the luminosity of a sector (in this case, in the variables
{floor_texture}, {ceiling_texture} and {luminosity} these values are obtained for the
sector number {255}).

{/}

The function {#197,set_sector_texture()} allows you to establish the textures and luminosity
of a mode 8 sector dynamically.

The function {#200,get_wall_texture()} allows you to find what the assigned texture of a mode 8
wall is .

{/}See: {#197,set_sector_texture()} - {#200,get_wall_texture()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.199,set_wall_texture()}

{set_wall_texture(}<number of sector>{,} <texture>{,} <luminosity>{)}

{Description:}

Modifies the {wall texture} of a mode 8 sector. The following parameters are
required:

{<number of wall>} - Number of the wall texture required. This number can
 be obtained in the three-dimensional maps editor,
as is explained in the user's manual of the program.

{<texture>} - The code of the graphic which is to be assigned as the new wall
texture (the number of the graphic inside of the FPG which contains every mode 8 texture) 
must be indicated. If a { -1} is indicated as the parameter, the current texture will remain
unchanged.

{<luminosity>} - Luminosity of the texture, from {0} (ambience colour, which is
normally black) up to {15} (texture with the original colours).
If a { -1} is indicated, the current level of luminosity will remain unchanged.

{/}

{Note:} every texture must be contained in the same file FPG,
this is the file which is loaded with {#132,load_fpg()} and which number is given
as a parameter to the function {#189,load_wld()}.

{/}

{#9999,Example program:}
PROGRAM example_set_wall_texture;

GLOBAL
    texture=104;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    start_mode8(id,0,0);
    ctype=c_m8;
    go_to_flag(1);
    FRAME;
    z+=128;
    LOOP
        IF (texture++==113) texture=104; END

        set_wall_texture(511,texture,15); // Modifies a wall texture

        FRAME;
    END
END
{-}

This small example starts a mode 8 region, loading the map
{wld_view.wld}, and it is placed in the predetermined coordinates with the
function {#191,go_to_flag()}.

Then, inside the program main loop, the texture of the wall number {511} 
is fixed with the function {set_wall_texture()}.

{/}

The function {#200,get_wall_texture()} allows you to find the current texture
of a wall.

The function {#197,set_sector_texture()} allows you to establish the {textures of
ground and ceiling} of a mode 8 sector.

{/}See: {#200,get_wall_texture()} - {#197,set_sector_texture()} - {#192,set_sector_height()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.200,get_wall_texture()}

{get_wall_texture(}<number of wall>{,} <OFFSET texture>{,} <OFFSET luminosity>{)}

{Returns:}

The {luminosity and the texture} of a mode 8 wall (in the variables
which {#1085,offset} are indicated in the parameters).

{Description:}

This function allows you to determine inside of a program, what the texture
and the luminosity is of a determined wall, inside of a mode 8.

To do this, the {<number of wall>} is required, and the {#1085,OFFSET} (pointer)
of the variables where the result will be stored.

{#9999,Example program:}
PROGRAM example_get_wall_texture;

GLOBAL
    texture;
    luminosity;

BEGIN
    load_fpg("help/WLD_VIEW.FPG");
    load_wld("help/WLD_VIEW.WLD",0);
    // ...

    // Obtains the luminosity and texture of a wall

    get_wall_texture(255,OFFSET texture,OFFSET luminosity);

    // ...
END
{-}

This small example shows how the function {get_wall_texture()} must be called 
to obtain the texture and the luminosity of a wall in a sector (in this case, the variables
{texture} and {luminosity} are assigned to the wall number {255}).

{/}

The function {#199,set_wall_texture()} allows you to establish the texture and luminosity
of a mode 8 wall dynamically.

The function {#198,get_sector_texture()} lets us know which are the floor
and ceiling textures of a mode 8 sector.

{/}See: {#199,set_wall_texture()} - {#198,get_sector_texture()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.201,set_env_color()}

{set_env_color(}<% red>{,} <% green>{,} <% blue>{)}

{Description:}

Modifies the colour of the ambience or fog of a mode 8 sector, to do this 
the components {<red>} (red), {<green>} (green) and {<blue>} (blue) of the 
sector are required.

The three components must be specified as percentage, from {0} to {100}.

By default, the fog is set as a black colour (0,0,0), but this colour can
be modified to create a different ambience.

{#9999,Example program:}
PROGRAM example_set_env_colour;

GLOBAL
    light;
    angle1;

BEGIN
  load_fpg("help/WLD_VIEW.FPG");
  load_wld("help/WLD_VIEW.WLD",0);
  start_mode8(id,0,0);
  ctype=c_m8;
  go_to_flag(0);
  FRAME;
  set_fog(30,90);
  z+=128;
  LOOP
      light=50+get_distx(angle1,50);
      angle1+=5000;

      set_env_color(light,light,light); // establishes the ambience colour

      FRAME;
  END
END
{-}

This small example shows how the function {set_env_color()} must be called 
to modify the fog colour of a mode 8 region.

The variable {light} varies from {0} to {100} (using the function {#118,get_distx()}), 
this percentage is the same for the three components of the colour, so this will
gradually change from {black} to {white}, going through all the grey scale in between.

{/}

{Note:} The function {#196,set_fog()} allows you to fix the density of the fog or ambience
of a mode 8 region.

{/}See: {#196,set_fog()} - {#190,start_mode8()} - {#1411,STRUCT m8}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.202,strcpy()}

{strcpy(}<string destination>{,} <string origin>{)}

{Returns:}

Copies a string from the origin to the string destination.

{Description:}

Copies the {<string origin>} to the {<string destination>}, 
(the original content of the string destination will be lost).

The {<string destination>} must be a data type {#1406,STRING}, of a length
long enough to contain the text of the {<string origin>}.

{#9999,Example program:}
PROGRAM example_strcpy;

GLOBAL
    STRING string1="Initial text";

BEGIN
    write(0,0,0,0,"Text contained in <string1>:");
    write(0,0,10,0,string1);
    write(0,0,192,0,"Press [SPACE] to copy another text in <string1>");
    LOOP
        IF (key(_space))

            strcpy(string1,"Final text"); // Modifies string1

        END
        FRAME;
   END
END
{-}

{/}

When the length of the copied string is smaller than 1024 characters, this
same operation can be done with the following statement:
(continuing with the previous example):

  {string1 = "Final text";}

With a generic statement of {#1019,assignation} as the following:

  {<string destination> = <string origin> ;}

The {<string destination>}Being always of a data type {#1406,STRING}. To join some
text strings together the function {#203,strcat()} must be used.

{/}See: {#203,strcat()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.203,strcat()}

{strcat(}<string destination>{,} <string origin>{)}

{Returns:}

Joins two strings together and returns the address of the string destination.

{Description:}

Joins two text strings, copying the {<string origin>} and adding on the end of 
the text contained in the {<string destination>}.

The {<string destination>} must be of data type {#1406,STRING}, of a length
long enough to contain both strings.

{#9999,Example program:}
PROGRAM example_strcat;

GLOBAL
    STRING string1="Beginning ";

BEGIN
    write(0,0,0,0,"Text contained in <string1>:");
    write(0,0,10,0,string1);
    write(0,0,192,0,"Press [SPACE] to add a text to <string1>");
    LOOP
        IF (key(_space))

            strcat(string1,"Final"); // Adds a text to string1

        END
        FRAME;
   END
END
{-}

{/}

When the length of the resultant string is smaller than 1024 characters, this same
operation can be achieved with the following statement :
(continuing with the previous example):

  {string1 = string1 + "Final";}

  (or)

  {string1 += "Final";}

Or with a generic statement of {#1019,assignation} (or with the symbol
{#1058,+=}, of operative assignation) such as the following:

  {<string destination> = <string destination> + <string origin> ;}

  (or)

  {<string destination> += <string origin> ;}

Being always {<string destination>} of data type {#1406,STRING}.

{/}

To copy text strings, the function {#202,strcpy()} must be used.

To separate (or substrate) text strings, the function {#211,strdel()}
must be used.

{/}See: {#202,strcpy()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.204,strlen()}

{strlen(}<text string>{)}

{Returns:}

The length of the string, in characters (with spaces included).

{Description:}

Counts the number of characters of the text given as a parameter, or contained
currently in the passed string.

The {<text string>} can be a literal (text between quotation marks) or data of
any other type.

{#9999,Example program:}
PROGRAM example_strlen;

GLOBAL
    STRING string1="Text example";
    length_string1;

BEGIN
    write(0,0,0,0,"Text contained in <string1>:");
    write(0,0,10,0,string1);
    write(0,0,20,0,"Length of <string1>:");

    length_string1=strlen(string1); // calculates the length

    write_int(0,0,30,0,OFFSET length_string1);
    LOOP
        FRAME;
    END
END
{-}

{/}

A character or string can be added to another string with the function {#203,strcat()}, or
with a statement of {#1019,assignation} such as the following:

  {string1+="a";}

To remove characters of a string use {#211,strdel()}, although it
is possible to eliminate characters at the end of a string with statements
such as the following:

  {string1--;}ú
  {string1-=1;}ú
  {string1=string1-1;}ú

{/}See: {#202,strcpy()} - {#203,strcat()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.205,strcmp()}

{strcmp(}<string1>{,} <string2>{)}

{Returns:}

{ +n} - If the first string is bigger than the second.ú
{  0} - If the strings are identical.ú
{ -n} - If the first string is smaller than the second.ú

{Description:}

Compares two text strings, character per character, giving back {0} when
both strings are identical.

{#9999,Example program:}
PROGRAM example_strcmp;

GLOBAL
    STRING mystring;

BEGIN
    // ...

    IF (strcmp(mystring,"abc")==0)

        // The two strings are identical ...

    END

    // ...
END
{-}

{/}

if the strings have less than 1024 characters, the comparison of strings can also be
done with the typical operators of comparison.

For example, the comparison of the previous example could be done with the
following statement:

  {IF (mystring=="abc")}ú
  {//...}ú
  {END}ú

In the same way, the symbol {#1046,<>} can be used to compare if the two strings
are different, with the symbols {#1069,<} or {#1072,<=} if a string is smaller,
or identical to another, etc.

{/}

To search for a string inside another (to see if it is contained in it), the 
function {#207,strstr()}, must be used, and to see if a string contains a specific character
the function {#206,strchr()} must be used.

{/}See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.206,strchr()}

{strchr(}<text string>{,} <characters>{)}

{Returns:}

 { -1} If none of the characters were found inside of the string.ú
 { +n} If one of the characters was found in the position {n} of the string.

{Description:}

Searches for one or some {<characters>} in a {<text string>}. It receives the
string as first parameter and, as the second, one or more characters in a 
literal (between quotation marks).

This function will determine if the string contains any of the characters and,
if so, will indicate at which position inside the string (from 0) the character appears. 
In the character appears on more than one occasion, the function
will always return the first position the character occurred.

{#9999,Example program:}
PROGRAM example_strchr;

GLOBAL
    STRING mystring="FGHIJK";
    position;

BEGIN
    write(0,0,0,0,"First vowel of <mystring> is in position:");

    position=strchr(mystring,"AEIOU");

    write_int(0,0,10,0,OFFSET position);
    LOOP
        FRAME;
    END
END
{-}

In this example the function {strchr()} is used to determinate the first vowel
of {mystring} is the position {3} of the string.

{/}

The characters of a data of {#1406,STRING} can be accessed always as if this would
be a table of characters. For example, to change in the data {mystring} of the
previous example, the character "I" for a character "-" the following statement
could be used:

  {mystring[3]=char("-");}

To convert a character, contained in a literal, in its ordinal value (ASCII)
the function {#184,char()} is used.

{/}

To determinate if a string is completely contained in another (if appears as
a substring inside of the same), the function {#207,strstr()} must be used.

{/}See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#205,strcmp()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.207,strstr()}

{strstr(}<string of text>{,} <substring>{)}

{Returns:}

 { -1} If the substring wasn't found inside of the string.ú
 { +n} If it was found in the position {n} of the text string.

{Description:}

Searches for the sequence of characters contained in the {<substring>} in a
{<text string>}.

This function will determine if a text string contains the substring (as "HOUSE"
contains "USE") and, if so, will indicate whereabouts the substring appears inside
of the string (from 0, 1 in the previous example).
If the substring on more than one occasion, the function will return
the position where the string first occurred.

{#9999,Example program:}
PROGRAM example_strstr;

GLOBAL
    STRING mystring="This is an example string.";
    position;

BEGIN

    position=strstr(mystring,"an");

    write_int(0,0,10,0,OFFSET position);
    LOOP
        FRAME;
    END
END
{-}

In this example the function {strstr()} is used to determine where 
the substring {"is"} is found inside {mystring}, it will return the position {8}.

{/}

To change from capital letters to small letters
the functions {#209,upper()} and {#210,lower()} can be used.

{/}

To determine if a string contains a character, the function
{#206,strchr()} must be used, which, allows you to search for
 any character inside the specified group simultaneously.

{/}See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#208,strset()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.208,strset()}

{strset(}<text string>{,} <character>{)}

{Description:}

Assigns to every position of the {<string>} the {<character>} indicated as
the second parameter.

The function can receive the {<character>} in two ways; as a literal (the
character between quotation marks), or as its ordinal (its ASCII value) which must be
a value between {0} and {255}.

The complete string will be replaced with this character. The length of the string
depends on the indicated value between "[]" in its initiation, if the function doesn't
know the length of the data of type {#1406,STRING}, a string of
{256} characters will be created (from the position 0 to 255).

{#9999,Example program:}
PROGRAM example_strset;

GLOBAL
    STRING mystring="This is an example string.";

BEGIN
    write(0,0,0,0,"content of <mystring> (press space to change it):");
    write(0,0,10,0,mystring);
    LOOP
        IF (key(_space))

            strset(mystring,"*"); // Fills up the string with "*"

        END
        FRAME;
    END
END
{-}

{/}

To calculate the current length of a string, the function {#204,strlen()} will be used.

To delete characters from a string (from the beginning and from the end) the function
{#211,strdel()} must be used.

{/}See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#209,upper()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.209,upper()}

{upper(}<string or character>{)}

{Returns:}

If a character was a small letter (lowercase), it returns the
same character but as a capital letter (uppercase).

{Description:}

converts a string (or just a character) to capital letters, including the special
characters, like the letter "ñ" or the accentuated vowels.

This function works in one of two ways, depending on the parameter it receives:

- If it receives a text string (or literal between quotation marks), it will convert to
capital letters every contained character in the string and won't return
any significant value (just the cursor of the receipt string).

- If it receives just one character (its ordinal value or ASCII value), it will return the
character converted into a capital letter (but just its ordinal value), and the function
will not change any data in memory.

{#9999,Example program:}
PROGRAM example_upper;

GLOBAL
    STRING mystring="This is an example string.";
    STRING myletter="a";

BEGIN

    upper(mystring); // converts a string to capital letters
    upper(myletter);  // converts a character to capital letters

    write(0,0,0,0,mystring);
    write(0,0,10,0,OFFSET myletter);
    LOOP
        FRAME;
    END
END
{-}

This example has defined two global data ({mystring} and {myletter}), the
function {upper()} will be used to convert it to capital letters, and then
it will be shown on screen.

{/}

This function will not modify those characters which are not small (lowercase) letters.

{/}

The function {#210,lower()} is the opposite to {upper()}, because it can converts
a string (or a character) to small (lowercase) letters.

{/}See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#210,lower()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.210,lower()}

{lower(}<string or character>{)}

{Returns:}

If a character is given to a capital letter (uppercase), it returns the
character changed to a small letter (lowercase).

{Description:}

Converts a string (or a simple character) into small letters, including the
special characters, like the letter "ñ" or the accented vowels.

This function can work in one of two modes, depending on the parameter given:

- If it receives a text string (or literal between quotation marks), it will change into
small letters every character contained in the string and will not return any
significative value (just the cursor of the string given).

- If it receives just a character (its ordinal value or ASCII), it will return
the character changed into a small letter (its ordinal value), and the
function won't change any data in memory.

{#9999,Example program:}
PROGRAM example_lower;

GLOBAL
    STRING mystring="THIS IS AN EXAMPLE STRING";
    STRING   myletter="A";

BEGIN

    lower(mystring); // Changes a string into small letters
    lower(myletter);  // Changes a character into small letters

    write(0,0,0,0,mystring);
    write(0,0,10,0,OFFSET myletter);
    LOOP
        FRAME;
    END
END
{-}

This example has defined two global data ({mystring} and {myletter}), the 
function {lower()} will be used to convert them into small letters, and
then will be shown on screen.

{/}

This function won't modify those characters which are not capital letters.

{/}

The function {#209,upper()} is the opposite to {lower()}, because it changes
a string (or a character) into capital letters.

{/}See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#211,strdel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.211,strdel()}

{strdel(}<string of text>{,} <initial subtraction>{,} <final subtraction>{)}

{Description:}

This function deletes characters from a {<string of text>}. Characters Will be eliminated
{<initial subtraction>} from the beginning of the string and characters {<final subtraction>}
from the end of it.

To eliminate just characters from the beginning of the string you must indicate
{0} as the {<final subtraction>}, and to eliminate just from the end, set {0} as {<initial
subtraction>}.

{#9999,Example program:}
PROGRAM example_strdel;

GLOBAL
    STRING mystring="This is an example string.";

BEGIN

    strdel(mystring,5,9);

    write(0,0,0,0,mystring);
    LOOP
        FRAME;
    END
END
{-}

This example uses the function {strdel()} to eliminate the first {5}
characters of {<mystring>} and the last {9}, and then, show the resultant string
on screen ("is an examp").

{/}

{Note:} If the quantity of characters to delete is negative (for the beginning or
for the end), the function will add spaces to the string.

{/}

It is also possible to eliminate characters from the end of a string with statements
such as the following:

  {string1--;}ú
  {string1-=1;}ú
  {string1=string1-1;}ú

{/}See: {#202,strcpy()} - {#203,strcat()} - {#204,strlen()} - {#205,strcmp()} - {#206,strchr()}
- {#207,strstr()} - {#208,strset()} - {#209,upper()} - {#210,lower()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.212,screen_copy()}

{screen_copy(}<region>{,} <file>{,} <graphic>{,} <x>{,} <y>{,} <width>{,} <height>{)}

{Description:}

Copies a screen region to a region of any graphic.

This is a potent function that can be very useful, because it gives
"feedback" from the computer screen, and can send an image of the screen to a graphic
(opposite operation to the normal).

First you must define the number of the rectangular {<region>} which is going to be
copied from the screen (of the previous image of the program), these regions are defined
with the function {#106,define_region()}. The {region number 0} is always related to
the entire screen.

Then, the graphic where the image is going to be transferred to must be indicated 
with the parameters {<file>} and {<graphic>} (the file will be the number 0, if the
graphic belongs to the first FPG loaded, or if it has been loaded already).

Finally,  {the zone inside of the graphic} the image must be transferred to will be defined.
This will be defined as {<x>}, {<y>}, {<width>} and {<height>}, related
to the coordinates inside of the graphic (being the coordinates [0,0] its upper left
corner).

{#9999,Example program:}
PROGRAM example_screen_copy;

GLOBAL
    angle1;
    angle2;

BEGIN
    load_fpg("help/help.fpg");
    graph=2;
    x=160;
    y=100;
    put(0,graph,x,y);
    LOOP

        // Copies the screen (region 0) to the graphic 2

        screen_copy(0,0,2,0,0,320,200);

        angle1+=1000;
        angle2+=1971;
        angle=get_distx(angle1,25000);
        size=95+get_disty(angle2,30);
        FRAME;
    END
END
{-}

In this example the file help.fpg is loaded, in which the {graphic number 2} is
a cell of different colours, and is placed on the screen and defined as the graphic
of the main process, which will rotate and change its size
(depending on the {angle} and {angle2}, respectively).

Then the function {screen_copy()} is used again to send the updated
image of the screen to this graphic, so this effect happens.

{/}

{Note:} The {size} of the screen region (the transferred zone) and the size of the
graphic region (where it's transferred) {doesn't have to match}. The function
{screen_copy()} will do a {reduction} or {ampliation} when needed to adjust
the size of the transferred zone.

{/}See: {#106,define_region()} - {#103,clear_screen()} - {#1126,graph}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.213,qsort()}

{qsort(}<structure name>{,} <field name>{,} <mode>{)}

{Description:}

Orders or shuffles one of the fields of a program structure .

It is a simple but useful function which allows the quick
ordering and shuffling of data structures.

Its use is very simple, all is required is the {<name of the structure>},
the one of the {<field which is going to be used as index>}, and the {<ordination mode>};
one of the indicated now:

{0} - Ascendent ordination (from min to max).

{1} - Descendent ordination (from max to min).

{2} - Random ordering (shuffling)

Any of the data contained in the structure can be used as the index field, without
depending on if it is numeric data or a string of text (in which case it will be
ordered alphabetically)

{#9999,Example program:}
PROGRAM example_qsort;

GLOBAL

  STRUCT mystructure[9];
    STRING name[32];
    points;
    x,y;
  END

BEGIN

  //...

  // Orders the registers of mystructure, the one with the biggest
  // score being placed at the beginning

  qsort(mystructure,points, 1);

  //...

END
{-}

This example shows the easy use of the function {qsort()} to order
a structure, that can represent any type of object inside of a
program.

It is not necessary that the field used as index ({points} in this case)
is the first field of the structure.

{/}

{Note:} The shuffling of a structure requires a field which makes 
differences between the different registers of the same. This operation can be
useful to give "randomness" to a program (for example, to "mix" or "shuffle"
a deck of cards).

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.214,load_song()}

{load_song(}<name of file>{,} <replay>{)}

{Returns:}

Identifier of the loaded song, or -1 if an error occurs.

{Description:}

Loads a song from an file MOD, S3M or XM, to its later reproduction.

The function requires the name of the file which contains the music module,
and if this one must be played back just once (indicating {0} in {<replay>}) or
indefinitely (indicating {1}).

These music modules can be composed with multiple shareware programs
or freeware programs. In DIV Games Studio these music modules can be played back, in the created programs,
but you cannot compose new modules.

{#9999,Example program:}
PROGRAM example_load_song;

GLOBAL
    id_song;

BEGIN

    load_song("help/help.xm",1); // Loads an XM module, with replay

    song(id_song);
    write(0,0,0,0,"Press ESC to finish");
    REPEAT
        FRAME;
    UNTIL (key(_ESC));
    unload_song(id_song);
END
{-}

This example loads the module contained in the file {help.xm} with the
function {load_song()}, indicating that this one must be played back indefinitely.
The reproduction of the file is begun with a call to the function {#216,song()}.

To delete a song from memory, the function {#215,unload_song()} must be used.

The sound volume of the song can be controlled with the function {#178,set_volume()} 
and the data contained in the {#1104,setup structure}.

{/}

{Note:} With this version of DIV Games Studio comes included some files of freeware 
music modules in the directory {MOD}.

{/}

{Note:} To reproduce songs contained in a CD-Audio track the functions
{#144,play_cd()} and {#164,stop_cd()} must be used.

{/}See: {#215,unload_song()} - {#216,song()} - {#144,play_cd()} - {#1104,Setup structure}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.215,unload_song()}

{unload_song(}<identifier of the module>{)}

{Description:}

Deletes from memory the music module whose identifier is given as the
parameter. This {<identifier of the module>} is the value which the
function returns  {#214,load_song()} when is loaded into memory.

After deleting a module {you must be very cautious}
not to use it again in the program, otherwise the program would crash.

{It is not necessary to delete the modules} before finishing the program
because the system will do it automatically.
So, just delete from memory the modules which are not going to be
used for the time being in order to liberate computer memory to load
other resources (other files of graphics, sounds, fonts, etc).

{#9999,Example program:}
PROGRAM example_unload_song;

GLOBAL
    id_song;

BEGIN
    load_song("help/help.xm",1);
    song(id_song);
    write(0,0,0,0,"Press ESC to finish");
    REPEAT
        FRAME;
    UNTIL (key(_ESC));

    unload_song(id_song); // Sets free the filled memory by the module

END
{-}

This example loads the module contained in the file {help.xm} with the
function {#214,load_song()}. The playback of the file is indicated with a
call to the function {#216,song()}.

The program will continue to play this module until the {ESC} key is pressed,
the module is then deleted from memory with the function {unload_song()},
indicating as the parameter {id_song} which contains the {identifier of the module}
returned when loaded.

{/}

{Note:} songs that are CD-Audio tracks, which can be played with
 the function {#144,play_cd()}, don't use up computer memory,
so they cannot be deleted with the function {unload_song()}.

{/}See: {#214,load_song()} - {#216,song()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.216,song()}

{song(}<identifier of the module>{)}

{Description:}

Starts playback of a music module loaded with the function
{#214,load_song()}. The function will receive as its only parameter the {<identifier
of the module>} to play back.

Just one module can be played at the same time, if another starts, the previous module
will stop. But a music module, a CD-Audio track (see {#144,play_cd()}) and multiple 
sound effects (see {#159,sound()}) can be played at the same time .

The playback will always begin from the start of the module (the beginning
of the song). To play a specific part of the module then use the function
{#218,set_song_pos()}, which sets the position from where playback of the module
will start.

{#9999,Example program:}
PROGRAM example_song;

GLOBAL
    id_song;

BEGIN
    load_song("help/help.xm",1);

    song(id_song); // Starts the reproduction of the music module

    write(0,0,0,0,"Press ESC to finish");
    REPEAT
        FRAME;
    UNTIL (key(_ESC));
    unload_song(id_song);
END
{-}

This example loads the module contained in the file {help.xm} with the
function {#214,load_song()}, indicating that this must be played
indefinitely (this must be indicated in the file's load).

Then the playback of the file begins with the function {song()}.

The program will then enter a loop in which this module will still be playing, 
until the {ESC} key is pressed and the program finishes.

The sound volume of playback can be controlled with the function
{#178,set_volume()} and the contained data in the {#1104,setup structure}.

{/}

{Note:} To finish the playback of a music module the function
{#217,stop_song()} must be used.

{/}

{Note:} The function {#222,is_playing_song()} can find if the module is being currently
played.


{/}See: {#214,load_song()} - {#217,stop_song()} - {#144,play_cd()} - {#159,sound()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.217,stop_song()}

{stop_song(}{)}

{Description:}

Stops the playback of the music module (MOD, S3M or XM) which is being played.
This function doesn't require any parameter, because only one music module can be
played at the same time.

It is not essential to stop the playback of a music module before being
deleted from memory (an operation made with the function {#215,unload_song()}), 
this is done automatically.

{#9999,Example program:}
PROGRAM example_stop_song;

GLOBAL
    id_song;

BEGIN
    load_song("help/help.xm",1);
    song(id_song);
    write(0,0,0,0,"Press SPACE to stop the song ...");
    LOOP
        IF (key(_space))

            stop_song(); // Stops the module

        END
        FRAME;
    END
    unload_song(id_song);
END
{-}

This example loads the module contained in the file {help.xm} with the
function {#214,load_song()}. The playback of the file begins with a
call to the function {#216,song()}.

The program will then enter into a loop in which this module will still be playing,
when the space bar is pressed it makes a call to the function {stop_song()}
and the module finishes.

To delete a song from memory the function {#215,unload_song()} must be used, 
all the programs created in DIV Games Studio will free any
filled memory automatically at the end.

{/}

{Note:} To stop a song of CD-Audio the function {#164,stop_cd()} is used, and for
a sound effect, use the function {#167,stop_sound()}.

{/}

{Note:} The function {#222,is_playing_song()} can find out if a module is playing.

{/}See: {#216,song()} - {#214,load_song()} - {#144,play_cd()} - {#159,sound()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.218,set_song_pos()}

{set_song_pos(}<position of the module>{)}

{Description:}

Fixes the position of the music module playback (the "pattern" number).

This {<position of the module>} is a number between 0 and the max number of
{pattern} of the module. This value varies for each module, and can be defined in the
programs used to compose them. The modules usually have quite a variable number of 
patterns, though the average is usually situated between 30 and 40.

Inside each pattern, the modules have a determined number of lines
(normally 64), in which appear the musical notes, so each pattern could be
defined as a small section of the music module.

To obtain the current position which is being played back the function
{#219,get_song_pos()} is used.

The position of the module can be changed if the module is playing or has stopped.
This function can be used to advance or to retard the playback of the module,
to implement diverse loops in certain parts of a module, etc.

{#9999,Example program:}
PROGRAM example_set_song_pos;

GLOBAL
    id_song;
    position_module;

BEGIN
    load_song("help/help.xm",1);
    song(id_song);
    write(0,0,0,0,"Press SPACE to change the position of the module ...");
    write(0,0,20,0,"position:");
    write_int(0,0,30,0,OFFSET position_module);
    LOOP
        IF (key(_space))
            position_module=rand(0,19);

            set_song_pos(position_module); // Changes the position of the module

        END
        position_module=get_song_pos();
        FRAME;
    END
END
{-}

This program loads the module contained in the file {help.xm} and then
starts its playback with the function {#216,song()}.

>From this moment the current position of the module will be shown on screen
and it can be changed by pressing the space bar (a random position will be assigned
between 0 and 19, because this module has 20 patterns).

{/}

{Note:} The playback line of a module can't be set (inside
each pattern), but the value can be obtained with the function {#220,get_song_line()}.

{/}See: {#219,get_song_pos()} - {#216,song()} - {#214,load_song()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.219,get_song_pos()}

{get_song_pos(}{)}

{Returns:}

The current position of the musical module which is being played.

{Description:}

Returns the current position of playback of the musical module, this
position can be set with the function {#218,set_song_pos()}.

This {<position of the module>} is a number between 0 and the max number of
{pattern} of the module. This value is different for each module, and is defined
in the programs used to compose them. The modules can have any variable number of
patterns, although the average is between 30 and 40.

Inside each pattern the modules have a determined number of lines
(normally 64), in which appear the musical notes, therefore
each pattern can be defined as a small section of the musical module.

{#9999,Example program:}
PROGRAM example_get_song_pos;

GLOBAL
    id_song;
    position_module;

BEGIN
    load_song("help/help.xm",1);
    song(id_song);
    write(0,0,0,0,"Position of the module:");
    write_int(0,0,10,0,OFFSET position_module);
    LOOP

        position_module=get_song_pos(); // Obtain the position

        FRAME;
    END
END
{-}

This program loads the module contained in the file {help.xm} and then
initiates its playback with the function {#216,song()}.

>From this moment the current position of the module on screen will be shown,
obtained with the function {get_song_pos()}.

{/}

{Note:} the line number which is played back Can be obtained, inside the pattern,
with the function {#220,get_song_line()}.

{/}See: {#220,get_song_line()} - {#218,set_song_pos()} - {#216,song()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.220,get_song_line()}

{get_song_line(}{)}

{Returns:}

The line number of the musical module.

{Description:}

The line number of a musical module playing can be obtained With this function.

This current position, or pattern, can be obtained with the function
{#219,get_song_pos()}.

Inside each pattern the modules have a determined number of lines
(normally 64), in which appear musical notes. The modules
often have a different number of patterns, although the average is between 30 and 40.

{#9999,Example program:}
PROGRAM example_get_song_line;

GLOBAL
    id_song;
    line_module;

BEGIN
    load_song("help/help.xm",1);
    song(id_song);
    write(0,0,0,0,"Line of module:");
    write_int(0,0,10,0,OFFSET line_module);
    LOOP

        line_module=get_song_line(); // Obtain the number of line

        FRAME;
    END
END
{-}

This program loads the module contained in the file {help.xm} and then
initiates its playback with the function {#216,song()}.

From this moment the current line of the module is shown on screen,
obtained with the function {get_song_line()}.

{/}

{Note:} The line of a musical module Cannot be set, although it is possible to fix
the position where playback begins with the function {#218,set_song_pos()}
(always will begin from the line 0 of the pattern).

{/}See: #219,get_song_pos()} - {#218,set_song_pos()} - {#216,song()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.221,is_playing_sound()}

{is_playing_sound(}<number of channel>{)}

{Returns:}

{0} - If the channel is stopped.ú
{1} - If is going the sound by the channel.

{Description:}

This function allows you to know if one of the {sound channels} are playing sound or if it is disposed.

the {<number of channel>} is required as the parameter, this value is obtained as the 
return of the function {#159,sound()} after initiating the playback of the sound effect.

{#9999,Example program:}
PROGRAM example_is_playing_sound;

GLOBAL
    sound_id;
    channel_id;

BEGIN
    write(0,0,0,0,"Press ESC to finish.");
    sound_id = load_sound("help/help.pcm",0);
    channel_id  = sound(sound_id, 256, rand(100,400));
    REPEAT

        // If the playback has finished, return the sound

        IF (NOT is_playing_sound(channel_id))

            channel_id = sound(sound_id, 256, rand(100,400));
        END
        FRAME;
    UNTIL (key(_ESC));
END
{-}

This example uses a function to continually test and restart the sound, 
controlled by the program, instead of automatically as is often 
indicated in the loading of a sound using the {#134,load_sound()} function.

The playback again always initiates once the sound channel is free,
it means, each time when playback of the sound has finished.

The program uses this circumstance (manual control of the replay)
to emit the sound with a different frequency in each case, this couldn't be done
with the automatic replay. This frequency is obtained as
a value between 100 and 400 with the function {#149,rand()}.

{/}

{Note:} The same sound can be played back by different channels each time,
therefore it is necessary to save the channel number each time when the playback is initiated.

{/}See: {#159,sound()} - {#102,change_sound()} - {#222,is_playing_song()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.222,is_playing_song()}

{is_playing_song(}{)}

{Returns:}

{0} - Any module is playing.ú
{1} - Is playing a musical module.

{Description:}

This function determines if a digital musical module of the file MOD,
S3M or XM is being played.

These modules must be loaded with the function {#214,load_song()} and their
playback is initiated with the call to {#216,song()}.

Only one module can be played back at the same time, therefore this function
doesn't require any parameter, only returns {1} if there is one module
reproducing.

{#9999,Example program:}
PROGRAM example_is_playing_song;

GLOBAL
    id_song;
    sounding;

BEGIN
    load_song("help/help.xm",1);
    song(id_song);
    write(0,0,0,0,"ENTER initiate the module / SPACE to stop it");
    write_int(0,0,10,0,OFFSET sounding);
    LOOP
        IF (key(_enter)) song(id_song); END
        IF (key(_space)) stop_song(); END

        sounding = is_playing_song(); // Determines if is playing

        FRAME;
    END
END
{-}

This example loads musical module contained in the file {help.xm} and
permits, inside one loop, initiate it with the key {ENTER} and stop it with
the space bar.

Inside the same loop is used the function {is_playing_song()} to
determine if it is playing each moment.

{/}

{Note:} To finish the playback of one musical module must be used the function {#217,stop_song()}.

{/}See: {#214,load_song()} - {#216,song()} - {#221,is_playing_sound()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.223,fopen()}

{fopen(}<name of file>{,} <mode>{)}

{Returns:}

The {handle} or identifier of the open file, or {0} if an error was produced.

{Description:}

Opens a data file to read or write to, with the help of a {handle} or {identifier of file}
which this function returns from the open or created file.

the {<name of file>} to open or create is required , and the {<mode>} of opening,
which must be a literal (text in inverted commas) inside the following:

 "{r}" - Open the file for reading of the data contained in it.

 "{w}" - Create the file to write (if it already exists, it will lose the presently contained data).

 "{a}" - Open the file to write to after finishing with it, or it creates the file if it didn't exist.

 "{r+}" - Open an existent file to activate it, permitting reading and writing.

 "{w+}" - Create a file to write to, permitting also its reading.

 "{a+}" - Open an file to read it from any position and write new data to add on the end.

Once an file is opened, you can use all the functions for files
based in {handles}, but once the necessary operations have been completed 
in the file {must not be closed}, you should then close it with the function {#224,fclose()}.

The main functions are {#225,fread()} for reading the data inside
the file and {#226,fwrite()} to write the data; it is important to
open the file in the appropriate {mode} for the requested operations.
For example, you cannot write in the file if it was opened only for reading.

{#9999,Example program:}
PROGRAM example_fopen;

GLOBAL
    list1[3]=11,22,33,44;
    list2[3];
    myhandle;

BEGIN

    myhandle=fopen("help/help.dat","w"); // Open file to write

    fwrite(OFFSET list1,4,myhandle);
    fclose(myhandle);

    myhandle=fopen("help/help.dat","r"); // Open file to read

    fread(OFFSET list2,4,myhandle);
    fclose(myhandle);
END
{-}

This example program has defined two global lists; {list1} with four values
initiated in 11, 22, 33 and 44, and {list2} with four without initiates (zero).

The functions of files are used to write in one file the content
of the {list1} and then load it over the {list2}. After finishing the program,
the data of the first list will have been copied into the second.

the function {fopen()} is called on two occasions, the first to {create it and
write} in it and the second to {open it and read} its contents.

It is important to underline that each time when you open or create the file, you must
close it with the function {#224,fclose()} (can be seen how in the example
the file is closed on two occasions).

{/}

The function {#227,fseek()} allows you to situate the {pointer of reading/writing}
at any position in the file. In this way, data at any point of the file 
can be read or written.

{/}

The function {#230,flush()} empties the buffers of writing and allows you also
to check how many files are open at any moment.

{/}

{Note:} The functions {#155,save()} and {#130,load()} allow you also
to save the data in files of the disk and restore them. These functions are
less useful, but their use is easier than
the functions based in {handles} here described.

{/}See: {#224,fclose()} {#225,fread()} - {#226,fwrite()} - {#155,save()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.224,fclose()}

{fclose(}<handle>{)}

{Returns:}

Number of closed files.

{Description:}

Closes an file opened with the function {#223,fopen()}, fclose must 
receive as parameter the {handle} or {identifier of file} returned
by this function.

In the second modality, the function {fclose()} can {close all opened
files} at one time, for this you indicate {0}
(zero) as its parameter, instead of {handle}.

Anyway, the function returns the number of files which were closed,
if it returns {0} it can mean one of these cases:

{ -} There was no open file.ú
{ -} The passed {handle} doesn't correspond to any opened file.
{ -} The file corresponding to this {handle} was already closed.

All open files must be closed before the program finishes its execution.

{#9999,Example program:}
PROGRAM example_fclose;

GLOBAL
    list1[3]=11,22,33,44;
    list2[3];
    myhandle;

BEGIN
    myhandle=fopen("help/help.dat","w");
    fwrite(OFFSET list1,4,myhandle);

    fclose(myhandle); // The file closes to be opened in other mode

    myhandle=fopen("help/help.dat","r");
    fread(OFFSET list2,4,myhandle);

    fclose(myhandle); // The file closes definitively
END
{-}

the functions of files Are used to write in one file the content
of the {list1} and then copy it over the {list2}. After finishing the program,
the data of the first will have been copied into the second.

If the open file in one mode (with the function {#223,fopen()}) wants to
access an file in a different mode, you must first close the file before opening it
in the new mode; in the example, the file of writing is then closed to open
it then in reading mode.

{/}

The function {#230,flush()} empties the buffers of writing and permits you also to 
check how many files are open at any moment.

{/}See also: {#223,fopen()} {#225,fread()} - {#226,fwrite()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.225,fread()}

{fread(}<OFFSET data>{,} <length>{,} <handle>{)}

{Returns:}

{0} - If an error was produced , or all asked data was not read .ú
{1} - If all data was read.

{Description:}

This function permits you to read the data of an file opened with the function
{#223,fopen()}, starting from the position indicated by the {pointer of
reading/writing}.

The file must be opened in the {reading mode}, or a mode which it permits
reading of data.

The {pointer} is situated at the beginning of the file, after it has been opened,
and advances sequentially during the reading of the data. But
this pointer can be situated in any position, using the function {#227,fseek()}
and the function {#228,ftell()} allows you to obtain the current
position of the pointer of an file.

The function {fread()} requires as a parameter the {<}{#1085,OFFSET}
{of the data>} in which must the data of file be read , it means,
the memory address from where must be placed the data which are reading from the file.

As second parameter is required the {<length>} or total size of the data
which you want to read, it means, the number of positions of memory
which occupy these data. The length of one data can be obtained with the
function {#1094,sizeof()}.

The last parameter must be the {handle} or {identifier of file} which
was obtained after open the file as value of return of {#223,fopen()}.

{#9999,Example program:}
PROGRAM example_fread;

GLOBAL
    list1[3]=11,22,33,44;
    list2[3];
    myhandle;

BEGIN
    myhandle=fopen("help/help.dat","w");
    fwrite(OFFSET list1,4,myhandle);
    fclose(myhandle);
    myhandle=fopen("help/help.dat","r");

    fread(OFFSET list2,4,myhandle); // Read the file about <list2>

    fclose(myhandle);
END
{-}

This example program has defined two global lists; {list1} with four
values initiated as 11, 22, 33 & 44, and {list2} with four without initiate
(all zero).

The file functions are used to write in one file the content
of the {list1} and then copy it over the {list2}. After finishing the program,
the data of the first list will have been copied into the second.

The function {#223,fopen()} is called on two occasions, the first to {create it and
write} in it and the second to {open it and read} its contents.

It is important to underline that each time you open or create the file, you must
close it with the function {#224,fclose()} (in the example
the file is closed on two occasions).

{/}

The inverse function to {fread()}, which permits you to write data in
an file instead of read it, is {#226,fwrite()}. The way to use this
function and its parameters are similar to those of {fread()}.

{/}

{Note:} By default, the {<length>} is specified as the number of simple data,
remembering that a simple data (a variable) occupies {4
bytes}. So for example, if ten data (indicating 10 as
length)are read, these date will occupy 40 bytes of memory.

This relation can be changed by modifying the global variable {#1420,drive_size},
which has a default value of {4} in all programs.

{/}See: {#223,fopen()} - {#226,fwrite()} - {#227,fseek()} - {#1420,drive_size}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.226,fwrite()}

{fwrite(}<OFFSET data>{,} <length>{,} <handle>{)}

{Returns:}

{0} - If an error was produced or the data was not successfully written.ú
{1} - If all the data was written.

{Description:}

This function allows you to write data into an file opened with the function
{#223,fopen()}, starting from the position indicated by the {cursor of reading/writing}.

The file must have been opened in a {write mode}.

The {cursor} is placed at the beginning of the file, when opened or created, 
and advances sequentially as the data is written.
But this cursor can be placed in any position of the file 
using the function {#227,fseek()} and the function {#228,ftell()} allows you to
obtain the current position of an file cursor.

The function {fwrite()} requires as its first parameter the {<}{#1085,OFFSET}
{of the data>} which must be written in the file, so, the address of memory.

As second parameter is required the {<length>} or total size of the
data which are wanted to be written, the number of memory positions
which fill these data. The length of a data can be obtained with the
function {#1094,sizeof()}.

The last parameter must be the {handle} or {identifier of file} which
was obtained when the file was opened as return value of {#223,fopen()}.

{#9999,Example program:}
PROGRAM example_fwrite;

GLOBAL
    mytable[3]=11,22,33,44;
    myhandle;

BEGIN
    myhandle=fopen("help/help.dat","w");

    fwrite(OFFSET mytable,4,myhandle); // Writes <mytable> in the file

    fclose(myhandle);
END
{-}

This example program writes the contained data in {<mytable>} in the file
{help.dat} of the disk.

The function {#223,fopen()} is called to create it and to the function {#224,fclose()}
to close it once every data has been written.

{/}

The opposite function to {fwrite()},that allows to read data in
an file instead of write to it, is {#225,fread()}. The way to use this function
and its parameters is the same as{fwrite()}.

{/}

{Note:} By default, the {<length>} is specified as the number of simple data
assuming that a simple data (a variable) fills {4 bytes} of memory. So, if for example, 
ten data are written (indicating 10 as length), then 40 bytes of data will be written.

This relation can be changed by modifying the global variable {#1420,drive_size},
which, by default is {4} in every program.

{/}See: {#223,fopen()} - {#225,fread()} - {#227,fseek()} - {#1420,drive_size}


# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.227,fseek()}

{fseek(}<handle>{,} <cursor position>{,} <mode>{)}

{Description:}

Places the {cursor of reading/writing} of an file at the indicated position.

The function requires, first, the {<handle>} or {identifier of the file}
returned by the function {#223,fopen()} when opened.

Then the new position where the {<cursor>} of the file must be placed is defined.
Now every future reading or writing operation which is done, will be from this position.

As a last parameter the {<mode>} in which the new position of the cursor 
must be specified is indicated, can be one of the following three modes:

 {seek_set} - Position is in relation to the beginning of the file (0).ú
 {seek_cur} - Increment related to the current position (1).ú
 {seek_end} - Position is in relation to the end of the file (2).ú

To obtain the current situation of an file cursor, the function
{#228,ftell()} must be used.

Every reading or writing operation of an file is done automatically, 
so all these access functions are called sequentially (reading or
writing the data one after another).

{#9999,Example program:}
PROGRAM example_fseek;

GLOBAL
    mytable[3]=11,22,33,44;
    mydata;
    myhandle;

BEGIN
    myhandle=fopen("help/help.dat","w");
    fwrite(OFFSET mytable,4,myhandle);
    fclose(myhandle);
    myhandle=fopen("help/help.dat","r");

    // Places the cursor to read the fourth data of the file (44)

    fseek(myhandle,3,seek_set);

    fread(OFFSET mydata,1,myhandle);
    fclose(myhandle);
END
{-}

This example writes the four data items contained in {mytable} (11,22,33 and 44)
in the file {help.dat}, and then, opens the file for reading and uses
the function {fseek()} to place the cursor in the {position 3} from the
beginning of the file (with {seek_set}).

>Then you can read from the fourth data item of the file, so that,
when a value is read in the variable {mydata} this will be {44},
the fourth value of the table.

{/}

{Note:} By default, the {<position of the cursor>} is specified as a
number of simple data items, assuming that a simple data (a variable)
fills {4 bytes} of memory. If, for example, the cursor is placed in the tenth position
from the beginning of the file, then the program can access the data 
from the fortieth byte.

This relation can be changed, by modifying the global variable {#1420,drive_size},
which by default is {4} for every program.

{/}See: {#228,ftell()} - {#225,fread()} - {#226,fwrite()} - {#1420,drive_size}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.228,ftell()}

{ftell(}<handle>{)}

{Returns:}

The current position of the cursor of reading/writing in an file.

{Description:}

Returns the position of the {reading/writing cursor} in an file, for which,
the only parameter required is the {<handle>} or {identifier of file} returned by the
function {#223,fopen()} when the file was opened.

To establish a new position for an file cursor, the function {#227,fseek()}
must be used. In contrast, the function, {ftell()} always returns
the position of the cursor, related to the beginning of the file.

Every reading or writing operation of an file
automatically moves the cursor forward, so every access is
done sequentially (reading or writing the data one after another).

{#9999,Example program:}
PROGRAM example_ftell;

GLOBAL
    mytable[3]=11,22,33,44;
    midata1;
    midata2;
    myhandle;

BEGIN
    myhandle=fopen("help/help.dat","w");

    midata1=ftell(myhandle); // Position of the cursor before writing

    fwrite(OFFSET mytable,4,myhandle);

    midata2=ftell(myhandle); // Position of the cursor after being written the data

    fclose(myhandle);
END
{-}

This example writes the four data items contained in {mytable} (11,22,33 & 44)
into the file {help.dat}.

After opening the file with {#223,fopen()} the position of the cursor is obtained
and saved in the variable {midata1} (this will be 0, the beginning of the file).

Then, the four values contained in the table are written in the file and the
position of the cursor is obtained again, which now is saved in {midata2} (will be
4, at the end of the file, after the four written values).

Finally, the file is closed with {#224.fclose()} before ends.

{Note:} By default, the {<position of the cursor>} is specified as a
number of simple data, assuming that a simple data (a variable)
fills {4 bytes}. So for example, if the cursor is placed in the tenth position
from the beginning of the file, then the program can access the data
from the fortieth byte.

This relation can be changed, modifying the global variable {#1420,drive_size},
which by default is set at {4} for every program.

{/}

{Nota:} The function {#229,filelength()} allows you to find the length of an
file, but to do this the file must already be open.

{/}See: {#227,fseek()} - {#225,fread()} - {#226,fwrite()} - {#1420,drive_size}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.229,filelength()}

{filelength(}<handle>{)}

{Returns:}

The length of the file

{Description:}

This function obtains the length of an file already opened
with {#223,fopen()}, to do this you need as a parameter the {<handle>} or
{identifier of file} returned by the {#223,fopen()} function.

This function doesn't modify the current position of the reading/writing
cursor of the file, but simply returns the number of data items contained 
therein.

{#9999,Example program:}
PROGRAM example_filelength;

GLOBAL
    mytable[3]=11,22,33,44;
    longitude;
    myhandle;

BEGIN
    myhandle=fopen("help/help.dat","w");
    fwrite(OFFSET mytable,4,myhandle);
    fclose(myhandle);
    myhandle=fopen("help/help.dat","r");

    longitude=filelength(myhandle); // Obtains the length of the file (4)

    fclose(myhandle);
END
{-}

This example program creates first an file called {help.dat},
writing to it the four values contained in {mytable}.

Once the file has been created, it will be reopened in read mode to obtain its {length}.

{/}

{Note:} By default, the {length of the file} is obtained as the number of
simple data items it contains, assuming that a simple data (a variable)
fills up {4 bytes}. If, for example, the length of an file is ten
then it will occupy forty bytes of memory.

This relation can be changed by modifying the global variable {#1420,drive_size},
which by default is {4} for every program.

{/}

{Note:} The functions {#231,get_dirinfo()} and {#232,get_fileinfo()} allow you to 
obtain a lot of information about the structure of directories (folders)
on the drive and about the files/files contained on it.

{/}See: {#223,fopen()} - {#231,get_dirinfo()} - {#1420,drive_size}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.230,flush()}

{flush(}{)}

{Returns:}

The number of opened files/files.

{Description:}

Empties the memory buffers, and ensures that all data written 
to a file which is still in the cache memory is saved
in its correspondent file.

This operation is not very necessary, because the administration of the
cache that the operating system makes, is very effective and the data is not going to 
be lost due to not being correctly written to its corresponding file/file.

But, this function has another utility. It will return the {number
of files opened with} {#223,fopen()} inside of a program.

The file system allows just a maximum number of files to be open at once,
which depends on the system's configuration.

Every file must be closed with {#224,fclose()} once the program has finished operating on them.
This last function allows you to close just one file, or everyone which is open.

{#9999,Example program:}
PROGRAM example_flush;

GLOBAL
    midata1;
    midata2;
    myhandle;

BEGIN
    myhandle=fopen("help/help.dat","w");

    midata1=flush(); // Obtains the number of opened files (1)

    fclose(myhandle);

    midata2=flush(); // Obtains the number of opened files (0)

END
{-}

This example obtains on two occasions the number of files opened, with 
the function {flush()}. After the file {help.dat} has been opened, the
function determines that there is one open file, and once closed,
could be used to check that no files are still open.

{/}See: {#223,fopen()} - {#224,fclose()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.231,get_dirinfo()}

{get_dirinfo(}<mask of directory>{,} <types of file>{)}

{Returns:}

Number of files of the directory which coincides with the mask and the
type selected.

{Description:}

This function allows you to obtain a list of the files in a directory (folder).

The {<mask of directory>} is required to select the type of files
which must be listed. This {<mask>} is just a name of a partial file
using jokers; for example, the mask {"*.*"} (must be indicated as a text
between quotation marks) will select every file in the directory.

You can also include in the mask, the {path} of the directory (if no path is defined
the files of the current directory will be listed). 
For example, the mask {"C:\WINDOWS\SYS*.??E"} will select every file of the
directory {"C:\WINDOWS"} whose name starts with {"SYS"} and whose extension finishes
with {"E"}.

As a second parameter the {<types of files>} must be indicated which are to
be included in the list, this will be one of the following:

{ _normal} - To list just the normal files.ú
{ _hidden} - To include also all hidden files.ú
{ _system} - To include also the system files.ú
{ _subdir} - To include also the subdirectories.ú
{ _volid}  - To list just the label of the volume.ú

The most common choice is to indicate {_normal} as the {<type of files>}, this type
covers most files, including read-only files, file files and read/write files 
(only some special files are excluded, which typically are internal system files).

If {_hidden}, {_system} or {_subdir} is indicated in this parameter, these types of files
will be included as well as the normal files (it's not necessary to specify {_normal}).
Also, you can select more than one of these types; for example, indicating {_hidden+_system}
will list every normal file, as well as every hidden and system file.

When {_volid) is indicated, just the name of the volume label of the disk
will be listed, no file or subdirectory will be listed (you can't add other types to this).

{/}

The function {get_dirinfo()} simply returns the {total number} of listed files;
the names of these files are saved in the global structure
{#1413,dirinfo} (the first name of the file is saved in {dirinfo.name[0]}, the
second in {dirinfo.name[1]}, etc.).

The {total number} of listed files which this function returns is saved
in {dirinfo.files}.

The list of file names is always saved in alphabetic order, but the function
{#213,qsort()} can be used to order the global structure {#1413,dirinfo} 
with any other criteria.

{/}

This function just allows you to obtain the {names} of the files, to
obtain further information about them (the attributes, the size, the data,
etc.) the function {#232,get_fileinfo()} must be used.

{#9999,Example program:}
PROGRAM example_get_dirinfo;

GLOBAL
    counter;

BEGIN
    write(0,0,0,0,"List of files - Press ESC to finish");

    get_dirinfo("C:\WINDOWS\*.EXE",_normal); // Obtains the list of files

    FOR (counter=0;counter<dirinfo.files;counter++)
       x=(counter%4)*80;
       y=16+(counter/4)*8;
       write(0,x,y,0,dirinfo.name[counter]);
    END

    REPEAT
        FRAME;
    UNTIL (key(_esc));
END
{-}

This example program lists every normal {EXE} file of the directory
C:\WINDOWS, and then shows them on screen.

The loop {#1025,FOR} is the one that shows on screen the list of the
files of the structure {#1413,dirinfo} in four columns, as otherwise the function
{get_dirinfo()} doesn't show any information on screen, it just fills up the
structure {#1413,dirinfo} with the names of the files found in the directory.

{/}

To open or create a file the function {#223,fopen()} can be used.

To change the directory, you must use the function {#235,chdir()}, and
{#236,mkdir()} to create a new directory.

The function {#238,disk_free()} allows you to find out the free disk space on a drive.

{/}See: {#232,get_fileinfo()} - {#223,fopen()} - {#235,chdir()} - {#236,mkdir()} - {#238,disk_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.232,get_fileinfo()}

{get_fileinfo(}<name of the file>{)}

{Returns:}

{0} - Can't obtain any information about the file.ú
{1} - The information about the file was saved correctly.ú

{Description:}

Obtains information about a file or directory on the disk, for which,
the function requires the {<name of the file>} as a parameter (between quotation
marks). You can either just indicate the filename, or include the path to
the file as well.

If the function finds the file in the specified directory (or in
the current one, in the case of no directory being specified), it will return back
the value {1} and will save all information about the file in the global structure
{#1414,fileinfo}, which contains the following fields:

{ fullpath} - Complete name (including the path).ú
{ drive}    - Disk drive (1-A:, 2-B:, 3-C:, ...).ú
{ dir}      - Directory of the file.ú
{ name}     - Name of the file.ú
{ ext}      - Extension of the file.ú
{ size}     - Size (in simple data, see {#1420,drive_size}).ú
{ day}      - Day (data of the last access).ú
{ month}    - Month (data of the last access).ú
{ year}     - Year (data of the last access).ú
{ hour}     - Hour (hour of the last access).ú
{ min}      - Minute (hour of the last access).ú
{ sec}      - Second (hour of the last access).ú
{ attrib}   - Attributes of the file.ú

The path to the file can be completely specified (from the
main directory of the drive, as "C:\WINDOWS\...") or relative to the current 
directory (from which the game is executed, like "MAP\MIOS\...").
Anyhow, the complete path from the main directory will always be stored in 
{fileinfo.fullpath}, including the drive letter of the disk.

{/}

The function {get_fileinfo()} just obtains information about a file,
to obtain the complete list of files in a directory, the function
{#231,get_dirinfo()} must be used.

{#9999,Example program:}
PROGRAM example_get_fileinfo;
BEGIN
    // ...

    get_fileinfo("help/HELP.FPG");

    // ...
END
{-}

This small example asks for information about the file {help.fpg}
contained in the directory {help}. It can be extracted and traced (with {F12})
to see how, after the call to the function, the global structure
predefined as {#1413,fileinfo} has been filled up with information concerning 
the file.

{/}

To open or create a file the function {#223,fopen()} can be used,
and to delete a file from the drive the function {#237,remove()} can be used.

The function {#238,disk_free()} allows you to ascertain the free disk space
of any drive.

{/}See: {#231,get_dirinfo()} - {#223,fopen()} - {#237,remove()} - {#238,disk_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.233,getdrive()}

{getdrive(}{)}

{Returns:}

The number of the current drive.

{Description:}

This function allows you to determine which is the drive that is being
currently used, this is returned as a number, where {1} corresponds to the drive {A:},
the number {2} to {B:}, {3} to {C:}, etc. 
There are no parameters required in the function call.

The function {#234,setdrive()} allows you to set the current drive;
all access to the disk (reading and writing files) is always done
on the selected drive which, by default, will be the drive
on which the program is executed.

{#9999,Example program:}
PROGRAM example_getdrive;

GLOBAL
    drive;

BEGIN
    write(0,0,0,0,"Current drive:");

    drive=getdrive();

    write_int(0,0,20,0,OFFSET drive);
    LOOP
        FRAME;
    END
END
{-}

This program shows on screen the number of the current drive obtained
using the function {getdrive()}.

{/}

To change the directory you must use the function {#235,chdir()}, and
{#236,mkdir()} to create a new directory.

The function {#238,disk_free()} allows you to ascertain the remaining free
disk space on a drive.

{/}See: {#234,setdrive()} - {#235,chdir()} - {#236,mkdir()} - {#238,disk_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.234,setdrive()}

{setdrive(}<drive>{)}

{Description:}

This function allows you to set the current drive; all access to the disk
(reading and writing files) is always done on the selected drive
which, by default, will be the drive on which the program was executed.


The {<drive>} must be indicated with a number, where 
the number {1} corresponds with the drive {A:}, the number  {2} with {B:},
{3} the {C:}, etc.   this function doesn't return any value.

The function {#233,getdrive()} allows you to obtain the number of the current drive.

{#9999,Example program:}
PROGRAM example_setdrive;

GLOBAL
    drive;

BEGIN
    // ...

    drive=getdrive();

    setdrive(1);      // Is placed in the drive A:

    // ...

    setdrive(drive); // Recovers the previous drive

    // ...
END
{-}

This program first, obtains the current drive with the function {#233,getdrive()}
and saves it in the variable {drive}, then the drive is set to {1} (A:)
before, finally, the drive is reset as the drive in which the program is
being executed.

{/}

{Note:} When a drive is changed with {setdrive()} no value is returned,
but afterwards {#233,getdrive()} can be called to check that the program
has been placed on the correct drive.

{/}

To change the directory you must use the function {#235,chdir()}, and
{#236,mkdir()} to create a new directory.

The function {#238,disk_free()} allows you to ascertain the remaining free
disk space on a drive.

{/}See: {#233,getdrive()} - {#235,chdir()} - {#236,mkdir()} - {#238,disk_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.235,chdir()}

{chdir(}<directory>{)}

{Returns:}

{1} - The indicated directory was changed.ú
{0} - This directory can't be read.

{Description:}

Changes the current directory, on the selected drive.

The directory must be indicated as a literal (text between quotation marks), and
can be a relative path (from the current directory) or an absolute path
(from the main directory).

The ways of use and possibilities of this function are the same as the
command {CD} that can be typed in at the command line of the operating system.

Each program is placed at the beginning of the directory where the main executable
is found.

New directories (or folders)can be created on a disk 
with the function {#236,mkdir()}, and with the function {#237,remove()} the other 
directories can be eliminated.

{#9999,Example program:}
PROGRAM example_chdir;
BEGIN
    chdir("MAP"); // Is placed in the directory MAP\

    // ...

    chdir("..");  // Comes back to the previous directory
END
{-}

This small example shows how the function {chdir()} can be used
to change the current directory.

{/}

The function {#234,setdrive()} allows you to set the current drive
and the function {#233,getdrive()} allows you to ascertain it;
all access to the disk (reading and writing of files) is always done on the selected
drive which, by default, will be the drive on which the program is being executed.

{/}

{Note:} The list of a directory's files can be obtained with the
function {#231,get_dirinfo()}.

{/}See: {#236,mkdir()} - {#237,remove()} - {#234,setdrive()} - {#233,getdrive()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.236,mkdir()}

{mkdir(}<directory>{)}

{Description:}

Creates a new directory (inside of the current directory or folder).

You must indicate as a parameter the name of the directory to be created 
as a literal (text between quotation marks).

The way of using and possibilities for this function are the same as
the command {MD} which can be typed at the command line of the operating
system.

Each program is placed at the beginning of the directory where the main
executable is found.

You create a new directory with the function {#235,mkdir()}, eliminate
the other directories with the function {#237,remove()}.

.
{#9999,Example program:}
PROGRAM example_mkdir;
BEGIN
    mkdir("temporal"); // Creates a new directory

    // ...
    remove("temporal");
END
{-}

This small program shows how the function {mkdir()} can be used to create
a directory, and then it is deleted with the function {#237,remove()}.

{/}

The function {#234,setdrive()} allows you to set the current drive
and the function {#233,getdrive()} allows you to ascertain it;
all access to the disk (reading and writing of files) is always done on the selected
drive which, by default, will be the drive on which the program is being executed.

{/}

{Note:} The directory's list of files can be obtained with the function
{#231,get_dirinfo()}.

{/}See: {#235,chdir()} - {#237,remove()} - {#234,setdrive()} - {#233,getdrive()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.237,remove()}

{remove(}<name of file or directory>{)}

{Description:}

Deletes files or subdirectories contained inside of the current directory
in which the program was executed.

The {<name of file or directory>} must be indicated in a literal (text
between quotation marks), also the joker/wild characters "?" and "*"  are accepted (as
for example "*.bak" to eliminate every file with the extension BAK).

The files eliminated will always be inside of the current directory (see {#235,chdir()}
to change the directory) and on the current drive (see {#234,setdrive()} to change
the drive).

With this function directories can also be eliminated, but only
if they are empty (if there are no files or other subdirectories inside).

{/}

{Note:} This function must be used with more caution, because the files
deleted cannot be recovered, and information or programs
contained on the disk can be lost .

{/}

{#9999,Example program:}
PROGRAM example_remove;
BEGIN
    mkdir("temporal");
    // ...

    remove("temporal"); // Deletes a directory
END
{-}

This small example creates a directory with the function {#236,mkdir()} and then
eliminates it with the function {remove()}.

{/}

{Note:} The directory's list of files can be obtained with the function
{#231,get_dirinfo()}.

{/}See: {#235,chdir()} - {#234,setdrive()} - {#231,get_dirinfo()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.238,disk_free()}

{disk_free(}<drive>{)}

{Returns:}

The free disk space on the drive.

{Description:}

This function allows you to determine the free disk space of any drive.

The number of the {<drive>} is required as the only parameter, the
number {1} meaning the drive {A:}, {2} with {B:}, {3} with {C:}, etc.

The remaining space on the drive is given in {Kbs} (in kilobytes,
each one being a total of 1024 bytes).

The current drive can be ascertained (the one where the program is being
executed) thanks to the function {#233,getdrive()}.

{#9999,Example program:}
PROGRAM example_disk_free;

GLOBAL
    drive;
    free_space;

BEGIN
    // ...

    drive=getdrive();
    free_space=disk_free(drive);

    // ...
END
{-}

This program uses first the function {#233,getdrive()} to
determine on which drive the program is being executed (where
the variable {drive})is stored on, and then determines the free 
disk space of that drive with {disk_free()}.

{/}

To obtain information about the size of the files etc... you must be use the
functions {#231,get_dirinfo()} and {#232,get_fileinfo()}.

{/}

{Note:} The function {#239,memory_free()} allows you to determine the free RAM 
memory, the quantity of memory that is available to run the program.

{/}See: {#233,getdrive()} - {#239,memory_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.239,memory_free()}

{memory_free(}{)}

{Returns:}

The free memory available for the program.

{Description:}

This function allows you to determine the computer's RAM memory that is
available for the use of the program.

No parameter is required, and the memory total is returned in Kbs
(in kilobytes, each one being a total of 1024 bytes).

This quantity of memory will be available for the program to load
all its resources (graphics, sounds, etc.), it is useful to
check with this function, at the start of a program, that the computer
has enough memory to load all the necessary resources.

{#9999,Example program:}
PROGRAM example_memory_free;

GLOBAL
    free_memory;

BEGIN
    // ...

    free_memory=memory_free();

    // ...
END
{-}

This small example uses the function {memory_free()} to save the quantity 
of RAM available for the program in the global variable {free_memory}.

{/}

{Note:} The function {#238,disk_free()} allows you to determine the free disk 
space on a computer drive.

{/}See: {#238,disk_free()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.240,ignore_error()}

{ignore_error(}<error number>{)}

{Description:}

This function allows you to ignore a specified execution error,
the {<error number>} is required as a parameter; this is the present
number in the information window of an error which appears on occasions
when a program is being executed.

At the beginning it is not recommended to ignore the execution errors,
because the program may not work correctly, and you may need some information
relative to the error to solve the problem.

When a program produces an execution error, it is always for a reason;
and to ignore the error will not solve the problem.

{/}

{Note:} Not all the errors can be ignored, there are some errors which
make it impossible for the program to run properly. These are the errors
denoted as "serious", which will always cause the program to abort.

{/}

{#9999,Example program:}
PROGRAM example_ignore_error;
BEGIN

    ignore_error(145); // To ignore the divisions by zero

    x=x/0;
END
{-}

In this example the function {ignore_error()} is called to advise 
the system that, from now on, it should ignore all divisions by zero
(these will produce an unquantifiable result).

Now a division by zero is made, to check that the program doesn't emit
an error message.

This error number is {145}, the same as the number given with the call to the
function {ignore_error()} of the previous example.

{/}

{List of codes of execution errors:}

{100} There is not enough memory to run the program.ú
{101} Call to key() with a nonexistent key code.ú
{102} The palette was not loaded, file not found.ú
{103} An invalid palette file was loaded.ú
{104} Too many FPG files are open at the same time.ú
{105} The file was not loaded, file not found.ú
{106} An invalid FPG file was loaded.ú
{107} Number of scroll invalid (must be between 0 and 9).ú
{108} Number of region invalid (out of range).ú
{109} file Code invalid.ú
{110} Code of graphic invalid.ú
{111} An FPG file was used before it was loaded.ú
{112} A graphic's code is needed for the scroll.ú
{113} Too many fonts have been loaded.ú
{114} The font was not loaded, file not found.ú
{115} An invalid font file was loaded.ú
{116} Identifier code of fonts invalid.ú
{117} Code of text centre invalid.ú
{118} There are too many blocks of text currently active in the program.ú
{119} Identifier of text invalid.ú
{120} Screen region is defined incorrectly.ú
{121} Nonexistent graphic was used.ú
{122} A block out of memory was written.ú
{123} The file you are attempting to write to hasn't been opened.ú
{124} Can't write to the file (check space on disk).ú
{125} A block out of memory was read.ú
{126} Can't open the file for reading.ú
{127} Can't read the file.ú
{128} Can't load the sound effect.ú
{129} Can't play the wanted sound effect.ú
{130} Can't start the wanted animation.ú
{131} Number of mode 7 invalid (must be between  0 and 9).ú
{132} A code of graphic for the mode 7 is needed.ú
{133} Number of checkpoint invalid.ú
{134} Number of button incorrect (must be between 0 and 3).ú
{135} Number of axis incorrect (must be between 0 and 3).ú
{136} Address of the palette table out of memory.ú
{137} Can't check regions in mode 7 graphics.ú
{138} Code of graphic information incorrect.ú
{139} Can't check collisions in mode 7 graphics.ú
{140} Access out of rank.ú
{141} An invalid process was accessed..ú
{142} The process looks like a block, expecting FRAME.ú
{143} Can't load the map, file not found.ú
{144} An invalid map file was loaded.ú
{145} A division by zero was made.ú
{146} The size of the region is incorrect.ú
{147} Can't load FLI/FLC animation, file not found.ú
{148} Value of timeout incorrect (must be between 1 and 60).ú
{149} Number of players incorrect (must be between 2 and 8).ú
{150} Only global data can be sent .ú
{151} Size of the square invalid (must be between 1 and 256).ú
{152} searching Map invalid (from 1x1 to 128x128).ú
{153} Size of the map incorrect (from 1x1 to 32768x32768).ú
{154} Number of colour incorrect (must be from 0 to 255).ú
{155} The centre is outside of the graphic's limits.ú
{156} The object is outside of the map and will be eliminated.ú
{157} Map texture not found.ú
{158} Texture size incorrect.ú
{159} Can't load the world, file not found.ú
{160} Can't load the world, file not valid.ú
{161} Flag number invalid.ú
{162} Dispositive invalid (just 1-IPX,2-SERIAL,3-MODEM).ú
{163} Packet size invalid (just from 1 to 199).ú
{164} The string of text destination is invalid.ú
{165} Null cursor was accessed.ú
{166} The access mode to the file is invalid.ú
{167} Can't load the module.ú
{168} Too many ignored errors.ú
{169} To many files opened..ú
{170} Identifier of file (handle) not valid.ú
{171} Value out of rank.ú
{172} Too many graphic objects visualised.ú
{173} Type of graphic object is not known.ú
{174} Percentage of link out of rank (0..15).ú
{175} Number of graphic object invalid.ú
{176} Error variable of type: Texture of map [a] not found in file [b].ú
{177} Map texture.ú
{178} Not found in file.ú
{179} Too many partitions of dynamic memory were made..ú
{180} The cursor doesn't correspond to any of the reserved blocks.ú
{181} Can't reserve blocks of less than one position.ú
{182} A block outside of the memory was (de)encrypted.ú
{183} Can't load another palette when the current one is enforced.ú
{200} file with corrupted data, can't be loaded.ú

{/}

{Note:} With the compilation options (see {#1400,Compiler_options}) the errors 
of execution can be ignored , but this practice is not recommended.

{/}See: {#1400,Compiler_options}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.241,save_map() / save_pcx()}

{save_map(}<file>{,} <graphic>{,} <name of the file>{)}

{save_pcx(}<file>{,} <graphic>{,} <name of the file>{)}

{Returns:}

{1} - If the file was loaded successfully.ú
{0} - While saving the file there was an error.

{Description:}

Creates a MAP or PCX file from a graphic loaded in memory.

The function requires the {<file>} and {<graphic>} codes which identify
the graphic, and the {<name of the file> MAP} or {PCX} which must be created
on the disk containing that image. The name of the file must be specified
as a literal (text between quotation marks, as "image.pcx").

Graphics loaded with the functions {#174,load_map()} or {#174,load_pcx()}
(or created with {#188,new_map()}) will be used as if they were from the
first file (the file with the code 0).

The function {save_map()} always creates {MAP} files, and {save_pcx()}
will always create {PCX} files, {independent of the indicated extension} in the
{<name of the file>}. If there is no error, the function will create the file
with the image and will return back the value {1}.

{/}

These maps can be loaded in the graphical environment of
DIV Games Studio or in the programs, using the functions
{#174,load_map()} o {#174,load_pcx()}.

{/}

{#9999,Example program:}
PROGRAM example_save_map;
BEGIN
    load_fpg("help/help.fpg");

    save_pcx(0,1,"help/help.pcx"); // Creates a PCX file 

END
{-}

This example uses the function {save_pcx()} to create a PCX file 
containing an image previously loaded inside of the file
{help.fpg} with the function {#132,load_fpg()}.

{/}

A graphic can be created with the function {#188,new_map()}, and to
modify a graphic the following functions can be used:

{#135,map_block_copy()} - Transfers a block of a graphic to another.ú
{#136,map_get_pixel()} - Obtains the colour of a graphic pixel.ú
{#137,map_put()} - Puts a graphic into another.ú
{#138,map_put_pixel()} - Fixes the colour of one point in a graphic.ú
{#139,map_xput()} - Places a graphic into another, with added effects.ú

{/}

{Note:} The function {#253,write_map()} allows you to write text in a 
graphic created in memory (instead of writing it on screen).

{/}See: {#174,load_map/pcx()} - {#176,unload_map/pcx()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.242,sin()}

{sin(}<angle>{)}

{Returns:}

The sin of a given angle.

{Description:}

Calculates the sin in thousandths of the angle given as the parameter.

The angles are always manipulated in thousandths of degree (see the
{#1044,use of angles in the language}), and the sin will be returned 
in thousandths of a unit as well (as a value from -1000 to 1000).

For example, {sin(90000)} will return  {1000}, because the sin of 90 degrees is 1.

{#9999,Example program:}
PROGRAM example_sin;

GLOBAL
    angles[15];
    sine[15];
    n;

BEGIN
    write(0,0,0,0,"Angles");
    write(0,160,0,0,"Sins");
    FROM n=0 TO 15;
        angles[n] = rand(0, 360000);

        sine[n] = sin(angles[n]); // The sin of the angle is calculated

        write_int(0, 0,   20+n*10, 0, offset angles[n]);
        write_int(0, 160, 20+n*10, 0, offset sine[n]);
    END
    write(0,0,192,0,"Press ESC to finish ...");
    REPEAT
        FRAME;
    UNTIL (key(_esc));
END
{-}

This program will print on screen a list of angles, randomly
chosen between 0 and 360000 (from 0 to 360 degrees), and use the function
{sin()} to calculate the sine of them.

{/}See: {#1035,Expression} - See: {#1044,Use of the angles in the language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.243,cos()}

{cos(}<angle>{)}

{Returns:}

The cosine of a given angle.

{Description:}

Calculates the cosine in thousandths of the angle given as the parameter.

The angles are manipulated always in thousandths of a degree (see the
{#1044,use of angles in the language}), and the cosine will be returned 
in thousandths of a unit also (as a value from -1000 to 1000).

For example, {cos(0)} will return  {1000}, because the cosine of 0 degrees is 1.


{#9999,Example program:}
PROGRAM example_cos;

GLOBAL
    angles[15];
    cosine[15];
    n;

BEGIN
    write(0,0,0,0,"Angles");
    write(0,160,0,0,"Cos");
    FROM n=0 TO 15;
        angles[n] = rand(0, 360000);

        cosine[n] = cos(angles[n]); // The cosine of the angle is calculated

        write_int(0, 0,   20+n*10, 0, offset angles[n]);
        write_int(0, 160, 20+n*10, 0, offset cosine[n]);
    END
    write(0,0,192,0,"Press ESC to finish ...");
    REPEAT
        FRAME;
    UNTIL (key(_esc));
END
{-}

This program will print on screen a list of the angles, randomly chosen
between 0 and 360000 (from 0 to 360 degrees), and will use the function
{cos()} to calculate the cosine of them.

{/}See: {#1035,Expression} - See: {#1044,Use of the angles in the language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.244,tan()}

{tan(}<angle>{)}

{Returns:}

The tan of a given angle.

{Description:}


Calculates the tangent in thousandths of the angle given as the parameter.

The angles are manipulated always in thousandths of a degree (see the
{#1044,use of angles in the language}), and the tan will be returned 
in thousandths of also (as a value inside of the rank 
{#1177,min_int} ... {#1178,max_int}).

For example, {tan(45000)} will return  {1000}, because the tan of 45 degrees 
is 1.

{#9999,Example program:}
PROGRAM example_tan;

GLOBAL
    angles[15];
    tangent[15];
    n;

BEGIN
    write(0,0,0,0,"Angles");
    write(0,160,0,0,"Tans");
    FROM n=0 TO 15;
         angles[n] = rand(0, 360000);

        tangent[n] = tan(angles[n]); // calculates the tan of the angle

        write_int(0, 0,   20+n*10, 0, offset angles[n]);
        write_int(0, 160, 20+n*10, 0, offset tangent[n]);
    END
    write(0,0,192,0,"Press ESC to finish ...");
    REPEAT
        FRAME;
    UNTIL (key(_esc));
END
{-}

This program will print on screen a list of the angles, randomly chosen
between 0 and 360000 (from 0 to 360 degrees), and will use the function
{tan()} to calculate the tangent of them.

{/}See: {#1035,Expression} - See: {#1044,Use of the angles in the language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.245,asin()}

{asin(}<asin>{)}

{Returns:}

The arcsine of a given sine.

{Description:}

Calculates the arcsine of the sine given as the parameter in thousandths, the corresponding
angle to a sine value is obtained (opposite operation to sine, which can be obtained
with the function {#242,sin()}).

The angles are always manipulated in thousandths of a degree (see the
{#1044,use of angles in the language}), and the asin will be returned 
in thousandths of a degree also (as a value inside of the rank 
{#1177,min_int} ... {#1178,max_int}).

The {<sin>} is required as a value from{ -1000} to {1000} (from -1.0 to +1.0),
and the result is returned as an angle between{ -90000} and {90000} (from -90
to +90 degrees).

{#9999,Example program:}
PROGRAM example_asin;

GLOBAL
    sine[15];
    angles[15];
    n;

BEGIN
    write(0,0,0,0,"Sin");
    write(0,160,0,0,"Asin (angle)");
    FROM n=0 TO 15;
        sine[n] = rand(-1000, 1000);

        angles[n] = asin(sine[n]); // calculates the arcsine of a sine

        write_int(0, 0,   20+n*10, 0, offset sine[n]);
        write_int(0, 160, 20+n*10, 0, offset angles[n]);
    END
    write(0,0,192,0,"Press ESC to finish ...");
    REPEAT
        FRAME;
    UNTIL (key(_esc));
END
{-}

This program will print on screen a list of sines, randomly chosen
between -1000 and 1000 (represented in thousandths), and will use the function
{asin()} to calculate the arcsine of these values.

{/}See: {#1035,Expression} - See: {#1044,Use of the angles in the language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.246,acos()}

{acos(}<cos>{)}

{Returns:}

The arccos of a given cos.

{Description:}

Calculates the arccos of the cosine given as the parameter in thousandths, the corresponding
angle to a cosine is obtained (inverse operation to the cosine, which can be obtained
using the function {#243,cos()}).

The angles are always manipulated in thousandths of a degree (see the
{#1044,use of angles in the language}), and the acos also returns values in thousandths
(as a value inside of the rank). 

The {<cos>} is required as a value from{ -1000} to {1000} (from -1.0 to +1.0),
and the result is returned as an angle between { -90000} and {90000} (from -90
to +90 degrees).

{#9999,Example program:}
PROGRAM example_acos;

GLOBAL
    cosine[15];
    angles[15];
    n;

BEGIN
    write(0,0,0,0,"Cos");
    write(0,160,0,0,"Acos(angle)");
    FROM n=0 TO 15;
        cosine[n] = rand(-1000, 1000);

        angles[n] = acos(cosine[n]); // The acos of a cos is calculated

        write_int(0, 0,   20+n*10, 0, offset cosine[n]);
        write_int(0, 160, 20+n*10, 0, offset angles[n]);
    END
    write(0,0,192,0,"Press ESC to finish ...");
    REPEAT
        FRAME;
    UNTIL (key(_esc));
END
{-}

This program will print on screen a list of the sins, randomly chosen
between -1000 and 1000 (represented in thousandths), and will use the function
{acos()} to calculate the asin of them.

{/}See: {#1035,Expression} - See: {#1044,Use of the angles in the language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.247,atan()}

{atan(}<tan>{)}

{Returns:}

The arctan of a given tangent.

{Description:}

Calculates the arctan of the tan given as a parameter in thousandths, the corresponding
angle to a tan is obtained (inverse operation to the tan of an angle, which can be obtained
with the function {#244,tan()}).

The angles are always manipulated in thousandths of a degree (see the
{#1044,use of angles in the language}), and the arctan will be returned 
in thousandths of a degree also.

The {<tan>} is required as a value inside of the rank {#1177,min_int}...
{#1178, max_int} (from -inf to +inf), and the result is returned as an 
angle between{ -90000} and {90000} (from -90 to +90 degrees).

{/}

{Note:} There is another function to calculate the arctan called {#248,atan2()},
this function takes as its parameters the values {<x>} and {<y>} and returns the arctan
of {y/x} between -180000 and 180000 (of -180 to 180 degrees).

{/}

{#9999,Example program:}
PROGRAM example_atan;

GLOBAL
    tangent[15];
    angles[15];
    n;

BEGIN
    write(0,0,0,0,"Tan");
    write(0,160,0,0,"Atan(angle)");
    FROM n=0 TO 15;
        tangent[n] = rand(-1000, 1000);

        angles[n] = atan(tangent[n]); // The arctan of a tan is calculated

        write_int(0, 0,   20+n*10, 0, offset tangent[n]);
        write_int(0, 160, 20+n*10, 0, offset angles[n]);
    END
    write(0,0,192,0,"Press ESC to finish ...");
    REPEAT
        FRAME;
    UNTIL (key(_esc));
END
{-}

This program will print on screen a list of the tans, randomly chosen
between -1000 and 1000 and use the function {atan()} to calculate the
arctan of them (between -45 and 45 degrees).

{/}See: {#1035,Expression} - See: {#1044,Use of the angles in the language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.248,atan2()}

{atan2(}<x>{,} <y>{)}

{Returns:}

The arctan of {<y>}/{<x>}.

{Description:}

Calculates the arctan of the tan obtained as the division of the
two values, given as the parameter ({<y>}/{<x>}), the angle corresponding
to arctan  (inverse operation to the tan of an angle, which can be obtained
with the function {#244,tan()}) is obtained.

The angles are always manipulated in thousandths of a degree (see the
{#1044,use of angles in the language}), and the arctan is also returned 
in thousandths as a value between{ -180000} and {180000} (from -180 to +180
degrees).

{/}

{Note 1:} Another function exists to calculate the arctan called
simply {#248,atan()}, this function takes as its only parameter the
tan of an angle and returns its arctan between -90000 and 90000 (from -90
to 90 degrees).

{/}

{Note 2:} There is also a version of {atan2()}, which is more simply adapted
to the geometric concepts; it is the function denoted as {#113,fget_angle()}
which obtains directly the angle between two points.

{/}See: {#1035,Expression} - See: {#1044,Use of angles in the language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.249,draw()}

{draw(}<type>{,} <colour>{,} <opacity>{,} <region>{,} <x0>{,} <y0>{,} <x1>{,} <y1>{,}{)}

{Returns:}

The {identifier of the primitive graphic} painted.

{Description:}

This is a generic function able to draw some primitive graphics
on screen (such as lines, boxes and circles). The following parameters
must be indicated:

{<type>} - Type of primitive graphic, as one of the following:

  {1} - Straight line.ú
  {2} - Rectangle.ú
  {3} - Filled rectangle.ú
  {4} - Ellipse.ú
  {5} - Filled ellipse.ú

{<colour>} - colour of the ink with which the primitive will be drawn 
(from {0} to {255}, as a colour of the palette).

{<opacity>} - Level of opacity of the primitive, from {0} to {15} (to allow
for transparency effects).

{<region>} - Number of region (window inside of the screen) where the primitive 
can be painted ; normally this value will be {0} to print the 
primitive in any position of the screen. To define
a region on the function {#106,define_region()} must be used.

{<x0>}, {<y0>} - Starting point of the straight line, or the upper left corner
of the box which contains the rectangle or ellipse.

{<x1>}, {<y1>} - End point of the straight line, or the lower right corner
of the box which contains the rectangle or ellipse.

{/}

When a primitive graphic is painted with {draw()} this will remain fixed
on screen until it is moved with the function {#251,move_draw()}, or eliminated with
the function {#250,delete_draw()}.

The {identifier of the primitive} returned by the function {draw()} will be 
necessary in order to move or delete the primitive.

The representation system of these graphic primitives is quite similar
to the system for texts; texts are painted with {#171,write()} and will remain fixed
until they are moved with {#141,move_text()} or eliminated with {#107,delete_text()}.

{/}

{Note:} The level of impression or depth of the primitive graphics can be controlled 
with the predefined global variable {#1418,draw_z}.

{/}

{#9999,Example program:}
PROGRAM example_draw;

GLOBAL
    counter;
    types;
    colour;
    opacity;
    x0,y0;
    x1,y1;

BEGIN
    write(0,0,0,0,"Press ESC to finish ...");
    REPEAT
        FROM counter=1 TO 10;
            types=rand(1,5);
            colour=rand(0,255);
            opacity=rand(0,15);
            x0=rand(0,319);
            y0=rand(0,199);
            x1=rand(0,319);
            y1=rand(0,199);

            // Paints a primitive graphic 

            draw(types,colour,opacity,0,x0,y0,x1,y1);

        END
        FRAME;
        delete_draw(all_drawing);
    UNTIL (key(_esc));
END
{-}

This example program draws on screen  10 primitive graphics
whose characteristics are selected randomly with the function
{#149,rand()}, and after creating an image with {#1029,FRAME}, it then deletes
them with the function {#250,delete_draw()}.

The process is repeated until the ESC key is pressed.

{/}

{Note:} a maximum of {256} primitive graphics can be represented on the screen at the same time.

{/}See: {#251,move_draw()} - {#250,delete_draw()} - {#1418,draw_z}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.250,delete_draw()}

{delete_draw(}<identifier of the graphic primitive>{)}

{Description:}

Deletes a primitive graphic which has been painted with the function {#249,draw()},
for which the {<identifier of the primitive>} is required as a parameter, 
which is the numeric code which was returned when it was painted.

If {all_drawing} is specified as a parameter the function will delete every
primitive graphic represented on screen, the {identifier} is only
necessary in the case of wanting to eliminate a particular primitive graphic.

{#9999,Example program:}
PROGRAM example_delete_draw;

PRIVATE
    id_draw;
    types;
    colour;
    opacity;
    x0,y0;
    x1,y1;

BEGIN
    write(0, 160, 8, 1, "[ENTER] To show a primitive / [SPACE] to delete it");
    draw(2,127,15,0,0,0,319,199);
    LOOP
        types=rand(1,5);
        colour=rand(0,255);
        opacity=rand(0,15);
        x0=rand(0,319);
        y0=rand(0,199);
        x1=rand(0,319);
        y1=rand(0,199);

        id_draw=draw(types,colour,opacity,0,x0,y0,x1,y1);

        WHILE (NOT key(_space))
            FRAME;
        END

        delete_draw(id_draw); // We delete the graphic

        WHILE (NOT key(_enter))
            FRAME;
        END
    END
END
{-}

In the previous example, a primitive is painted on screen, then the program waits
for the {space bar} to be pressed, at which moment the primitive is deleted
and then when the {ENTER} key is pressed the program repeats the loop.

This is the second primitive, which identifier has been saved in the variable {id_draw}
(the first primitive is the rectangle which has the same size as the screen and is
painted with the first call to the function {#249,draw()} of the program).

To delete every primitive graphic call the function {delete_draw(all_drawing);}, 
the parameter all_drawing will also eliminate the rectangle.

{/}

{Note:} The characteristics of a graphic primitive presented on screen (position,
colour, opacity and size) can be modified with the function {#251,move_draw()}. 

{/}See: {#249,draw()} - {#251,move_draw()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.251,move_draw()}

{move_draw(}<identifier of the primitive graphic>{,} <colour>{,} <opacity>{,} <x0>{,} <y0>{,} <x1>{,} <y1>{)}

{Description:}

Modifies a primitive graphic which has been painted with the function {#249,draw()},
to do this, the following parameters are required:

{<identifier of the primitive>} - Is the numeric code which was returned by the
function {#249,draw()} when the primitive graphic was painted and which is now wanted to
be modified.

{<colour>} - colour of ink for the primitive (from {0} to {255}, as a colour
of the palette).

{<opacity>} - Level of opacity of the primitive, from {0} to {15} (to allow
for transparency effects).

{<x0>}, {<y0>} - Initial point of the straight line, or the upper left corner
of the box which contains the rectangle or ellipse.

{<x1>}, {<y1>} - Final point of the straight line, or the lower right corner
of the box which contains the rectangle or ellipse and the screen coordinates
({x}, {y}) where it must be moved to.

{/}

{#9999,Example program:}
PROGRAM example_move_draw;

PRIVATE
    id_draw;
    colour;
    opacity;

BEGIN
    write(0, 0, 0, 0, "Move the mouse ...");
    id_draw=draw(4, 127, 15, 0, 0, 0, 32, 32);
    LOOP
        colour=rand(0,255);
        opacity=rand(0,15);

        // The graphic primitive is moved to the mouse coordinates

        move_draw(id_draw, colour, opacity, mouse.x-16, mouse.y-16, mouse.x+16, mouse.y+16);

        FRAME;
    END
END
{-}

In the example a circular primitive graphic is painted with the function {#249,draw()},
and its {identifier of graphic primitive} is saved in the global variable {id_draw}.

Then, inside of a loop, the function {move_draw()} will be used 
to place the circle at or near the mouse coordinates, and assign a randomly chosen colour 
and opacity to each image.

{/}

{Note:} To eliminate (delete) a primitive graphic the function
{#250,delete_draw()} is used, and with the predefined global variable {#1418,draw_z} 
the priority of impression of them can be handled .

{/}See: {#249,draw()} - {#250,delete_draw()} - {#1418,draw_z}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.253,write_in_map()}

{write_in_map(}<font>{,} <text>{,} <code of centre>{)}

{Returns:}

The created {code of the graphic} containing the text.

{Description:}

Creates a new map in memory (without loading it on disk, very similar to the
function {#188,new_map()}), and writes in the map some text which characteristics
are described with the following parameters:

{<font>} - The {code of the font} or {type of letter} which is going to be used.
Here a  0 must be placed when you want to use the system font
(font of white colour, small, of 6 to 8 points), or the {code of font} returned
by the function {#131,load_fnt()} when a new font is loaded in the program.

{<text>} -  specify the text to be written as a literal, as text between quotation
  marks (see the {#1047,delimitation symbols of literals}).

{<code of centre>} - This code value determines where the {centre} of the text
will be placed on the {#1136,checkpoint} of the created map. its
possible values are:

  {0}-Up left     {1}-Up     {2}-Up rightú
  {3}-Left           {4}-centre     {5}-Rightú
  {6}-Down left      {7}-Down      {8}-Down rightú

The text will always be fitted in a new map of the same dimensions, but
this {#1136,checkpoint} will specify which point of the map will centred on
the coordinates where it will then be placed.

{/}

This function works practically the same as {#174,load_map()}, but instead of
reading a file on the disk which contains the graphic it creates a graphic
which contains a written message.

The {code of the graphic} is given as the return value, which is a numeric
value which must be specified in order to use the graphic in the variable
{#1126,graph} or, in any function which requires a {code of graphic}
as its parameters.

When the {code of file} which belongs to the graphic is wanted inside of a function
the code {0} must be indicated (which is the code
of the first {file FPG} which is loaded in the program).

{/}

{#9999,Example program:}
PROGRAM example_write_in_map;

GLOBAL
    mi_font;

BEGIN
    mi_font=load_fnt("help/help.fnt");

    // A new map is created with the text "MOUSE"
    // with the checkpoint in the centre, and is
    // assigned as the graphic of the mouse cursor.

    mouse.graph = write_in_map(mi_font,"MOUSE",4);

    REPEAT
        FRAME;
    UNTIL (key(_esc));
    unload_map(mouse.graph);
END
{-}

In the example a font is loaded with the function {#131,load_fnt()},
and then a map is created with the function {write_in_map()}, saving the
{code of the graphic} which is returned in the variable {#1100,mouse.graph}, so
it will appear as the mouse cursor.

The new map is created with the message {"MOUSE"} written with the font {help.fnt},
and its main {#1136,checkpoint} is placed in the centre (with the code {4}).

Pressing the {ESC} key will bring you out of the loop and the program will
delete the graphic with the function {#176,unload_map()} (exactly the same
as if it were a file loaded from the drive).

But, {it is not necessary to delete the graphic from memory} before finishing
the program, because the system will do it automatically.

{/}

The main advantage of the function {write_in_map()} is to be able
to work with texts as if they were graphics, so they can be rotated,
scaled, printed with transparency effects, etc...

{Note:} {write_in_map()} can show a numeric value if used with the function 
{#255,itoa()}, which allows you to convert a numeric value into a string of text.

{/}See: {#171,write()} - {#176,unload_map/pcx()} - {#1126,graph} - {#255,itoa()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.254,calculate()}

{calculate(}<text with a numeric expression>{)}

{Returns:}

The result of the numeric expression.

{Description:}

Allows you to convert a literal (or text between quotation marks), which contains a
number or numeric expression, to a constant value which can be assigned to any
data.

Allows you to convert some text into a number; for example, the
statement {x=calculate("234");} will assign the value {234} to the variable
{x} (exactly the same as with the statement {x=234;}). The function {#255,itoa()}
allows the opposite operation, to convert a number into text.

But also, the function {calculate()} can evaluate an expression, contained
in the text with some operators, that can be the following (all the symbols
accepted by each operator are indicated):

{ + -}      Addition and substraction.ú
{ * /}      Multiplication and division.ú
{ % MOD}    Modulus, or rest of an entire division.ú
{ < <<}     Binary rotation to the left.ú
{ > >>}     Rotation to the right.ú
{ ^ ^^ XOR} OR binary exclusive.ú
{ | || OR}  OR binary.ú
{ & && AND} AND binary.ú
{ ! NOT}    Binary negation.ú
{ SQRT}     Square root.ú

Parentheses {( )} can also be used the to indicate priorities
inside of the calculation of the expression. For example, {calculate(}"(2+3)*4"{)}
would return the value {20} as a result.

{/}

{Note:} The operation of this function is very similar to the window
of the {#1301,calculator} ({System\Calculator}) of the windows environment.

{/}

{#9999,Example program:}
PROGRAM example_calculate;

GLOBAL
    STRING calculation;
    result;

BEGIN
    write(0,0,0,0,"Introduce an expression:");
    write(0,0,10,0,calculation);
    write(0,0,30,0,"Result:");
    write_int(0,0,40,0,OFFSET result);
    LOOP
        SWITCH(ascii)
            CASE 8:
                calculation--;
            END
            CASE 27:
                calculation="";
            END
            CASE 0..31:
            END
            DEFAULT:
                calculation+=ascii;
            END
        END

        result = calculate(calculation); // Evaluates the calculation

        IF (timer MOD 100>50)
            calculation+="_";
        ELSE
            calculation+=" ";
        END
        FRAME;
        calculation--;
    END
END
{-}

This example program allows you to introduce an expression to a string of text
(See {#1406,STRING}) and then evaluates it with the function
{calculate()} to show the result of the same string.

{/}

{Note:} if an error is produced in the evaluation of the expression (for example,
if there exists any parenthesis which are not closed again), the function will return {0} as
its result.

{/}See: {#255,itoa()} - {#171,write()} - {#1406,STRING}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.255,itoa()}

{itoa(}<expression>{)}

{Returns:}

A string of text containing the result.

{Description:}

This function is used to convert a numeric value or {<expression>} into
a string of text, that allows you to convert a number into text.
The string will have as many types as digits has the result.

The function {#254,calculate()} allows the opposite operation;
to convert a literal or string of text into a numeric value.

{#9999,Example program:}
PROGRAM example_itoa;

GLOBAL
    STRING message;

BEGIN
    load_fpg("help/help.fpg");
    mouse.graph=200;
    write(0,0,0,0,message);
    REPEAT

        // It makes a message with text and numbers using itoa()

        message = "Cursor of the mouse in (" + itoa(mouse.x) +
                  "," + itoa(mouse.y) + ").";

        FRAME;
    UNTIL (key(_esc));
END
{-}

This example program creates a string of text called {message}
(see {#1406,STRING}) letters and numeric values (the coordinates
of the mouse, see {#1100,mouse}), and it is represented on screen
with the function {#171,write()}.

The program loads the file {help.fpg} with {#132,load_fpg()} and assigns
the graphic {200} as the cursor of the mouse. The program will continue until
the {ESC} key is pressed.

{/}

{Note:} The name of the function {itoa()}, that comes from the C language, comes
from the expression "integer to ascii". And the function that does the opposite
operation, "ascii to integer" is called {#254,calculate()}.

{/}See: {#254,Calculate()} - {#1035,Arithmetic expressions} - {#171,Write()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.256,change_channel()}

{change_channel(}<channel>{,} <volume>{,} <balance>{)}

{Description:}

This is a complementary function to {#102,change_sound()}, which modifies
the properties of one of the sound channels which plays back the digital sound effects 
(See {#159,sound()}) or music modules (See {#216,song()}).

The {<channel>} number which is wanted to be adjusted must be indicated, (normally
the channel number returned by the function {#159,sound()}), and the two following
values:

{<volume>} - Is given as the volume of the channel, between {0} and {512},
independent of the volume of the sound and the general volume level.

When the volumes of the different channels are too loud the sound will be distorted,
so it is recommended to  modify the volume of the sound effects
through the function {#102,change_sound()} which, also allows you to adjust the
frequency of the sound.

{<balance>} - Is the "panning" or difference of volume between the left speaker
and the right one, it must be a value between {0} and {255}.

{/}

{Note:} The general levels of volume can be adjusted with the
global structure {#1104,setup} (digital sound, cd-audio and general volume).

{/}

{#9999,Example program:}
PROGRAM example_change_channel;

PRIVATE
    balance=128;     // volume level (0..256)

    id_sound;
    channel_id;

BEGIN
    load_fpg("help/help.fpg");
    put_screen(0, 1);

    id_sound = load_sound("help/help.pcm", 1);
    channel_id = sound(id_sound, 256, 256);

    write(0, 160, 0, 1, "Press right or left to change the balance.");
    write_int(0, 160, 10, 1, offset balance);
    LOOP

        // Changes the balance of the channel

        change_channel(channel_id, 50, balance);

        IF (key(_right) AND balance<255) balance++; END
        IF (key(_left) AND balance>0) balance--; END
        FRAME;
    END

END
{-}

In the example a sound (contained in the file {help.pcm})is loaded and played.
Inside of the program's main loop the channel balance through which the sound 
with the function {change_channel()}is being played , can be changed using
the cursor keys.

{/}

{Note:} See also the global predefined table in the predefined global table 
{#1416,channel}, that indicates which of the sound channels are being used.

{/}See: {#102,change_sound()} - {#159,sound()} - {#216,song()} {#1104,STRUCT setup}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.257,malloc()}

{malloc(}<length>{)}

{Returns:}

The {OFFSET} of the memory block asked, or {0} if the memory available is not
enough.

{Description:}

This function assigns dynamic memory, or a new block of free memory if required, 
to the program.

the {<length>} of the memory block to be occupied is required as a parameter. 
This length is specified as a number of simple data blocks, each one of them 
taking up 4 bytes of memory; for example, if a block of length {100} is required
then 400 bytes of memory will be put aside.

A max number of {256 blocks} can be requested inside of a program, 
irrespective of its size, the function {#258,free()} allows you to liberate
these memory blocks.

{/}

Normally the {OFFSET} (memory address) returned by the function
{malloc()} is assigned to a data of type pointer (See {#1405,POINTER}).

{/}

{#9999,Example program:}
PROGRAM example_malloc;

GLOBAL
    POINTER mytable[1000];  // pointer of a table of 1000 data
    counter;
BEGIN

    mytable = malloc(1000); // Asks for 1000 memory positions

    FOR (counter=0;counter<1000;counter++) // Accesses the data
        mytable[counter]=-1;
    END

    free(mytable);          // Liberates the memory occupied by the table
END
{-}

This small example shows how a pointer to the table can be defined 
(the pointer contains none of the data of the table, just a handle to the table itself),
and to assign memory to this pointer with the function {malloc()}.

Once the memory is assigned to the table of data, the program accesses them
(they are initiated to -1, as an example), and finally frees up the memory.

The memory blocks which are not liberated  with the function {#258,free()}, will be
liberated automatically by the system when the program has finished.

{/}

{Note:} the quantity of available memory for the processing of program data
(local and private data) can be controlled with the compilation options
(See {#1400,Compiler_options}).

{/}See: {#258,free()} - {#1405,POINTER}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.258,free()}

{free(}<OFFSET of the memory block>{)}

{Description:}

Liberates a block of dynamic memory which has been reserved previously with the
the function {#257,malloc()}

the {OFFSET} or memory address in which the block starts is required as a parameter, 
which is the value obtained when it is reserved.

The memory blocks not liberated with the function {free()}, will be liberated
automatically by the system when the program ends.

{#9999,Example program:}
PROGRAM example_free;

GLOBAL
    POINTER mytable[1000];  // Pointer of a table of 1000 data
    counter;
BEGIN

    mytable = malloc(1000); // Asks for 1000 positions of memory

    FOR (counter=0;counter<1000;counter++) // Accesses to the data
        mytable[counter]=-1;
    END

    free(mytable);          // Liberates the memory filled up by the table
END
{-}

This small example shows how a pointer to a table can be defined 
(the pointer contains none of the data of the table, just a handle to the table itself),
memory assigned to this with the function {#257,malloc()}.

Once the memory is assigned to the table of data, the program accesses them
(they are initiated to -1, as an example), and finally frees up the memory.

{/}See: {#248,free()} - {#1405,POINTER}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.259,encode()}

{encode(}<OFFSET of the data>{,} <length>{,} <clue>{)}

{Description:}

encrypt or un-encrypts a block of data in memory with a determined clue.
The necessary parameters are the following:

{<OFFSET of the data>} - Memory address in which starts the block which must
be compressed, to obtain this address the operator {#1085,OFFSET} must be used.

{<length>} - Length of the data to be compressed, the number of
positions of memory, filled up for the same, the length of any
data can be obtained with {#1094,SIZEOF()}.

{<clue>} - A literal (text between quotation marks) with the clue of encryption
or decryption of the data.

The algorithm is reversible so, to decrypt the data, simply you must to encrypt
them with the same clue.

The algorithm of encryption is very complex, so, any encrypted data with a clue
just can be recovered applying to it the same clue again.

{#9999,Example program:}
PROGRAM example_encode;

CONST
    password="mypass";

GLOBAL
    table_original[14]  =0,1,2,3,4,5,6,7,8,9,10,11,12,13,14;
    table_encrypted[14]=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14;
    counter;

BEGIN
    write(0,0,  0,0,"Original values");
    write(0,160,0,0,"encrypted values");
    write(0,0,190,0,"[SPACE] to encrypt/decrypt the values");

    // encrypts the values of the second table

    encode(OFFSET table_encrypted,sizeof(table_encrypted),password);

    FOR (counter=0;counter<15;counter++)
        write_int(0,0,  20+counter*8,0,OFFSET table_original[counter]);
        write_int(0,160,20+counter*8,0,OFFSET table_encrypted[counter]);
    END

    LOOP
        IF (scan_code==_space)

            // encrypts and decodes of values of the second table

            encode(OFFSET table_encrypted,sizeof(table_encrypted),password);

        END
        FRAME;
    END
END
{-}

This program has defined two tables of global data both with the same
values and allows, pressing the {space bar}, to encrypt and
decrypt one of the two tables (the denominated {table_encrypted[]}).

It can be seen how, when the data are encrypted a second time they are recovered
in its original state. If a different clue is used, the result will be 
completely different.

{/}

{Note:} There are other two functions which allow to encrypt and 
decrypt any kind of file, in this case must be used a function to
each operation: {#260,encode_file()} to encrypt and {#261,decode_file()}
to decrypt.

{/}See: {#260,encode_file()} - {#261,decode_file()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.260,encode_file()}

{encode_file(}<name of file>{,} <clue>{)}

{Description:}

encrypts one or more files of the disk with a pre-determined clue.
The necessary parameters are the following:

{<name of the file>} - Description of a file which must be encrypted,
a literal (text between quotation marks) with the name of the file. 
You can use the joker characters "?" and "*" in the specifying of
these files (for example, "*.BAK" to encrypt every file with extension BAK).

{<clue>} - A literal containing the clue of encryption of the file or files.

The encryption algorithm is quite complex, but any encrypted file
with a clue can be recovered simply by applying the same clue to it
with the function {#261,decode_file()}. If this function is not called,
the resulted file will be completely useless, being impossible to recover
the data contained in it.

Files which are already encrypted cannot be encrypted a second time.

{#9999,Example program:}
PROGRAM example_encode_file;

CONST
    password="mypass";

GLOBAL
    mytable[]=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14;

BEGIN
    save("help/help.enc",OFFSET mytable,sizeof(mytable));

    encode_file("help/help.enc",password); // encrypts the file
END
{-}

This small program uses the function {#155,save()} to create a file
called {help.enc} with the data contained in {mytable}, and then the program
encrypts it with the function {encode_file()}.

You can see how the contents of the created file (inside of the directory
{help/}) doesn't bear any relation to the original data (independent
of what the encryption clue is).

{/}

There is another function called {#259,encode()} which allows you to encrypt
and decrypt data in memory, in this case the operation is reversible, so
the same function is used for both operations.

{/}

{Note:} The functions {#262,compress_file()} and {#263,uncompress_file()}
allow you to compress and uncompress files of the disk. The encrypted files
{cannot be compressed} with the functions (as their contents are randomly 
organised).

{/}See: {#259,encode()} - {#261,decode_file()} - {#262,compress_file()} - {#263,uncompress_file()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.261,decode_file()}

{decode_file(}<name of the file>{,} <clue>{)}

{Description:}

Decodes one or more files on the disk, that share the same clue as the one
they were encrypted with using the function {#260,encode_file()}. The necessary 
parameters are the following:

{<name of file>} - Description of a file which must be unencrypted,
a literal (text between quotation marks) with the name of the file. 
You can use the joker characters "?" and "*" in the specifying of
these files (for example, "*.BAK" to decrypt every file with extension BAK).

{<clue>} - A literal specifying the clue of encryption for the file or files.
This clue must be {exactly} the same as the clue that the files were originally 
encrypted with, if {they are unencrypted with a different clue, the files will
remain indecipherable}.

The files unencrypted cannot be unencrypted again.

{#9999,Example program:}
PROGRAM example_decode_file;

CONST
    pass="mypass";

GLOBAL
    mytable[]=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14;

BEGIN
    save("help/help.enc",OFFSET mytable,sizeof(mytable));
    encode_file("help/help.enc",pass);
    // ...

    decode_file("help/help.enc",pass); // decodes the file

END
{-}

This small program uses the function {#155,save()} to create a file
called {help.enc} with the data contained in {mytable}, and is encrypted with
the function {encode_file()}.

Before the program finishes the contents of the file are recovered again using 
the function {decode_file()} which decodes the data. The file will be returned
to its original form.

{/}

The function {#259,encode()} allows you to encrypt and decode data in
memory, but in this case, the operation is reversible, so
the same function is used for both operations.

{/}

{Note:} the functions {#262,compress_file()} and {#263,uncompress_file()}
allow you to compress and uncompress files on the disk. The files encrypted
{cannot be compressed} with these functions (due to its content being completely 
randomly organised).

{/}See: {#260,encode_file()} - {#259,encode()} - {#262,compress_file()} - {#263,uncompress_file()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.262,compress_file()}

{compress_file(}<name of file>{)}

{Description:}

Compresses one or more files of the disk, the only parameter required is 
the {<name of file>} which must be compressed, as a literal (text between
quotation marks). The joker characters "?" & "*" can be used to specify some
files (for example, "*.BAK" to compress every file with the extension BAK).

To uncompress these files the function {#263,uncompress_file()} must be used.
The format of file encryption is a format specific to DIV Games Studio,
so it can't be uncompressed with any other external utility program.

The file will be saved compressed with the same name and extension as the
original. Files already compressed cannot be compressed a second time.


{#9999,Example program:}
PROGRAM example_compress_file;

GLOBAL
    counter;
    mytable[999];

BEGIN
    FOR (counter=0;counter<1000;counter++)
        mytable[counter]=counter;
    END

    save("help/help.cmp",OFFSET mytable,sizeof(mytable));

    compress_file("help/help.cmp"); // Compress the file.
END
{-}

This small program uses the function {#155,save()} to create a file
called {help.cmp} with the data contained in {mytable}, this being a group of
consecutive numbers from 0 to 1000.

Once created, the file is compressed with the function {compress_file()}.

In this case, the original size of the file is 4000 bytes (1000 blocks of data),
and the size of the compressed file is 1441 bytes (36% of the original size).

{/}

{Note:} the functions {#260,encode_file()} and {#261,decode_file()}
allow you to encrypt and decode files on the disk.

The files encrypted with these functions {can't be compressed}
due to their being content completely randomly organised. But, {the files
compressed can be encrypted}.

{/}See: {#263,uncompress_file()} - {#260,encode_file()} - {#261,decode_file()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.263,uncompress_file()}

{uncompress_file(}<name of file>{)}

{Description:}

Uncompresses one or more files on the disk, previously compressed
with the function {#262,compress_file()}, the only parameter required is
the {<name of file>} which must be uncompressed, as a literal
(text between quotation marks). The joker characters "?" & "*" can be used 
to specify some files (for example, "*.BAK" to uncompress every
file with extension BAK).

The format of file encryption is a format specific to DIV Games Studio,
so it can't be uncompressed with any other external utility program.

The file will be uncompressed with the same name and extension as the 
one compressed. Files not compressed with the function
{#262,compress_file()} can't be uncompressed using this function.


{#9999,Example program:}
PROGRAM example_uncompress_file;

GLOBAL
    counter;
    mytable[999];

BEGIN
    FOR (counter=0;counter<1000;counter++)
        mytable[counter]=counter;
    END

    save("help/help.cmp",OFFSET mytable,sizeof(mytable));

    compress_file("help/help.cmp"); // Compress an file

    // ...

    uncompress_file("help/help.cmp"); // Uncompress the file

    load("help/help.cmp",OFFSET mytable);
END
{-}

This small example uses the function {#155,save()} to create a file
called {help.cmp} using the data contained in {mytable}, this being  a group
of consecutive numbers from 0 to 1000, then the file is compressed
with the function {#262,compress_file()}.

Once the compressed file has been created, it is then uncompressed with the function
{uncompress_file()} and is again loaded over the original table using the
function {#130,load()}.

{/}

{Note:} the functions {#260,encode_file()} and {#261,decode_file()}
allow you to encrypt and decode files of the disk.

The encrypted files, generated with these functions {cannot be compressed}
due to their contents being completely randomly organised. 
But, {the compressed files can be encrypted}.

{/}See: {#262,compress_file()} - {#260,encode_file()} - {#261,decode_file()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.264,find_color()}

{find_color(}<red>{,} <green>{,} <blue>{)}

{Returns:}

The {colour number} in the palette.

{Description:}

Finds the colour from the current palette nearest to the indicated colour.

the desired colour must be specified in the palette using the three
component RGB system of colour coding, that is {<red>} (red), {<green>} (green)
and {<blue>} (blue), all of them being expressed as values between 0 and 63.

the {number of colour} of the palette which is the nearest to the indicated 
component colours, will be given as the return value of the function.

For example, if the program calls a function like {find_color(63,63,0)}, it will
return the colour number of the palette which is the nearest to or identical to this
colour, namely {yellow}.

{/}

{Note:} the function {find_color()} {doesn't modify the current palette}, it just
searches for the defined colours in the palette, to modify a colour of the
palette the function {#179,set_color()} must be used.

{#9999,Example program:}
PROGRAM example_find_colour;

GLOBAL;
    blue;
    green;
    yellow;
    red;

BEGIN

    blue=find_color(0,0,63);      // Search for the colour blue
    green=find_color(0,63,0);     // Search for the colour green
    yellow=find_color(63,63,0);    // Search for the colour yellow
    red=find_color(63,0,0);       // Search for the colour red

    draw(2,blue,15,0,0,0,79,79);
    draw(2,green,15,0,80,0,159,79);
    draw(2,yellow,15,0,160,0,239,79);
    draw(2,red,15,0,240,0,319,79);

    LOOP
        FRAME;
    END
END
{-}

This example uses the function {find_color()} to define the colours
{blue}, {green}, {yellow} and {red} inside of the palette, and then
using the function {#249,draw()}, shows four squares of these colours.

The advantage of using this system is that it doesn't matter if the program 
changes the current palette, because the same colours can always be found.

{/}

To modify the whole palette, the file must be loaded with the
function {#133,load_pal()}.

To create other palette effects, the function {#154,roll_palette()} can be used,
which allows you to create cycles of colour, or the function {#110,fade()}
which allows you to create multiple fades and saturations of colour at different speeds.

{/}See: {#179,set_color()} - {#154,roll_palette()} - {#133,load_pal()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.265,load_screen()}

{load_screen(}<name of the file>{)}

{Description:}

Loads an image file {MAP} or {PCX} into the background of the screen.

If the graphic is a different size (in pixels) to the screen size
the graphic will be printed centred on the screen.

To delete the screen background the function {#103,clear_screen()} must be used.

{/}

It is a function that combines three actions into one:

{1 -} To load a file which contains a map with the background image (using the
function {#174,load_map()} or {#174,load_pcx()}).

{2 -} To establish the image as the background (using {#148,put_screen()}).

{3 -} To delete the previous image file from memory (with {#176,unload_map()} or
{#176,unload_pcx()})

{/}

{#9999,Example program:}
PROGRAM example_load_screen;
BEGIN
    load_screen("help/help.map");
    LOOP
        FRAME;
    END
END
{-}

In the example the background image contained in the file {help.map}
is loaded with the function {load_screen()}.

{/}

{Note:} If you want to print a graphic on a solid part of the screen
or region which is {not centred}, then use the function {#146,put()}
in conjunction with it. The function {#173,xput()} allows, you 
to print graphics rotated, scaled, mirrored and/or transparent
on any region of the screen.

{/}See: {#174,load_map/pcx()} - {#148,put_screen()} - {#176,unload_map/pcx()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.266,force_pal()}

{force_pal(}<name of file>{)}

{Description:}

Loads a colour palette (a file of type PAL, FPG, MAP, PCX or FNT) and
{establishes it as the obligatory palette} for all the graphics and fonts which are
loaded thereafter.

The functioning is very similar to {#133,load_pal()} (which simply loads and
activates a palette) but, once the palette has been loaded with {force_pal()},
{every map, file and font} loaded afterwards {will adapt automatically 
to the current palette}.

The {graphics already loaded} before {force_pal()} was called {won't
be adapted}, and as such, if all the graphics are wanted to be seen with
a unique palette, this function must be called at the beginning of the program.

It is {important} to note that the maps, files & fonts will just adapt in the
computer's memory, the original files remain unaltered, each one with
their own palette.

{/}

{Note:} To stop adapting the loaded graphics to the unique palette, the function 
{force_pal(0)} must be called (indicating a {0} as its parameter, instead of the 
name of a file.

{/}

{#9999,Example program:}
PROGRAM example_force_pal;
BEGIN

    force_pal("help/help.pal");

    // Now all the files, maps and fonts can be loaded 
    // which are wanted, irrespective of their own palette, to be adapted
    // automatically to the current palette.

    // ...

END
{-}

This small example shows how all the graphics can be forced to just one 
palette inside of a program by calling {force_pal()} at the beginning of
program execution.

{/}

A palette can't be deleted from the computer's memory, because this doesn't
take up any space in memory.

{/}See: {#133,load_pal()}

# -----------------------------------------------------------------------------
# Extended information about compiler error messages
# -----------------------------------------------------------------------------

{.500,Insufficient memory.}

There is not {enough memory} to compile the program.

# -----------------------------------------------------------------------------

{.501,ltobj.def was not found}

The <LTLEX.DEF> file has not been found in the DIV directory; this
file is indispensable to compile the programs.

Recover the original file if you have a copy. Otherwise, you will have to reinstall the application.

# -----------------------------------------------------------------------------

{.502,Invalid ltlex.def file.}

The changes made in the <LTLEX.DEF> file {are invalid}. Recover
the original file if you have a copy. Otherwise, you will have to reinstall the application.

# -----------------------------------------------------------------------------

{.503,Invalid ltlex.def file.}

{Too many symbols} have been defined in the <LTLEX.DEF> file. Recover
the original file if you have a copy. Otherwise, you will have to reinstall the application.

# -----------------------------------------------------------------------------

{.504,Invalid ltlex.def file.}

{An invalid symbol} has been defined in the <LTLEX.DEF> file. Recover
the original file if you have a copy. Otherwise, you will have to reinstall the application.

# -----------------------------------------------------------------------------

{.506,ltobj.def was not found}

The <LTOBJ.DEF> file has not been found in the DIV directory; this 
file is indispensable to compile the programs.
 
Recover the original file if you have a copy. Otherwise, you will have to reinstall the application.
 
# -----------------------------------------------------------------------------

{.507,Invalid ltobj.def file.}

The changes made in the <LTOBJ.DEF> file {are invalid}. Therefore, you must recover the original 
file if you have a copy. Otherwise, you will have to reinstall the application. 

# -----------------------------------------------------------------------------

{.510,Unknown character.}

A character that does not belong to any symbol of the language 
and that, moreover, {is not valid} to create a new name was found in the program.

If it is a {#1002,comment} it is necessary to indicate it correctly with a symbol
// at the beginning of the comments of a line, or the symbols /* and */ to
indicate the beginning and the end, respectively, of comments occupying more than one line.

If you intend to create a {#1001,name} you must replace that character by another one among the characters allowed by the language.

{/}See: {#1000,Syntax} - {#1002,Comments}

# -----------------------------------------------------------------------------

{.511,Unclosed literal.}

Literals are {texts in inverted commas}. In the indicated position of the program, a literal starts but it is not closed.

All the literals must be closed in the same line as they started. It is not possible to define literals occupying more than one line.

The literals may start and finish with the character [{#1047,'}] or even with the
character [{#1047,"}] (but they have to start and finish with the same character). There are two ways to include the character [{#1047,"}] in a literal, supposing that the aim is to define a literal containing the text: a"B"c

 - Duplicating the character: "a""B""c"

 - Defining it with the simple inverted comma: 'a"B"c'

It happens the same regarding the character [{#1047,'}], that can be included in a literal if it is duplicated, or if the literal is delimited with the character [{#1047,"}].

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.512,Unknown symbol.}

In the indicated position of the program there is a symbol that does not belong to the language. Check the symbols available in the language to construct the expression correctly.

It is probably a typographic mistake; check the syntax.

{/}See: {#1000,Syntax} 

# -----------------------------------------------------------------------------

{.520,expecting [PROGRAM]}

All the programs must start with the reserved word {PROGRAM} followed by the program name. Before this word, only can appear {#1002,comments} (explanatory texts preceded by the symbol // or between the symbols /* and */)
or the {#1400,compilation options}.

Check if the word has been correctly written, as no difference is made between uppercase and lowercase letters. Therefore, {PROGRAM}, {program}, {Program}, ... are valid words.

{#9999,Example:}
// -------------------
// Listing of my game
// -------------------

PROGRAM my_game;
BEGIN
    LOOP
        FRAME;
    END
END
{-}

{/}See: {#1000,Syntax} - {#1002,Comments} - {#1003,Program's head}

# -----------------------------------------------------------------------------

{.521,expecting the program's name.}

expecting the program's name to come after the reserved word {PROGRAM}.

{#9999,Example:}
PROGRAM program_name;
BEGIN
    //...
END
{-}

The name of this program is {program_name}.

{/}See: {#1000,Syntax} - {#1001,Names} - {#1003,Program's head}

# -----------------------------------------------------------------------------

{.522,The name is not new.}

As a name of the structure, it has been used a name that had already been given to another object previously defined. It can be a name, a constant, a variable, a table, a structure, a process or a function of the program.

It is also possible that you have intended to use the same name inside the program to identify two different objects, or {that a predefined name has been used for another use inside the language}.
In that case, it is possible to access the glossary to see which is the object that this name is referred to.

Anyhow, {that name must be replaced by another similar one}.

{#9999,Example:}
PROGRAM program_name;
GLOBAL
    position=0;
    STRUCT position[9] // Error: The name is not new.
        x, y;
    END
BEGIN
    //...
END
{-}

{/}See: {#1000,Syntax} - {#1001,Names} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.523,expecting [=]}

To define a table, its length is normally indicated in square brackets. If the number of elements of the table is not specified in square brackets, it is necessary to wait for it to be initialised so that the compiler can determine its length.   

A table without a defined length has been found. Thus, after the square brackets ({#1079,[]}) have been closed, the compiler was expecting the symbol {#1073,=} to precede the initialisation of the table.

Indicate the length of the table in square brackets, or assign values to the different positions of the table.

When a table is not initialised, all its positions will be initialised at zero.

{#9999,Example:}
PROGRAM program's_name;
GLOBAL
    table1[3];
    table2[]=2, 4, 6, 8;
    table3[]; // Error: expecting [=].
BEGIN
    //...
END
{-}

In the example, two tables of four positions (0..3), table1
initialised at (0, 0, 0, 0) and table2 initialised at (2, 4, 6, 8) have been defined.

{/}See: {#1000,Syntax} - {#1011,Declaration of table}

# -----------------------------------------------------------------------------

{.525,expecting [)]}

The compiler was  expecting a bracket previously open with the symbol {#1053,)} to be closed at the indicated position.

This error normally appears for one of the two following reasons:

- In an expression, several brackets have been opened and then some of them have not been closed. In this case, the opened brackets must be closed.

- Inside an expression in brackets, any operator has been omitted, then appearing  two operands in a row, for instance, {(2*3 4)}. In this case, it is necessary to indicate the lacking operator.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.526,expecting []]}

The compiler was expecting a square bracket previously opened, with the symbol {#1079,]} to be closed in the indicated position.

This error normally appears for one of the following reasons:

- The opening of a square bracket ({[}) has been indicated in a table or structure and, after having indicated its length or index, it has not been closed. In this case, the symbol {]} must be added in the indicated position.

- On indicating the index of a table or structure, any operator has been omitted, then appearing, two operands in a row, for instance {table[2*3 4]}. It is necessary now to indicate the lacking operator.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.527,An operand was waited for.}

The indicated position in the program is inside the context of an expression and, at this point of the expression, an operand (a value on which it is possible to do some calculations) was waited for. Instead of it, another different element on which it is not possible to do any calculation is given.

There are several causes that can provoke this error, among which the most frequent are the following ones:

- A reserved word of the language has been used as if it was a variable,
for instance {x=global*2;}. In this case, it is possible to check whether it is a reserved word by accessing the glossary.

- An operand has been omitted inside an expression, for instance {x=2+ /y;}.

- A square bracket or a bracket that had not been previously opened has been closed inside an expression, for instance {x=);}.

Anyhow, you must check the {#1000,syntax} of the indicated expression to correctly construct it.

{/}See: {#1000,Syntax} - {#1009,Declaration of data}

# -----------------------------------------------------------------------------

{.528,Unknown name.}

A constant, a variable, a table or a structure is used in the indicated position of the program with the aim of accessing it before having declared it.  

The compiler can not resolve the problem because it does not know the kind of involved object.

All the constants must be defined at the beginning of the program, inside the {#1004,CONST} section.

The variables, tables and structures may be defined inside the
{#1006,GLOBAL}, {#1007,LOCAL} or {#1008,PRIVATE} sections, depending on their scope, but they have always to be defined before being used.

This error frequently appears in the following cases:

- A name has been incorrectly written, for instance;

{#9999,Example:}
PROGRAM my_game;
CONST
    centre=160;
BEGIN
    x=centre; // Error: Unknown name.
    //...
END
{-}

- An object is used before and then declared, for instance:

{#9999,Example:}
PROGRAM my_game;
CONST
    double=simple*2; // Error: Unknown name.
    simple=1;
BEGIN
    //...
END
{-}

  In this case, the two  previous declarations should be exchanged.

- On initialising a table or structure, a comma has been accidentally put after the list of values.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table[]=0, 1, 2, 3,
    a=0; // Error: Unknown name.
BEGIN
    //...
END
{-}

  In this case, the compiler will report this error in the {a} variable, as
it interprets that it is the following value in the list of the table's initialisation, and it is a name that has not been defined yet.

{/}See: {#1000,Syntax} - {#1004,Constants declaration}

# -----------------------------------------------------------------------------

{.529,expecting [BEGIN]}

This error appears when an invalid declaration is made inside the {#1004,CONST}, {#1006,GLOBAL}, {#1007,LOCAL} or
{#1008,PRIVATE} sections.

After the initial statement {#1003,PROGRAM program's_name;} wait for any of the sections previously mentioned to appear (always in the same order), finally appearing the word {#1086,BEGIN}.

After the beginning of a process ({#1016,PROCESS process_name(}...{)})
or function ({#1408,FUNCTION} {name_of_function(}...{)}) wait
for the {#1008,PRIVATE} section or the {#1086,BEGIN} word to be shown.

The error can appear under the following circumstances:

- The name of any section has been incorrectly written.

- Several sections have been put in an incorrect order:

{#9999,Example:}
PROGRAM my_game;
LOCAL
    a=0;
GLOBAL // Error: expecting [BEGIN]
    b=0;
BEGIN
    //...
END
{-}

  Keep in mind that the sections must appear in the following order:

    {CONST}ú
    {#1006,GLOBAL}ú
    {#1007,LOCAL}ú
    {#1008,PRIVATE}ú

- Inside any of the sections previously mentioned, an element that is not a valid declaration inside that section appear. 

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    +variable=0; // Error: expecting [BEGIN]
BEGIN
    //...
END
{-}

  In this example, on reaching the symbol {#1056,+} the compiler determines
that the {#1006,GLOBAL} section has already finished. Therefore, as the following element
is not the beginning of the {#1007,LOCAL} or {#1008,PRIVATE} sections, the compiler is 
expecting the {#1086,BEGIN} reserved word to appear, indicating the beginning of the program code.

- At the beginning of the program or on defining a process, the word {BEGIN} has been omitted.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    //...
END

PROCESS my_process()
    FRAME; // Error: expecting [BEGIN]
END
{-}

{/}See: {#1000,Syntax} - {#1086,BEGIN}

# -----------------------------------------------------------------------------

{.530,A constant expression was waited for.}

To initialise {#1004,constants}, variables, tables and structures it is necessary to use numeric values or expressions whose value may be determined when the program is compiled.

An expression starts in the indicated position. The value of this expression has not been resolved in compilation time, probably because it uses global, local or private data, or because a function is called.

In constant expressions, it is only possible to use:

    - {#1004,Constants} previously defined.ú
    - {Numeric values}.ú
    - Arithmetic or logical {operators}.ú
    - {Literals} (texts in inverted commas).ú
    - The {#1094,sizeof()} function.ú

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    my_variable=4;
    position=2*my_variable; // Error: A constant expression was waited for.
BEGIN
    //...
END
{-}

In this example, {position} can not be initialised, as the {x} local variable is being used for that purpose.

{/}See: {#1000,Syntax} - {#1005,Definition of constants}

# -----------------------------------------------------------------------------

{.531,The table has been exceeded.}

The constant expression that starts in the indicated position of the program can not be calculated, as in it you access a table or structure out of its range of positions.

Check the range of the table or structure in its definition.
Keep in mind that a table defined, for instance, as {table[10]}
has {11} positions (from table[0] to table[10]).

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table[]=1, 3, 5;
    value=table[3]; // Error: The table has been exceeded.
BEGIN
    //...
END
{-}

In this example, the {value} variable can not be initialised as an non-existent table position is being used for this purpose.

{/}See: {#1000,Syntax} - {#1011,Declaration of table}

# -----------------------------------------------------------------------------

{.532,The offset can not be calculated.}

In the expression indicated in the program, the {#1085,offset} operator (or the {#1085,&} synonymous symbol) is used with the aim of obtaining the address (offset) of an object. That object has no address, as it is not a variable, a table or a structure. Therefore, the compiler can not resolve the expression.

Probably you have intended to obtain the address of a constant expression or an expression involving several operands.

Now, a program is shown with several examples of valid and invalid uses of the {#1085,offset} operator.

{#9999,Example:}
PROGRAM my_game;
CONST
    my_constant=0;
GLOBAL
    my_offset=0;
    my_variable=0;
    my_table[10];
    STRUCT my_structure[10]
        variable;
    END
BEGIN
    // Correct examples
    my_offset=offset my_variable;
    my_offset=offset my_table;
    my_offset=offset my_table[my_variable];
    my_offset=offset my_structure[0].variable;
    my_offset=offset id.x;

    // Invalid examples
    my_offset=offset (my_variable*2);
    my_offset=offset my_constant;
    my_offset=offset 0;
    write_int(0, 0, 0, 0, offset (my_variable+1));
END
{-}

There is no difference between the use of the {#1085,offset} reserved word
or the symbol {&}.

The {#1005,constants} such as {my_constant} have no offset as they are just
synonymous of the numeric value they represent.

The statement {my_offset=offset (my_variable*2);} is invalid as the multiplication is made at first and, once it has been done, the {my_variable*2} value is transformed into a numeric result that has no assigned address.

Unlikely, the {offset my_variable*2} expression is valid as, in this case, the address of {my_variable} is obtained at first and then, this address will be multiplied by {2}.

{/}See: {#1000,Syntax} - {#1085,offset}

# -----------------------------------------------------------------------------

{.533,Too many values for the table.}

A table has been initialised with more values than it can contain.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table1[3]=0, 1,2 , 3, 4; // Error: Too many values for the table.
BEGIN
    //...
END
{-}

To initialise a table take into account that, at the most, it can have as many values as the number in square brackets plus 1 indicates.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table1[3]=2, 4, 6, 8;
BEGIN
    //...
END
{-}

In this case, the table {table1} may contain four values (table1[0]=2,
table1[1]=4, table1[2]=6 and table1[3]=8).

Another option is {not to indicate the size of the table}, so the compiler will deduce it from its initialisation.  

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table1[]=2, 4, 6, 8;
BEGIN
    //...
END
{-}

In this case, if it was necessary to refer to the table's length inside the program,  
the {sizeof(table1)} expression should be used, being equal to {4} in this example.

{/}See: {#1000,Syntax} - {#1011,Declaration of table} - {#1094,sizeof()}

# -----------------------------------------------------------------------------

{.534,Division by 0.}

In the indicated position of the program, a {#1005,constant expression} unresolved because it contains a division by 0 among its operations, appears.

On dividing a number by zero results ñ infinite and, as in the programming language only integers within the range ({#1177,min_int} ... {#1178,max_int}) can be used, it is not possible either to store the result of that operation in any variable or to relate it with a constant.

{#9999,Example:}
PROGRAM my_game;
CONST
    infinite=1/0; // Error: Division by 0.
BEGIN
    //...
END
{-}

It is probably an involuntary error. Thus, on evaluating the expression it is necessary to avoid doing any division by zero.

{/}See: {#1000,Syntax} - {#1019,Statement of assignment}

# -----------------------------------------------------------------------------

{.535,Table of negative length.}

To define a table indicating in square brackets its length, it is necessary to use a positive integer (0, 1, 2, 3, ...), taking into account that all the tables start in the zero position and finish in the position indicated in the index.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table1[9];
    table2[-9]; // Error: Table of negative length.
BEGIN
    //...
END
{-}

The compiler has detected a table defined with a negative length such as {table2}. In this example, it is necessary to define the table such as
{table1} that, in this case, will be a table of 10 positions (from
table1[0] to table1[9]).

{/}See: {#1000,Syntax} - {#1011,Declaration of table}

# -----------------------------------------------------------------------------

{.536,expecting [(]}

The compiler is expecting a bracket with the {#1053,(} symbol to be opened in the indicated position of the program.

There are many cases in which the opening of a {#1053,bracket} is obligatory:

- {After a process name or a function}, its call parameters must always be indicated in brackets. Even when the process or the function have no parameters, a bracket must be opened and, later, closed.  

{#9999,Example:}
PROGRAM my_game;
BEGIN
    my_process();
    //...
END
PROCESS my_process()
BEGIN
  //...
END
{-}

- {In the control statements requiring a condition} to control the program's flow, that condition must be put in brackets.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    IF (x<10)
        //...
    END

    WHILE (x<10)
        //...
    END

    REPEAT
        //...
    UNTIL (x<10)

    SWITCH (x)
        //...
    END

    FOR (x=0;x<10;x++)
        //...
    END
END
{-}

  In this example, it is possible to see how the different control statements indicate the condition in brackets. There are two exceptions:

  - The {#1021,SWITCH} statement does not require a condition, but a simple expression, which must be in brackets, anyhow.

  - The {#1025,FOR} statement has three parts inside the brackets, separated
by  semicolons. These parts are the following ones: initialisation ({x=0}),
condition ({x<10}) and increment ({x++}).

- {After the {#1089,DUP} operator} (used to initialise
tables and structures) it is also obligatory to open a bracket.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table1[]=10 dup (1, 2, 3);
BEGIN
    //...
END
{-}

  In this example, table1 would be a table of 30 positions (from table1[0]
to table1[29]) initialised in the following way: 1, 2, 3, 1, 2, 3, ...

{/}See: {#1000,Syntax} - {#1053,( )}

# -----------------------------------------------------------------------------

{.538,Only can be repeated once or twice.}

The {#1089,DUP} operator used to initialise tables and
structures allows us to repeat (duplicate) a sequence of
values a specific number of times: from once (in this case, the operator is useless) to an undetermined positive number of times.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table1[]=10 dup (1, 2, 3);
    table2[]=-10 dup (1, 2, 3); // Error: Only can be repeated once or twice.
BEGIN
    //...
END
{-}

In this example, table1 would be a table of 30 positions (from table1[0]
to table1[29]) initialised in the following way: 1, 2, 3, 1, 2, 3, ...

It is also possible, moreover, to omit the {#1089,DUP} operator. In this case, the declaration of table1 would become as follows:

  {table1[]=10(1, 2, 3);}

The effect is exactly the same as in the previous example. That is to say,
when the compiler is in a table's initialisation, the {number (sequence_of_values ... )} sequence interprets that you intend to repeat the {sequence_of_values} the {number} of times indicated.

Therefore, it is not possible to repeat a sequence of values zero times or a negative number of times.

{/}See: {#1000,Syntax} - {#1089,DUP}

# -----------------------------------------------------------------------------

{.539,Invalid assignment.}

The indicated assignment can not be done in this position of the program.
In an assignment statement it is only allowed to assign values to
objects such as variables (of any kind), to a position of a table, or to an element of a structure.

It is not possible to assign a value to a {#1004,constant}, a
function or to a process or, in general, to any numeric or logical expression.

The following program shows examples of several kinds of invalid assignments:

{#9999,Example:}
PROGRAM my_game;
CONST
    my_constant=0;
BEGIN
    my_constant=1;  // Error: Invalid assignment.
    type my_game=2; // Error: Invalid assignment.
    sizeof(mouse)=3; // Error: Invalid assignment.
    4+5=6;           // Error: Invalid assignment.
    //...
END
{-}

All these assignments are invalid because the result of an expression, which is just a numeric value, can not be modified with an assignment. Thus, it is the same as to put a statement of the kind {2=4;} that, obviously, is impossible.

{/}See: {#1000,Syntax} - {#1035,Definition of expression}

# -----------------------------------------------------------------------------

{.540,expecting [END]}

A block of statements is waited for inside the {#1086,BEGIN} and {#1091,END} reserved words, as well as inside statements such as the following ones:
  {#1020,IF} ... {#1090,ELSE} ... {#1091,END}ú
  {#1024,LOOP} ... {#1091,END}ú
  {#1022,WHILE} ... {#1091,END}ú
  {#1025,FOR} ... {#1091,END}ú
  {#1043,FROM} ... {#1091,END}ú
  {#1021,SWITCH} ... {#1091,END}ú

A block of statements finishes (and only can finish) with any of these three reserved words: {#1091,END}, {#1097,UNTIL} or {#1090,ELSE}.

In the program, there is a block expected to finish with the {#1091,END} reserved word, but it finishes with another word. The two more usual cases are the following ones:

- That a {#1023,REPEAT} or a {#1020,IF} have been lost, finishing the statements block with a {#1097,UNTIL} or a {#1090,ELSE}. In this case, the {#1023,REPEAT} or {#1020,IF} associated must be looked for.

{#9999,Example:}
PROGRAM my_game;
BEGIN
//  REPEAT
    //...
    UNTIL (key(_esc)); // Error: expecting [END].
END
{-}

  In this example, the statements block that started with the {#1086,BEGIN}
of the main program has finished with an {#1097,UNTIL} (because the
{#1023,REPEAT} has been accidentally commented), and the compiler was expecting this block to finish with an {#1091,END}.

- That an {#1091,END} of any statement has been lost and the following {#1016,PROCESS} or the end of the program expecting the END that has been lost is reached.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    IF (x<0) x++;
END
PROCESS my_process() // Error: expecting [END].
BEGIN
    //...
END
{-}

  In this case, the {#1091,END} of the {#1020,IF} has not been put, interpreting the compiler that the {#1020,IF} finishes when the following {#1091,END}
(the one of {#1086,BEGIN}) is reached and, therefore, when the new {#1016,PROCESS} or {#1408,FUNCTION 
comes, it goes on expecting the {#1091,END} of the {#1086,BEGIN}.

{/}See: {#1000,Syntax} - {#1091,END}

# -----------------------------------------------------------------------------

{.541,Invalid expression.}

In the indicated position of the program there is an expression incorrectly constructed, so the compiler can not interpret it.

- Check the {#1000,syntax} of the expression.

- If the error is not found, try to express it in a different way.

- Try to divide the expression into several subexpressions, sequentially and separately doing the different calculations done in the original expression. For instance, the expression:

  {x=(x*4+1)/2;}

  can be expressed as the three following expressions:

  {x=x*4;}ú
  {x=x+1;}ú
  {x=x/2;}ú

  Thus, it is possible to locate the exact point in which the operation that can not be done is.

{/}See: {#1000,Syntax} - {#1035,Definition of expression}

# -----------------------------------------------------------------------------

{.542,expecting [UNTIL]}

A block of statements that started with the reserved word {#1023,REPEAT}
must necessarily finish with the word {#1097,UNTIL}. In the indicated position
of the program, the block of statements has finished with a
different word. So probably:

- A {#1023,REPEAT} has finished with an {#1091,END}. In this case,
if  you intend to create a loop indefinitely, the {#1024,LOOP} ... {#1091,END} statement must be used.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    REPEAT
    //...
    END // Error: expecting [UNTIL]
END
{-}

- Inside the {#1023,REPEAT} ... {#1097,UNTIL} loop will appear a spare word such as {#1091,END} or {#1090,ELSE} without its corresponding beginning ({#1020,IF}, {#1022,WHILE}, ...).

{#9999,Example:}
PROGRAM my_game;
BEGIN
    REPEAT
        IF (x<0) x++; END
            y++;
        END // Error: expecting [UNTIL]
    UNTIL (x>=0);
END
{-}

  In this case, the {#1091,END} of the {#1020,IF} has been put twice,
interpreting the compiler that the second {#1091,END} intends to close the {#1023,REPEAT}.

- Or finally, that you have forgotten to put the {#1097,UNTIL} of the {#1023,REPEAT}.

{/}See: {#1000,Syntax} - {#1023, Statement REPEAT} - {#1020,IF} - {#1022,WHILE}

# -----------------------------------------------------------------------------

{.543,Local variable that can not be accessed.}

In the indicated position of the program, the aim is to access a variable
of another process. But this is not possible, as this variable is not local
in the other process.

It is necessary to verify that the variable intended to access either is defined inside the {#1007,LOCAL} section of the program, or is a local variable predefined in the language (such as {#1123,x}, {#1124,y}, {#1126,graph},
{#1128,size}, ...).

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    id_my_process;
    score=0;
BEGIN
    id_my_process=my_process();
    id_my_process.x=0;
    id_my_process.score=0; // Error: Local variable that can not be accessed.
END
PROCESS my_process()
BEGIN
    //...
END
{-}

In this case, the aim is to access the {score} of {my_process}, but
{score} is just a single {#1006,GLOBAL} variable and not a {#1007,LOCAL}
variable of every process. This can also happen by trying to access a constant
(defined in {#1005,CONST}) or an expression like:

  {x=id_my_process.(x+1);}

In this example, the expression makes no sense at all. The following expression would probably be the one intended to be used:

  {x=id_my_process.x+1;}

  (equivalent to {x=(id_my_process.x)+1;}).

{/}See: {#1000,Syntax} - {#1007,Declaration of local data}

# -----------------------------------------------------------------------------

{.544,Invalid parameter.}

The processes can receive parameters in the following kinds of data:

- A predefined local variable (like {#1123,x}, {#1128,size}, {#1127,flags}, ...).

- A local variable defined inside the {#1007,LOCAL} section.

- A global variable defined inside the {#1006,GLOBAL} section.

- A private variable of the process declared inside the {#1008,PRIVATE} section
of the process.

- A private variable {not declared} inside the {#1008,PRIVATE} section.

In all these cases, it is understood that a variable can be referred to a
variable, to a specific position of a table or to an element inside a structure.

In the indicated position of the program, the aim is either to receive a parameter in an object different from those aforementioned, or to indicate an expression instead of a simple variable. These are some examples of invalid parameters' declarations:

  {PROCESS my_process(my_constant)}ú
  A parameter can not be received in a constant.

  {PROCESS my_process(x*2)}ú
  A parameter can not be received in an expression.

  {PROCESS my_process(x=0)}ú
  A parameter can not be received in an assignment.

{/}See: {#1000,Syntax} - {#1018,Parameters of a process}

# -----------------------------------------------------------------------------

{.545,expecting another parameter.}

In the calls to processes or functions, it is necessary to put as many values or expressions as parameters are required, all of them inside the same {#1053,bracket} and separated by {#1059,commas (,)}. This error appears when the bracket is closed after a {#1059,comma}, as in the following example:

{#9999,Example:}
PROGRAM my_game;
BEGIN
    signal(id, ); // Error: expecting another parameter.
END
{-}

There are two reasons for that: either a comma has been accidentally put after the last parameter, or the last parameter has been omitted (like in the previous example).

{/}See: {#1000,Syntax} - {#1018,Parameters of a process}

# -----------------------------------------------------------------------------

{.546,Invalid number of parameters.}

The process or function has a number of parameters different from the one that appears in the indicated position of the program.

If it is a function, access {Glossary} to consult the required parameters
or place the cursor on the name of the function in the program and then press {F1}.

If it is a {process}, then it is possible that in the indicated position, the number of parameters is correct, but a call to this process has previously appeared in the program with a different number of parameters.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    my_process();
END
PROCESS my_process(x, y) // Error: Invalid number of parameters.
BEGIN
    //...
END
{-}

In this example, the error is not in the definition of the process as it is shown,
but in the previous call to that process ({my_process();}). This is like this because when the compiler finds a call to a process that does not know, it records it like a new process and notes down its number of parameters.
If the next time it finds that process the number of parameters does not coincide with those it had recorded, then the error appears.

Therefore, if the call or definition of the process shown in the program is correct, then use the search option ({ALT-F}) to check the number of parameters in the previous calls to that process.

{/}See: {#1000,Syntax} -  {#1018,Parameters of a process}

# -----------------------------------------------------------------------------

{.547,expecting [;]}

The {#1024,FOR} statement has three parts inside the brackets separated by semicolons. These parts are the following ones:

  FOR ({initialisation}; {condition}; {increment})

- The {initialisation} is normally an {#1019,assignment} that sets the value of a variable when the {#1025,FOR} statement starts to run.

- The condition secondly established determines the continuance inside the loop. In every iteration it will be checked first whether this condition is complied with. Otherwise, the execution of the {#1025,FOR} statement will finish.

- The {increment} updates the variable's value that is used as a counter after every iteration of the loop.

None of these three parts are obligatory, except the brackets and the two symbols {#1068,semicolon (;)} that separate the parts.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FOR ( graph=10 ; graph<20 ; graph=graph+1 )
        //...
    END
    FOR ( graph=10 ; graph<20 graph=graph+1) // Error: expecting [;]
        //...
    END
END
{-}

Several statements can be put inside every of the three parts providing that they are separated by {#1059,commas (,)} (several initialisations, conditions or
increments).

{/}See: {#1000,Syntax} - {#1068, Semicolon (;)} - {#1025,Statement FOR}

# -----------------------------------------------------------------------------

{.548,[BREAK] does not appear inside a loop.}

The {#1026,BREAK} statement makes the program continue after the loop that is running.

This statement is used to exit the following loops:

  {#1024,LOOP} ... {#1091,END}ú
  {#1043,FROM} .. {#1096,TO} .. {#1095,STEP} .. ... {#1091,END}ú
  {#1023,REPEAT} ... {#1097,UNTIL} {#1053,(} .. {#1053,)}ú
  {#1022,WHILE} {#1053,(} .. {#1053,)} ... {#1091,END}ú
  {#1025,FOR} {#1053,(} .. {#1068,;} .. {#1068,;} .. {#1053,)} ... {#1091,END}ú

A {#1026,BREAK} statement will make the program continue to be executed after the {#1091,END} or {#1097,UNTIL} of the loop closest to the statement.
{#1026,BREAK} can only appear inside one of these loops.

If there are several nested loops (one inside another one) the {#1026,BREAK} statement will exit the inner loop.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    LOOP
        REPEAT
            IF (key(_esc)) BREAK; END
            //...
        UNTIL (x==0);
        //...
    END
    BREAK; // Error: [BREAK] does not appear inside a loop.
END
{-}

In this example the {#1026,BREAK} statement will exit {#1023,REPEAT} ... {#1097,UNTIL} (when the {ESC} key is pressed)
but not {#1024,LOOP} ... {#1091,END}.

{/}See: {#1000,Syntax} - {#1026,Statement BREAK}

# -----------------------------------------------------------------------------

{.549,[CONTINUE] does not appear inside a loop.}

The {#1027,CONTINUE} statement makes the program finish the current iteration of the loop that is running.

This statement is used to go to the beginning/end of the following loops:

{#1024,LOOP} ... {#1091,END}ú
A {#1027,CONTINUE} statement inside this loop will jump to {#1024,LOOP}.

{#1043,FROM} .. {#1096,TO} .. {#1095,STEP} .. ... {#1091,END}ú
A {#1027,CONTINUE} statement inside this loop will make the increment ({#1095,STEP}) and, if the value indicated in the {#1096,TO} has not been passed, the program will continue at the beginning of the loop.

{#1023,REPEAT} ... {#1097,UNTIL} {#1053,(} .. {#1053,)}ú
A {#1027,CONTINUE} inside this loop will jump to {#1097,UNTIL}.

{#1022,WHILE} {#1053,(} .. {#1053,)} ... {#1091,END}ú
A {#1027,CONTINUE} inside this loop will jump to {#1022,WHILE}.

{#1025,FOR} {#1053,(} .. {#1068,;} .. {#1068,;} .. {#1053,)} ... {#1091,END}ú
A {#1027,CONTINUE} inside this loop will make the increment
and the comparison. If the latter is true, the program will continue at the beginning of the loop. But if it is false, the program will continue after the {#1091,END} of the {#1025,FOR}.

{#1027,CONTINUE} {must obligatory appear inside one of these loops}.

If there are several nested loops (one inside another) the {#1027,CONTINUE} statement will take effect only in the inner loop.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FOR (x=0, y=0;x<10;x++)
        IF (x<5) CONTINUE; END
        y++;
    END
END
{-}

In this example, after the whole loop has been executed, {x} will be equal to {10} and {y} will be equal to {5} as, providing that {x} is less than 5, the {#1027,CONTINUE} statement prevents the {y++;} statement from being executed.

{/}See: {#1000,Syntax} - {#1027,Statement CONTINUE}

# -----------------------------------------------------------------------------

{.550,expecting [CASE], [DEFAULT] o [END]}

The syntax of the {#1021,SWITCH} statement is, broadly speaking, as follows:

    {#1021,SWITCH} {#1053,( }expression{#1053, )}ú
        {#1087,CASE} value{#1067, :}ú
            statements{#1068,;}ú
        {#1091,END}ú
        {#1087,CASE} value{#1064, .. }value{#1067, :}ú
            statements{#1068,;}ú
        {#1091,END}ú
        {#1087,CASE} value, value, value{#1067, :}ú
            statements{#1068,;}ú
        {#1091,END}ú
        //...ú
        {#1088,DEFAULT} {#1067,:}ú
            statements{#1068,;}ú
        {#1091,END}ú
    {#1091,END}

The position indicated in the program is inside a {#1021,SWITCH} statement,
but out of a {#1087,CASE} or {#1088,DEFAULT} section. For that reason, the compiler was expecting one of the three following statements to appear in that position:

- The reserved word {#1087,CASE} starting a new section to be executed
when the expression would coincide with the indicated value.

- The reserved word {#1088,DEFAULT} starting a section by default to be executed when the expression would not coincide with any of the values
indicated in the different sections {#1087,CASE}.

- The reserved word {#1091,END} finishing the {#1021,SWITCH} statement.

For a more detailed description of the {#1021,SWITCH} statement,
consult the syntax of the language.

{/}See: {#1000,Syntax} - {#1021,Statement SWITCH}

# -----------------------------------------------------------------------------

{.551,expecting [END]}

An {#1091,END} of the {#1087,CASE} or {#1088,DEFAULT} was waited for inside the {#1021,SWITCH} statement.

Inside the reserved words {#1021,SWITCH} and {#1091,END} one or more sections of the following kind were waited for:

  {#1087,CASE} ... {#1091,END}ú
  {#1088,DEFAULT} ... {#1091,END}ú

In the program, there is one of these sections that was expected to finish with the reserved word {#1091,END}, but it finishes with another word. The most usual case is the following one:

- That a {#1023,REPEAT} or a {#1020,IF} have been lost, finishing the block
of statements with an {#1097,UNTIL} or an {#1090,ELSE}. In this case, the associated {#1023,REPEAT} or {#1020,IF} must be looked for.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    SWITCH (x)
        CASE 0:
            //REPEAT
            //...
            UNTIL (key(_esc)); // Error: expecting [END]
        END
    END
END
{-}

In this example, the section that started with {#1087,CASE} has finished with {#1097,UNTIL} (because {#1023,REPEAT} has been accidentally commented), and the compiler was expecting this section to finish with {#1091,END}.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.552,expecting [PROCESS]} or [FUNCTION]}

The compiler has interpreted that, in the indicated position of the program, the main program ({#1015,PROGRAM} ... {#1086,BEGIN} ... {#1091,END}), or the last process ({#1016,PROCESS} or function ({#1408,FUNCTION}) and have finished and then, it was expected that either a process would start or the program would finish.

The most frequent is to have duplicated {#1091,END} inside the last block of statements {#1086,BEGIN} ... {#1091,END}.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    IF (x<0) x++; END
    END
    FRAME; // Error: expecting [PROCESS].
END
{-}

In this example, the {#1091,END} of the {#1020,IF} has been accidentally put twice, interpreting the compiler that the second is that of {#1091,END}
of the {#1086,BEGIN}. Therefore, after this last {#1091,END} only
the end of the program or the reserved word {#1016,PROCESS} or {#1408,FUNCTION} 
can come, marking the beginning of a new process. When a {#1029,FRAME} statement is placed in that position, the compiler reports the error.

{/}See: {#1000,Syntax} - {#1016,Declaration of process}

# -----------------------------------------------------------------------------

{.553,A table can not be specified as a parameter.}

It is not necessary to declare the {#1018,parameters of the process} inside the {#1008,PRIVATE} section, as they are automatically declared. But if they are declared, they must be declared as variables, not as tables or structures, and they must not be initialised.

You have probably intended to use the same name for two different objects. On the one hand, for the parameter of the process and, on the other hand, for a {#1008,PRIVATE} table of the same process.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    //...
END
PROCESS my_process(a)
PRIVATE
    a[9]; // Error: A table can not be specified as a parameter.
BEGIN
    //...
END
{-}

The compiler interprets that the parameter {a} is being typified as a table of 10 positions and, since a table can not be passed as a parameter, it reports the error.

{/}See: {#1000,Syntax} - {#1018,Parameters of a process}

# -----------------------------------------------------------------------------

{.554,A parameter can not be initialised.}

It is not necessary to declare the {#1018,parameters of the process} inside the {#1008,PRIVATE} section, as they are automatically declared. But if they are declared, they must be declared as variables, not as tables or structures, and they must not be initialised.

You have probably intended to use the same name for two different objects. On the one hand, for the parameter of the process and, on the other hand, for a {#1008,PRIVATE} variable of the same process.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    //...
END
PROCESS my_process(a)
PRIVATE
    a=0; // Error: A parameter can not be initialised.
BEGIN
    //...
END
{-}

The compiler interprets that the parameter {a} is being initialised at {0}
and, as it is not allowed to initialise a parameter (as it will take its value depending on the call to the process), the error is reported.

{/}See: {#1000,Syntax} - {#1018,Parameters of a process}

# -----------------------------------------------------------------------------

{.555,The end came inside a comment.}

The end of the program has come inside a comment of several lines
(those defined between the{#1002, /*} and{#1002, */} symbols).

This error appears because any comment has not been closed. Therefore, check that all the comments opened with the{#1002, /*} symbol have their corresponding{#1002, */} symbol closing them.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    /* Beginning of the comment
    FRAME;
END // Error: The end came inside a comment.
{-}

{/}See: {#1000,Syntax} - {#1002,Definition of comments}

# -----------------------------------------------------------------------------

{.556,It is not possible to access external PRIVATE data.}

In the indicated position of the program, there is an attempt to access a {#1008,PRIVATE} variable of another process. It is not allowed.

If the aim is to access a variable of a process from another process, this variable must be declared inside the {#1007,LOCAL} section.

{#9999,Example:}
PROGRAM my_game;
PRIVATE n;
BEGIN
    my_process();
    //...
END
PROCESS my_process()
PRIVATE n;
BEGIN
    father.n=0; // It is not possible to access external PRIVATE data.
END
{-}

It is not possible to access {#1008,PRIVATE} data, even when the accessed process is of the same kind as the process that is trying to access the variable.

The correct way to declare the variable {n} in the previous example is as follows:

{#9999,Example:}
PROGRAM my_game;
LOCAL n;
BEGIN
    my_process();
    //...
END
PROCESS my_process()
BEGIN
    father.n=0;
END
{-}

Keep in mind that all the processes of the program will have the data declared inside the {#1007,LOCAL} section (all the processes of the previous example
will have an own variable named {n}).

{/}See: {#1000,Syntax} - {#1008,Declaration of PRIVATE data}

# -----------------------------------------------------------------------------

{.557,A structure must contain one element, at least.}

In the indicated position of the program, the aim is to close the declaration of a structure without any element (field) defined in it with {#1091,END}.

A structure ({#1012,STRUCT}) is like a list of index cards
(records) with several pieces of information (fields) in every index card.

{STRUCT name_structure[10]}ú
    {x, y;}ú
{END}

In this example, the structure (set of index cards) is called {name_structure}
and it has {10 records} (ten index cards) with {2 fields} each one (with two pieces of information; {x} and {y}).

Therefore, defining a structure without fields makes no sense (since it is the same as defining a set of index cards with no piece of information).

Then, to access the information of the index cards, the structure is used as follows (suppose that in the global variable {n} the aim is to put the value
{y} of the index card number {5}).

{n=name_structure[5].y;}

An invalid program is shown now.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT my_structure[10]

    END // Error: A structure must contain one element, at least.
BEGIN
    //...
END
{-}

{/}See: {#1000,Syntax} - {#1012,Declaration of structure}

# -----------------------------------------------------------------------------

{.558,expecting an element of the structure.}

In the indicated position of the program, the aim is to declare an invalid element (field) of the structure.

A structure can just have the following kind of fields:

- A variable. In this case, the name of the declaration without being initialised must be indicated.

- A table, indicating its name and, subsequently, its length in square brackets (keep in mind that a table declared like {my_table[9];} is a table of {10} positions, from my_table[0] to my_table[10]). They must not be initialised.

- Another structure. It is possible to include as many structures inside other structures as necessary, with no limit of nesting. An example of structures nesting is shown now.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT my_structure[9]
        elements;
        STRUCT data[9]
            x, y;
        END
    END
    a, b;
BEGIN
    FROM a=0 TO 9;
        my_structure[a].elements=-1;
        FROM b=0 TO 9;
            my_structure[a].data[b].x=-1;
            my_structure[a].data[b].y=-1;
        END
    END
    //...
END
{-}

In this example, every record of {my_structure} will have a variable
called {elements} and another structure with 10 elements, each one with two
variables: {x} and {y}.

Next, in the same example, it is possible to see an example of access
to that structure with two nested loops that initialise all the values of the structure at{ -1}.

To see how to initialise the values of a structure in the definition itself, go to the topic {#1000,syntax}.

{/}See: {#1000,Syntax} - {#1012,Declaration of structure}

# -----------------------------------------------------------------------------

{.560,It is not a type of process.}

The {#1042,TYPE} operator may only be used if it goes before a process name of the program or the word {#1100,mouse} (to detect collisions with the mouse pointer).

In the indicated position of the program, it is not preceding a process name. It is probable either that the process name has been incorrectly written or that the type of a process is intended to be obtained from its {#1039,identifying code}.

There is a way to obtain the type of a process having its {#1039,identifying code}, as it is shown below (suppose that we have the identifier in the {id2} variable).

    {id2.reserved.process_type}

Instead of {TYPE id2} that is not allowed (as there is no process
named {id2}, since {id2} is a variable).

Next, an example of correct use of the {#1042,TYPE} operator is shown
(with the aim of obtaining the {#1039,identifying code} of a process).

{#9999,Example:}
PROGRAM my_game;
PRIVATE
    id2;
BEGIN
    //...
    id2=get_id(TYPE my_process);
    //...
    id2=get_id(TYPE id2); // Error: It is not a type of process.
    //...
END
PROCESS my_process()
BEGIN
    //...
END
{-}

As it can be noticed, the {#1042,TYPE} operator requires the process name of the program with no brackets or parameters.

{/}See: {#1000,Syntax} - {#1042,Types of processes}

# -----------------------------------------------------------------------------

{.561,The size can not be calculated.}

The {#1094,sizeof()} function may be used to obtain the number of elements of a table or structure. For that purpose, it requires in {#1053,brackets}, the name of the table or structure (with no square brackets or index).

It can also be used with the name of a variable but, in this case,
the function will always return 1.

It can indistinctly be used with global, local or private data.

In the indicated position of the program, the aim is to obtain the size of an object that is not a variable, table or structure. For instance, this error
will appear if the aim is to obtain the size of a constant, function, process, etc.

{#9999,Example:}
PROGRAM my_game;
CONST
    my_constant=99;
GLOBAL
    a=sizeof(my_constant); // Error: The size can not be calculated.
BEGIN
    //...
END
{-}

This example will provoke the error on trying to obtain the number of elements
of a {#1004,constant}, as a constant is not an object having a size, but just a synonymous of the numeric values that it represents.

{/}See: {#1000,Syntax} - {#1094,sizeof}

# -----------------------------------------------------------------------------

{.562,Use: import "name.dll"}

The compiler was expecting the file name to appear in inverted commas after the reserved word {#1014,IMPORT}.

To declare the use of an external library, it is necessary to put a declaration
like that of the following example.

{#9999,Example:}
PROGRAM my_game;
IMPORT "library.dll";
BEGIN
    //...
END
{-}

This program declares the use of the library called {library.dll}
(alleged name of an hypothetical library of external functions).

This declaration must be put just before the {#1008,PRIVATE} section or the
{#1086,BEGIN} of the main program. It is possible to make several {#1014,IMPORT} declarations in a row to declare the use of more than one library

{/}See: {#1000,Syntax} - {#1014,Declaration of libraries}

# -----------------------------------------------------------------------------

{.563,Use of an invalid external DLL.}

In the indicated position of the program, the aim is to load an invalid {DLL}, which is explained for the following reasons:

- The file with the {DLL} has become corrupted because it has been stored in a damaged environment.

- It is not a {DLL} specifically designed for DIV Games Studio.

- The file with extension {DLL} is not found in the path specified by the {#1014,IMPORT} statement.

It is not possible to use {DLL} of other languages, as they are not compatible with this language even if all the files have the extension {DLL}.

When this {DLL} has been prepared for this language, check the installation instructions and verify either that the file with extension {DLL} is in the directory of DIV Games Studio, or that the {#1014,IMPORT} statement specifies the complete path of that file.

{/}See: {#1000,Syntax} - {#1014,Declaration of libraries}

# -----------------------------------------------------------------------------

{.564,Expression with no sense.}

In the indicated position of the program, the compiler has supposed that a statement of the following types started:

    Assignments, e.g.:ú
    <data>{ = }<expression>{ ; }

    Increments or decrements, e.g.:ú
    <data>{ ++ ;}

    Call to a process or function, e.g.:ú
    <name_process>{ ( }...{ ) ;}

Nevertheless, it has found an expression that apparently makes no sense, as once its operations have been done, its result is not used for any purpose.

It is probably an isolated operator that has been left out of a statement, for instance, because an operator has been lost.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    x+1; // Error: Expression with no sense.
    //...
END
{-}

This error is reported in this example, as the {x+1;} statement is not useful; it adds the {x} variable and the constant {1} but then, this result is not used for any purpose. If the aim is to add {1} to the {x} variable, then the following statement must be used:

    {x=x+1;}

Here, the {x} variable and the constant {1} are added and then this result is assigned to the {x} variable. It could have also been done with the {x++;} statement (incrementing x).

{/}See: {#1000,Syntax} - {#1019,Statement of assignment}

# -----------------------------------------------------------------------------

{.565,expecting [:]}

The indicated position in the program is inside a {#1021,SWITCH} statement,
after the beginning of a section with "{#1087,CASE} value". For that reason, the compiler was expecting the symbol{#1067, :} to appear in this position preceding the statements of that section.

The syntax of the {#1021,SWITCH} statement is, broadly speaking, as follows:

    {#1021,SWITCH} {#1053,( }expression{#1083, )}ú
        {#1087,CASE} value{#1067, :}ú
            statements{#1068,;}ú
        {#1091,END}ú
        {#1087,CASE} value{#, .. }value{#1067, :}ú
            statements{#1068,;}ú
        {#1091,END}ú
        {#1087,CASE} value, value, value{#1067, :}ú
            statements{#1068,;}ú
        {#1091,END}ú
        //...ú
        {#1088,DEFAULT} {#1067,:}ú
            statements{#1068,;}ú
        {#1091,END}ú
    {#1091,END}

For a more detailed description of the {#1021,SWITCH} statement,
consult the syntax of the language.

{/}See: {#1000,Syntax} - {#1021,Statement SWITCH}

# -----------------------------------------------------------------------------

{.566,expecting [;]}

The compiler is expecting a {#1068,semicolon (;)} in the indicated position of the program.

In the language, the following points of the program must be indicated with semicolons:

- The end of the {#1400,options of compilation}.

- The end of the {#1003,declaration PROGRAM}.

- The end of a {#1009,declaration of data}.

- The end of a {#1014,declaration IMPORT}.

- The end of the following statements:ú
    {#1019,Assignments or increments of data}.ú
    {#1033,Calls to processes}.ú
    {#1032,Calls to functions}.ú
    {#1029,FRAME}, {#1028,RETURN}, {#1031,DEBUG}, {#1026,BREAK} and {#1027,CONTINUE}.ú

- The end of the beginning of a loop {#1043,FROM}.

- And as division of the different parts of a {#1025,FOR} statement.

The compiler will indicate when the symbol {;} is missing in any of these periods.

Moreover, this symbol can be put in other specific points of the programs. For instance, after any other type of statement, even if, in this case, it will be optional and, therefore, the compiler will not notice its lack.

{/}See: {#1000,Syntax} - {#1068, ; }

# -----------------------------------------------------------------------------

{.567,expecting a variable.}

The compiler was expecting a global, local or private variable of the process in the indicated position of the program.

The syntax of the {#1043,FROM} loop statement is the following one:

{FROM} <variable>{=}{#1005,<constant>} {#1096,TO} {#1005,<constant>} {#1095,STEP} {#1005,<constant>}{;}ú
    {#1017,<statement>} {;}ú
    ...ú
{END}

Being the {STEP <constant>} declaration optional.

After the reserved word {#1043,FROM}, the {#1001,name} of a variable (normally local or private) of the process must appear directly.

If the aim is to use a variable of another process, a table or an element of a structure as a counter, the {#1025,FOR} statement must be used instead of {#1043,FROM}, as it allows us to define the conditions of the loop more freely.

{/}See: {#1000,Syntax} - {#1043,Statement FROM}

# -----------------------------------------------------------------------------

{.568,expecting [=]}

The compiler was expecting a symbol {#1073,=} (assignment) in the indicated position of the program.

The syntax of the {#1043,FROM} loop statement is the following one:

{FROM} <variable>{=}{#1005,<constant>} {#1096,TO} {#1005,<constant>} {#1095,STEP} {#1005,<constant>}{;}ú
    {#1017,<statement>} {;}ú
    ...ú
{END}

Being the {#1095,STEP <constant>} declaration optional.

After the reserved word {#1043,FROM}, the {name} of a variable (normally local or private) of the process must appear directly, and then the symbol {#1073,=} (assignment).

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    id2;
BEGIN
    //...
    FROM id2.x=0 TO 9; // Error: expecting [=].
        //...
    END
END
{-}

In this example, the error will appear on detecting the symbol{#1063, . (period)} instead of {#1073,=} after the {first name} ({id2}) that appears. This happens because a variable of another process can not be used as a counter of a {#1043,FROM} loop.

If the aim is to use a variable of another process, a table or an element of a structure as a counter, the {#1025,FOR} statement must be used instead of {#1043,FROM}, as it allows us to define the conditions of the loop more freely.

{/}See: {#1000,Syntax} - {#1043,Statement FROM}

# -----------------------------------------------------------------------------

{.569,expecting [TO]}

The compiler was expecting the reserved word {#1096,TO} of the {#1043,FROM} statement in the indicated position of the program.

The syntax of the {#1043,FROM} loop statement is the following one:

{#1043,FROM} <variable>{=}{#1005,<constant>} {#1096,TO} {#1005,<constant>}
{#1095,STEP} {#1005,<constant>}{;}ú
    {#1017,<statement>} {;}ú
    ...ú
{#1091,END}

Being the {#1095,STEP <constant>} declaration optional.

After the reserved word {#1043,FROM}, the {name} of a variable (normally local or private) of the process must appear directly, and then the symbol {#1073,=} (assignment), preceding a constant. After this constant value, only the reserved word {#1096,TO} can appear.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    id2;
BEGIN
    //...
    FROM id2.x=0 STEP 9; // Error: expecting [TO].
        //...
    END
END
{-}

In a {#1043,FROM} statement, the {initial} and {final} values of the loop's counter variable must always appear in both sides of the word {#1096,TO}.

{/}See: {#1000,Syntax} - {#1043,Statement FROM}

# -----------------------------------------------------------------------------

{.570,The value STEP is not valid.}

In a {#1043,FROM} statement:

- If the initial value {is less} than the final value, a negative value can not be specified in the declaration {#1095,STEP}.

- If the initial value {is bigger} than the final value, a positive value can not be specified in the declaration {#1095,STEP}.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FROM x=0 TO 10 STEP -1; // Error: The value STEP is not valid.
        //...
    END
END
{-}

This loop is not valid as, if {1} is subtracted from {x} (that originally will be equal to {0}) in every iteration, it will never reach {10}. If the aim is to create a continuous loop, the {#1024,LOOP} statement must be used.

{/}See: {#1000,Syntax} - {#1043,Statement FROM}

# -----------------------------------------------------------------------------

{.571,Invalid FROM statement.}

In a {#1043,FROM} statement:

- The {initial} and {final} values of a {#1043,FROM} loop must be different.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FROM x=0 TO 0; // Error: Invalid FROM statement.
        //...
    END
END
{-}

Creating this loop makes no sense, as the inner set of statements will be repeated just once, which would be equivalent to initialising {x} at {0} (with the {x=0;} statement) and, then, to directly putting the inner statements, omitting the loop {#1043,FROM}.

If the aim is to create an ever-repeating loop, the {#1024,LOOP} statement must be used.

{/}See: {#1000,Syntax} - {#1043,FROM statement}

# -----------------------------------------------------------------------------

{.599,Correct compilation}

The program has no errors of compilation. Press:

{Menu programs\Execute} or {F10}.ú
To save, compile and execute the program.

{Menu programs\Debug} or {F12}.ú
To save, compile and debug the program step by step.

# -----------------------------------------------------------------------------

{.600,Exceeded the capacity of the names vector.}

The buffer to store the {#1001,names} of the program has been exceeded.
This error can only be due to the fact that too long data names and processes have been used.

The only solution to compile the program is to replace some of these names by other shorter names.

# -----------------------------------------------------------------------------

{.601,Exceeded the capacity of the demo version.}

This DEMO version of DIV Games Studio does not allow us to create programs as big as this one. It can only compile programs of a specific number of variables and processes.

In the complete version of DIV GAMES STUDIO does not exist this limit, being possible to create programs of any size.

The only option to compile this program is first eliminating all the processes and data that are no longer required or indispensable.

# -----------------------------------------------------------------------------

{.602,Exceeded the capacity of the table of objects.}

The available space to store data records and the program's processes has been exceeded.

This error should never happen, but when it happens it is difficult to resolve. The program is too big for this version of the compiler.

If there is a new version of the compiler or any 'patch' that updates this limitation, it must be updated.

Otherwise, the only option is to eliminate from the program all the processes and {#1034,data} that are not required or essential any longer.

# -----------------------------------------------------------------------------

{.610,expecting the structure name.}

To define a structure of data, its name must be specified after the reserved word {#1012,STRUCT}.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT positions[9]
        x, y;
    END
BEGIN
    //...
END
{-}

This structure has been defined with the name {positions} and contains {ten records} (from 0 to 9) each one with two values {x} and {y}.

{/}See: {#1000,Syntax} - {#1001,Names} - {#1012,Declaration Structures}

# -----------------------------------------------------------------------------

{.611,expecting the process name.}

To define a process, its name must be specified after the reserved word {#1016,PROCESS}.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    //...
END

PROCESS my_process()
BEGIN
    //...
END
{-}

This process has been declared with the name {my_process}.

{/}See: {#1000,Syntax} - {#1001,Names} 

# -----------------------------------------------------------------------------

{.612,expecting the name of a process.}

The name of one of the processes defined in the program must be defined after the reserved word {#1042,TYPE}.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    //...
    signal(TYPE my_process, s_kill);
    //...
END

PROCESS my_process()
BEGIN
    //...
END
{-}

{/}See: {#1000,Syntax} - {#1001,Names} - {#1042,Types of processes}

# -----------------------------------------------------------------------------

{.613,expecting a name.}

As a parameter, the {#1094,sizeof()} function requires the name of a variable. It can also be the name of a variable, a table or a structure of the program.

This function returns the number of data (or elements) that the object whose name is passed as an argument has. Therefore, if that object was a
variable, the function would always return 1.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    table[]=0, 1, 2, 3;
    length_table;
BEGIN
    length_table=sizeof(table);
END
{-}

In this example {length_table} will be equal to {4} after the statement execution,
as the table contains four data.

{/}See: {#1000,Syntax} - {#1001,Names} - {#1094,sizeof}

# -----------------------------------------------------------------------------

{.614,The name is not new.}

A name has been used twice for a field of the structure. You must replace this name by another similar one.

{#9999,Example:}
PROGRAM name_of_the_program;
GLOBAL
    STRUCT position[9]
        x0, x0; // Error: The name is not new.
    END
BEGIN
    //...
END
{-}

{/}See: {#1000,Syntax} - {#1001,Names} - {#1012,Declaration of structure}

# -----------------------------------------------------------------------------

{.615,The name is not new.}

An invalid program's {#1001,name} has been used as it was already predefined as the name of another object. You must replace this name by another similar one.

In order to know which is the object identified with that {#1001,name}, it is possible to access the {#4,Glossary}.

{#9999,Example:}
PROGRAM x; // Error: The name is not new.
BEGIN
    //...
END
{-}

In this example, the aim was to use {x} as the name of the program,
that is predefined as the name of the local variable that indicates the x coordinate of the processes.

{/}See: {#1000,Syntax} - {#1001,Names} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.616,The name is not new.}

To define a {#1004,constant}, an invalid {#1001,name}
has been used, as it was already predefined as the name of another object.
It can be the name of a constant, variable,
table, structure, process or a function of the program.

It is also possible either that the same {#1001,name} has been used inside the program to identify two different objects, or {that a predefined name has been used with another purpose inside the language}. In that case, it is possible to access the {Glossary} to see the object to which this name is referred.

You must replace this name by another similar one.

{#9999,Example:}
PROGRAM my_game;
CONST
    x=0; // Error: The name is not new.
BEGIN
    //...
END
{-}

In this example, the aim was to use {x} as a constant's name that is predefined as the local variable that indicates the {#1123,x}  coordinates of the processes.

{/}See: {#1000,Syntax} - {#1001,Names}  -----------------------------------------------------------------------------

{.617,The name is not new.}

To define a new data, an invalid {#1001,name}
has been used, as it was already predefined as the name of another object.
It can be the name of a {#1004,constant}, variable,
table, structure, process or a function of the program.

It is also possible either that the same name has been used inside the program to identify two different objects, or {that a predefined name has been used with another purpose inside the language}. In that case, it is possible to access the {Glossary} to see the object to which this name is referred.

You must replace this name by another similar one.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    x[3]=0, 1, 2, 3; // Error: The name is not new.
BEGIN
    //...
END
{-}

In this example, the aim was to use {x} as a global table's name
that is predefined as the local variable that indicates the {#1123,x} 
coordinates of the processes.

{/}See: {#1000,Syntax} - {#1001,Names}

# -----------------------------------------------------------------------------

{.618,The name is not new.}

A {#1001,name} of an invalid process has been used, as it was already predefined as the name of another object. It can be the name of a {#1004,constant}, variable, table, structure, process or a function of the program.

It is also possible either that the same name has been used inside the program to identify two different objects, or {that a predefined name has been used with another purpose inside the language}. In that case, it is possible to access the {Glossary} to see the object to which this name is referred.

You must replace this name by another similar one.
{#9999,Example:}
PROGRAM my_game;
BEGIN
    //...
END

PROCESS my_game() // Error: The name is not new.
BEGIN
    //...
END
{-}

In this example, the aim was to use the name that had been previously used to identify the main program as the name of a process.

{/}See: {#1000,Syntax} - {#1001,Names} 

# -----------------------------------------------------------------------------

{.619,expecting [=]}

To define a constant, a symbol {#1073,=} must be put after the name of the constant.

The compiler has understood that the last defined word was the name of a new {#1004,constant} and, in the indicated position, it was expected for the symbol of assignment ({#1073,=}) to be shown.

{#9999,Example:}
PROGRAM my_game;
CONST
    a=0;
    b=1;
    c,d; // Error: expecting [=].
BEGIN
    //...
END
{-}

{/}See: {#1000,Syntax} - {#1009,Declaration of data}

# -----------------------------------------------------------------------------

{.620,Too many values for the structure.}

A structure has been initialised with more values than it can contain.

To initialise a structure, take into account the greatest number of values that it can contain. This number will be:

    {N§ of records} X {N§ of fields}

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT positions[9]
        x, y;
    END = 10 dup (-99, 99);
BEGIN
    //...
END
{-}

In this case, the structure {positions} has {10 records} (from positions[0]
to positions[9]) and {2 fields} (x and y). Then, the greatest number of values that it can contain is {20}. In the example, all the fields {x} are initialised at{ -99} and all the fields {y} are initialised at {99}.

{/}See: {#1000,Syntax} - {#1012,Declaration of structure}

# -----------------------------------------------------------------------------

{.621,Unknown name.}

In the indicated position of the program, reference is made to a non-existent {#1016,PROCESS} {#1408,FUNCTION},
that can be one of the following cases:

- The name of a process has been incorrectly keyed. In this case, check the name of the original process, as it is possible that the name does not correctly appear in its definition.

- The aim has been to use a language function and its name has not been correctly written. In this case, it is possible to access the general index to look for the exact name of the function.

- Reference is made to a process whose code has not been defined yet. Therefore, if the aim is to compile the program, it is necessary to define the process, at least, as follows:

{#9999,Example:}
PROGRAM my_game;
BEGIN
    my_process();
END

PROCESS my_process()
BEGIN
END
{-}

  Indicating in the process the parameters that it receives (in the previous example, it does not receive any parameter).

{/}See: {#1000,Syntax} 

# -----------------------------------------------------------------------------

{.622,The increment can not be performed.}

In the indicated expression of the program the operator {#1057, ++} (or the operator{#1061, --}) are incorrectly used with the aim of incrementing (or decrementing) an object. That object has no offset, as it is not a variable, table or structure. Thus, the compiler can not perform an increment (or decrement) about it.

The aim has probably been to increment or decrement a constant expression or an expression involving several operands.

Now, a program with several examples of valid and invalid use of the operators{#1057, ++} and{#1061, --}, is shown.

{#9999,Example:}
PROGRAM my_game;
CONST
    my_constant=0;
GLOBAL
    my_variable=0;
    my_table[10];
    STRUCT my_structure[10]
        variable;
    END
BEGIN
    // Valid examples
    my_variable++;
    my_table--;
    ++my_table[my_variable];
    --my_structure[0].variable;
    id.x++;

    // Invalid examples
    (my_variable*2)++;
    my_constant--;
    ++0;
    --(my_variable+1);
END
{-}

The constants like {my_constant} can not be incremented as they are just synonymous of the numeric value they represent.

The {(my_variable*2)++;} statement is not valid because the
multiplication is first done and then, the value {my_variable*2} becomes a numeric result that has no offset and, therefore, it is not possible to access it in order to increment it.

In this case, the correct statement that should have been used is probably {my_variable=my_variable*2+1;}

{/}See: {#1000,Syntax} - {#1057,++} - {#1061,--}

# -----------------------------------------------------------------------------

{.623,Structure of negative length.}

To define a structure indicating its number of records in {#1079,square brackets} a positive integer (0, 1, 2, 3, ...) must be used, taking into account that all the structures start in the record zero and finish in the record indicated in the index.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT e1[9]
      x, y;
    END
    STRUCT e2[-9] // Error: Structure of negative length.
      x, y;
    END
BEGIN
    //...
END
{-}

The compiler has detected a structure defined with a negative number of records, like {e2}. In this example, the structure must be defined as {e1} that,
in this case, will be a structure of 10 records (from e1[0] to e1[9])
and two fields (x and y).

{/}See: {#1000,Syntax} - {#1012,Declaration of structure}

# -----------------------------------------------------------------------------

{.624,A statement was expected.}

The indicated position of the program is within the context of a block of statements. Thus, a statement was expected to start in the indicated position. These are the possible types of statements:

assignment statementsú
<expression>{#1035,=}<expression>;

control statementsú
{#1020,IF} and {#1021,SWITCH}.

loop statementsú
{#1043,FROM}, {#1022,WHILE}, {#1023,REPEAT}, {#1024,LOOP} and {#1025,FOR}.

break statementsú
{#1026,BREAK}, {#1027,CONTINUE} and {#1028,RETURN}.

special statementsú
{#1029,FRAME}, {#1030,CLONE} and {#1031,DEBUG}.

Being possible that, in this position, one of the following reserved words that can mark the end of a block of statements appear:

{#1091,END}, {#1090,ELSE} and {#1097,UNTIL}.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    CASE 0: // Error: A statement was expected.
        //...
    END
END
{-}

This example will provoke error, because the reserved word {#1087,CASE} is not valid to start a statement. It is only valid inside a {#1021,SWITCH} statement.

{/}See: {#1000,Syntax} - {#1017,Declaration of statements}


# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.625,expecting the name of the string}

To define a string of text you must specify the its name after the reserved word {STRING}.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRING player[32];
    STRING message;
BEGIN
    //...
END
{-}

In this example two global text strings were defined. The first is defined with the name
{player} which can accumulate up to 32 characters and the second with the name {message}
which with the undeclared length can accumulate up to 256 characters (because this is
the application's maximum size of text strings).

{/}See: {#1000,syntax} - {#1001,names}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.626,The name has already been allocated}

An item has been given a name that has already been used. It could be a name,
a constant, a variable, a table, a structure, a process or function
of the program.

You may be attempting to use the same name inside the program
to identify two different objects, or {a name you allocated is predefined for
another use was inside the language}.
In this case you can access the glossary to see to which object the name belongs to.


In each case,{you must substitute this name with another one}.

{#9999,Example:}
PROGRAM name_of_program;
GLOBAL
    player=0;
    STRING player; // Error: The name is not unique.
BEGIN
  //...
END
{-}

{/}See: {#1000,syntax} - {#1001,Names}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.627,Text string has a negative length}

To define a text string you indicate in brackets its length,
it is necessary for its length to be defined as a positive whole number 
(0, 1, 2, 3, ...), remembering that all strings begin in the position null
and finish in the position which indicates the index.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRING string1[9];
    STRING string2[-9]; // Error: Text string has negative length.
BEGIN
    //...
END
{-}

The compiler detected a text string with a negative string length such as {string2};
in this example you must define the string as
{string1} which will be the string of 10 characters (from
string1[0] to string1[9]).

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.628, a literal was expected}

Literals are {texts in brackets}. In the indicated position of the
program a literal was expected to be given as the initial value of 
a text string.

The text strings can be initiated as shown in this example.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRING string="initial text in the string";
BEGIN
    //...
END
{-}

It is not obligatory to initiate the text strings of a program.
In the case of initiation, the string could have an empty text ("") at the beginning of the program,
so, these two declarations would be identical:

  {STRING} string;ú
  {STRING} string{=}""{;}

In these cases, their length is not declared, therefore the strings can accumulate
to a maximum of 256 characters (because this is the maximum size allowed for strings of text).

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.629,Literal is too long}

A text string was initiated with a literal with a bigger number of characters than the string
can contain.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRING string1[3]="ABCDE"; // Error: Literal is too long
BEGIN
    //...
END
{-}

To initiate a text string you must remember that the maximum number of characters it can
contain is the number contained in square brackets, plus one.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRING string1[3]="ABCD";
BEGIN
    //...
END
{-}

In this case a text string {string1} can contain four characters
(string1[0]=char("A"), string1[1]=char("B"), string1[2]=char("C") and
string1[3]=char("D")).

The other option is {not to indicate the size of the text string}, establishing in
this case the string size maximum of 256 characters.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRING string1="ABCDEF";
BEGIN
    //...
END
{-}

In this case, {string1} would contain initially six indicated characters
("ABCDEF"), but it can reach 256 during the execution of the program.

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.630,A comma was expected }

It is accessing an array indicating less dimensions than required.

It means that an array of two dimensions is pretending to take one dimension as its 
parameters or an array of three dimensions is attempting to use it as a two
dimensional array.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    array1[9,9];
BEGIN
    //...
    array1[0]=0; // Error: A comma was expected.
END
{-}

Check the previous declaration of the named array of data in the program.

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.631,A comma was expected }

It is accessing a structure indicating less dimensions than required.

It means that a structure of two dimensions is attempting to use one dimension as its
parameters or a structure of three dimensions is attempting to use it as a two
dimensional structure.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT structure1[9,9];
      n;
      //...
    END
BEGIN
    //...
    structure1[0].n=0; // Error: A comma was expected.
END
{-}

Check the previous declaration of the named structure of data in the program.


{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.632,Cannot calculate the offset of the data}

In the expression indicated in the program the operator {#1085,offset} is used 
(or synonymous symbol {#1085,&}) with the goal to obtain the location
(dislocation) of a {#1406,character}, {#1404,byte} or {#1403,word} which belongs
to a table.

It is only possible to obtain the location at the beginning of the
table, but not of its data (except such data as {#1402,int}).

Shown below is a program with two examples of the use of the operator
{#1085,offset} (or the symbol {&}) for tables of such type {#1404,byte}; one valid, another not.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    BYTE my_table[99];
    offset_data;
BEGIN
    // Correct example
    offset_data=offset my_table;

    // Erroneous example
    offset_data=offset my_table[1];
END
{-}

{/}

It is also applicable to {text strings} (data like {#1406,string}),
meaning, it is not possible to obtain the location of a character inside of the string.

In this case, the operator {#1085,offset} is not necessary to obtain the
dislocation of a string of text (it can be omitted).
It means, that both of these two statements would be valid:

  offset_string{=}offset my_string{;}ú
  offset_string{=}my_string{;}

{Note:} To operate with the text strings one has to use the functions
of the language which were written to manipulate text (see for example
{#202,strcpy()}).

{/}See: {#1000,syntax} - {#1085,offset}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.633,Assignation to incorrect string}

With text strings you can only realise assignations of three types:

- Conventional assignations (=), a copy of the string to the right of the {=} sign
will be made to the left-hand string.

- Sum and assignation (+=), the substring on the right hand side will be added to the left-hand string.

- Subtraction and assignation (-=), characters of the string will be removed.

If another type of assignation is attempted this error will be given.

{/}See: {#1000,syntax} - {#1035,Definition of expression}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.635,text string is too long}

To define a string of text indicating in brackets its length,
one must use a whole number {less than 1048576}, remembering
that all strings start from the position zero and finish in the position which indicates the index.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRING string1[29999999]; // Error: text string is too long.
BEGIN
    //...
END
{-}

The compiler detected a text string that was too long, such as {string1}; the maximum that can be declared 
is a string of text of 1 Megabyte, with such declaration:  {STRING} string1{[}1048575{];}

{string1} can contain up to {1024*1024} characters, from string1[0] to string1[1048575].

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.636,Incorrect initiation}

The number of values indicated in the initiation does not coincide with the previous declaration of the structure.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT my_structure[9];
        STRING name;
        x,y;
    END = 10 dup ("AAA",0); // Error: Incorrect initiation.
BEGIN
    //...
END
{-}

In the last example the program declares a structure of three fields, and then 
initiates it as if it had only two fields.

You must check the original declaration, always remembering that a
structure as {my_structure[9]} has {10} registers (from {0} to {9}). For example,
the valid initiation for the structure would be:

  10 {dup (}"AAA"{,} 0{,} 0{);}


{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.637,expecting [;]}

The compiler expects a {#1068,semicolon (;)} in the position indicated in the program.

In the language you must indicate the end of a declaration of data with a semicolon.

{/}See: {#1000,syntax} - {#1068, ; }

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.638, Expecting a compilation option}

The compiler was expecting a compilation option in the indicated position of the program.

See the {#1400,options of compilation} disposed in this version of the language.

{/}See: {#1000,syntax} - {#1003,Headline of program}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.639,Expecting [=]}

To set a maximum number of processes you must use the statement
{#1400,compiler_options} as it is shown in this program:

{#9999,Example:}
COMPILER_OPTIONS _max_process = 100;

PROGRAM my_game;
BEGIN
    //...
END
{-}

In this case it was established that during the execution of the program 
{ a maximum of 100 processes} can execute simultaneously.

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.640,Assignation inside of a condition}

The compiler detected, in the fly out position of the program, a statement of assignation inside of one condition.

Probably was intended to compare two values using for it the assignation symbol {#1073,=}, 
instead of the symbol of comparison / equivalence {#1074,==}.

{/}

{Note for new users:} If you want to {compare} two values with the symbol{=},
you must include in the program the option {#1400,_simple_conditions}.
For it you must put in the first line (before {PROGRAM ...}) this statement:

  {COMPILER_OPTIONS _simple_conditions;}

{/}

{Note for users of the previous version:} In this new version of the language
are prohibited the {assignations inside of one condition}, to simplify
the program syntax for new users. But it can be changed with
the options of compilation (see {#1400,_extended_conditions and _simple_conditions}).

{/}See: {#1000,syntax} - {#1400,Compiler_options}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.641,The length does not coincide with the previous declaration}

a text string or pointer was declared {twice}, as a parameter and as
private data, and in the declarations a different length was specified.

It is not necessary to declare this data as private, because you can
specify its length in the same parameters of the process.

{#9999,Example:}
PROGRAM name_of_program;
BEGIN
  //...
END

PROCESS my_process(string my_string[16])
BEGIN
  //...
END
{-}

The process of this example receives a parameter in a {private} string (but
this is not indicated in the process) of {17} characters in length (from
my_string[0] to my_string[16]).

The previous process can return to declare this string in the section
{#1008,PRIVATE} (for example, to add an explanatory commentary), but in this case the 
specified lengths must coincide. In this case,{my_string} will be declared as shown
below.

{#9999,Example:}
PROGRAM name_of_program;
BEGIN
  //...
END

PROCESS my_process(string my_string[16])

PRIVATE
  string my_string[16]; // Here I will receive some text.

BEGIN
  //...
END
{-}

{/}See: {#1000,syntax} - {#1008,Declaration of private data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.642,Expecting a name}

To define a table or group of bytes you must specify its name after the reserved word {BYTE}.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    BYTE my_byte;
    BYTE my_table1[127];
    BYTE my_table2[255,255];
BEGIN
    //...
END
{-}

In this example three variable of this type were defined. The first is the name
{my_byte} which can contain only the values (between 0 and 255), the second
with the name {my_table1} can contain up to 128 values  from 
(from my_table1[0] to my_table1[127]), and the third, which is a table
of bytes of two dimensions, can contain a total of 65536 values
(the result of multiplying 256 by 256).

{/}See: {#1000,syntax} - {#1001,Names}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.643,Value of BYTE out of rank (0...255)}

a variable of type {BYTE} was initiated with a value too big, or negative. This
type of data can only contain values inside the rank {0} ... {255}.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    BYTE mi_value=300; // Error: Value of byte out of rank (0...255).
BEGIN
    //...
END
{-}

If you want to assign this value to the data, you must not declare the data of this type {BYTE},
 as is shown in this program.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    my_value=300;
BEGIN
    //...
END
{-}

As this form creates a variable which can contain a whole number value
inside the rank ({#1177,min_int} ... {#1178,max_int}).

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.644,Value of word out of rank (0...65535)}

A {WORD} was initiated with a value too big or negative. This
type of data can only contain values inside the rank {0} ... {65535}.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    WORD my_value=70000; // Error: Value of word out of rank (0...65535).
BEGIN
    //...
END
{-}

If you want to assign this value to the data, you must not declare the data as type {BYTE},
as is shown in this program.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    my_value=70000;
BEGIN
    //...
END
{-}

As this form creates a data which can contain a whole number value
inside the rank ({#1177,min_int} ... {#1178,max_int}).


{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.645,Expecting a name}

To define a table of bytes you must specify its name after the reserved word {WORD}.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    WORD my_word;
    WORD my_table1[127];
    WORD my_table2[255,255];
BEGIN
    //...
END
{-}

In this example three variable of this type were defined. The first is the name
{my_word} and can only contain a value (between 0 and 65535), the second
with the name {my_table1} can contain up to 128 values
(from my_table1[0] to my_table1[127]), and the third, which is a table
of bytes of two dimensions, can contain a total of 65536 values
(because it is the result of multiplying 256 by 256).

{/}See: {#1000,syntax} - {#1001,Names}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.646,Cannot specify a table as the parameter}

The {#1018,parameters of the process} must be declared as variables,
not as tables or structures, and cannot be initiated (because they will receive 
their value with each call).

{#9999,Example:}
PROGRAM my_game;
BEGIN
    //...
END
PROCESS my_process(a[9]) // Error: Cannot specify a table as the parameter.
BEGIN
    //...
END
{-}

The compiler interprets the parameter {a} as a table of 10 positions, 
and cannot pass a table as the parameter, so emits the error.

{/}See: {#1000,syntax} - {#1018,Parameters of a process}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.647,statement IMPORT is incorrect (see corresponding help)}

The declaration of external libraries must be done {below the headline
of the program}, in other words, after the declaration {PROGRAM name_of_program;}.
Different declarations of {#1014,IMPORT} can be used to declare
the use of more than one library, as in this example.

{#9999,Example:}
// Headline of the program

PROGRAM my_game;

// Declaration of libraries

IMPORT "lib1.dll";
IMPORT "lib2.dll";
//...

// And in continuation (optional) the rest of the sections that make up the program.

CONST
   //...
GLOBAL
   //...
LOCAL
   //...
PRIVATE
   //...

BEGIN
    //...
END
{-}

This program declares the use of the denoted libraries {lib1.dll} and
{lib2.dll} (supposed names of hypothetical libraries with external functions).

{/}

{Note 1:} In the original version of DIV, this declaration had to be done 
between sections {LOCAL} and {PRIVATE} of the program.

{Note 2:} The libraries prepared in the original (DIV1 or DIV2) versions of the language 
{will not function correctly} in DIV3, it is necessary first to re-compile
these libraries with new files of declarations for modern systems. It means,
that the font code of the libraries will be valid, but beforehand they must be 
re-compiled with new headline files (because they contain
declarations for the new data and structures which exist in the DIV3 language).

{/}See: {#1000,syntax} - {#1014,Declaration of libraries}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.648,expecting a name}

To declare a pointer you must specify its name after the reserved word {#1405,POINTER} (or the symbol {*}).

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    POINTER ptr;
    WORD POINTER my_words[15];
    BYTE POINTER my_bytes;
BEGIN
    //...
END
{-}

In this example three variable of this type were defined. The first
with the name {ptr} is a pointer to any conventional data, and it has no
limitation of rank in its access (you can access ptr[{n}]with{n} being any value). 
The second is a pointer to data of type {WORD} 
(whole value between 0 and 65535) with a limitation of access to the first 16
values only. And the third is a pointer of data of type {BYTE} (whole between
0 and 255) without limitation of rank.

{/}See: {#1000,syntax} - {#1001,Names}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.649,expecting a name}

To declare a data type you must specify its name after the reserved word {INT}, but in this case it is not so important
(because all the data by default will be of the same type).

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    INT a,b;  // declare two whole number data
    c,d;      // declare another two whole number data
BEGIN
    //...
END
{-}

In this example you can see 4 data of the  type whole number declared, for
the first two ({a} and {b}) the type was specified as (INT) (as in "integer"), 
but there is no difference, in the level of declaration, with the last two 
({c} and {d}), because these would also be data of the type (INT).

{/}See: {#1000,syntax} - {#1001,Names}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.650,Incorrect declaration of the pointer to a structure}

The compiler was expecting, at the indicated position of the program, the name
of a structure previously declared, with the intention of declaring it as a pointer.

To define a pointer to a data structure you must use the following syntax:

{STRUCT POINTER name_structure name_pointer;}

{name_structure} being the name of a data structure declared
previously in the program, and {name_pointer} being the name of a pointer
to the structure which is being declared.

{/}See: {#1000,syntax} - {#1001,Names} - {#1012,Declaration Structures}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.651,Cannot receive a structure as the parameter}

A process cannot receive a structure as its parameter, if you want to
access an external structure from a process, the process must receive as
its parameter a pointer to the structure.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT positions[9]
        x, y;
    END
BEGIN
    my_process(OFFSET positions);
    //...
END

PROCESS my_process(STRUCT POINTER positions pos[9]);
BEGIN
    //pos[ ... ].x = ... ;
    //...
END
{-}

In this example you can access the structure inside {my_process}
using the pointer {pos}.

{/}See: {#1000,syntax} - {#1001,Names} - {#1012,Declaration Structures}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.652,expecting a name of structure}

The indicated function requires as its parameter, at the indicated position, the name
of a data structure of the program.

You do not have to use the operator {#1085,offset}, you just need to indicate the name 
of the structure.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT records[9]
        STRING initials[2];
        points;
    END
BEGIN
    //...
    qsort(offset records,points,1); // Error: expecting a name.
END
{-}

In this example the function {qsort} is used, which requires the name of a
structure as its first parameter. In this case, the correct instruction 
to order the table{records} is this one:

  qsort(records,points,1);

This instruction indicates how to order the structure, namely as a function
of the field {points} and in descending order.

{/}

{Note 1:} Also it is possible that the indicated name has nothing to do with a
structure of data, but with the another type of object (for example, the name 
specified was of a table of data).

{Note 2:} This data structure cannot belong simultaneously to another
structure, so you cannot specify the name of a structure inside another one.

{/}See: {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.653,expecting a field of the structure}


The indicated function requires as its parameter, in the indicated position, the name
of {a field pertinent to the structure previously indicated}.

You don't have to use the operator {#1085,offset}, you only need to indicate the name of the field.


{#9999,Example:}
PROGRAM my_game;
GLOBAL
    STRUCT records[9]
        STRING initials[2];
        points;
    END
BEGIN
    //...
    qsort(records,&points,1); // Error: expecting a field of the structure.
END
{-}

In this example the function {qsort} is used, which requires the name of a field
of the structure as its second parameter. In this case, the instruction to order 
the table (records) would be :

  qsort(records,points,1);

This instruction indicates how to order the structure, as a function
of the field {points} and in descending order.


{/}

{Note:}  the indicated name does not always have to be a data structure.

{/}See: {#1000,syntax}


# -----------------------------------------------------------------------------
# Information about programming language
# -----------------------------------------------------------------------------

{.1000,Syntax of a program.}

Now, the general structure of a program is shown in the language. To see the corresponding syntactic definition, click on the section of your interest with the mouse.

{#1003,<Program's head>}ú
{#1004,<Declaration of constants>}ú
{#1006,<Declaration of global data>}ú
{#1007,<Declaration of local data>}ú
{#1014,<Declaration of libraries>}ú
{#1008,<Declaration of private data>}ú
{#1015,<Main code>}ú
{#1016,<Declaration of processes>}ú

All the programs must respect the previous structure with an exception: it is possible to put {#1002,explanatory comments}
in any point of the program.

{/}See: {#3,Index} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1001,Definition of a name.}

A name is a sequence of alphanumeric characters used to {identify} an object of the program, such as the name of a process, {#1004,constant} or variable.

These names can be made up of the following characters:

  Symbols:ú
  {_ # ¦ § $ ž Ÿ œ  ›}ú
  Digits:ú
  {0123456789}ú
  Letters:ú
  {abcdefghijklmnopqrstuvwxyz}ú
  Letters (extended):ú
  {¤ ‡ ‘ ƒ„…†  ˆ‰Š‚ Œ‹¡ “”•¢ –—£ ˜}ú

provided that the following rules to create new names are respected:

- The sequence of characters must not contain characters that are not in the previous list (except {capital} letters corresponding to lower case letters included in the list).

- Inside the sequence, it is not possible to put blanks. That is to say, {enemy spacecraft} is not a valid name as, for the compiler, it would imply two names. In 
this case, the name can be declared as {enemy_spacecraft}.

- A name can not start with a numeric digit. That is to say, {0a} is not a valid name. Nevertheless, all the necessary digits can be included in the name after the first character ({a0} is indeed a valid name).

- The name must not coincide either with any of the language's reserved words or with any of the objects (constants, variables, etc.)
predefined in the language. To check it, see the list of reserved words and predefined objects, being possible to access the Glossary at any moment. The reserved words appear in capital letters and the predefined objects in lower case letters.

- There is no difference between the capital and lower case letters (for the compiler, {ABc} and {abC} are the same name).

- The same name can not be used for two different objects.
For instance, it is not possible to name a constant {value} and then, to declare
a process {PROCESS value(x, y);}.

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1002,Definition of comments.}

A comment is an explanatory note about the program. The comments are not
necessary for the program's correct working.

There are two kinds of comments:

- Of a single line: they start with the symbol{ //} and finish at the end of the line in which they are defined.

- Of several lines: they start with the symbol{ /*} and finish with the symbol {*/}.

{#9999,Example:}
/*
    This is an example of a comment
    of several lines in which explanations
    about the program can be given
*/

PROGRAM my_game; // Example of a single line comment.
BEGIN             // The main program starts.
    FRAME;
END               // The main program finishes.
{-}

All the texts included in a comment are ignored by the compiler.
As many comments as necessary can be put, in any point of the program.

The comments starting with{ /*} and finishing with{ */} (comments of several lines) can also start and finish in the same line.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1003,Program's head.}

{PROGRAM} {#1001,<name>} {;}

All the programs must start with the reserved word {PROGRAM} followed by the name of the program and a symbol {#1068,; (semicolon)}.

This head is obligatory in all the programs. Before it, only one or several {#1002,comments} (explanatory texts preceded by the symbol{ //}, or between the symbols{ /*} and{ */}) can optionally appear.

In the names and reserved words there is no difference between capital and lower case letters, so {PROGRAM}, {program}, {Program}, ... are valid words.

{#9999,Example:}
// -------------------
// Listing of my game
// -------------------

PROGRAM name_of_my_game;
BEGIN
    //...
END
{-}

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1004,Declaration of constants.}

{CONST}ú
    {#1001,<name>} {=} {#1005,<constant>} {;}ú
    ...

This section of the programs is optional, as its utility deals with setting a series of synonymous for some numeric values.

In a game, for instance, number 3 has been set in one or several points of the program as the maximum lives of the protagonist. If the aim is to modify this number, increasing or decreasing it, it will be necessary to look for this number and to replace it in the program. But there is a risk of replacing other '3' numbers appearing in the program with different aims.

An alternative is to declare a constant called, for instance,
{maximum_lives} as a synonymous of the numeric value 3 and use that constant in the program instead of the number. Now, if the aim is to replace this value by another one, it is done simply in the declaration of the constant {maximum_lives}.

This section then establishes a list of names that are going to represent a series of numeric constants.

This section must obligatory start with the reserved word {CONST} and then, for every declared constant, its name followed by the symbol {#1073,= (assignment symbol)} and a constant expression (numeric value) must appear. After the declaration of every constant, the symbol {#1068,;} (semicolon) must appear.

{#9999,Example:}
PROGRAM my_game;
CONST
    maximum_lives=3;
BEGIN
    //...
END
{-}

Once a value has been assigned to a constant, it won't later be possible to modify the former in the program.

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1005,Definition of a constant.}

A constant is a constant value or a numeric expression.

As values, only integers within the range ({#1177,min_int} ... {#1178,max_int}) can be used.

The constant numeric expressions are mathematical formulas in which it is possible to use:

    - {Constants} previously defined.ú
    - {Numeric values}.ú
    - Arithmetic or logical {operators}.ú
    - {Literals} (texts in inverted commas).ú
    - The {#1094,sizeof()} function.ú

These expressions will be evaluated when the program is compiled and their result will be used in the program's execution.

The {operators} that can be used in a constant expression are the following ones (the synonymous of the operator, if they exist, are shown in brackets).

    {#1056, +}    Additionú
    {#1060, -}    Subtraction (or negative sign)ú
    {#1054, *}    Multiplicationú
    {#1065, /}    Divisionú
    {#1048, MOD}  Module ({#1048,%})ú
    {#1070, <<}   Rotation to the rightú
    {#1077, >>}   Rotation to the leftú
    {#1045, NOT}  Binary and logical negation ({!})ú
    {#1051, AND}  AND binary and logical ({&},{&&})ú
    {#1083, OR}   OR binary and logical ({|},{||})ú
    {#1082, XOR}  Exclusive OR ({^}, {^^})ú
    {#1074, ==}   Comparisonú
    {#1046, <>}   Different ({!=})ú
    {#1076, >}    Greater thanú
    {#1075, >=}   Bigger or equal ({=>})ú
    {#1069, <}    Lessú
    {#1072, <=}   Less or equal ({=<})ú
    {#1085, OFFSET} Direction or offset ({&})ú
    {#1053, ( )}  Bracketsú

Now, some examples of valid constants are shown:

{ 0}ú
{ -1000}ú
{ 2+2}ú
{ "Hello!"}ú
{ 4*(2+1)}ú
 ...

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1006,Declaration of global data.}

{GLOBAL}ú
    {#1009,<declaration of variable>} {#1068,;}ú
    ...

This section of the programs is optional. Global data, the {data that can be used from any point of the program}, are declared in this section.

A section must obligatory start with the reserved word GLOBAL followed by a series of {#1009,declarations of data} finished with a symbol {#1068,;} (semicolon).

In general, all those data that establish general conditions of the game related to several processes are declared as global data. An example could be the score obtained by the player, that could be stored in the {score} global variable. Thus, any process of the game could increment it, if necessary.

A declaration of global data will define a single data that can be used for all the program's processes. But, a declaration of local data will define a variable of this kind and name for each of the program's processes.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    score=0;
BEGIN
    //...
END
{-}

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1007,Declaration of local data.}

{LOCAL}ú
    {#1009,<declaration of data>} {#1068,;}ú
    ...

This section of the programs is optional, as local data, the {data that all the program's processes have} are declared here, each one with its own values (as the {#1123,x} and {#1124,y} predefined local variables determine the coordinates of all the processes).

A section must obligatory start with the reserved word {LOCAL}
followed by a series of {#1009,declarations of data} finished with a symbol {#1068,;} (semicolon).

In general, the important information of the processes, the data to be consulted or modified from other processes, are declared as local data.

The energy remaining a process (a spacecraft, a shotgun, the character, etc.) could be an example. This information could be stored in the {energy} local variable, so any process can access or modify the energy of the rest (for instance, on colliding with them, energy could be subtracted).

{#9999,Example:}
PROGRAM my_game;
LOCAL
    energy=0;
BEGIN
    //...
END
{-}

If a variable declared as local is to be used only inside one process, then the former can be defined as a private data (inside the section {#1008,PRIVATE} of that process).

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1008,Declaration of private data.}

{PRIVATE}ú
    {#1009,<declaration of data>} {#1068,;}ú
    ...

These sections of the programs are optional. Private data, {data that are going to be used exclusively inside a process}, can be declared in this section.

This section is defined just before the {#1086,BEGIN} of the process that is going to use these data and must start with the reserved word PRIVATE
followed by a series of {#1009,declarations of data} finished with a symbol {#1068,;} (semicolon).

The main program is also considered as a process. Its declaration of private data can go just before its {#1086,BEGIN}.

In general, all the data that are going to contain information necessary only for a process, as well as those that can not be accessed from any other process, are declared as private data.

Those variables that are going to be used as counters in a loop, variables to contain angles or secondary identifying codes, etc. are normally defined as private data.

{#9999,Example:}
PROGRAM my_game;
PRIVATE
    n;
BEGIN
    FROM n=0 TO 9;
        //...
    END
    //...
END

PROCESS my_process()
PRIVATE
    id2;
    angle2;
BEGIN
    id2=get_id(TYPE my_process);
    IF (id2<>0)
        angle2=id2.angle;
        //...
    END
    //...
END
{-}

If you need to consult or modify a variable declared as private from another process (variable.identifier), then that data will have to be declared local (inside the program's section {#1007,LOCAL}). Thus, all the processes will have the data and every process can access its value or the value that this data has in another process.

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1009,Declaration of a variable.}

In a declaration of a variable, three different kinds of objects can be shown:

  {#1010,<Declaration  of a variable>}ú
  {#1011,<Declaration of a table>}ú
  {#1012,<Declaration of a structure>}ú

In general, a variable will store a simple numeric value. A table will store a
list of numeric values. And a structure will store a list of records of several fields (such as a list of index cards with varied information).

All the data will be declared with a name which, from that moment, will become the means to access or modify the information contained in those data.

Each data will belong to a specific area, depending on the fact that its declaration has been made inside the {#1006,GLOBAL}, {#1007,LOCAL} or {#1008,PRIVATE}.. sections.

  {#1006,<Declaration of global data>}ú
  {#1007,<Declaration of local data>}ú
  {#1008,<Declaration of private data>}ú

It is possible to access all the global data from any point of the program. Local data belong to all the processes (every process has its own value in them). Finally, private data belong to a single specific process.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1010,Declaration of a variable.}

{#1001,<name>}

(or, if the aim is to initialise)

{#1001,<name>} {#1073,=} {#1005,<constant>}

To declare a variable inside a {#1006,GLOBAL}, {#1007,LOCAL}
or {#1008,PRIVATE} section, suffice will be to indicate its name inside that section. In this case, the variable will be initialised at 0 (zero).

To initialise the variable at other values, the symbol {#1073,=} (assignment) will be put after the name of the variable. The constant value at which the variable is intended to be initialised will be put after this symbol.

A variable is a cell (or position) of the computer's memory to which we refer by its name and that can contain whole numeric values within the range ({#1177,min_int} ... {#1178,max_int}).

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1011,Declaration of a table.}

{#1001,<name>} {#1079,[} {#1005,<constant>} {#1079,]}

(or, if the aim is to initialise the table)

{#1001,<name>} {#1079,[} {#1005,<constant>} {#1079,]} {#1073,=} {#1013,<list of constants>}

(or, if it is initialised without defining its length)

{#1001,<name>} {#1079,[} {#1079,]} {#1073,=} {#1013,<list of constants>}

To declare a table inside a {#1006,GLOBAL}, {#1007,LOCAL}
or {#1008,PRIVATE} section, suffice will be to indicate its name followed by the length of the table in square brackets (symbols {#1079,[} {#1079,]}). In that case, all the positions of the table will be initialised at 0 (zero).

The table's length is expressed as the maximum value of its index. That is to say, all the tables range from the position 0 to the position indicated in the square brackets in their declaration. For instance, a table declared as {my_table[9]}, will be a table of length {10} (of 10 positions, from my_table[0] to my_table[9]).

If the aim is to initialise the different positions of the table, it is necessary to put the symbol {#1073,=} (assignment) after the previous declaration and, after this symbol, a {#1013,list of constants}.

If the table is initialised with a list, then it is not necessary to indicate
the table's length in square brackets, as the compiler will create a table
with as many positions as the number of values included in the list.

A table is a series of cells (or positions) of the computer's memory that is called by its name, appearing after it, in square brackets, the number of cell inside the table intended to be accessed.

Every table's cell is a variable that can contain whole numeric values within the range ({#1177,min_int} ... {#1178,max_int}).

For instance, if we declare a table as the following one:

    {my_table[]=33, -1, 6, -3, 99;}

We will be declaring a table whose name is {my_table} and that has
{5} cells (or positions), from cell no. 0 to cell no. 4. In the previous declaration, cell 0 ({my_table[0]}) is initialised with the value {33}, cell 1 ({my_table[1]}) with the value{ -1}, etc.

The language allows us to access cell 0 simply with the name of the table ({my_table}), as if it was a variable, omitting the zero in square brackets that should appear after. That is to say, for the compiler, {my_table[0]} will be the same as {my_table} (the first cell of the table).

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1012,Declaration of a structure.}

{STRUCT} {#1001,<name>} {#1079,[} {#1005,<constant>} {#1079,]}ú
    {#1009,<declaration of data>} {#1068,;}ú
    ...ú
{#1091,END}

(or, if you initialise the structure)

{STRUCT} {#1001,<name>} {#1079,[} {#1005,<constant>} {#1079,]}ú
    {#1009,<declaration of data>} {#1068,;}ú
    ...ú
{#1091,END} {#1073,=} {#1013,<list of constants>}

To declare a structure inside a {#1006,GLOBAL}, {#1007,LOCAL} or {#1008,PRIVATE} section, it is necessary to put the reserved word {STRUCT} preceding its name. After it, the number of records of the structure must be indicated, in square brackets (symbols {#1079,[ ]}).

After this head defining the name of the structure and the number of records, all the data that belong to the structure and that will comprise its fields, will be declared. Finally, the reserved word {#1091,END} must appear to finish the declaration.

The records' number of the structure is expressed as the maximum records' number of the structure. That is to say, all the structures have from record 0 to the record indicated in the square brackets. For instance, a structure declared as {STRUCT my_structure[9]}, will be a structure of {10} records (from the record my_structure[0] to my_structure[9]).

A structure is like an index card file (records), each of them with different written information (fields). For instance, a structure in which we could include the initial and final positions of a series of processes of a game could be as follows (an index card file with 10 cards, each of them indicating the (x, y) initial
and the (x, y) final of a process):

{STRUCT movement_enemies[9]}ú
    {x_initial;}ú
    {y_initial;}ú
    {x_final;}ú
    {y_final;}ú
{END}

This structure, that would be accessed with the name {movement_enemies}, has ten records and four fields in each record (two coordinates that determine the initial position of the process [x_initial ,y_final], and two that determine the final position [x_final, y_final]).
{Movement_enemy[0].x_final} would be used to access the {x} final of the first enemy.

The language allows us to access the record 0 of the structure simply with the name of the structure ({movement_enemies.x_final}), omitting the zero in square brackets that should come later. That is to say, for the compiler
{movement_enemies[0].x_final} will be the same as {movement_enemies.x_final}.

Each field of the structure may be a variable, a table
or another complete structure, with its different records and fields.

If the aim is to initialise the structure (establishing the initial values of its fields in the different records), the symbol {#1073,=} (assignment) must be put after the reserved word {#1091,END} followed by a {#1013,list of constants}. If the structure is not initialised in this way, all the fields will be put at 0 by default.

Keep in mind that , in order to initialise a structure, the first values will be the values of the fields of the first record, the following ones those of the second record, and so on. 

For instance, if the following declaration is made:

STRUCT a[2]ú
    b;ú
    c[1];ú
END = 1, 2, 3, 4, 5, 6, 7, 8, 9;

First, it must be taken into account that the structure {a} has 3 records
(from a[0] to a[2]) and that there are three fields (b, c[0] & c[1]) in each record. Then, the previous declaration will initialise the structure in the following way:

a[0].b=1;ú
a[0].c[0]=2;ú
a[0].c[1]=3;ú
a[1].b=4;ú
a[1].c[0]=5;ú
...

{/}See: {#1000,Syntax} - {#4,Glossary}

# -----------------------------------------------------------------------------

{.1013,Definition of a list of constants.}

A constant is a constant value or numeric expression (see {#1005,<definition of constant>}).

The lists of constants are basically a series of constants separated by {#1059,commas (,)} and they are used to initialise the values of tables or structures.

An example of a list of constants is shown below:

1, 2, 3, 4, 5;

But, besides this basic definition, the use of the operator {#1089,DUP} is allowed to repeat a series of constants a specific number of times. For instance, the following list:

0, 100 DUP (1, 2, 3), 0;

It is a list of 302 constants (0, 1, 2, 3, 1, 2, 3, ..., 1, 2, 3, 0). That is to say, that
the operator {#1089,DUP} (duplication) allows us to repeat the sequence appearing after it in brackets, the indicated number of times.

It is possible to nest operations {#1089,DUP}. For instance, the following list:

2 {DUP} (88, 3 DUP (0, 1), 99);

would be equivalent to:

88, 0, 1, 0, 1, 0, 1, 99, 88, 0, 1, 0, 1, 0, 1, 99;

Moreover, the omission of the operator {#1089,DUP}, that
{2 DUP (0, 1)} is equivalent to {2(0, 1)}, is allowed.

The operator DUP is specially useful to initialise structures. If, for instance, the aim is to initialise the following 100 record structure:

{STRUCT a[99]}ú
    {b;}ú
    {c[9];}ú
    {d[9];}ú
{END}

With the fields {b} initialised at {0}, the fields {c[9]} at {1} and the fields
{d[9]} at {2}, the following list of initialisation would be used:

100 {#1089,DUP} (0, 10 DUP(1), 10 DUP(2));

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1014,Declaration of libraries.}

{IMPORT} {<name of file>}

The creation of libraries of functions for the language is a {very advanced} issue,
only for programmers with broad experience in the {C} language and/or {Assembler}.

The libraries must be distributed with two files: the first one, with extension {DLL}, 
containing the own library and, the second one, with the same name but with extension {TXT}, 
that must be a text file ascii (MS-DOS), explaining the purpose and working of the library. 
All the provided functions, the installation process and the use of the library must be 
explained in the second file.

The libraries must be imported from the language, by inputting the reserved word {IMPORT} 
(after the declaration of local and global data) followed by the path of the file {DLL}. 
If the file with extension {DLL} has been copied in the directory of {DIV Games Studio}, 
then it is not necessary to specify the library's path.

{#9999,Example:}
PROGRAM my_game;
IMPORT "hboy.dll";
BEGIN
    //...
END
{-}

From the moment when the libraries of functions can freely be developed, 
{the correct working of DIV Games Studio is not guaranteed if external libraries 
DLL are used}. The incorrect working of the {programs' debugger} can be usual when 
a DLL which modifies vital parts of the library of functions or of the processes' 
manager of DIV Games Studio is stored in a game.

{/}

{Note 1:} In the first version of the DIV programming language, this
declaration had to be done between the {LOCAL} and {PRIVATE} sections of the program.

{Note 2:} The libraries prepared for the first version of the language {will not
function correctly} in later versions, you must first re-compile
these libraries with the new declarations. In other words,
the font code of the libraries will still be valid, but they 
must be re-compiled with new the headline files (because they
contain the declarations for the new data and structures which exist in the language).

{Note 3:} If you are a programming expert in C and Assembler, you can get more
information about the creation of new libraries in the file DLL\SOURCE\Readme.TXT on the 
DIV CD.


{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1015,Main code.}

{#1086,BEGIN}ú
    {#1017,<statement>} {;}ú
    ...ú
{#1091,END}

The main code of a program starts with the reserved word {#1086,BEGIN}. After it, any number of statements may appear. The main code finishes with the reserved word {#1091,END}.

This code controls the main process of the program, which initialises the program, controls the loops of the menu and game, and finishes the program.

{#9999,Example:}
PROGRAM my_game;

GLOBAL
    option;             // Option chosen in the menu.

BEGIN                   // Beginning of the main code.

    set_mode(m640x480); // Beginning.
    set_fps(24, 4);
    // ...              // Loads files, sounds, etc.

    REPEAT              // Beginning main loop.

        option=0;       // Control loop of the options menu.
        //...           // Begins the options menu.
        REPEAT
            // ...
            IF (key(_enter)) option=1; END  // Playing is chosen.
            IF (key(_esc)) option=2; END    // Finishing is chosen.
            FRAME;
        UNTIL (option>0);

        IF (option==1)  // If the playing option has been chosen.

            // Starts regions, scroll, etc.
            // Creates the game processes.
            // Loop of game's control, expecting its end.

        END

    UNTIL (option==2);  // End of the main loop.

    let_me_alone();     // Finishes all the processes.

END                     // End of the main code.

// ...                  // Declaration of the program's processes.
{-}

The end of the main code's execution does not imply the end of the program's execution, as it will continue if there are alive processes. To force the end of the program when the code finishes, it is possible to use, for instance, the {#129,let_me_alone()} function just before the {#1091,END} that marks the main code's end, to eliminate the rest of processes that may remain alive.

The execution of the program can also be finished at any of its points with the {#109,exit()} function, which will automatically eliminate all the processes.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1016,Declaration of processes.}

Two types of code blocks exist (besides the {#1015, main code}):
the {PROCESS} blocks (which will be detailed below), and the {#1408,FUNCTION} blocks.

{PROCESS} {#1001,<name>} {(} {#1018,<parameters>} {)}ú
{#1008,<Declaration of private data>}ú
{#1086,BEGIN}ú
    {#1017,<statement>} {;}ú
    ...ú
{#1091,END}

A process must start with the reserved word {PROCESS} followed by its name and its call {#1018,parameters} in brackets. The parameters are a list of data in which the process is going to receive different values. The brackets are obligatory even if the process has no parameters.

After this header, a {#1008,PRIVATE} section, declaring data to be used by the process exclusively, may be put optionally.

And finally, the process code, that is a sequence of statements between the reserved words {#1086,BEGIN} and {#1091,END}, will be specified.

A process normally corresponds with a kind of object of the
game, such as a spacecraft, an explosion, a shot, etc. Inside the process' code, a loop (in which all the necessary values to display this object, such as graphic, coordinates, etc., will be established) is normally implemented. Then, with the {#1029,FRAME} statement, the order to display the object with the established attributes is given.

{#9999,Example:}
PROGRAM my_game;
PRIVATE
    id2;
BEGIN
    load_fpg("help/help.fpg");
    id2=my_process(160, 100);
    write_int(0,150,10,4,offset id2);
    write(0,100,10,4,"Process ID=");
    // ...
END

PROCESS my_process(x, y)
PRIVATE
    n;
BEGIN
    graph=100;
    FROM n=0 to 99;
        x=x+2;
        y=y+1;
        FRAME;
    END
END
{-}

As it can be noticed in this example, when a process is called, it returns its {#1039,identifying code} (that, in the example, is stored in the {#1008,PRIVATE} variable of the main program {id2}). If the aim is to implement a process in the style of the functions of other languages that returns a numeric result, then it is necessary to use the {#1028,RETURN(}value{)} statement, not using the {#1029,FRAME} statement inside the process, as this statement returns to the father process (caller), returning the process' {#1039,identifying code} as return value.

{/}See: {#1000,Syntax}  - {#1408,The blocks FUNCTION}

# -----------------------------------------------------------------------------

{.1017,Declaration of statements.}

A statement is an order to be executed by the computer in a program. 
The possible types of statements are the following ones:

Assignment statementsú
    {#1019,=}ú

Control statementsú
    {#1020,IF}ú
    {#1021,SWITCH}ú

Loop statementsú
    {#1024,LOOP}ú
    {#1043,FROM}ú
    {#1023,REPEAT}ú
    {#1022,WHILE}ú
    {#1025,FOR}ú

Break statementsú
    {#1026,BREAK}ú
    {#1027,CONTINUE}ú
    {#1028,RETURN}ú

Special statementsú
    {#1029,FRAME}ú
    {#1030,CLONE}ú
    {#1031,DEBUG}ú

Call statementsú
    {#1033,Call to a process}ú

The statements always appear as a group of statements, from none (which makes no sense) to as many as necessary.

All the statements will sequentially be executed (the first one,
the second one, the third one ...), with the exception of the statements that can control the flow of the program (control, loop and break statements).

{/}See: {#1000,Syntax} 

# -----------------------------------------------------------------------------

{.1018,Parameters of a process.}

The parameters of a process are basically a list of data in which the process will receive different information every time it is called or used from another process.

The processes can receive parameters in the following types of data:

- A predefined local variable (such as {#1123,x}, {#1228,size}, {#1127,flags}, ...).

- A local variable defined inside the {#1007,LOCAL} section.

- A global variable defined inside the {#1006,GLOBAL} section.

- A process' private variable declared inside the {#1008,PRIVATE} section of the process itself.

- A private variable {not declared} inside the {#1008,PRIVATE} section.

In all these cases, it is understood that a variable may be referred to a variable,
to a specific position of a table or to an element inside a structure.

As an example of the different types of parameters, a program with a process that receives five parameters different from the types respectively indicated in the previous list, is now shown.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
    score=0;
LOCAL
    energy=0;
BEGIN
    my_process(1, 2, 3, 4, 5);
    // ...
END

PROCESS my_process(x, energy, score, n, m)
PRIVATE
    n;
BEGIN
    // ...
END
{-}

The process {my_process} receives five parameters in five variables:
predefined local, local, global, {#1008,private} declared and {#1008,private} not
declared variables.

Receiving a parameter (such as the {#1006,GLOBAL} {score} variable) in a global data is equivalent to make the assignment ({score=3;}) and then,
call the process.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1019,Assignment statement.}

The assignment statements are used to calculate expressions and
{to assign them} to a variable.

{#1034,<Reference to a variable>} {#1073,=} {#1035,<expression>} {#1068,;}

The data in which the result of the expression is going to be stored must be indicated, followed by the symbol {#1073,=} (symbol of the {assignment}), as well as the numeric or logical expression to evaluate when the statement is executed. After this statement, the symbol{#1068, ;(semicolon)} must always be put.

In an assignment statement it is only allowed to assign values to objects
such as any kind of variables, to a {#1011,position of a table},
or to an {#1012,element of a structure}.

It is not possible to assign a value to a {#1004,constant}, to a function
or to a process or, in general, to any {#1035,numeric or logical expression}.

Now, a program with several assignments is shown.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    x=x+1;
    angle=(angle*3)/2-pi/2;
    size=(x+y)/2;
    z=abs(x-y)*3-pow(x, 2);
    // ...
END
{-}

This is the basic form of the assignments, even if there are other symbols of assignment that, instead of assigning a new value to the referred variable, modify its value. These are the symbols of {operative assignments}:

{#1058, +=} Adds to the variable the result of the expressionú
        {x=2; x+=2;} -> (x==4)

{#1062, -=} Subtracts from the variable the result of the expressionú
        {x=4; x-=2;} -> (x==2)

{#1055, *=} Multiplies the variable by the result of the expressionú
        {x=2; x*=3;} -> (x==6)

{#1066, /=} Divides the variable by the result of the expressionú
        {x=8; x/=2;} -> (x==4)

{#1049, %=} Puts in the variable the remainder of dividing it by the result of the
expressionú
        {x=3; x%=2;} -> (x==1)

{#1052, &=} Performs an AND (binary and/or logical) between the variable and the result of the expression, assigning it as a new variable's valueú
        {x=5; x&=6;} -> (x==4)

{#1084, |=} Performs an OR (binary and/or logical) between the variable and the result of the expression, assigning it as a new variable's valueú
        {x=5; x|=6;} -> (x==7)

{#1081, ^=} Performs an exclusive OR (XOR binary and/or logical) between the data and the result of the expression, assigning it as a new variable's valueú
        {x=5; x^=3;} -> (x==3)

{#1078, >>=} Rotates the variable to the right as many times as indicated by the result of the expression (each rotation to the right is equivalent to dividing the variable by 2)ú
        {x=8; x>>=2;} -> (x==2)

{#1071, <<=} Rotates the variable to the left as many times as indicated by the result of the expression (each rotation to the left is equivalent to multiplying the variable by 2)ú
        {x=2; x<<=2;} -> (x==8)

Within the category of assignment statements, the {increments} and {decrements} of a variable are also allowed. For instance, if we wanted to add 1
to the local variable {x} we could do it either with the {x=x+1;} or
{x+=1;} statements, or with the operator of increment: {x++;} o{ ++x;}.

That is to say, {#1057,increments ( ++ )} or {#1061,decrements ( -- )} of a variable are accepted as assignment statements.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1020,IF statements}

{IF} {#1053,(} {#1037,<condition>} {#1053,)}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}

(or)

{IF} {#1053,(} {#1037,<condition>} {#1053,)}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1090,ELSE}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}

The {IF} statement is used to run a block of statements optionally, when a condition is complied. In the second aforementioned variant,
another block of statements will also be executed (inside the
{#1090,ELSE} section) when the condition is {not} complied.

A program with several {IF} statements is now shown.

{#9999,Example:}
PROGRAM my_game;
BEGIN

    IF (key(_esc))
        exit("Good by!", 0);
    END

    IF (x>100 AND x<220)
        y=y+4;
    ELSE
        y=y-8;
    END

    IF (size>0)
        size=size-1;
    END

    IF (timer[5]>1000)
        z=1;
    ELSE
        z=-1;
    END

    // ...
END
{-}

It is possible to nest {IF} statements with no limits. That is to say, more {IF} statements can be put inside the part that is running when the condition is complied ({IF part}) or inside the one that is executed when the condition is not
complied (part {#1090,ELSE}).

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1021,SWITCH statement}

{SWITCH} {#1053,(} {#1035,<expression>} {#1053,)}ú
    {#1087,CASE} {<range of values>} {#1067,:}ú
        {#1017,<statement>} {#1068,;}ú
        ...ú
    {#1091,END}ú
    ...ú
    {#1088,DEFAULT} {#1067,:}ú
        {#1017,<statement>} {#1068,;}ú
        ...ú
    {#1091,END}ú
{#1091,END}

A {SWITCH} statement is made up with a series of {#1087,CASE} sections and, optionally, of a {#1088,DEFAULT} section.

When a {SWITCH} statement is executed, the expression is first evaluated and then, if the result is within the range of values included in the first {CASE} section, its statements will be executed and the statement will finish. If the result of the expression is not in the first {#1087,CASE}, it will be looked for in the second, third, etc. {#1087,CASE}. Finally, if there is a {#1088,DEFAULT} section and the result of the expression has not coincided with any of the {#1087,CASE} sections, then the statements of the {#1088,DEFAULT} section will be executed.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    SWITCH (x)
        CASE 1:
            x=-1;
        END
        CASE 2:
            x=-2;
        END
        CASE 3:
            x=-3;
        END
        CASE 99:
            x=-99;
        END
        DEFAULT:
            x=0;
        END
    END
END
{-}

The {SWITCH} statement of this program will change the sign of the {x} variable if it is equal to {1}, {2}, {3} or {99}. Otherwise, the statement will put the variable at {0}.

{Range of values of a case section}{/}

A value, a range of values (minimum {#1064,..} maximum), or a list of values and/or ranges separated by {#1059,commas (,)} may be specified in a case section. For instance, the previous statement could have been expressed as follows:

  {SWITCH (x)}ú
      {CASE 1..3, 99:}ú
          {x=-x;}ú
      {END}ú
      {DEFAULT:}ú
          {x=0;}ú
      {END}ú
  {END}ú

Once one of the {#1087,CASE} sections of a {SWITCH} statement has been executed {no more sections will be executed}, even if they also specify the
result of the expression, for instance, in the following statement:

  {SWITCH (2+2)}ú
      {CASE 3..5:}ú
          {x=x+1;}ú
      {END}ú
      {CASE 2, 4, 6:}ú
          {y=y-1;}ú
      {END}ú
  {END}

The {x=x+1;} section will be executed and then, the statement will finish and the {y=y-1;} section won't be executed as, even if the result of the evaluated expression ({4}) is included in it, it is also included in the previous section,
(as 4 is within the range 3..5).

It is not necessary to arrange the {#1087,CASE} sections according to their values (smaller to larger, or larger to smaller), but it is indispensable that the {#1088,DEFAULT} section (if it exits) is the last section. There can only be one {#1088,DEFAULT} section.

It is possible to nest {SWITCH} statements with no limits. That is to say, new {SWITCH} statements (and any other kind of statement) can be put inside a {#1087,CASE} section.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1022,WHILE statement}

{WHILE} {#1053,(} {#1037,<condition>} {#1053,)}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}ú

The {WHILE} statement implements a {loop}. That is to say, it is capable of {repeating a group 
of statements a specific number of times}.

In order to implement this loop, the condition that has to be complied for the group of 
statements to be executed must be specified in brackets, after the reserved word {WHILE}. 
All the statements that necessarily have to be repeated will be put after the specification 
of this condition. Finally, the end of the loop will be marked with the reserved word {#1091,END} 
(It doesn't matter whether
more words {#1091,END} appear inside the loop when they belong to internal statements of that loop).

When a {WHILE} statement is executed, the specified verification will be carried out. 
If the result is true, the internal statements will be executed. Otherwise, the program will 
continue from the {#1091,END}, that marks the end of the {WHILE}.

If the internal statements have been executed (what is called to make a loop's {iteration}), 
the condition will be verified again. If it is true, another {iteration} will be made 
(the internal statements will be executed again). This process will be repeated until it is 
verified that the condition of the {WHILE} is false.

If the condition turns to be false directly while a {WHILE} statement is executed, then 
the internal statements will never be executed.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    x=0;
    WHILE (x<320)
        x=x+10;
        FRAME;
    END
END
{-}

In this example, the {x} local variable ( x coordinate of the process) will be put at 
zero and then, providing that x is less than 320, 10 will be added to {x} and a {#1029,FRAME} will be performed.

A {#1026,BREAK} statement inside a {WHILE} loop will immediately finish it, continuing the program from the following statement to that loop.

A {#1027,CONTINUE} statement inside a {WHILE} loop will force the program to
verify the initial condition immediately and, if it is true, to execute again the internal statements from the beginning (after the {WHILE}).
If the condition turns to be false, the {#1027,CONTINUE} statement will finish the loop.

The internal statements of a {WHILE} loop can be as many as desired, and of any kind, obviously including new {WHILE} loops.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1023,REPEAT statement}

{REPEAT}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1097,UNTIL} {#1053,(} {#1037,<condition>} {#1053,)}

The {REPEAT} (REPEAT ... UNTIL( ... )) statement implements a {loop}. That is to say, it is capable of {repeating a group of statements a specific number of times}.

In order to implement this loop, it is necessary to start with the reserved word {REPEAT}, followed by the statements that you want to repeat once or more times, and the end of the statement will be determined by putting the reserved word {#1097,UNTIL}, followed by the condition that has to be complied for {the statement to finish}.

When a {REPEAT} statement is executed, the internal statements (those placed between the {REPEAT} and the {#1097,UNTIL}) will be executed first and then, the condition specified in the {#1097,UNTIL} will be verified. If it is still false, the internal statements will be executed again. The process will be repeated until the condition of the {#1097,UNTIL} turns to be true, continuing then the execution of the program after this statement.

Every time that the internal statements are executed, a loop's {iteration} has been made. The {REPEAT} ... {#1097,UNTIL} (the {<condition>} is complied) statement will always execute the internal statements at least once, so it always verifies the condition after the execution.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    x=0;
    REPEAT
        x=x+10;
        FRAME;
    UNTIL (x>320)
END
{-}

In this example, the {x} local variable (x coordinate of the process) will be put at 
zero and then, 10 will be added to {x} and a {#1029,FRAME} will be performed {until} {x} becomes a number bigger than 320.

A {#1026,BREAK} statement inside a {REPEAT} loop will immediately finish it, continuing the program from the following statement to that loop.

A {#1027,CONTINUE} statement inside a {REPEAT} loop will force the program to immediately make the verification of the {#1097,UNTIL} and, if it is true, it will execute again the internal statements from the beginning (after the reserved word {REPEAT}). If the condition turns to be true, the {#1027,CONTINUE} statement will finish the loop.

The internal statements of a {REPEAT } loop can be as many as desired, and of any kind, obviously including new {REPEAT} loops.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1024,LOOP statement}

{LOOP}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}

The {LOOP} statement implements an {infinite loop}. That is to say, it {indefinitely repeats a group of statements}.

In order to implement this loop, it is necessary to start with the reserved word {LOOP}, followed by the statements intended to be repeated continuously, putting the reserved word {#1091,END} at the end.

When a {LOOP} ... {#1091,END} statement is found in a program, all the internal statements of that loop will repeatedly be executed from this position.

In order to finish a {LOOP} loop, it is possible to use the {#1026,BREAK} statement which, on being executed inside a loop of this kind, will force the program to continue from the {#1091,END}.

Every time that the internal statements are executed, a loop's {iteration} has been made. The {#1027,CONTINUE} statement inside a loop will finish the current {iteration} and will start the following one (the program will go on running after the reserved word {LOOP}.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    x=0;
    LOOP
        IF (key(_esc))
            BREAK;
        END
        x=x+1;
        FRAME;
    END
END
{-}

In this example, the {x} local variable (x coordinate of the process) will be put at 
zero and then, 1 will be added to {x} and a {#1029,FRAME} will continuously be done. If the escape key ({ESC}) is pressed, then the {#1026,BREAK} statement will be executed, finishing the {LOOP} loop.

The internal statements of a {LOOP} loop can be as many as desired, and of any kind, obviously including new {LOOP} loops.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1025,FOR statement}

{FOR} {#1053,(}<initialisation>{#1068,;} <condition>{#1068,;} <increment>{#1053,)}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}

The {FOR} statement (replica of the C language) implements a {loop} and is capable of {repeating 
a group of statements a specific number of times}.

In order to implement this loop, three different parts must be specified in brackets, 
separated by symbols {#1068,;} (semicolon) after the reserved word {FOR}. 
These three parts, that are optional (they can be omitted), are the following ones:

- {Initialisation}. An assignment statement is normally codified in this part. This kind of statement establishes the initial value of the variable that is going to be used as a counter of the loop's {iterations} (each execution of the inner group of statements is called a loop's {iteration}).  The assignment statement {x=0}, that would put the {x} variable at zero at the beginning of the loop (value
for the first iteration), is an example.

- {#1037,Condition}. A condition is specified in this part. Just before each iteration, this condition will be checked and, if it is true, the group of statements will be executed. If the condition is false, the {FOR} loop will finish, continuing the program after the {#1091,END} of the {FOR} loop.
An example of condition can be {x<10}, that would allow the inner group of statements to be executed only when the {x} variable is a number
less than {10}.

- {Increment}. The increment of the variable used as a counter for each iteration of the loop is indicated in the third part. It is normally expressed with an assignment statement. For instance, the {x=x+1} statement would add {1} to the {x} variable after each iteration of the loop.

The group of inner statements of the loop that are going to sequentially be repeated while the condition of continuance (second part) is complied, must appear after the definition of the {FOR} loop with its three parts. After this group of statements, the reserved word {#1091,END} will determine the end of the {FOR} loop.

When a {FOR} statement appears in a program, the part of the initialisation will be executed first, 
checking the condition. If it is true, the inner group of statements first and, the part of the 
increment then, will be executed, being the condition checked again, etc. If, before any iteration, 
the condition turns to be false, the {FOR} loop will immediately finish.

A program with a {FOR} loop containing the three parts mentioned in the previous sections is now shown.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FOR ( x=0 ; x<10 ; x=x+1 )
        // The internal statements would be put here.
    END
END
{-}

This loop would first run with the {x} variable equal to {0}, the second one equal to {1}, ..., and the last variable equal to {9}. The part of the increment would be executed after this iteration, becoming {x} equal to {10}. Then, on
checking the condition of continuance in the loop ({x} is less than {10}), if it is false, the loop would finish.

As it has been mentioned, the three parts in the definition of the loop are optional. If the three were omitted:

  {FOR ( ; ; )}ú
      // ...ú
  {END}

Then, this loop would be equivalent to a {#1024,LOOP} ... {#1091,END} loop.

Moreover, several parts of initialisation, condition or increment can be put in a {FOR} loop, separated by commas ({#1059,,}). At first, all the initialisations will be executed. Then, all the conditions of continuance will be checked (if any of them turns to be false, the loop will finish). The inner statements and, after every iteration, all the increments, will finally be checked.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FOR ( x=0, y=1000 ; x<y ; x=x+2, y=y+1 )
        // The internal statements would be put here.
    END
END
{-}

A {#1026,BREAK} statement inside a {FOR} loop will immediately finish it, continuing the program from the following statement of this loop.

A {#1027,CONTINUE} statement inside a {FOR} loop will force to execute the part of the increment directly and then, to verify the condition of continuance. If it is true, then the inner statements will be executed again from the beginning. If the condition turns to be false, then the {#1027,CONTINUE} statement will finish the {FOR} loop.

A {FOR} loop is practically equivalent to a {#1022,WHILE} loop, implemented
in the following way:

{#9999,Example:}
PROGRAM my_game;
BEGIN
    x=0;
    WHILE (x<10)
        // The internal statements would be put here.
        x=x+1;
    END
END
{-}

With the only exception that a {#1027,CONTINUE} statement, inside this {#1022,WHILE} loop, would not execute the part of the increment, while it would do so inside a {FOR} loop.

If, after the execution of the initialisation, the condition turns to be false directly inside a {FOR} loop, no inner statements will ever be executed.

The internal statements of a {FOR} loop can be as many as desired, and of any kind, obviously including new {FOR } loops.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1026,BREAK statement}

A {BREAK} statement inside a loop will immediately finish it, continuing the program from the following statement to that loop.
This statement can only be put inside the following loops:

  {#1022,LOOP} ... {#1091,END}ú
  {#1043,FROM} .. {#1096,TO} .. {#1095,STEP} .. ... {#1091,END}ú
  {#1023,REPEAT} ... {#1097,UNTIL} {#1053,(} .. {#1053,)}ú
  {#1022,WHILE} {#1053,(} .. {#1053,)} ... {#1091,END}ú
  {#1025,FOR} {#1053,(} .. {#1068;} .. {#1068,;} .. {#1053,)} ... {#1091,END}ú

A {BREAK} sentence will make the program continue its execution after the {#1091,END} or the {#1097,UNTIL} of the loop closer to the statement.

If there are several nested loops (one inside another one), the {BREAK} statement will only exit the inner loop.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    LOOP
        REPEAT
            IF (key(_esc)) BREAK; END
            //...
            FRAME;
        UNTIL (x==0);
        //...
    END
END
{-}

In this example, the {BREAK} statement will exit the {#1023,REPEAT} ... {UNTIL} (when the 
{ESC} key is pressed), but not the {#1022,LOOP} ... {#1091,END}.

{Important}{/}

The {BREAK} statement is not valid to finish {#1020,IF},
{#1021,SWITCH} (or the {#1087,CASE} sections of this statement), or
{#1030,CLONE} statements.

{BREAK} can only finish the statements that implement a loop.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1027, CONTINUE statement}

A {CONTINUE} statement inside a loop will force the program to
finish its current iteration and start the following iteration.

We call {iteration} to each execution of the set of statements internal to a loop (the statements between a {#1024,LOOP} and its {#1091,END}, for instance).

This statement can only be put inside one of the following loops:

{#1024,LOOP} ... {#1091,END}ú
A CONTINUE inside this loop will jump to the LOOP.

{#1043,FROM} .. {#1096,TO} .. {#1095,STEP} .. ... {#1091,END}ú
A CONTINUE inside this loop will perform the increment (STEP) and, if the value indicated in the TO has not been passed, the program will continue at the beginning of the loop.

{#1023,REPEAT} ... {#1097,UNTIL} {#1053,(} .. {#1053,)}ú
A CONTINUE inside this loop will jump to the UNTIL.

{#1024,WHILE} {#1053,(} .. {#1053,)} ... {#1091,END}ú
A CONTINUE inside this loop will jump to the WHILE.

{#1025,FOR} {#1053,(} .. {#1068,;} .. {#1068,;} .. {#1053,)} ... {#1091,END}ú
A CONTINUE inside this loop will perform the increment
and the comparison. If the latter is true, the program will continue at the beginning of the loop. But if it is false, the program will continue after the END of the FOR.

If there are several nested loops (one inside another), the {CONTINUE} statement will take effect only in the inner loop.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FOR (x=0, y=0;x<10;x++)
        IF (x<5) CONTINUE; END
        y++;
    END
END
{-}

In this example, after the whole loop has been executed, {x} will be equal to {10} and {y} will be equal to {5} as, providing that {x} is less than 5, the {CONTINUE} statement prevents the {y++;} statement from being executed.

{Important}{/}

The {CONTINUE} statement is not valid inside {#1020,IF},
{#1021,SWITCH} (or the {#1087,CASE} sections of this statement), or
{#1030,CLONE} statements (as these statements do not implement loops and, therefore, they do not make iterations).

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1028,RETURN statement}

The {RETURN} statement immediately finishes the current process, as if the {#1091,END} of its {#1086,BEGIN} was reached.

When this statement is included in the main code, it will finish the current process. But if there are alive processes, they will go on running. For instance, the {#109,exit()} function can be used to finish a program and all its processes.

A {RETURN} inside a process will finish it, killing this process.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    LOOP
        IF (key(_esc))
            RETURN;
        END
        FRAME;
    END
END
{-}

In this example, the {RETURN} statement will be executed by pressing the escape key ({ESC}), finishing the program.

{Use of RETURN to return a value}{/}

It is possible to design processes with a performance similar to the functions
of other programming languages, that {receive a series of parameters and
return a value}. For instance, a process receiving two numeric values and returning the biggest one.

For that, this statement must be used with the following syntax:

{RETURN(}{#1035,<expression>}{)}

It is also important not to use the {#1029,FRAME} statement inside the process,
as this statement will immediately return to the calling process. When the compiler finds the {#1029,FRAME} statement inside a {#1016,PROCESS}, it directly classes it as a process, ruling out its hypothetical use as a function.

{Important:} To return a value with the {RETURN} statement after execution of one or more
{#1029,FRAME} statements , you must make a block of this type, ie. a {#1408,FUNCTION}.

{/}


The example proposed before is shown now: an implementation of the
mathematical function {max} that returns the greater of its two parameters.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    x=max(2, 3)+max(5, 4);
END
PROCESS max(a, b)
BEGIN
    IF (a>b)
        RETURN(a);
    ELSE
        RETURN(b);
    END
END
{-}

After the execution of this program, the {x} variable of the main process will be equal to {8} (3+5).

{Important}{/}

By default, if the {RETURN} statement is used without the expression
in brackets or the {#1029,FRAME} statement is used in a process, its return value will be its 
{#1039,identifying code} of the process}.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1029,FRAME statement}

The {FRAME} statement is an essential part of the language. A program's working is described below 
in general terms:

- The main program starts its execution. This process may create more processes (objects of the game) 
at any point. All the processes may finish at any moment, and they may create or eliminate other processes.

- The games will always be displayed frame by frame. In each frame, the system will execute all the 
processes existing at that moment, one by one, until each one executes the {FRAME} statement, which 
will indicate that it is ready for the next display (frame).

In the preparation of each frame, all the processes will be executed in the established priority 
order (the {#1121,priority} local variable of the processes determines this order).

Therefore, this statement is similar to an order for the processes to be displayed.

If a process starts its execution and it neither finishes nor executes this statement, then the program 
will become blocked, as there is a process that is never ready for the next display. Therefore, the 
system won't be capable of showing the following frame.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    my_process();
    my_process();
    LOOP
        IF (key(_esc))
            my_second_process();
        END
        FRAME;
    END
END
PROCESS my_process()
BEGIN
    LOOP
        FRAME;
    END
END
PROCESS my_second_process()
BEGIN
    LOOP
    END
END
{-}

In this program, the main process (a {my_game} type process) creates other two
processes ({my_process} type). From that moment, the three processes
will continuously be executed, each one to their {FRAME} statement. But if the escape key ({ESC}) is pressed, then the main process will create a new process ({my_second_process} type) that will remain in a {#1024,LOOP} loop indefinitely, without executing any {FRAME}. Consequently, the program will be interrupted (the system will report such a situation after few seconds; see {#1115,max_process_time}).

Basically, all the processes that correspond with objects of a game
construct a loop inside which, every frame establishes all its display values ({#1123,x}, {#1124,y}, {#1126,graph}, {#1128,size}, {#1129,angle}, ...), executing then the {FRAME} statement.

{Synchronisation of processes}{/}

It is possible to use this statement with the following syntax:

{FRAME(}<percentage>{)}

By putting in brackets a whole percentage, from 0 to 100 or bigger, after the reserved word {FRAME}.

This figure will indicate the percentage of the following frame, completed by the  process. That is to say, the absence of this percentage is equivalent to putting {FRAME(100)} (100% of the work previous to the following display has been completed by the process).

For instance, if a process executes the {FRAME(25)} statement in a loop, it will need to execute it {4 times} before it is ready for the next display (as 4*25% is the 100%).

On the other hand, if a process executes the {FRAME(400)} statement inside its loop, after its first execution, it will have completed 400% the display. Therefore,even after the display, a completed 300% of display will still be missing. For that, in the preparation of the following {3} frames the system won't execute this process, as it is ready for the display. Then, this process would be executed just once every 4 frames (unlike the example of the previous paragraph, in which it was executed 4 times every game's frame).

The processes won't reach the next display unless they give {100%, at least}. For instance, if a process always executes {FRAME(80)} statements, it will execute them twice before the first display, so it will have completed 160% (2*80%) the display. Therefore, it will have pre calculated 60% (160%-100%) for the next display. For that reason, in the second display it will only require a {FRAME(80)} statement to be displayed, as this 80%, plus the remaining 60% of the first display, will be equal to a 140% completed. Therefore, it will immediately be displayed ,and a 40% will be left to prepare the next frame.

{/}

A {FRAME(0)} statement completing a 0% of the next display only makes sense in the two following cases:

- It can be a way to force the system to execute in this point the rest of the processes having the same priority as the current one and, after them, the system will execute the latter again.

- It can also be a way to initialise functions such as {#120,get_id()} or
{#104,collision()}, as they return some specific values for every frame. If the aim is to obtain values again, it is possible to execute a {FRAME(0)} statement that will be interpreted as a new frame by these functions.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1030,CLONE statement}

{CLONE}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}

This statement creates a new process identical to the current one, with the exception that the statement between the reserved words {CLONE} and {#1091,END} will only be executed in the new process, but not in the current one.

For instance, if any process of the program, with specific coordinates ({#1123,x}, {#1124,y}) and with a specific graphic ({#1126,graph}), executes the following statement:

  {CLONE}ú
      x=x+100;ú
  {#1091,END}

A new process will be created, identical to the former, with the same graphic and the same values in all its variables, with the exception of the {#1123,x} coordinate that, in the new process, will be placed {100} pixels farther to the right.

This statement is used to create replicas of a process, dividing it into two processes (almost) similar.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    // ...
    x=0;
    y=0;
    CLONE
        x=x+10;
    END
    CLONE
        y=y+10;
    END
    // ...
END
{-}

In this example, the {2} {CLONE} statements will create {3} copies of the main process (and not 2, as it could have been expected).

On executing the first {CLONE} statement, a new process will be created. Thus, there will be {2} processes: one in (x=0, y=0) and the other in (x=10, y=0). These two processes will execute the second {CLONE} statement. The first one (the original one) will create a new process in (x=0, y=10), and the second one will create the new process in (x=10, y=10).

To create only {2} copies of the original process, the program could have been constructed, for instance, in the following way:

{#9999,Example:}
PROGRAM my_game;
BEGIN
    // ...
    x=0;
    y=0;
    CLONE
        x=x+10;
        CLONE
            y=y+10;
        END
    END
    // ...
END
{-}

The original process (x=0, y=0) will create one in (x=10, y=0) and the latter will create another one in (x=10, y=10). Therefore, only two copies of the original will be created.

Much care must be taken when it comes to using the {CLONE} statement sequentially or inside a {loop},
as it is necessary to take into account that the first '{clones}' may also create new '{clones}'.

This statement can be used without putting statements between the words {CLONE} and {#1091,END}.
But, intending to have two identical processes with the same coordinates, the same graphic and
executing the same code, seems to make little sense, at least at first.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1031,DEBUG statement}

The {DEBUG} statement will call the interactive debugger when it is executed.

It is normally used to debug programs, to find possible
errors of the programs. On some occasions, it is normally put in the following points.

- Where you want to verify that a part of the program has done what was expected. After the execution of that part, {DEBUG} will call the debugger, from which it is possible to check all the active processes and the value of all their variables.

- When you are not very sure whether something can happen in a program, you can put this statement in that point to report you whether what we are expecting actually happens.

This statement is only used temporarily, until the error that is looked for is found. From that moment, the statement won't be necessary. Thus, it can be removed from the program since it has no additional effect.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    // ...
    IF (x<0)
        DEBUG;
    END
    // ...
END
{-}

In this example, it is verified that, in a specific point of the program, the {x} coordinate of the process is not a negative number (less than zero). If this happens, the debugger will be called to find out why it has happened.

When this statement is executed, a dialog box appears, offering us the following options:

- To disable the {DEBUG} statement, preventing it from being activated in this execution of the program.

- To stop the program and enter the debugger, to be able to examine all the processes and their variables.

- Or to finish the execution of the program immediately, returning to its edition in the windows' graphic environment.

Moreover, if the escape key {ESC} is pressed in that box, the {DEBUG} statement will simply be ignored, and the program will continue to be executed as usual.

{/}

When a program is executed from the windows' graphic environment, the debugger can be called at any moment by pressing the {F12} key.

On invoking the debugger in this way, the program will always be interrupted just before starting the processing of a new frame. All the processes to be executed will appear before the next display.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1032,List of functions of the language.}{+4,1}{-}

  Process interaction functionsú
    {#104,collision()}ú
    {#116,get_angle()}ú
    {#117,get_dist()}ú
    {#118,get_distx()}ú
    {#119,get_disty()}ú
    {#120,get_id()}ú
    {#129,let_me_alone()}ú
    {#158,signal()}ú

  Geometry functionsú
    {#101,advance()}ú
    {#113,fget_angle()}ú
    {#114,fget_dist()}ú
    {#142,near_angle()}ú
    {#183,xadvance()}ú

  Path finding functionsú
    {#185,path_find()}ú
    {#187,path_free()}ú
    {#186,path_line()}ú

  Mathematical functionsú
    {#100,abs()}ú
    {#246,acos()}ú
    {#245,asin()}ú
    {#247,atan()}ú
    {#248,atan2()}ú
    {#243,cos()}ú
    {#145,pow()}ú
    {#242,sin()}ú
    {#160,sqrt()}ú
    {#244,tan()}ú

  Random number functionsú
    {#149,rand()}ú
    {#150,rand_seed()}ú

  Graphics functionsú
    {#103,clear_screen()}ú
    {#123,get_pixel()}ú
    {#135,map_block_copy()}ú
    {#136,map_get_pixel()}ú
    {#137,map_put()}ú
    {#138,map_put_pixel()}ú
    {#139,map_xput()}ú
    {#188,new_map()}ú
    {#146,put()}ú
    {#147,put_pixel()}ú
    {#148,put_screen()}ú
    {#212,screen_copy()}ú
    {#173,xput()}ú

  Primitive graphics drawing functionsú
    {#250,delete_draw()}ú
    {#249,draw()}ú
    {#251,move_draw()}ú

  Audio system functionsú
    {#256,change_channel()}ú
    {#102,change_sound()}ú
    {#175,reset_sound()}ú
    {#178,set_volume()}ú

  Sound effect functionsú
    {#221,is_playing_sound()}ú
    {#134,load_sound()}ú
    {#159,sound()}ú
    {#167,stop_sound()}ú
    {#170,unload_sound()}ú
    
  CD music functionsú
    {#127,is_playing_cd()}ú
    {#144,play_cd()}ú
    {#164,stop_cd()}ú

  Digital music functionsú
    {#220,get_song_line()}ú
    {#219,get_song_pos()}ú
    {#222,is_playing_song()}ú
    {#214,load_song()}ú
    {#218,set_song_pos()}ú
    {#216,song()}ú
    {#217,stop_song()}ú
    {#215,unload_song()}ú

  Input functionsú
    {#121,get_joy_button()}ú
    {#122,get_joy_position()}ú
    {#128,key()}ú

  Palette control functionsú
    {#105,convert_palette()}ú
    {#110,fade()}ú
    {#111,fade_off()}ú
    {#112,fade_on()}ú
    {#264,find_color()}ú
    {#266,force_pal()}ú
    {#133,load_pal()}ú
    {#154,roll_palette()}ú
    {#179,set_color()}ú

  Mode7 and scroll functionsú
    {#140,move_scroll()}ú
    {#152,refresh_scroll()}ú
    {#162,start_mode7()}ú
    {#163,start_scroll()}ú
    {#165,stop_mode7()}ú
    {#166,stop_scroll()}ú

  Mode 8 Functions (3D mode)ú
    {#195,get_point_m8()}ú
    {#193,get_sector_height()}ú
    {#198,get_sector_texture()}ú
    {#200,get_wall_texture()}ú
    {#191,go_to_flag()}ú
    {#189,load_wld()}ú
    {#201,set_env_color()}ú
    {#196,set_fog()}ú
    {#194,set_point_m8()}ú
    {#192,set_sector_height()}ú
    {#197,set_sector_texture()}ú
    {#199,set_wall_texture()}ú
    {#190,start_mode8()}ú
    {#182,stop_mode8()}ú

  Text display functionsú
    {#107,delete_text()}ú
    {#131,load_fnt()}ú
    {#141,move_text()}ú
    {#171,write()}ú
    {#177,unload_fnt()}ú
    {#172,write_int()}ú
    {#253,write_in_map()}ú

  String handling functionsú
    {#184,char()}ú
    {#210,lower()}ú
    {#203,strcat()}ú
    {#206,strchr()}ú
    {#205,strcmp()}ú
    {#202,strcpy()}ú
    {#211,strdel()}ú
    {#204,strlen()}ú
    {#208,strset()}ú
    {#207,strstr()}ú
    {#209,upper()}ú

  String conversion functionsú
    {#254,calculate()}ú
    {#255,itoa()}ú

  Animation functionsú
    {#108,end_fli()}ú
    {#115,frame_fli()}ú
    {#153,reset_fli()}ú
    {#161,start_fli()}ú

  Screen region functionsú
    {#106,define_region()}ú
    {#143,out_region()}ú

  Graphics information functionsú
    {#124,get_point()}ú
    {#125,get_real_point()}ú
    {#126,graphic_info()}ú

  Initialisation functionsú
    {#156,set_fps()}ú
    {#157,set_mode()}ú

  Resource handling functionsú
    {#132,load_fpg()}ú
    {#174,load_map()}ú
    {#174,load_pcx()}ú
    {#169,unload_fpg()}ú
    {#176,unload_map()}ú
    {#176,unload_pcx()}ú
    {#241,save_map()}ú
    {#241,save_pcx()}ú

  Data IO functionsú
    {#130,load()}ú
    {#155,save()}ú

  File-handling functions ú
    {#224,fclose()}ú
    {#229,filelength()}ú
    {#230,flush()}ú
    {#223,fopen()}ú
    {#225,fread()}ú
    {#227,fseek()}ú
    {#228,ftell()}ú
    {#226,fwrite()}ú

  Directory-handling functions ú
    {#235,chdir()}ú
    {#238,disk_free()}ú
    {#231,get_dirinfo()}ú
    {#232,get_fileinfo()}ú
    {#233,getdrive()}ú
    {#236,mkdir()}ú
    {#237,remove()}ú
    {#234,setdrive()}ú

  File compression functionsú
    {#262,compress_file()}ú
    {#263,uncompress_file()}ú

  File encryption functionsú
    {#261,decode_file()}ú
    {#259,encode()}ú
    {#260,encode_file()}ú

  System functionsú
    {#109,exit()}ú
    {#240,ignore_error()}ú
    {#168,system()}ú

  Dynamic memory allocation functionsú
    {#258,free()}ú
    {#257,malloc()}ú
    {#239,memory_free()}ú

  Network functions ú
    {#181,net_get_games()}ú
    {#180,net_join_game()}ú

{/}

{Note:} To obtain help about a specific function directly, place the edit
cursor on the name of the function (in the programs editor) and press {F1}.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1033,Call to a process}

<process_name>{(}<list of parameters>{)}

To call a process, put the {#1001,name} of the process, followed by a list including as 
many expressions separated by {#1059,commas (,)}, as {#1018,parameters} of the process, 
in {#1053,brackets (())}. The brackets are obligatory, even if the process has no call {#1018,parameters}.

A call to a process will always return a value that depends on which one of the following 
actions is performed first by the called process.

- If the {#1029,FRAME} statement is executed, then the process will return its {#1039,identifying code}.

- If the process executes the {#1028,RETURN}{#1053,(}<expression>{#1053,)} statement, 
then the former will return the result of this expression.

- If the process finishes, either because the {#1091,END} of its {#1086,BEGIN} is reached 
or because a {#1028,RETURN} statement is executed with no expression, the process will 
return the {#1039,identifying code} of itself, but as the process has now finished (killed), 
it is necessary to take into account that this {#1039,identifying code} can be assigned by the system 
to any new process created from now on.

The return value can be ignored, assigned to a variable or used inside an expression.

{#9999,Example:}
PROGRAM my_game;
PRIVATE
  id2;
BEGIN
    my_process(0, 0);
    id2=my_process(320, 200);
    // ...
END
PROCESS my_process(x, y)
BEGIN
    LOOP
        FRAME;
    END
END
{-}

In this example, the main process {my_game} makes two calls to the process {my_process}, which receives two parameters in its {x} and {y} local variables.

As the process executes the {#1029,FRAME} statement, it will return its {#1039,identifying code}.

It can be noticed how the value returned in the first call to the process
is ignored (it is not used at all), and how, in the second call, the {#1039,identifying code} of {my_process(320, 200)} is assigned to the private variable of the main process {id2}.

When a call to a process is made, the execution of the current process is momentarily stopped, and the code of the called process is executed, until it is returned through one of the three mentioned cases (until it finishes or executes a {#1029,FRAME} or {#1028,RETURN} statement).

If the process has finished with a {#1029,FRAME} statement, it will be displayed in the following frame according to the values established in its local variables ({#1023,x}, {#1024,y}, {#1026,graph}, ...) and, in the preparation of the following frame, this process will go on running from the {#1029,FRAME} statement.

{/}See: {#1000,Syntax} - {#1018,Parameters of a process}

# -----------------------------------------------------------------------------

{.1034,Reference to a variable}

A reference to a variable is any expression making reference to a cell or a position of the computer's memory. It is normally understood as one of the following aspects:

- If the variable is a variable, in order to refer to the variable in this way, we must simply specify its name.

Example of a reference to a variable: {x}

- If the variable is a table, reference to it is normally made with its name followed by an expression in square brackets ({#1079,[ ]}).That expression will determine the position of the table intended to be accessed.
If the index in square brackets is omitted, the first position of the table (position 0) will be accessed.

Example of a reference to a table: {timer[0]}

- If the variable is a structure, reference to it will be made with its name followed by an expression in square brackets ({#1079,[ ]}) that will determine the number of records that will be accessed. After it, the symbol{#1063, . (period)} will be put, preceding the specific name of the structure's field that is going to be accessed. If the record number in square brackets is omitted, the first record of the structure (number 0) will be accessed. 

Example of a reference to a structure: {scroll[0].z}

These three cases deal with accessing data of the process itself or global data. To access an alien variable (a local variable of another process), it will be preceded by the {#1039,identifying code} of the alien process and the symbol{#1063, . (period)}, operator of access to local data and structures).

Example of a reference to an alien local variable: {father.x}

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1035,Definition of an expression}

An expression is basically a mathematical formula involving one or more {operands} ({x}, {2}, {id}, ...) through different {operators} ({*}, {AND}, {>>}, ...); some examples of expressions would be:
{2}, {2+3} or {(x*4)/-3}.

Only integers within the range ({#1177,min_int} ... {#1178,max_int}) can be used as values. The result of the expression will always be truncated within this range.

These expressions will be evaluated when the statement containing them inside the program is executed.

The {operands} that can be used in an expression are the following ones:

    - {#1004,Constants}.ú
    - {Numeric values}.ú
    - {Literals} (texts in inverted commas).ú
    - Variables, tables or structures of any kind.ú
    - Any kind of function or process.ú
    - {#1039,Identifying code} of the process.ú
    - Type of process ({#1042,type <name>}).ú

The {operators} that can be used in an expression are the following ones (the synonymous of the operator, if they exist, are shown in brackets):

    {#1056, +}    Additionú
    {#1060, -}    Subtraction (or sign negation)ú
    {#1054, *}    Multiplicationú
    {#1065, /}    Divisionú
    {#1048, MOD}  Module ({#1048,%})ú
    {#1070, <<}   Rotation to the rightú
    {#1077, >>}   Rotation to the leftú
    {#1045, NOT}  Binary and logical negation ({#1045,!})ú
    {#1051, AND}  Binary and logical AND({#1050,&}, {#1051,&&})ú
    {#1083, OR}   Binary and logical OR({#1083,|}, {#1083,||})ú
    {#1082, XOR}  Exclusive OR ({#1080,^}, {#1082,^^})ú
    {#1074, ==}   Comparisonú
    {#1046, <>}   Different ({#1046,!=})ú
    {#1076, >}    Greater thanú
    {#1075, >=}   Bigger or equal ({#1075,=>})ú
    {#1069, <}    Lessú
    {#1072, <=}   Less or equal ({#1072,=<})ú
    {#1085, OFFSET} Direction or offset ({#1050,&})ú
    {#1057, ++}   Operator of incrementú
    {#1061, --}   Operator of decrementú
    {#1079, POINTER} Addressing operator ({#1054,*}, {#1080,^}, {#1079,[ ]})ú
    {#1053, ( )}  Bracketsú

Click on "{#1036,Evaluation of an expression}" to see the order in which the calculations are made inside an expression and when the brackets must be used.

Some examples of valid expressions are now shown:

{    -33}ú
{    44-2*22}ú
{    id}ú
{    x+1}ú
{    (angle*3)/2-pi/2}ú
{    (x+y)/2}ú
{    abs(x-y)*3-pow(x, 2)}ú
    ...

{/}See: {#1000,Syntax} - {#1036,Evaluation of an expression}

# -----------------------------------------------------------------------------

{.1036,Evaluation of an expression}

It is important to know the way in which the expressions are evaluated in order to know where it is necessary to put brackets indicating the way in which the expression is intended to be evaluated.

In the language, an expression can contain operators of different levels of priority.

In the evaluation of an expression, the operators of {priority 1} (if they exist), will always be processed first, and then, those of {priority 2}, {priority 3} and so on.

Priority 1ú
    {#1053, ( )}  Brackets, beginning and end of a sub expressionú

Priority 2ú
    {#1063, .}    Period, access' operator to local data and structuresú

Priority 3ú
    {#1045, NOT}  Binary and logical negation (#1045,{!})ú
    {#1085, OFFSET} Offset (#1050,{&})ú
    {#1079, POINTER} Addressing operator ({#1054,*}, {#1080,^}, {#1079,[ ]})ú
    { -}  Sign negationú
    {#1057, ++}   Operator of incrementú
    {#1061, --}   Operator of decrementú

Priority 4ú
    {#1054, *}    Multiplicationú
    {#1065, /}    Divisionú
    {#1048, MOD}  Module ({#1048,%})ú

Priority 5ú
    {#1056, +}    Additionú
    {#1060, -}    Subtractionú

Priority 6ú
    {#1070, <<}   Rotation to the rightú
    {#1077, >>}   Rotation to the leftú

Priority 7ú
    {#1051, AND}  Binary and logical AND ({#1050,&}, {#1051,&&})ú
    {#1083, OR}   Binary and logical OR ({#1083,|}, {#1083,||})ú
    {#1082, XOR}  Exclusive OR ({#1080,^}, {#1082,^^})ú

Priority 8ú
    {#1074, ==}   Comparisonú
    {#1046, <>}   Different ({#1046,!=}ú
    {#1076, >}    Greater thanú
    {#1075, >=}   Bigger or equal ({#1075,=>}ú
    {#1069, <}    Lessú
    {#1072, <=}   Less or equal ({#1072,=<}ú

Priority 9ú
    {#1073, =}    Assignmentú
    {#1058, +=}   Addition-assignmentú
    {#1062, -=}   Subtraction-assignmentú
    {#1055, *=}   Multiplication-assignmentú
    {#1066, /=}   Division-assignmentú
    {#1049, %=}   Module-assignmentú
    {#1052, &=}   AND-assignmentú
    {#1084, |=}   OR-assignmentú
    {#1081, ^=}   XOR-assignmentú
    {#1078, >>=}  Rotation to the right-assignmentú
    {#1071, <<=}  Rotation to the left-assignmentú

The operators of {priority 3} are known as {unary} operators. They do not link two operands (unlike the {binary} operators such as, for instance, a multiplication), but they just affect the value of an operator. Inside the {unary} operators, those closest to the operand will be executed first. For instance, in the expression:

  {NOT -x}

The operand {x} has two {unary} operators, the negation of sign{ -} and
the logical and/or binary {#1045,NOT}. Among them, the negation of sign will be executed first, as it is closer to the operand.

From {priority 4}, all the operators are {binary} and they will be executed according to their level of priority. Therefore, when in an expression there is more than one operator of the same level (for instance, a multiplication and a division, both of priority 4), they will be processed from left to right. That is to say, in the following expression:

  {8/2*2}

The division will be executed first and then, the multiplication (it is the natural way to evaluate the expressions mathematically).

The only exception are the operators of {priority 9} ({assignment} operators),
that will be evaluated from right to left (instead of from left to right). That is to say, in the expression:

  {x=y=0}

{y=0} will be processed first ({y} will be put at {0}) and then, {x=y} ({x} will also be put at {0}, as {y} will now be equal to {0}).

As it can be noticed, the assignments work like an operator
After the assignment, they return the value they have assigned as a result of the operation.

{/}See: {#1000,Syntax} - {#1035,Definition of an expression}

# -----------------------------------------------------------------------------

{.1037,Definition of a condition}

The conditions are expressions normally similar to the following ones:

  {x<320}ú
  {size==100 AND graph>10}ú
  {y==0 OR (x>=100 AND x<=200)}ú
  ...

In general, any expression is valid as a condition. In the language, all the {ODD} expressions are interpreted as {true} and all the {EVEN} expressions are interpreted as {false}.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    IF (20*2+1)
        x=x+1;
    END
END
{-}

In this example, the {x=x+1;} statement will always be executed, as the expression {20*2+1} is equal to {41}, an {odd} number.

All the available operators are valid inside a condition. It is even possible to perform assignments inside a condition (the assignments are operations that return the assigned value as a result).

All the {#1039,identifying codes} of processes are {odd} numbers. That is to say, all of them are {true}. Therefore, it is possible to implement conditions
as the following one (supposing that {id2} has been declared as a variable,
and that {shot} is a type of process of the program).

  {id2=get_id(type shot);}ú
  {WHILE (id2)}ú
      {id2.size=id2.size-1;}ú
      {id2=get_id(type shot);}ú
  {END}


In the {id2=get_id(type shot)} condition, the result of the {get_id} function is being assigned to the {id2} variable. If that function has returned an {#1039,identifying code}, it will be an {odd} number and the condition will be evaluated as {true} (if {get_id()} does not find (more) identifiers of "{shot} type" processes, then it will return {0} (an {even} number), and the condition will be interpreted as {false}, finishing the {#1022,WHILE} statement.

The previous statements would decrement the {#1128,size} variable of all the {shot} type processes existing in the program.

{/}See: {#1000,Syntax} - {#1035,Definition of an expression}

# -----------------------------------------------------------------------------

{.1038,Ways to obtain the identifying code of a process.}

All the processes have their own {#1039,identifying code} in {#1092,ID}
(reserved word in the language that is equivalent to the {#1039,identifying code} of the process).

When a process is created (is called), it returns its own {#1039,identifying code} as return value, unless it has finished with a {#1028,RETURN}{#1053,(}<expression>{#1053,)}. That is to say, a process will always return its {#1039,identifying code} when it finishes (when its {#1091,END} is reached), when it executes the {#1029,FRAME} or the {#1028,RETURN} statements without expression in brackets.

In the following example, a process ({my_process} type) is created from the main program, and its identifier is stored in the {id2} variable.

{#9999,Example:}
PROGRAM my_game;
PRIVATE id2;
BEGIN
    id2=my_process();
    // ...
END
PROCESS my_process()
BEGIN
    // ...
END
{-}

All the processes have the following local variables predefined with identifiers of other processes:

{#1117,father} - father, identifier of the process that created it (the one that made the call).

{#1118,son} - son, identifier of the last process created by it (last called process).

{#1120,bigbro} - Elder brother, identifier of the last process created by the father before creating it.

{#1119,smallbro} - Younger brother, identifier of the following process created by the father after having created it.

These variables can be equal to {0} if they have not been defined (for instance,
{#1118,son} will be equal to {0} until a process is not created or if this process has disappeared).

The processes' identifying codes allow us to access their local variables (<identifier>.<variable>) and, as {#1117,father}, {#1118,son}, etc. are also local variables, it is possible to make combinations such as {son.bigbro} to access the identifier of the penultimate process created (as {#1118,son} is the last one; therefore, its elder brother will be the penultimate one).

Besides creation or direct relationship, there are other ways to obtain identifying codes of processes, as indicated below:

- The {#120,get_id()} function to obtain the identifiers of the processes of a specific type (spacecraft, shot, etc.) existing at a specific moment in the game.

- The {#104,collision()} function to obtain the identifiers of the
processes with which it is colliding.

When a specific process needs to access from many others, as it is an important process such as, for instance, the protagonist spacecraft of a game,
then it can be more useful to assign its identifier to a {#1006,GLOBAL} variable of the program (that can be accessed by any process at any point). Thus, any process will be able to interact with it, as it will have its identifier.

{#9999,Example:}
PROGRAM my_game;
GLOBAL
  id_spacecraft;
BEGIN
    id_spacecraft=spacecraft();
    // ...
END
PROCESS spacecraft()
BEGIN
    // ...
END
PROCESS enemy()
BEGIN
    // ...
    id_spacecraft.z=0;
    // ...
END
{-}

In this example, at a specific point the {enemy} type processes access the {z} variable of the {spacecraft} created by the main program, using for that purpose its identifier, that is included in the {id_spacecraft} global variable.

{/}See: {#1039,Identifying codes of processes.}

# -----------------------------------------------------------------------------

{.1039, Identifying codes of processes.}

A process is an object independent of the program, that executes its own code and that can have its own coordinates, graphics, etc. Processes of a program can be, for instance, a shot, spacecraft or enemy.

When something similar to what is below is input inside a program:

{PROCESS shot(}...{);}ú
{#1086,BEGIN}ú
   { // }statements{ ...}ú
{#1091,END}

The statements that are going to execute the "{shot} type" processes (the code ruling their performance), are specified.

As it can be noticed, more than one {shot} type process may exist in a program. Then, how can they be distinguished? Simply by their identifying code.

Every time that a new process is created in a game, an identifying code is assigned to this process. This code is going to be the exclusive reference of the process until it disappears.

Two different processes will never have the same identifying code at the same time. However, the code that belonged to a process that has already disappeared can be assigned to a new process (something similar to what happens in relation to an i.d.).

The identifying codes are always whole, positive, odd numbers, like 471, 1937 or 10823.

All the processes have their own identifying code in {#1092,ID}, that is something similar to a process' local variable local, with the proviso that it can not be modified.

Moreover, the processes have the identifying code of the process that created them (that called them) in {#1117,father}. They have the identifying code of the last process they created (the last one they called) in {#1118,son}. And so on.
(see {#1041,Hierarchies of processes}).

{What are the identifying codes for?}{/}

Normally, all the processes need the identifying code of the other processes in order to interact with them (to see where they are, to modify them, ...).

For instance, it is not possible to subtract energy from the "{enemy} type" process, as many or none of this type of processes may exist. It is necessary to have the specific identifying code of the {enemy} process from which you want to subtract energy.

A process accesses all its own variables simply by their names, such as {#1123,x}, {#1128,size} or {#1126,graph}. Thus, if the identifier of a process is known (in {#1118,son}, {#1117,father} or any variable defined by the user, such as {id2}), then it is possible to access the variables of that process, like ({son.x}, {father.size} or {id2.graph}). That is to say, the syntax to access local variables of another process is as follows:

  <identifying_code> . <name_variable>

These variables can normally be used to consult them modify them.

{It is not at all possible to access {#1008,PRIVATE} variables of another process at any rate}. In order to access a private variable of another process, it is necessary to change its declaration to the {#1007,LOCAL} section to transform it into a local variable. Then, any process will be able to access that variable just having the identifying code of the process, as all the processes will have that variable.

The identifiers have more utilities other than the access to alien local variables,
such as the {#158,signal()} function, that can send specific signals to a process if its identifying code is known (for instance, to eliminate the process).

There are also other functions, such as {#104,collision()}, used to detect collisions with other processes. When this function detects a collision, it returns the identifying code of the process with which it is colliding. Once this code is known, it is possible to access the variables of the process and send them signals.

The {#120,get_id()} function operates in a similar way to {#104,collision()},
obtaining the identifying code of a process. But in this case, no collision with it is necessary.

{/}See: {#1038,Ways to obtain the identifying code of a process.}

# -----------------------------------------------------------------------------

{.1040,States of a process.}

Processes are the different elements of a program (objects of the game). They may experience different states on creating, destroying or receiving specific signals with the {#158,signal()} function.

{alive or awake.} process

A process is alive when it is running (when it is interpreting the statements
located between its {#1086,BEGIN} and its {#1091,END}).

{dead.} process

A process is dead when it finishes (either because its {#1091,END} is reached in  the execution, a {#1028,RETURN} is executed or because it receives a signal {#1153,s_kill} or {#1157,s_kill_tree}).

{asleep.} process

A process may receive the signal {#1155,s_sleep} (or {#1159,s_sleep_tree}), then becoming asleep. In this state, this process will appear to be dead. But it is not as, at any moment, it may receive a signal {#1154,s_wakeup} and return to the alive or awake states. It is also possible to kill an asleep process.

{frozen.} process

The signal {#1156,s_freeze} (or {#1160,s_freeze_tree}) freezes a process. In the frozen state, the process, that is still visible, remain blocked. It may be detected by the rest of the processes (for instance, as for collisions), but it is not executed (it stops interpreting its code statements). It will remain in this state until it receives another signal that changes its state or that kills it.

A frozen process may be controlled (moved) by another process,
directly manipulating its variables.

{/}

When a signal is sent to a process, aiming at changing its state, this signal will have no effect before its following display ({#1029,FRAME}) is reached if the process is running. If the process is not running, then the signal will have an immediate effect.

No signal must be sent to nonexistent processes (to an {#1039,identifying code} that does not correspond with any process).

This signal will be ignored when the aim is to put a process in the state in which it is already.

{/}See: {#1041,Hierarchy of processes.}

# -----------------------------------------------------------------------------

{.1041,Hierarchies of processes.}

A process is an independent object of the program, that executes its own code and that may have its own coordinates, graphics, etc. For instance, a shot, spacecraft or enemy can be processes of a program.

When a program starts to run there is only one process: the initial process, which starts the execution of the main code's statements. But, from this moment, this process can create new processes that, at the same time can create other processes, destroy them, etc.

In order to clarify the events appearing through a program, we use a simile, treating the processes as if they were alive beings that are born and killed (when they are created or destroyed). For that reason, the following terms are established:

{Father}, name given to the process that has created another one (mother would have been a more appropriate name).

{Son}, process created by another one.

{Brothers}, processes created by the same father.

{Orphan}, process whose father has died (as it has been either eliminated or finished).

This vocabulary may be spread as far as your imagination desires {grandfathers}, {grandsons}, {uncles}, etc.

All the processes have direct access to the identifying codes of the processes with which they have direct relationship (see: {#1038,Ways to obtain the {#1039,identifying code} of a process}.

Occasionally, reference is made to actions performed by  "{the system}". This process, called {div_main}, controls the rest. Therefore, it is in charge of creating the initial process at the beginning of the execution, of setting the speed execution, the debugger, etc. All the processes that are orphaned become sons of this process.

The {div_main identifier} can be obtained with {#120,get_id(0)}. It can be used to send a tree signal to all the processes, but this process won't be displayed on screen , even if its {#1123,x}, {#1124,y}, {#1126,graph}, etc. variables are defined.

{/}See: {#1040,States of a process }

# -----------------------------------------------------------------------------

{.1042,Types of processes.}

The blocks of the programs starting with the reserved word {#1016,PROCESS}
determine the performance of a specific process type. Then, when the program is executed,  any number of processes of this type will be able to exist at a specific moment. Each of these processes will have a different {#1039,identifying code}, but all of them are of the same type.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    // ...
END
PROCESS spacecraft()
BEGIN
    // ...
END
PROCESS enemy()
BEGIN
    // ...
END
PROCESS shot()
BEGIN
    // ...
END
{-}

In this example, four types of processes are defined: {my_game} (the type of the program's initial process), {spacecraft}, {enemy} and {shot}.

The number of processes of each of these types existing in the game depends on the number of calls made to these processes.

All the processes of {spacecraft} type will always execute the statements defined in the {PROCESS spacecraft()} of the program.

{A "process type" is a numeric code referred to the name of the PROCESS that determines how the} process {works} {during the game. This numeric code can be obtained with: TYPE <name_of_the_process>.}

{TYPE} is an operator defined in the language that, applied to a process name,
returns this numeric code.

For instance, {TYPE spacecraft} will be equivalent to a specific numeric constant and {TYPE enemy} will be equivalent to another one.

All the processes have a local variable containing this numeric code, which is: {reserved.process_type}.

{What is the process type for?}{/}

The process type is used for several things, as it is mentioned below:

- For the {#120,get_id()} function that receives a process type (for instance, {get_id(TYPE enemy)}) as a parameter and returns the identifying codes of the processes of this type existing in the game at that moment.

- For the {#104,collision()} function is similar to the previous one, with the proviso that it returns the identifying codes of the processes with which it is colliding (the graphics of both processes are partially superposed).

- For the {#158,signal()} function, that may send a signal to all the existing processes of a specific type.

- Or to verify, from a process' {#1039,identifying code}, what kind of process it is (type spacecraft, type shot, etc.).

{/}

The operator TYPE can only be used preceding a process name of the program or the word {mouse}, to detect collisions with the mouse pointer (with {collision(TYPE mouse)}).

{/}See: {#1039,Identifying codes of processes.}

# -----------------------------------------------------------------------------

{.1043,FROM statement}

{FROM} <variable>{#1073,=}{#1005,<constant>} {#1096,TO} {#1005,<constant>}{#1068,;}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}

(or)

{FROM} <variable>{#1073,=}{#1005,<constant>} {#1096,TO} {#1005,<constant>} {#1095,STEP} {#1005,<constant>}{#1068,;}ú
    {#1017,<statement>} {#1068,;}ú
    ...ú
{#1091,END}

The {FROM} statement implements a {loop}. That is to say, it is capable of {repeating a group of statements a specific number of times}.

A {#1006,GLOBAL}, {#1007,LOCAL} or {#1008,PRIVATE} variable of the process itself that can be used as a loop counter is needed to implement this loop.

The reserved word {FROM} must be put before the statements that will comprise the inner group of statements. This word will be followed by the {name of the counter variable}, the symbol of assignment ({#1073,=}), the {initial value} of the variable, the reserved word {#1096,TO} and, finally, the {final value} of the variable.
The symbol {#1068,;} (semicolon) must be put after this declaration of the loop {FROM}.

The inner group of statements that is intended to be repeated a specific number of times is put after this head defining the conditions of the loop. Finally, the reserved word {#1091,END} will be put.

The name of {iteration} of the loop is referred to the number of times that the inner set of statements is executed.

The first iteration will be performed with the {initial value}
in the variable used as a counter. After this iteration, {1 will be added}
to this variable (if the initial value {is less} that the final value). Otherwise {1 will be subtracted} from it. After having updated the value of the variable, it is necessary to pass to the following iteration, provided that the value of this variable has not reached (or exceeded) the {final value} of the loop.

The reserved word {#1095,STEP} can be put as second meaning of the {FROM} statement, after the initial and final values of the statement. This word must be followed by a {constant value} indicating the increment of the counter variable after every iteration of the loop, instead of {1} or{ -1}, which are the increments
that will be performed by default if the {#1095,STEP} declaration is omitted.

The following example shows a program with two loops {FROM}: one without 
{#1095,STEP} declaration (with increment or decrement by default) and the other with it.

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FROM x=9 TO 0;
        // Inner statements ...
    END
    FROM x=0 TO 9 STEP 2;
        // Inner statements ...
    END
END
{-}

The first loop will be executed {10} times with the {x} variable . Its value will range between {9} and {0} in the different iterations. By default, 1 will be subtracted from the variable each time, as the initial value (9) is bigger than the final value (0).

In the second loop, constant {2} is indicated as the increment of the variable. Thus, the loop will be executed {5} times with the {x} variable, whose values will be {0}, {2}, {4}, {6} and {8}, respectively, in the consecutive iterations.
As it can be noticed, no iteration will be performed with {x} being equivalent to {9}, even if it is the loop's {final value}.

By default, if {2} had not been specified as {#1095,STEP} of the loop,
{1} would have been added to the {x} variable after each iteration.

A loop {FROM} can always be performed with the {#1025,FOR} statement,
as it is now shown (with two loops equivalent to those of the previous example).

{#9999,Example:}
PROGRAM my_game;
BEGIN
    FOR ( x=9 ; x>=0 ; x=x-1 )
        // Inner statements ...
    END
    FOR ( x=0 ; x<=9 ; x=x+2 )
        // Inner statements ...
    END
END
{-}

The {initial} and {final} values of a loop {FROM} must be different.

If the initial value {is less} than the final value, it is not possible to specify a negative value in the {#1095,STEP} declaration.

If the initial value {is bigger} than the final value, it is not possible to specify a positive value in the {#1095,STEP} declaration.

A {#1026,BREAK} statement inside a loop {FROM} will immediately finish it, continuing the program from the following statement to this loop (after the {#1091,END}).

A {#1027,CONTINUE} statement inside a {FROM} loop will force the program to increment the variable used as a counter immediately and then, if the final value has not been exceeded, to start the following iteration.

The statements inner to a loop {FROM} may be as many as desired, of any kind, obviously including new loops {FROM}.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1044,Use of angles in the language.}

In the language, all the angles are specified in degree thousandths.
For instance:

  {0} is {0 degrees} (to the right)ú
  {90000} are {90 degrees} (up)ú
 { -45000} are{ -45 degrees} (down right diagonal)ú

If {360 degrees} (360000) are added to or subtracted from any angle, an equivalent angle is obtained. For instance, the angles -90000 and 270000 are equivalent (the angles of {-90 degrees} and {270 degrees}
go both downwards)

The constant {#1179,PI} predefined as {180000}, {3.1415 radians} or, what is the same, {180 degrees}, can be used as reference. For instance, {PI/2} will be equal to 90 degrees (90000).

Some of the functions dealing with angles are mentioned below:

  {#116,get_angle()}ú
  {#118,get_distx()}ú
  {#119,get_disty()}ú
  {#113,fget_angle()}ú
  {#142,near_angle()}ú
  {#101,advance()}ú
  {#183,xadvance()}ú

All the processes have a predefined local variable called {angle}
which, by default, will be equal to {0}. If its value is modified, the display's angle of the graphic of the process will be changed (the graphic will rotate in the indicated degrees, from the original graphic).

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1045,NOT  !}

Unary operator of logical and binary {negation} used in expressions and
conditions.

The reserved word {NOT} and the symbol {!} are synonymous.

{NOT logical:} If the operand is {true}, on applying this operator to it, a {false} expression will be obtained, and vice versa.

  TRUE  ->  FALSEú
  FALSE   ->  TRUEú

{NOT binary:} Changes all the bits of the operand. That is to say, it passes 0 to 1 and 1 to 0.

{/}

{Note:} This operator indistinctly works as logical and binary as, in the language, the {true} logical expressions are interpreted as those that have their last bit at 1 (bit 0, weight 1) or, in other words, the odd numbers (1, -1, 3, -3, ...). And the {false} logical expressions are interpreted as those having their last bit at 0 (the even numbers: 0, 2, -2, 4, -4, ...).

On changing the {NOT} operator, all the bits also change the last one, transforming then the even numbers into odd numbers (false expressions into
true ones) and the odd numbers into even numbers (true expressions into false ones).

{/}See: {#1000,Syntax} - {#1035,Expression} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1046,<>  !=}

Logical operator [{different from}] used in conditions. The symbols
{<>} and {!=} are synonymous.

It must be used between two numeric expressions, and it returns a logical result:

{False} - If both expressions have the same result (if these two expressions are equivalent), as they ARE NOT different.

{True} - If the expressions have different results, as they ARE different.

{Examples:}

  {2+2 <> 4} will return {false}.
  {0 <> -1}  will return {true}.

{/}See: {#1000,Syntax} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1047,"  '}

Symbols delimiting literals.

Literals are the {texts in inverted commas}. Literals may start and finish with the character [{'}] or even with the character [{"}] (but they have to start and finish with the same character). There are two ways to include the character [{"}] in a literal, supposing that the aim is to define a literal containing the text: a"B"c

 - Duplicating the character: "a""B""c"

 - Defining it with the simple inverted comma: 'a"B"c'

It happens the same regarding the character [{'}], that can be included in a literal if it is duplicated, or if the literal is delimited with the character [{"}].

All the literals must be closed in the same line as they started. It is not possible to define literals occupying more than one line.

{/}

{Literals of several lines.}

It is possible to define the literals over several lines, to do this you just need to divide the
text into several lines, and put them successively (do not separate them with any symbol). 
For example, you could define a constant as:

{salute="­Ho"}ú
{       "la!";}

This also can be used to initiate the data of type {#1406,STRING}.
There is no limit in the number of lines. Only {#1002,Comments}
can appear between two successive literals.


{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1048,MOD  %}

Arithmetic operator of {module} or {remainder of a whole division}. The reserved word {MOD} 
and the symbol{ %} are synonymous.
This operator is used in the {#1035,arithmetic expressions} between two
operands, to obtain the module of the first one divided by the second one.

For instance, {7 MOD 3} will return 1, as the whole division of 7
by 3 give us 2 as quotient and {1} as {remainder}.

That is to say, {n MOD m} will always return a number within the range (0..m-1).

To understand easily how to obtain the remainder of an operation
{n MOD m}, the following steps may be followed:

{Step 1} - If {n} is less than {m}, then the result of the operation {MOD} is {n}.

{Step 2} - (When {n} is bigger than or equal to {m}), subtract {m} from {n} and go to {step 1}.

{/}

{Use:} On some occasions, this operator is used in the programs requiring that a counter variable always changes between {0} and {other number}. For instance, if the aim is that the {x} variable indefinitely varies between 0 and 319 (x=0, x=1, x=2, ..., x=319, x=0, x=1, ...), then there would be the following option:

  {x=0;}ú
  {LOOP}ú
  {    x=x+1;}ú
  {    IF (x==320) x=0;}ú
  {    // ...}ú
  {END}ú

But many programs replace these statements by the following ones:

  {x=0;}ú
  {LOOP}ú
  {    x=(x+1) MOD 320;}ú
  {    // ...}ú
  {END}ú

that fulfills the same function, as the operator {MOD} will truncate 
the expression when it is bigger than or equal to 320 at a lesser value.

{/}

The {quotient} of a whole division is obtained through the operator {#1065,/}
(division).

{/}See: {#1000,Syntax} - {#1035,Expression}

# -----------------------------------------------------------------------------

{.1049,%=}

Operative assignment. Operation of {module} or {remainder of a} whole {division}.

The {#1019,assignment statements} are used to calculate expressions and
{to assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol {%=} is used instead of {=} to perform the assignment,
the following {module} or {remainder of the division} will be assigned to the variable:

  [{previous_value_of_the_variable}] / [{result_of_the_expression}]

Example: {x=3; x%=2;} -> (x=1)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, a {n %= m;} type statement will be equivalent to this other {n = n MOD m;} statement.

See the operator {#1048,MOD} for further information about the {module}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1050,&}

Bi functional symbol, that has two different uses depending on whether it is used as an unary or binary operator.

An {UNARY} operator appears inside an expression, simply preceding an operand (as if it was its sign). In this case, the operator{ &} will be a synonymous of {#1085,OFFSET}.

{Example: &x} is equivalent to {OFFSET x}

A {BINARY} operator appears inside an expression, concatenating
two operands (showing an operation between both). In this case, the
operator{ &} will be a synonymous of {#1051,AND}.

{Example: x&2} is equivalent to {x AND 2}

{/}See: {#1000,Syntax} - {#1085,OFFSET} - {#1051,AND}

# -----------------------------------------------------------------------------

{.1051,AND  &&}


Binary operator of the {logical product} used in expressions and conditions.

The reserved word {AND} and the symbol{ &&} are synonymous.

{AND logical:} The conditions to the right and left of the operator are first 
evaluated and, if both are {true}, this operator will return {true}. Otherwise, 
the operator will always return {false}.

  FALSE  AND FALSE  = FALSEú
  FALSE AND TRUE = FALSEú
  TRUE AND FALSE  = FALSEú
  TRUE AND TRUE = TRUEú

These are used to verify that more than one condition is satisfied; for instance:

  {(x>0 AND x<100)}

To verify that the variable is bigger than 0 {AND} less than 100.

{AND binary:} Evaluates the bits of the expressions appearing before 
and after the operator, returning the value of the bits that are common to both expressions as follows:

  0 AND 0 = 0ú
  0 AND 1 = 0ú
  1 AND 0 = 0ú
  1 AND 1 = 1ú

This rule will be applied to all the bits of the operands (in the language, these are 32 bit integers).

{/}

{Note:} This operator indistinctly works as logical and binary as, in the language, the {true} logical expressions are interpreted as those that have their last bit at 1 (bit 0, weight 1) or, in other words, the odd numbers (1, -1, 3, -3, ...). And the {false} logical expressions are interpreted as those having their last bit at 0 (the even numbers: 0, 2, -2, 4, -4, ...).

The operator {AND} will only leave the last bit at 1 (it will only return {true}
as a result} when both operands have this bit at 1 (when both are {true} expressions).

{/}

{Note:} The symbol{ &} can also be used as another synonymous of {AND} and  { &&}.

{/}See: {#1000,Syntax} - {#1035,Expression} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1052,&=}

Operative assignment. Binary operation of {logical product} ({AND}).

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol {&=} is used instead of {=} to perform the assignment,
the following {logical product} will be assigned to the variable:

  [{previous_value_of_the_variable}] AND [{result_of_the_expression}]

Example: {x=5; x&=6;} -> (x=4)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n &= m;} type statement will be equivalent to this other {n = n AND m;} statement.

See the operator {#1051,AND} for further information about the {logical product}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1053,(  )}

The symbols {(} and {)}, called brackets, must always appear in pairs and in this same order.

They are used to delimit some calculations, parameters or conditions
of the programs, marking their beginning with the symbol {(} and
the end with the symbol {)}.

{/}

Inside an expression, they indicate that the calculation within them must be done before the calculation out of them.

For instance, the expression {2*3+2} will be evaluated as {8}, as the multiplication (2 by 3 equals 6) will be done first and then, the addition (6 plus 2 equals 8).

Using brackets, it is possible to force to do the addition at first,
expressing the calculation as {2*(3+2)}, that will be evaluated as {10}, as now the addition (3 plus 2 equals 5) will be done first and then, the multiplication (2 by 5 equals 10).

{/}

The brackets are also use to delimit the call parameters of the {#1033,processes} or the functions and inside the syntax of different statements of the language.

{/}See: {#1000,Syntax} - {#1035,Expression}

# -----------------------------------------------------------------------------

{.1054,*}

Arithmetic operator of whole {multiplication}. This operator is used in the {#1035,arithmetic expressions} between two operands, to obtain the result of their multiplication.

For instance, {2 * 8} will return {16}, {99 * 0} will return {0}, {2 * -1}
will return{ -2}, etc.

All the variables are 32 bit {integers} with sign in the language.
Therefore, only integers within the range ({#1177,min_int} ... {#1178,max_int})} can be used. Then, when the result of the {multiplication} must exceed that range, {incorrect results will be shown}. In this case, the system won't report any error. Hence, much care must be taken.

{/}

This symbol is bi functional; it has two different uses depending on whether it is used as an unary or binary operator.

A {UNARY} operator appears inside an expression, simply preceding an operand (as if it was its sign). In this case, the operator {*} will be a synonymous of {#1079,POINTER}.

{Example: &x} is equivalent to {POINTER x}

A {BINARY} operator appears inside an expression, concatenating
two operands (showing an operation between both). In this case, the
operator {*} will be the arithmetic operator of {multiplication} previously explained.

{/}See: {#1000,Syntax} - {#1035,Expression} - {#1079,POINTER}

# -----------------------------------------------------------------------------

{.1055,*=}

Operative assignment. Arithmetic operation of {multiplication}.

The {#1019,assignment statements} are used to calculate expressions and
{to assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol {*=} is used instead of {=} to perform the assignment,
then the following {multiplication} will be assigned to the variable:

 [{previous_value_of_the_variable}] * [{result_of_the_expression}]

Example: {x=2; x*=3;} -> (x=6)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, a {n *= m;} type statement will be equivalent to this other {n = n * m;} statement.

See the operator {#1054,*} for further information about the {multiplication}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1056,+}

Arithmetic operator of {addition}. This operator is used in the {#1035,arithmetic expressions} between two operands, to obtain their addition.

For instance {2 + 6} will return 8, the result of 2 plus 6.

All the variables are 32 bit {integers} with sign in the language.
Therefore, only integers within the range ({#1177,min_int} ... {#1178,max_int})} can be used. Then, when the result of the {addition} must exceed that range, {incorrect results will be shown}. In this case, the system won't report any error. Hence, much care must be taken.

{/}See: {#1000,Syntax} - {#1035,Expression}

# -----------------------------------------------------------------------------

{.1057,++}


Operator of increment. This operator, derived from the C language, allows us to increment the value 
of a variable (to add 1 to it) without requiring an
{#1019,assignment statement} for that purpose.

The variable can be a variable, a {position of a table}, or a {field of a structure}.

This operator can be included in an expression with two forms:
{pre-increment} and {post-increment}.

{Operator of pre-increment.}

When the symbol { ++} is put just before a variable, 1 will be added to it {before the execution of the statement}. As examples, see the following statements:

{ ++x;} - statement that will add 1 to the {x} variable.

{ z=++x+y;} - statement that will add 1 to the {x} variable and then, it will assign
the addition between {x} (already incremented) and {y} to the {z} variable.

{Operator of post-increment.}

When the symbol{ ++} is put just after a variable, 1 will be added to it {after the execution of the statement}. As examples, see the following statements:

{ x++;} - statement that will add 1 to the {x} variable.

{ z=x+y++;} - statement that will assign the addition between {x} and {y} to the {z} variable, incrementing then the {y} variable.

{/}

{Summary:}

Generally, a{ ++variable;} or {variable++;} type statement is always equivalent
to the following statement: {variable=variable+1;} (or {variable+=1;}).

The difference between the {pre-increment} and the {post-increment} is that in the first case, the value of the variable already incremented is taken to evaluate the rest of the expression, while in the second case, the expression is evaluated with the value that the variable had before being incremented.

{/}See: {#1000,Syntax} - {#1035,Expression} - {#1061,Decrement(--)}

# -----------------------------------------------------------------------------

{.1058,+=}

Operative assignment. Arithmetic operation of {addition}.

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol {+=} is used instead of {=} to perform the assignment,
the result of the following {addition} will be assigned to the variable:

  [{previous_value_of_the_variable}] + [{result_of_the_expression}]

Example: {x=2; x+=2;} -> (x=4)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n += m;} type statement will be equivalent to this other {n = n + m;} statement.

See the operator {#1056,+} for further information about the {addition}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1059,,}


The symbol of the comma ( {,} ) is used inside the programming language,
in different points of a program, {to separate} two consecutive elements of a list.

It is used, for instance, in the following points:

- In the {#1013,lists of constants} to separate their different numeric values.

- In the definition of the {#1018,parameters of a process} to separate
the names of the different parameters.

- In the {#1032,call to a function} and in the {#1033,call to a process} to also separate different expressions that will be assigned to the parameters of the function or process.

- In the {#1025,FOR statement} to separate different initialisations,
conditions or increments.

- In the {#1021,SWITCH statement} to define the different values
accepted in a block {CASE ... END}.

{/}

The symbol of the comma can also be used to separate several
{#1009,declarations of data}, instead of finishing each of them with a symbol {semicolon} ({#1068,;}).

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1060,-}

Arithmetic operator of {subtraction}. This operator is used in the {#1035,arithmetic expressions} between two operands, to obtain the result of this subtraction.

For instance, {2 - 6} will return -4, the result of subtracting 6 from 2.

All the variables are 32 bit {integers} with sign in the language.
Therefore, only integers within the range ({#1177,min_int} ... {#1178,max_int})} can be used. Then, when the result of the {subtraction} must exceed that range, {incorrect results will be shown}. In this case, the system won't report any error. Hence, much care must be taken.

{/}

This symbol is bi functional. That is to say, it has two different uses depending on whether it is used as an unary or binary operator.

A {UNARY} operator appears inside an expression, simply preceding an operand (as if it was its sign). In this case, the operator { -} will be the {minus sign}.

{Example: -7} the negative integer {minus seven}.

A {BINARY} operator appears inside an expression, concatenating
two operands (showing an operation between both). In this case, the
operator{ -} will be the arithmetic operator of {subtraction} previously explained.

{/}See: {#1000,Syntax} - {#1035,Expression}

# -----------------------------------------------------------------------------

{.1061,--}

Operator of decrement. This operator, derived from the C language, allows us to decrement the value of a variable (to subtract 1 from it) without requiring an
{#1019,assignment statement} for that purpose.

The variable can be a variable, a {position of a table}, or a {field of a structure}.

This operator can be included in an expression with two forms:
{pre-decrement} and {post-decrement}.

{Operator of pre-decrement.}

When the symbol{ --} is put just before a variable, 1 will be subtracted from it {before the execution of the statement}. As examples, see the following statements:

{ --x;} - statement that will subtract 1 from the {x} variable.

{ z=--x+y;} - statement that will subtract 1 from the {x} variable and then, it will assign the addition between {x} (already decremented) and {y} to the {z} variable.

{Operator of post-decrement.}

When the symbol{ --} is put just after a variable, 1 will be subtracted from it {after the execution of the statement}. As examples, see the following statements:

{ x--;} - statement that will subtract 1 from the {x} variable.

{ z=x+y--;} - statement that will assign the addition between {x} and {y} to the {z} variable, decrementing then the {y} variable.

{/}

{Summary:}

Generally, a{ --variable;} or {variable--;} type statement is always equivalent
to the following statement: {variable=variable-1;} (or {variable-=1;}).

The difference between the {pre-decrement} and the {post-decrement} is that, in the first case, the value of the variable already decremented is taken to evaluate the rest of the expression, while in the second case, the expression is evaluated with the value that the variable had before being decremented.

{/}See: {#1000,Syntax} - {#1035,Expression} - {#1057,Increment(++)}

# -----------------------------------------------------------------------------

{.1062,-=}

Operative assignment. Arithmetic operation of {subtraction}.

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol {-=} is used instead of {=} to perform the assignment,
the result of the following {subtraction} will be assigned to the variable:

  [{previous_value_of_the_variable}] + [{result_of_the_expression}]

Example: {x=4; x-=2;} -> (x=2)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n -= m;} type statement will be equivalent to this other {n = n - m;} statement.

See the operator {#1060,-} for further information about the {subtraction}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1063,.  ->}

Operator of access to structures or to alien local data. The symbols{ .} and{ ->}
are synonymous. Therefore, they can indistinctly be used.

{/}

{Access to structures.}

To access a field of a structure, this operator must be used in the following way:

<name of the structure>{[}<no. record>{]}{ . }<name of the field>

(or, using the other symbol)

<name of the structure>{[}<no. record>{]}{ -> }<name of the field>

{Examples:}ú
  {scroll[0].camera}ú
  {m7[1]->z}ú

{Note:} Keep in mind that the record number in square brackets can be omitted when record number 0 is accessed. For instance, {scroll[0].camera} will always be equivalent to {scroll.camera}.

{/}

{Access to alien local data (belonging to another process).}

To access a {#1007,LOCAL} variable of a process from another one, the {#1039,identifying code} of the process whose variable is going to be read or modified must be known. Then, it will be possible to access it in the following way:

<identifying code>{ . }<local variable name>

(or using the other symbol)

<identifying code>{ -> }<local variable name>

{Examples:}ú
   {father.x}ú
   {son->graph}ú

{/}See: {#1012,Declaration of a structure} - {#1039,Identifying codes} - {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1064,..}

{Range of values of a section CASE}{/}

The symbol{ ..} (double period) is used to define a range of values. That is to say, to express the numbers ranging between two values (inclusive).

This symbol is {only used in the} {#1021,SWITCH} {statements}, inside the {sections CASE}, to specify a range of values.

It doesn't matter to express a range either as {minimum..maximum} or as {maximum..minimum}.

For instance, the range defined as{ -2 .. 1} would be made up of the numbers{ -2},{ -1}, {0} & {1}.

{/}See: {#1000,Syntax} - {#1021,SWITCH statement}

# -----------------------------------------------------------------------------

{.1065,/}

Arithmetical operator of whole {division}. This operator is used in the {#1035,arithmetic expressions} between two operands, to obtain the quotient
of the first one divided by the second one.

For instance {7 / 3} will return 2 as, on doing the whole division of 7
by 3, the quotient will equal {2} (and the remainder will be 1).

That is to say, {n / m} will always return the result of the division of {n} by {m}, but with no decimals (as all the variables are 32 bit {integers} with sign in the language).

{/}

The {remainder} of a whole division is obtained through the operator {#1048,MOD} (module).

{/}See: {#1000,Syntax} - {#1035,Expression}

# -----------------------------------------------------------------------------

{.1066,/=}

Operative assignment. Operation of {whole division}.

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol {/=} is used instead of {=} to perform the assignment,
the {whole result} (quotient) of the following {division} will be assigned to the variable:

  [{previous_value_of_the_variable}] / [{result_of_the_expression}]

Example: {x=8; x/=2;} -> (x=4)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n/-= m;} type statement will be equivalent to this other {n = n / m;} statement.

See the operator {#1065,/} for further information about the {whole division}.

{/}See: {#1000,syntax} - {#1019,Assignation}

# -----------------------------------------------------------------------------

{.1067,:}

The symbol {:} (colon) is used to finish a {#1087,CASE} or {#1088,DEFAULT} declaration of a {#1021,SWITCH statement}.

Actually, the symbols {:} (colon) and {;} (semicolon) are synonymous
in this language. That is to say, they can be used indistinctly.

However, similarly to what happens in other programming languages,
the symbol {semicolon} is normally used to finish statements and the symbol {colon} is normally used inside the syntax of the {#1021,SWITCH statement}.

{/}See: {#1000,Syntax} - {#1087,CASE} -  {#1088,DEFAULT} - {#1021,SWITCH statement}

# -----------------------------------------------------------------------------

{.1068,;}


The symbol {;} (semicolon) is used in many points of a program to indicate always that a statement or any kind of declaration finishes. This is called {finishing} symbol, whose only purpose is to indicate the end of something.

In the language, the following points of the program must be indicated with semicolon:

- The end of the {#1003,PROGRAM declaration}.

- The end of a {#1009,declaration of a variable}.

- The end of an {#1014,IMPORT declaration}.

- The end of the following statements:ú
    {#1019,Assignments or increments of data}.ú
    {#1033,Calls to processes}.ú
    {#1032,Calls to functions}.ú
    {#1029,FRAME}, {#1028,RETURN}, {#1031,DEBUG}, {#1026,BREAK} and {#1027,CONTINUE}.

- The end of the beginning of a loop {#1043,FROM}.

- And separating the different parts of a {#1025,FOR} statement.

The compiler will indicate the lacking of the symbol {;} in any of these points.

It is also possible to put this symbol in other specific points of the programs, such as after any other kind of statement, even if it will be optional in this case and, therefore, the compiler won't report its lacking.

{/}

Actually, the symbols {;} (semicolon) and {:} (colon) are synonymous
in this language. That is to say, they can be used indistinctly.

However, similarly to what happens in other programming languages,
the symbol {semicolon} is normally used to finish statements and the symbol {colon} 
is normally used inside the syntax of the {#1021,SWITCH statement}.

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1069,<}

Logical operator [{less than}] used in conditions. It must be used between two numeric expressions, and it returns a logical result:

{False} - If the first expression ISN'T less than the second one.

{True} - If the first expression IS less than the second one.

{Examples:}

  {2+2 < 4} will return {false}.
  {1 < 2}   will return {true}.

{/}See: {#1000,Syntax} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1070,<<}


Binary operator of {rotation to the left}. This operator is used in the {#1035,arithmetic expressions}, 
between two operands, to obtain the result of rotating the first operand to the left as 
many times as indicated by the second. For instance, the following rotation:

  {n} << {m}

Will return {n} rotated to the left {m} times. Every rotation to the left is equivalent to multiplying the number by 2. That is to say, rotating to the left once, is equivalent to multiplying by 2; rotating to the left twice is equivalent to multiplying by 4; 3 times is equivalent to multiplying by 8, and so on.

Or, what is the same, (the {#145,POW function}{(2, m)} returns {2} raised to {m}):

  {n} * POW(2, {m})

For instance, {2<<3} will return 16, {4<<1} will return 8, {100<<0} will return 100, etc.

All the variables are 32 bit {integers} with sign in the language.
Therefore, only integers within the range ({#1177,min_int} ... {#1178,max_int})} can be used. 
Then, when the result of the {rotation} must exceed that range, {incorrect results will be shown}. 
In this case, the system won't report any error. Hence, much care must be taken.

{/}

The operator of rotation to the right (the contrary operation) is the
{#1077,symbol >>}.

{/}See: {#1000,Syntax} - {#1035,Expression}

# -----------------------------------------------------------------------------

{.1071,<<=}

Operative assignment. Binary operation of {rotation to the left}.

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol {<<=} is used instead of {=} to perform the assignment,
the result of the following rotation will be assigned to the variable:

  [{previous_value_of_the_variable}] << [{result_of_the_expression}]

Or, what is the same, (the {#145,POW function}{(2, n)} returns {2} raised to {n}):
 
  [{previous_value_of_the_variable}] * POW(2, [{result_of_the_expression}]

That is to say, if the result of the expression is:

  0 -> the variable will maintain its value.ú
  1 -> the variable will be multiplied by 2.ú
  2 -> the variable will be multiplied by 4.ú
  3 -> the variable will be multiplied by 8.ú
  ...

Example: {x=2; x<<=2;} -> (x=8)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n <<= m;} type statement will be equivalent to this other {n = n << m;} statement.

See the operator {#1070,<<} for further information about the {rotation to the left}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1072,<=  =<}

Logical operator [{less than or equal to}] used in conditions. The symbols {<=} and {=<} are synonymous.

It must be used between two numeric expressions, and it returns a logical result:

{False} - If the first expression ISN'T less than or equal to the second one.

{True} - If the first expression IS less than or equal to the second one.

{Examples:}

  {2+2 <= 3} will return {false}.
  {2+2 <= 4} will return {true}.

{/}See: {#1000,Syntax} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1073,=}


The symbol {=} (symbol of {assignment}) is used in the language inside the {#1009,data declarations}
to initialise them to their initial value. In the {#1019,assignment statements}, this symbol is used
to separate the reference to the variable from the assigned expression.

Inside an expression, this operator can be used as a conventional binary arithmetic operator, 
which is placed between two operands, returning
the second operand's value as a result (besides assigning this result to the variable defined as first operand).

This operator represents an {imperative order} according to which, on executing the statement that contained it, the first operand (before the symbol) will take the value of the second operand (or expression after the symbol).

On evaluating an expression, the assignment operands are always those of {less priority} (the last ones that are interpreted in the expression),
being possible to use brackets to force a bigger priority. If, in an expression (or statement) several assignment operands have been used,
they will be evaluated (executed) from right to left.

For instance, in the statement:

  {x=y=x+y;}

The addition ({x+y}) will first be done. Then, the result will be assigned as the new value of the {y} variable ({y=x+y}) and, finally, this same value will be assigned to the {x} variable ({x=y}).


{/}See: {#1000,Syntax} - {#1009,Data declarations} - {#1019,Assignment statements}

# -----------------------------------------------------------------------------

{.1074,==}

Logical operator [{equal to}] used in conditions. It must be used between two numeric expressions and it returns a logical result:

{False} - If the expressions give different results, as they AREN'T equal
(or equivalent).

{True} - If both expressions give the same result (if they are equivalent expressions), as they ARE equal.

{Examples:}

  {0 == -1}  will return {false}.
  {2+2 == 4} will return {true}.

{/}

{Note:} The symbol {#1073,=} can not be used to compare two expressions
or numeric values, as it is the assignment symbol.

{/}See: {#1000,Syntax} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1075,>=  =>}

Logical operator [{bigger than or equal to}] used in conditions. The symbols {>=} and {=>} are synonymous.

It must be used between two numeric expressions, and it returns a logical result:

{False} - If the first expression ISN'T bigger than or equal to the second one.

{True} - If the first expression IS bigger than or equal to the second one.

{Examples:}

  {2+2 >= 3} will return {false}.
  {2+2 >= 4} will return {true}.

{/}See: {#1000,Syntax} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1076,>}

Logical operator [{bigger than}] used in conditions. It must be used between two numeric 
expressions, and it returns a logical result:

{False} - If the first expression ISN'T bigger than the second one.

{True} - If the first expression IS bigger than the second one.

{Examples:}

  {2+2 > 4} will return {false}.
  {2 > 1} will return {true}.

{/}See: {#1000,Syntax} - {#1037,Condition}

# -----------------------------------------------------------------------------

{.1077,>>}

Binary operator of {rotation to the right}. This operator is used in the {#1035,arithmetic expressions}, between two operands, to obtain the result
of rotating the first operand to the right as many times as indicated by the second one. For instance, the following rotation:

  {n} >> {m}

Will return {n} rotated to the right {m} times. Every rotation to the right is equivalent to dividing the number by 2. That is to say, rotating to the right once, is equivalent to dividing by 2; rotating to the right twice is equivalent to dividing by 4; 3 times is equivalent to dividing by 8, and so on.

Keep in mind that all the numbers used in this language are {integers}  (with no decimals). Therefore, an {integer} will always be returned as a result of the division (for instance, 7 divided by 2 will return 3).

Or, what is the same, (the {#145,POW function}{(2, m)} returns {2} raised to {m}):

  {n} / POW(2, {m})

For instance, {16>>3} will return 2, {2>>1} will return 1, {100>>0} will return 100, etc.

{/}

The operator of rotation to the left (the contrary operation) is the
{#1070,symbol <<}.

{/}See: {#1000,Syntax} - {#1035,Expression}

# -----------------------------------------------------------------------------

{.1078,>>=}

Operative assignment. Binary operation of {rotation to the right}.

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<Variable reference>} {=} {#1035,<expression>} {;}

If the symbol {>>=} is used instead of {=} to perform the assignment,
the result of the following rotation will be assigned to the variable:

  [{previous_value_of_the_variable}] >> [{result_of_the_expression}]

Or, what is the same, (the {#145,POW function}{(2, n)} returns {2} raised to {n}):
 
  [{previous_value_of_the_variable}] / POW(2, [{result_of_the_expression}]

That is to say, if the result of the expression is:

  0 -> the variable will maintain its value.ú
  1 -> the variable will be divided by 2.ú
  2 -> the variable will be divided by 4.ú
  3 -> the variable will be divided by 8.ú
  ...

Example: {x=8; x>>=2;} -> (x=2)

The result of a rotation to the right will always be an integer,
with no decimals or, what is the same, the quotient of the previous whole division.

Example: {x=9; x>>=2;} -> (x=2)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n >>= m;} type statement will be equivalent to this other {n = n >> m;} statement.

See the operator {#1077,>>} for further information about the {rotation to the right}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1079,POINTER  [  ]}

Addressing operator. This operator requires a slightly advanced level in programming techniques. The use of pointers is a characteristic of other languages that, even if it may be very useful, is not indispensable to make programs, no matter how difficult they are.

The reserved word {POINTER} is used to make reference to a specific position of the computer's memory.

{Practical case.}{/}

For instance, having a variable named {my_variable} with value {3}, which will be stored in an offset of the memory (all the variables have an offset), the operator {#1085,OFFSET} is used to obtain this offset.

Supposing that there is another variable named {offset_of_my_variable} used
to store the offset of the previous variable, which would be done with the following statement:

  {offset_of_my_variable = OFFSET my_variable;}

This offset will be an integer, for instance {12345}. In order to obtain or modify the value of the variable ({3}), having only the offset (position) of the variable (and not its name) in the memory, the operator {POINTER} must be used. The statement to obtain the value of the variable from its offset would be as follows:

  {my_variable = POINTER offset_of_my_variable;}

A series of expressions and their numeric equivalents are now shown in order to clarify the concepts of {name of the variable}, {offset of the variable} and {value of the variable}.

  {my_variable} = {3}ú
  {OFFSET my_variable} = {12345}ú
  {offset_of_my_variable} = {12345}ú
  {POINTER offset_of_my_variable} = {3}ú

The offset of a variable may vary as a program is expanded (by adding new data and statements to it).

In short, {the operator POINTER accesses the value that is in the
position of the computer's memory indicated after it}. That is to say:

  {POINTER 12345} = {3}ú

It means that value {3} is in the offset {12345} of the computer's memory, as it is in this offset where the value of the {my_variable} variable is {stored}, and it is its value.

{/}

The {#1054,symbol *} and the {#1080,symbol ^} may be used as {synonyms} of the reserved word {POINTER} (in the previous example {*12345} = {3} or {^12345} = {3}).

{/}

The square brackets (symbols {[ ]}) work in a similar way to the operator
{POINTER}, with the proviso that they access the variable whose offset is indicated in them (in the previous example {[12345]} = {3}).

The square brackets are also used to specify the index in the tables and structures.

{/}See: {#1000,Syntax} - {#1085,OFFSET}

# -----------------------------------------------------------------------------

{.1080,^}

This symbol is bi functional; it has two different uses, depending on whether it is used as an unary or binary operator.

A {UNARY} operator appears inside an expression, simply preceding an operand (as if it was its sign). In this case, the operator{ ^} will be a synonymous of {#1079,POINTER}.

{Example: ^x} is equivalent to a {POINTER x}

A {BINARY} operator appears inside an expression, concatenating
two operands (showing an operation between both). In this case, the
operator{ ^} will be a synonymous of {#1082,XOR}.

{Example: x^2} is equivalent to {x XOR 2}

{/}See: {#1000,Syntax} - {#1079,POINTER} - {#1082,XOR}

# -----------------------------------------------------------------------------

{.1081,^=}

Operative assignment. Logical and binary operation of {exclusive OR} ({XOR}).

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol{ ^=} is used instead of {=} to perform the assignment,
the following {exclusive OR} will be assigned to the variable:

  [{previous_value_of_the_variable}] XOR [{result_of_the_expression}]

Example: {x=5; x^=3;} -> (x=3)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n ^= m;} type statement will be equivalent to this other {n = n XOR m;} statement.

See the operator {#1082,XOR} for further information about the {exclusive OR}.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1082,XOR  ^^}

Logical and binary operator of {exclusive OR} used in expressions and conditions.

The reserved word {XOR} and the symbol{ ^^} are synonymous.

{XOR logical:} The conditions on the right and left of the operator are first evaluated and, if (only one) is {true}, this operator will return {true}. Otherwise, the operator will always return {false}.

 FALSE  XOR FALSE  = FALSEú
 FALSE XOR TRUE = TRUEú
 TRUE XOR FALSE  = TRUEú
 TRUE XOR TRUE = FALSEú

It is used to verify that one (and only one) of the two specified conditions is complied; for instance:

  {(y>0 XOR x>0)}

To verify either that the first variable is bigger than 0, or (exclusive"or") that the second variable (but not the first one) is bigger than 0.

{XOR binary:} Evaluates the bits of the results of the expressions appearing before and after the operator, giving as a result a value of 1
only for those bits that had at 1 one (and only one) of the expressions.

  0 XOR 0 = 0ú
  0 XOR 1 = 1ú
  1 XOR 0 = 1ú
  1 XOR 1 = 0ú

This rule will be applied to all the bits of the operands (in the language, they are integers of 32 bits).

{/}

{Note:} This operator indistinctly works as logical and binary as, in the language, the {true} logical expressions are interpreted as those that have their last bit at 1 (bit 0, weight 1) or, in other words, the odd numbers (1, -1, 3, -3, ...). And the {false} logical expressions are interpreted as those having their last bit at 0 (the even numbers: 0, 2, -2, 4, -4, ...).

The operator {XOR} will only leave the last bit at 1 (it will only return {true}
as a result} when one (and only one) of both operands have this bit at 1 (when only one of the two expressions is {true}).

{/}

{Note:} The symbol{ ^} can also be used as another synonymous of {XOR }  and{ ^^}.

{/}See: {#1000,Syntax} - {#1035,Expression} - {#1037,Condition} - {#1083,OR}

# -----------------------------------------------------------------------------

{.1083,OR  ||  |}

Binary operator of {logical addition} used in expressions and conditions.

The reserved word {OR} and the symbols{ ||} and{ |}are synonymous.

{OR logical:} The conditions to the right and left of the operator are first evaluated and if, at least, one of them is {true}, this operator will return {true}. Otherwise, the operator will always return {false} (when both conditions are {false}).

 FALSE  OR FALSE  = FALSEú
 FALSE OR TRUE = TRUEú
 TRUE OR FALSE  = TRUEú
 TRUE OR TRUE = TRUEú

It is used to verify that one of the specified conditions is complied; for instance:

  {(x>0 OR y>0)}

To verify that, at least, one of both variables is bigger than 0. That is to say, it is verified that the first {OR} the second conditions are complied.

{OR binary:} Evaluates the bits of the results of the expressions appearing before and after the operator, giving as a result a value that will have at 1 the bits that any of the expressions would have at 1.

  0 OR 0 = 0ú
  0 OR 1 = 1ú
  1 OR 0 = 1ú
  1 OR 1 = 1ú

This rule will be applied to all the bits of the operands (in the language, they are 32 bit integers).

{/}

{Note:} This operator indistinctly works as logical and binary as, in the language, the {true} logical expressions are interpreted as those that have their last bit at 1 (bit 0, weight 1) or, in other words, the odd numbers (1, -1, 3, -3, ...). And the {false} logical expressions are interpreted as those having their last bit at 0 (the even numbers: 0, 2, -2, 4, -4, ...).

The operator {OR} will leave the last bit at 1 (it will return {true}
as a result) when one of any of the operands have this bit at 1 (when, at least, one of the two expressions is {true}).

{/}See: {#1000,Syntax} - {#1035,Expression} - {#1037,Condition} - {#1082,XOR}

# -----------------------------------------------------------------------------

{.1084,|=}

Operative assignment. Binary operation of {logical addition} ({OR}).

The {#1019,assignment statements} are used to calculate expressions and {assign them} to a variable.

{#1034,<reference to a variable>} {=} {#1035,<expression>} {;}

If the symbol{ |=} is used instead of {=} to perform the assignment,
the following {logical addition} will be assigned to the variable:

  [{previous_value_of_the_variable}] OR [{result_of_the_expression}]

Example: {x=5; x|=6;} -> (x=7)

{/}

{Note:} This symbol is a simple abbreviation derived from the {C language}. Anyhow, the {n  |= m;} type statement will be equivalent to this other {n = n OR m;} statement.

See the operator {#1083,OR} for further information about the {logical addition}.

{/}

{Note:} don't confuse this symbol with that of [{different from}] expressed as {#1046,!=}, that is used to compare whether two expressions have different results.

{/}See: {#1000,Syntax} - {#1019,Assignment}

# -----------------------------------------------------------------------------

{.1085,OFFSET}

The reserved word {OFFSET} allows us to obtain the offset of a
variable inside the computer's memory.

All the data of a program correspond with any specific position of the memory in which its value is stored. The operator {OFFSET} allows us to obtain this position as a numeric value.

This operator is mainly used in the parameters of any of the language's functions. Thus, these functions are able to modify these parameters.

If you have a variable (called, for instance, {my_variable}) with value {321} and this variable is passed, as a parameter, to a parameter function, the number 321 is being passed to the function. Then, the function won't be able to modify the variable, as it knows its value but not {where the variable is} (because many
{321} values may exist in the whole computer's memory, and it won't know which of them is the variable).

If {OFFSET my_variable} is passed to this function as a parameter, it is receiving information about the place in which the variable value is stored. Then, the function will be able to access this value in order to consult it or modified it.

For further information about this operator, it is possible to access the
{#1079,operator POINTER} that does the operation opposite to that of the operator {OFFSET} (it obtains the value stored in a specific position of the memory).

{/}

The {#1050,symbol &} can be used as {synonymous} of the reserved word {OFFSET}.

{/}See: {#1000,Syntax} - {#1079,POINTER}

# -----------------------------------------------------------------------------

{.1086,BEGIN}

This reserved word shows the beginning of the program or process.

That is to say, the word {BEGIN} is used to separate the area of data declaration of the main program or of a process, from the area of statements.

The {BEGIN} declaration is obligatory in the main program and in all the processes.

When a program or process are executed, they will always start with the statement coming after {BEGIN}.

The {BEGIN} statement {does nothing}. It is only used as a delimiting element inside the structure of the programs.

{/}

Every {BEGIN} is directly linked to an {#1091,END}  that will mark the end of the area of statements of the program or process.

{/}See: {#1000,Syntax} - {#1015,Main Code} - {#1016,Declaration of processes} - {#1408,FUNCTION}

# -----------------------------------------------------------------------------

{.1087,CASE}

This reserved word is a part of the {#1021,SWITCH} statement. It is used as the beginning of the different sections of statements that can or can not be executed, depending of the result of the evaluated expression.

Every {CASE} must have a word {#1091,END} indicating the end of the section.

The {#1021,SWITCH} statement evaluates an expression, and the word {CASE} means "{in case that the result of the expression is ..., then the following statements must be executed ...}".

{/}See: {#1000,Syntax} - {#1021,SWITCH statement}

# -----------------------------------------------------------------------------

{.1088,DEFAULT}

This reserved word is a part of the {#1021,SWITCH} statement, that is used to begin a section of statements that must be executed when the result of the evaluated expression is not contemplated in any of the sections {#1087,CASE} of the statement.

Every {DEFAULT} must have a word {#1091,END} indicating the end of the section.

The {#1021,SWITCH} statement evaluates an expression. Every section
{#1087,CASE} of the statement will contemplate one of several results in which that section must be executed. Finally, a section {DEFAULT} appears to express "{in case that the result of the expression is none of the previous ones, then the following statements must be executed ...}".

{/}See: {#1000,Syntax} - {#1021,SWITCH statement}

# -----------------------------------------------------------------------------

{.1089,DUP}

This word is used to define {#1013,lists of constants} (numeric values),
by repeating a simple pattern. It is used to initialise the initial values of tables and structures.

Its syntax is as follows:

<number of times> {DUP (}<sequence to repeat>{)}

It is equivalent of putting the <sequence to repeat> the indicated <number of times>.

For instance, the sequence {1, 2, 3, 1, 2, 3, 1, 2, 3} would be equivalent to the sequence {3 DUP (1, 2, 3)}.

{/}See: {#1000,Syntax} - {#1013,Definition  of a list of constants}

# -----------------------------------------------------------------------------

{.1090,ELSE}

This word is a part of the {#1020,IF} statement, and is used to specify where the block of statements that must be executed starts when the condition specified in the {#1020,IF} is not complied.

The format of the {#1020,IF} statement is the following one:

{IF (<}condition{>)}ú
    // Code to execute when the condition is compliedú
{ELSE}ú
    // Code to execute when the condition  {isn't} compliedú
{END}ú

The meaning of {ELSE} is "{otherwise ...}".

{/}

The section {ELSE} is optional. The {#1020,IF} statement can be formulated in the following way:

{IF (<}condition{>)}ú
    // Code to execute when the condition is compliedú
{END}ú

When no statement is required to be executed {in the opposite case}.

{/}See: {#1000,Syntax} - {#1020,IF statement}

# -----------------------------------------------------------------------------

{.1091,END}

This reserved word marks the end of one of the following statements:

  {#1086,BEGIN}ú
  {#1020,IF}ú
  {#1022,WHILE}ú
  {#1021,SWITCH}ú
  {#1087,CASE}ú
  {#1087,DEFAULT}ú
  {#1025,FOR}ú
  {#1043,FROM}ú
  {#1024,LOOP}ú
  {#1030,CLONE}ú

That is to say, the function of the word {END} is {to delimit where a statement finishes}.

Keep in mind that the statements may be nested (they may be included one inside another). Therefore, if a program is not well structured (tabulating the code), it can be difficult to find out to which statement each {END} corresponds.

For instance, in the following code it is possible to see clearly to which statement each {END} belongs.

{BEGIN}ú
    {IF (x>0)}ú
        {x=x-1;}ú
    {END}ú
{END}ú

But this same code could have been expressed as follows:

{BEGIN}ú
    {IF (x>0)}ú
    {x=x-1;}ú
{END}ú
    {END}ú

being much more complicated the reading of the program, even if for the compiler of the language {both code blocks are exactly the same} (the compiler will continue to interpret that the first {END} is that of the {IF} statement and the second one that of the {BEGIN} statement, even if they are incorrectly tabulated).

{/}See: {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1092,ID}

The reserved word {ID} is used to obtain the {#1039,identifying code} of a process while executing.

An {#1039,identifying code} is a numeric value that {identifies} each of the active processes at any moment (each of the game's objects).

That is to say, {ID} is like a numeric constant, with the only difference that its value will be different for each consulted process.

It is not possible to change the value of {ID}, as it is a simple object of
reading.

Normally, a process accesses this value when it intends to report
to other processes its {#1039,identifying code}.

{/}See: {#1000,Syntax} - {#1039,Identifying codes}

# -----------------------------------------------------------------------------

{.1093,SETUP_PROGRAM}

This reserved word is used to designate  special kinds of programs, related to the {sound hardware setup}.

The special characteristic of these programs is that they start with the reserved word {SETUP_PROGRAM} instead of {#1003,PROGRAM}.

This topic is very advanced, for expert users only.

A program of this type can be observed in the {SETUP} directory of DIV Games Studio. These programs, once they have been compiled, will automatically be included in the installations of the rest of the programs, when the box "{Include sound setup}" is activated during the installation process.

{Note:} In the installations, the last setup program compiled in DIV Games Studio will always be included.

{/}

However, keep in mind that it is not indispensable to create sound setup programs, as the games created with DIV Games
Studio will automatically detect whether the computer in which they are executed is provided with a sound card compatible with {Sound Blaster} or {Gravis Ultrasound}, providing that it is correctly configured.

{/}

This kind of programs normally modify the {#1104,setup global structure}, that controls the parameters of the sound system.

{/}See: {#1000,Syntax} - {#1104,Setup structure}

# -----------------------------------------------------------------------------

{.1094,SIZEOF()}

{SIZEOF(}<name of the variable>{)}

{Returns:}

The numbers of elements contained in the variable.

{Description:}

The reserved word {SIZEOF} is used to calculate the number of elements that a  table or a structure have.

This reserved word {is used as if it was a function} of the language,
indicating in brackets, the {#1001,name} of the variable and returning the number of elements (positions) of the latter.

It can be used to obtain the number of elements of a variable but, in this case, {SIZEOF} will always return {1} as the number of elements (as a variable is a single element).

{#9999,Example program:}
PROGRAM example_sizeof;

PRIVATE
    table1[]=0, 1, 2, 3;
    table2[]=4, 5, 6, 7, 8;
    variable=9;

BEGIN
    // ...

    save("help.dat", OFFSET table1, SIZEOF(table1)+SIZEOF(table2)+SIZEOF(variable));

    // ...
END
{-}

In this example, {SIZEOF} is used to obtain the number of elements
of the following three data:

{table1} of {4} elements.ú
{table2} of {5} elements.ú
{variable} ({1} element).ú

In this case, it is used to save in the {help.dat} file the contents of these three data with the {#155,save()} function that requires the number of elements intended to be stored in the file, as a third parameter.

In this case, {10} elements will be stored in the {help.dat} file, numbers from {0} to {9}, according to the initialisation of the data in the example.

The {#155,save()} statement of the previous example could have also been expressed without using {SIZEOF}, in the following way:

  {save("help.dat", OFFSET table1, 10);}

There is only one difference: if, in the program of the example, some elements were added to any of the two tables, it would be not necessary to modify the call to the {#155,save()} function, as {SIZEOF} will always return the current size of the tables.

{/}See: {#1000,Syntax} - {#1011,Declaration of a table} - {#1012,Declaration of a structure}

# -----------------------------------------------------------------------------

{.1095,STEP}

The reserved word {STEP} is a part of the {#1043,FROM} statement and it is used to indicate the increment (step) that has to be made in every loop iteration.

The {#1043,FROM} statement implements a loop, a group of statements that are going to be repeated a specific number of times. For that, it uses a variable as a counter of the number of repetitions.

Both the initial and final values of the variable are defined. The loop will be repeated until the variable reaches the final value, starting from the initial value.

By default, the variable will pass through all the whole numeric values ranging between the initial and final values. But it is possible to indicate a {STEP} declaration to establish a different variable increment.

For instance, if a loop in which the {x} variable is going to have the values ranged from {1} to {10} is defined, this loop will be executed a total of {10} times. But if {STEP} is established as {2}, then the loop will only be executed {5} times, in which the {x} variable will take the {1}, {3}, {5}, {7} and {9} values, as it has been established that the variable must be incremented {2} by {2}. This loop would be implemented in the following way:

{FROM x=1 TO 10 STEP 2}ú
  // Statements that are going to be repeated five timesú
{END}ú

If the {STEP} declaration is omitted from the {#1043,FROM} statement, then the increment will always be 1 by 1, adding 1 to the variable after every loop
iteration (or subtracting 1, in case that the final value is less than the initial value).

{Note:} Only whole increments can be established.

{/}See: {#1000,Syntax} - {#1043,FROM statement}

# -----------------------------------------------------------------------------

{.1096,TO}

The reserved word {TO} is a part of the {#1043,FROM} statement and it is used to separate the constants that indicate the initial and final values that the variable used as a loop counter must take.

The {#1043,FROM} statement implements a loop, a set of statements that are going to be repeated a specific number of times. For that, it uses a variable as a counter of the number of repetitions.

Both the initial and final values of the variable are defined. The loop will be repeated until the variable reaches the final value, starting from the initial value.

{Example:}

  {FROM x=1 TO 10}ú
    // Statements that will be repeated 10 timesú
  {END}ú

By default, the variable will take all the whole numeric values ranging between the initial and final values. But it is possible to indicate a {#1095,STEP} declaration to establish a different increment of the variable.

{/}See: {#1000,Syntax} - {#1043,FROM statement} - {#1095,STEP}

# -----------------------------------------------------------------------------

{.1097,UNTIL}

The reserved word {UNTIL} is a part of the {#1023,REPEAT} statement,
whose syntax is, broadly speaking, the following one:

{#1023,REPEAT}ú
    {#1017,<statement>};ú
    ...ú
{UNTIL (<}condition>}{)}

The {#1023,REPEAT} statement implements a loop, it is capable of repeating a set of statements a specific number of times.

The end of the statement is determined by putting the reserved word {UNTIL}
followed by the condition that must be complied so that the {statement finishes}.

{/}See: {#1000,Syntax} - {#1023,REPEAT statement}

# -----------------------------------------------------------------------------

{.1100,GLOBAL STRUCT mouse}

{STRUCT mouse;}ú
    {x, y;}                // Coordinatesú
    {graph;}               // Graphic codeú
    {file;}                // File codeú
    {z;}                   // Depth planeú
    {angle;}               // angleú
    {size;}                // Size (%)ú
    {flags;}               // Mirrors indicatorú
    {region;}              // Clipping regionú
    {left, middle, right;} // State of buttonsú
    {cursor;}              // Emulation with cursorsú
    {speed;}               // Speed of mouseú

{END}ú

This global structure is used to control the mouse. It contains a series of fields related to the programming of this driver, such as the screen position, the pointer graphic, the state of the buttons, etc.

In order to access these fields, the name of the field must be preceded by the word {mouse}  and by the symbol {#1063,. (period)}. For instance, in order to
access the field {x} (horizontal coordinate of the mouse pointer), it is necessary to use {mouse.x}.

{/}

{x}, {y} - Horizontal and vertical coordinates of the mouse. It will be necessary to read only these two fields ({mouse.x} and {mouse.y}) to know the position of the mouse cursor on screen.

To {locate the mouse at other coordinates} (to force its position),
suffice will be to assign the new coordinates to these two fields.

{/}

{graph} - {Graphic code} assigned as a mouse pointer. By default {the mouse won't be visible}. To make it visible, it is necessary to create the graphic that is going to be used as a pointer in the {graphic editor}, to load it in the program (with the {#132,load_fpg()} or {#174,load_map()}  or {#174,load_pcx()} functions, depending on whether this graphic has been stored in a {file FPG} or in an {file MAP/PCX}) and finally, to assign its {graphic code} to this variable ({mouse.graph}). Then, the mouse pointer will be seen on screen.

The centre of the graphic will appear at the {mouse.x}, {mouse.y} coordinates, unless its {#1136,control point} number {0} has been defined in the {graphic editor}. If this point (usually called {hot spot}) is defined, then it will appear at the coordinates indicated in the fields {mouse.x} and {mouse.y}.

For instance, if an arrow is created to depict the mouse pointer (as it happens dealing with the mouse pointer of DIV Games Studio), the hot spot (control point number {0}) will be defined in the upper left corner of the graphic, as it is the {active point} inside the graphic. Then, when the mouse was located
at the (0, 0) coordinates, for instance, the "{tip of this arrow}" would precisely be located at those coordinates

{/}

{file} - {File code} containing the graphic. The {file code} containing the graphic of the mouse pointer is defined in this field.
{It is not necessary} to indicate a value here if the graphic was loaded from an
{file MAP or PCX}, or if it is stored in the first {file FPG} loaded in the program. Otherwise, {mouse.file} will have to be assigned the {file code} that returned the {#132,load_fpg()} function on loading the file that contains the graphic of the mouse pointer.

{/}

{z} - Priority of the graphic display. Indicates the depth plane in which the graphic of the mouse pointer must be displayed. {By default} this field will be equal to{ -512}, which implies that {the pointer will be seen above the rest of graphics and texts}. The bigger this field is, the deeper the mouse pointer will be located.

If the aim was to make a graphic of a process appear above the mouse pointer,  suffice would be to assign an integer lesser than{ -512} 
(for instance,{ -600}) to the {#1125,local z} variable of that process.

{/}

{angle} - angle with which the graphic of the mouse pointer will be seen.
The value of {mouse.angle} by default is {0}, which implies that this graphic won't be seen rotated, unless a new angle is assigned to this field.

Keep in mind that the angles must be specified in degree thousandths. For instance, the {mouse.angle=90000;} statement will make the pointer appear rotated {90 degrees} (see the {#1044,use of angles in the language}).

{/}

{size} - Size of the graphic in percentage. By default, this field will be equal to {100} (the graphic will be seen 100%). Then, it is not necessary to indicate another value here, unless the aim is to scale the graphic (to display it expanded or reduced).

If, for instance, the aim was to double the original size of the graphic (being displayed at 200%), the {mouse.size=200;} statement should be used.

{/}

{flags} - In this field, different values will be indicated when the aim is to
mirror the graphic of the mouse (horizontally or vertically inverted), or to display it as a (semi) transparent graphic. The possible values that can be assigned to the {mouse.flags} are the following ones:

 {0}-Normal graphic (value by default).ú
 {1}-Horizontal mirror.ú
 {2}-Vertical mirror.ú
 {3}-Horizontal and vertical mirror (180ø).ú
 {4}-Transparent graphic.ú
 {5}-Transparent and horizontal mirror.ú
 {6}-Transparent and vertical mirror.ú
 {7}-Transparent, horizontal and vertical mirror.ú

{/}

{region} - Graphic's clipping region. A value must be assigned to this field {just when the aim is to make the mouse pointer visible only inside a region} (a rectangular zone of the screen). In order to achieve it, it is necessary first to
define this region with the {#106,define_region()} function and then, to assign the number of the region that has been defined to this field ({mouse.region}).

By default, this value will be equal to {0}, that is a number of region referred to the entire screen. Therefore, the graphic will be seen on the whole screen.

{/}

{left}, {middle} and {right} - These three fields store logical values ({0} or {1}) depending on whether the mouse buttons are pressed or not (they correspond with the left, central and right mouse buttons). Normally, only two buttons of the mouse ({left} and {right}) are activated, being ignored the state of the central button. This depends on the mouse {driver} installed in the computer.

For instance, to perform an action in a program {when the mouse left button is pressed} ({mouse.left}), it is necessary to include the following statement in the code:

  {IF (mouse.left)}ú
    // Action to perform (statements)ú
  {END}ú

{cursor} - indicates if the mouse emulator is active with the {Cursors} and {Enter} keys, 
you can move the pointer with the mouse or with the cursors. By default,
this emulation will be deactivated ({mouse.cursor=0;}). If the
program doesn't detect a mouse connected to the system, the emulation automatically in this case
will be activated (this means, that if {mouse.cursor} values are {1} at the beginning of the program, 
then there is no mouse connected to the pc).

{/}

{speed} - it is now possible to regulate the speed at which the mouse pointer functions in the programs. 
This is a value between {0} (maximum speed) and {9} (minimum), by default {mouse.speed} will have the value {2}.


{/}See: {#1200,Global data}

# -----------------------------------------------------------------------------

{.1101,GLOBAL STRUCT scroll}

{STRUCT scroll[9];}ú
    {x0, y0;}    // Foreground's coordinatesú
    {x1, y1;}    // Background's coordinatesú
    {z;}         // Depth planeú
    {camera;}    // {#1039,Identifying code} of the cameraú
    {ratio;}     // Relative speed of the backgroundú
    {speed;}     // Maximum speed of the foregroundú
    {region1;}   // First screen regionú
    {region2;}   // Second screen regionú
{END}ú

This {10} record structure contains certain fields related to changeable parameters of the {scroll windows}. These ten records have the same field names, but each of them modifies the parameters of a different scroll window
(as up to 10 windows of this type can be activated).

A {scroll window} could be defined as a screen region that only shows a part of a graphic bigger than that window (this graphic is normally the {decor} or {background} of the game). The {scroll} is the movement of that window through the graphic in any direction, being displayed the entire graphic little by little, section by section.

For a record (from {0} to {9}) of the {scroll structure} to make sense,
that {scroll window} (from {0} to {9}) must first be activated with the
{#163,start_scroll} function (for further information about the scroll windows, see this function}.

It is understood that the fields of this structure are complementary to those of the call parameters of this last function.

{/}

{How to use the scroll structure:}

To access these fields, the field name must be preceded by the word {scroll}, the record's number in square brackets and the symbol {#1063,.} (period).

For instance, if two scroll windows, number 0 and number 1, are initialised, it could be possible to access the {camera} field of both windows as
{scroll[0].camera} and {scroll[1].camera}, respectively. Moreover, when the scroll window number 0 is accessed, it is possible to omit the window's number in square brackets. That is to say, the {scroll.camera} and the {scroll[0].camera} variables are, to all intents and purposes, the same for the language.

{/}

{A detailed description of every field is now shown.}

{x0, y0} - Coordinates of the scroll's foreground, when the scroll {ISN'T} automatic (the {camera} field has not been defined), {These are the fields that will have to be modified in order to move the scroll window's foreground}.

These two fields store the horizontal and vertical coordinates of the upper left corner of the scroll window (the point of the foreground's graphic that will be seen in the window's upper left corner).

When the {camera} field of this structure has been defined, the movement of the scroll window will be automatic; thus, they are read-only fields. In order to check where the scroll is at every moment (see the {#140,move_scroll()} function).

{/}

{x1, y1} - Background's coordinates, when a graphic for the background has been defined. When the scroll {ISN'T} automatic (the {camera} field has not been defined), {these are the fields to modify in order to move the background of the scroll window}.

When the {camera} field of this structure has been defined, the movement of the
scroll window will be automatic; thus, they will be read-only fields, and the definition of the background's movement speed will depend on the {ratio} field of the same structure.

{/}

{z} - Scroll display priority, to indicate the depth plane in which this window must be painted, with respect to the rest of processes. By default, this variable will equal {512}, which implies that, as the processes have their {#1125,local z} variable at {0} by default, the scroll window will be painted in a greater (deeper) depth plane, being the graphics of the processes displayed above the window. In order to vary this situation, it is possible to modify either the {z} window's variable (for instance, putting it at{ -1}) or the {z} processes' variable (for instance, putting it at {600}).

{/}

{camera} - It is not necessary to initialise this field, as it will be initialised when the aim is that the scroll is {automatic}, that the system deals with it to always follow a process (a game's graphic). For that, it is necessary to put
the process' {#1039,identifying code} in this field. Thus, the shift of the scroll window will pass to be controlled automatically by the system, always trying to centre the graphic of this process in the window. This process must have the {#1122,ctype} local variable with the value {#1168,c_scroll}.

By default, this field will equal {0}, which implies that the scroll won't follow any process, unless the 
{#1039,identifying code} of a process is assigned to {camera}. When it is done, this process will be known 
as the scroll's {camera process}.

{Note:} A series of fields are now shown {only for automatic scroll windows}. It means that for those fields to make sense (and, therefore, effect), the {camera} field of this structure has to be defined previously with the {#1039,identifying code} of the process that is going to be centred in the scroll. These values will affect the way in which the process called {scroll camera} is going to be followed.

{/}

{ratio} - {Automatic scroll windows}. When two scroll planes have been defined in the call to the {#163,start_scroll()} function, in this field it is possible to define the {movement speed of the background} with respect to that of the foreground. By default, this value will equal {200}, which implies that the background will move half the speed of the foreground; if it is defined as {400}, it will move at the fourth part (four times slower), {100} at the same speed, {50} at double speed of the foreground, etc.

{/}

{speed} - {Automatic scroll windows}. Maximum speed of the scroll foreground, which will equal {0} by default. It means that no speed limit is imposed. If a limit is imposed, specifying the maximum number of points that the foreground can be shifted for every game's frame, the {camera process} will be off centre in the scroll window when it is moved at a higher speed.

{/}

{region1} - {Automatic scroll windows}. Scroll lock region, whose value by default equals{ -1}, which means that there is no lock region.
If this field is defined with a number of region (a rectangular zone of the screen previously defined with the {#106,define_region()} function), then the system won't scroll as long as the {camera process} remained inside it.

{/}

{region2} - {Automatic scroll windows}. External region of the scroll. By default, its value is equal to{ -1}, which means that there is no external region.
If this field is defined with a region's number and a {maximum speed} has been defined in the {speed} field, then the system will ignore that speed limit when the {camera} process is going to exceed from this region (it is done in order to continue to see the process (for its graphic to be visible always within the scroll window).

{Note:} If the two regions ({region1} and {region2}) are defined, region 1 is normally lesser than region 2 (the first one is contained in the second one). It will imply that:

- The background won't shift (the scroll won't be performed) while the camera process' graphic is inside region 1.

- If a maximum {speed} has been defined, then a scroll will be performed
to try to restore the graphic of the camera process to region 1, but without exceeding the imposed speed limit.

- If the graphic of the camera process tried to exceed from region 2, the imposed speed limit would be ignored in order not to allow it.

{/}See: {#1200,Global data} - {#163,start_scroll()} - {#166,stop_scroll()}

# -----------------------------------------------------------------------------

{.1102,GLOBAL STRUCT m7}

{STRUCT m7[9];}ú
    {camera;}   // {#1039,Identifying code} of the cameraú
    {height;}   // Height of the cameraú
    {distance;} // Distance of the cameraú
    {horizon;}  // Height of the horizonú
    {focus;}    // Focusú
    {z;}        // Depth planeú
    {colour;}    // colour of the exteriorú
{END}ú

This {10} record structure contains certain fields dealing with changeable parameters of the {mode 7 window}. The ten records have the same fields names, but each of them modifies the parameters of a different mode 7 window (as up to 10 windows of this type may be activated).

A {mode 7 window} could be defined as a screen region that shows a graphic plane three-dimensionally folded (for instance, like a sheet of paper with a picture horizontally positioned, displayed on screen with a virtual bottom (or top).

For a record (numbered from {0} to {9}) of the {m7 structure} to make sense,
that {mode 7 window} (from {0} to {9}) must first be activated with the {#162,start_mode7()} function (see this function for further information about the mode 7 windows}.

It is understood that the fields of this structure are complementary to the call parameters of this function. In order to observe a practical example
of a mode 7, it is possible to access the help about the {#162,start_mode7()} function.

{/}

{How to use the m7 structure:}

To access these fields, the field name must be preceded by the word {m7}, the number of record in square brackets and the symbol {#1063,. (period)}.

For instance, if two mode-7 windows, number 0 and number 1, were initialised the {camera} variable of both windows could be accessed as {m7[0].camera} and {m7[1].camera}, respectively. When the mode-7 window number 0 is accessed, it is also possible to omit the number of windows in square brackets. The {m7.camera} variable and the {m7[0].camera} variable are, to all ends, the same for the language.

{/}

{A detailed description of each field is now shown.}

{camera} - {#1039,Identifying code of the process} followed by the camera. To move the camera that controls the mode-7 view, only a mode-7 process must be created, a process having its local variable {#1122,ctype} {=} {#1169,c_m7}, and its {#1039,identifying code} must be put in the {camera} variable of this structure. After so, only the {#1123,x}, {#1124,y} and {#1129,angle} local variables of this process must be modified  and, for instance, the {#101,advance()} function must be used to move forward the camera.

For the mode 7 window to be activated, it is {indispensable} to initialise the {camera} field. Without this field, the window can not determine from where the folded plane must be {seen}.

{/}

{height} - Height of the camera. This variable of the structure manages the distance to which the camera is placed from the bottom. By default, its value equals {32}. Any positive number will make the camera be placed upper as the number is greater. If a negative number (less than zero) is put in the {height} field of this structure, then the camera will be placed below the folded plane, showing a "{top}" instead of a "{bottom}".

Two mode-7 must be created within the same region: one as top and the other as bottom (one with positive {height} and the other with negative height). In
this case, it is important to establish the {z} variable of the {#1102,m7 structure} of both, to thus determine the depth plane in which each one must be painted.

{/}

{distance} - Distance from the camera to the followed process. The perspective of the camera will always be positioned slightly behind the process whose identifier has been put in the {camera} field of the structure. This is done for the graphic of the process used as a camera to be seen, just in case this process has defined it (in its {#1126,graph} or {#1132,xgraph} local variable).

By default, the camera will be positioned at {64} points behind the process. "Behind" means a point placed at the indicated distance from the graphic
in the angle opposite to that one to which the process is orientated. For instance, if the process is facing right, 64 points to its left.

{/}

{horizon} - Horizon's height. This is the same value as that indicated as last parameter of the {start_mode7()} function. Its initial value will equal to the one indicated in the call to this function. The utility of this variable is to make the horizon go up or down in every frame of the game, depending on the needs of the latter.

On changing the {horizon's height}, the "{facing up}" and "{facing down}" effects will be obtained in the {mode 7 window}.

{/}

{focus} - Focus for the camera. This variable controls the perspective of the camera. By default, its value equals 256, but any value ranging from {0} and {512} may be put, obtaining different distortion effects of the three-dimensional plane.

This field controls the angle got by the camera focus. The greater this value is, the closer all the objects (processes) placed in the folded plane will be seen.

{/}

{z} - Mode-7 display priority. To indicate the depth plane in which this window must be painted, with respect to the rest of processes. By default, this variable will equal {256}, which means that, as the processes have their {#1125,local z} variable at {0} by default, the mode-7 window will be painted in a greater (deeper) depth plane, being the graphics of the processes painted above the window. This situation may change by modifying the {z} variable of the window (for instance, putting it at{ -1}) or the {z} variable of the processes (for instance, putting it at {257}).

{/}

{colour} - colour for the mode-7 exterior. When, in the call to the {start_mode7()}
function, any {external graphic} is not specified (the fourth call parameter is put at {0}), this variable will control the colour in which it is aim to paint the exterior. In other words, the colour that the screen must be painted in beyond the graphic that is being folded (beyond its limits).

By default, this field is initialised at {0}, which is normally the black colour
in the colour palette, Therefore, if this field is not assigned another value (and an external graphic is not defined) the screen will be seen in black beyond the foreground.

{/}See: {#1200,Global data} - {#162,start_mode7()} - {#165,stop_mode7()}

# -----------------------------------------------------------------------------

{.1103,GLOBAL STRUCT joy}

{STRUCT joy;}ú
    {left;}    // Left controlú
    {right;}   // Right controlú
    {up;}      // Up controlú
    {down;}    // Down controlú
    {button1;} // First buttonú
    {button2;} // Second buttonú
    {button3;} // Third buttonú
    {button4;} // Fourth buttonú
{END}ú

This global structure is used to control the {joystick}. It contains a series of logical fields related to the programming of this device: the state of the buttons (whether they are pressed or not) and the state of the main four control directions.

To access these fields, the name of the field must be preceded by the word {joy} and the symbol {#1063,. (period)}. For instance, to access the {left} field (which indicates whether the left control is pressed), it is necessary to use {joy.left}.

{/}

{left} - This field will be at {1} when the {joystick} is orientated to the {left}, and at {0} in the opposite case.

{right}  - This field will be at {1} when the {joystick} is orientated to the {right}, and at {0} in the opposite case.

{up}  - This field will be at {1} when the {joystick} is orientated {up}, and at {0} in the opposite case.

{down}  - This field will be at {1} when the {joystick} is orientated {down}, and at {0} in the opposite case.

For instance, to perform an action in a program {when the joystick is moved to the right} ({joy.right}), a statement like the following one must be included in the code:

  {IF (joy.right)}ú
    // Action to perform (statements)ú
  {END}ú

For diagonal positions, the two fields comprising this diagonal must be verified. For instance, to perform an action when the {joystick} is in the upper right diagonal, the following statement will be used:

  {IF (joy.up AND joy.right)}ú
    // Action to perform (statements)ú
  {END}ú

{/}

{button1}, {button2}, {button3} and {button4} - These fields indicate the state
of up to four joystick's buttons, being at {1} when the respective button is pressed, and at {0}, when it is not.

Some joysticks only have 2 buttons. In this case, they will be buttons number 0 and 1. In computers with two connected joysticks, the second joystick
will have the buttons number 2 and 3.

{/}

{Note:} When an analogical reading of the {joystick} is required (to know the exact coordinates at which the joystick is located), it will be necessary to use the {#122,get_joy_position()} function. Obviously, this function will only be useful in an analogical {joystick}, and it won't work in the digital ones.

{/}See: {#1200,Global data} - {#122,get_joy_position()} - {#121,get_joy_button()}

# -----------------------------------------------------------------------------

{.1104,GLOBAL STRUCT setup}

{STRUCT setup;}ú
    {card;}     // Type of cardú
    {port;}     // Access portú
    {irq;}      // Interruption requestú
    {dma;}      // Direct memory access channelú
    {dma2;}     // 16 bit channel of accessú
    {mixer;}    // Type of mixerú
    {rate;}     // Max frequencyú
    {master;}   // Master (general) volumeú
    {sound_fx;} // Effects volumeú
    {cd_audio;} // CD audio volumeú
{END}ú

This is a very advanced data structure, which is not at all necessary to create a game, no matter how difficult it is, as DIV Games Studio's process manager will normally take charge of the sound hardware automatically.

All the fields referred to the sound hardware are automatically updated by the program if you have a sound card, provided that the {BLASTER} or {GRAVIS} environment variable is properly initialised.

This one record structure contains a series of fields divided into two
groups: the first one, to activate new parameters of the sound hardware installed in the computer, and the second one to adjust the different volume controls managed by the sound system's {mixer}.

{/}

{Important:}

The {#175,reset_sound()} function must be called to activate the new parameters of the sound hardware inserted in this structure (in the {card}, {port}, {irq}, {dma} and {dma2} fields).

The {#178,set_volume()} function must be called to activate the new volume levels inserted in the structure (in the {master}, {sound_fx} and {cd_audio} fields). 

This structure is normally used inside the sound system setup programs (see {#1093,setup_program}).

{Note:} To access these fields, the field name must be preceded by the word {setup} and by the symbol {#1063,. (period)}. For instance, {setup.master} must be used to access the {master} field (which indicates the mixer's general volume level).

{/}

A more detailed description of every field of this structure is now shown.

{card} - Indicates the type of sound card installed in the computer.
The program accepts cards of the {Sound Blaster} (tm) and {Gravis Ultra Sound} (tm) families, as well as all those {100%} compatible with them.

The values that this field can take are the following ones, depending on the sound card type:

    Without card or sound    = {0}ú
    Sound Blaster 1.5        = {1}ú
    Sound Blaster 2.0        = {2}ú
    Sound Blaster Pro        = {3}ú
    Sound Blaster 16         = {4}ú
    Sound Blaster AWE        = {5}ú
    Gravis Ultra Sound       = {6}ú
    Gravis Ultra Sound MAX   = {7}ú

{/}

{port} - Indicates the computer's communications port in which
the data of the sound card must be written and read.

The values that this field can take are the following ones, depending on the port assigned to the sound hardware:

    0x210 = {0}ú
    0x220 = {1}ú
    0x230 = {2}ú
    0x240 = {3}ú
    0x250 = {4}ú
    0x260 = {5}ú

{/}

{irq} - This field indicates the number of IRQ (Interrupt request) assigned to the active sound card.

The values that this field can take are the following ones, depending on the IRQ used by the card:

    IRQ 2   = {0}ú
    IRQ 3   = {1}ú
    IRQ 5   = {2}ú
    IRQ 7   = {3}ú
    IRQ 10  = {4}ú
    IRQ 11  = {5}ú
    IRQ 12  = {6}ú
    IRQ 13  = {7}ú
    IRQ 14  = {8}ú
    IRQ 15  = {9}ú

{/}

{dma} - The direct memory access (DMA) channel's number used by the sound card must be indicated in this field.

This field can take values from 0 to 10, directly depending on the channel's number.

{/}

{dma2} - Some sound cards have a second direct memory access channel
faster than the previous one, of 16 bits, commonly named HDMA, DMA2 or DMA16.

Like in the previous field of this structure, this second channel can take values from 0 to 10 depending on the 16 bit channel's number used by the card.

{/}

{mixer} - Type of mixer used by the sound system, can be one of these two constants:

  {fast_mixer} - Fast mixer with two sound channels (1).ú
  {quality_mixer} - Max quality mixer (2).ú

By default, all programs will be initialised with the fast mixer setting activated 
({setup.mixer=fast_mixer;}) because this is the faster mode.

{/}

{rate} - Max permitted frequency (bit rate), a value between {11025}Hz (the min permitted quality of sound) and {44100}Hz (quality CD). By default, all programs are configured as 44100 ({setup.rate=44100;}), 
but it can be changed, because with the best quality, 
the sound system will be slower and will consume more processor time.

The value specified in {setup.rate} is the {max quality}
of sound, this means all loaded effects of sound will
reconfigure to this quality if they have a better quality. This means, all effects
saved to a frequency of 11025 will play with poor quality, although
the max permitted frequency may be bigger.

{/}

{bits} - Resolution of the digital effects samples and musical modules,
this field can have one of these constants as its value :

  {sound_bits_8} - 8 bit samples.ú
  {sound_bits_16} - 16 bit samples.ú

The effect is similar to the value specified in the field {rate}, the {8 bit} sounds will sound
worse (and occupy less space) than those of {16 bit} quality. The value
indicated in {setup.bits} indicates the max depth of the sample.

By default, all programs activate {16 bit} samples ({setup.bits=sound_bits_16;)), 
because the difference in quality is considerable.

{/}
{master} - This field contains the output general or master volume of the card. A number ranging from 0 (minimum volume) and 15 (maximum volume) must be here indicated. By default, the value equals {15}, the maximum volume.

Turning the master volume down will affect the sound effects' volume as well as the CD audio music reproduction's volume.

{/}

{sound_fx} - This field controls the volume to which the sound effects executed with the {#159,sound()} functions are reproduced.

This volume is independent from that used with the sound functions. The former is general for all the sound effects. On the contrary, the latter (volume indicated in the functions) is specific for every sound.

The values of this field also range from 0 (minimum volume) and 15 (maximum volume). By default, the value will be equal to the maximum volume.

{/}

{cd_audio} - This field controls the volume of the music that will be reproduced from the audio tracks of a CD ROM or Compact Disc.

Similar to the two previous fields, the values of this field can also rage from 0 (minimum volume) and 15 (maximum volume). By default, the value will be equal to the maximum volume.

{/}See: {#1200,Global data} - {#175,reset_sound()} - {#178,set_volume()}

# -----------------------------------------------------------------------------

{.1105,GLOBAL timer[]}

{timer[9];} // Counters of time{/}.

This is a 10 position global table, from {timer[0]} to {timer[9]},
and each of these 10 positions is a counter of {second hundredth} that is automatically incremented.

At the beginning of the program, these 10 counters will be put at  zero. They are use to time within a program. For that purpose, they can be put at zero at any time.

There are 10 counters so that the user can dedicate each of them to perform a different action inside the game, no matter which ones of the 10 counters are used. Normally, if the program only needs one counter (most of the times), that numbered {0} ({timer[0]}) is used, as the language allows us to omit the zero in square brackets in this case. If only one counter is needed, it is possible to use {timer} simply.

For instance, to implement a process that 5 seconds after the beginning of its execution (if it had been called) performed a specific action, it would be constructed in a way similar to the following one (by using, for instance,
the counter timer[9]):

 {PROCESS process_example();}ú
 {BEGIN}ú
     {timer[9]=0;}ú
     // ...ú
     {LOOP}ú
         {IF (timer[9]>=500)}ú
             // Action to perform ...ú
         {END}ú
         // ...ú
         {FRAME;}ú
     {END}ú
 {END}ú

{/}

{Note 1:} As timing is performed in second hundredths, these counters can be incremented in {1} hundredth, {2}, {3}, {4}, etc. in every frame of the game In an example like the previous one, the user can not wait for {timer[9]} to equal {500} exactly, as a frame could indicate {497} hundredths passed (since it was put at zero with {timer[9]=0;}) and the following frame {502} hundredths, without having passed through value {500}.

{/}

{Note 2:} It is also important to underline that much care must be taken to prevent several processes of the program from using the same counter for different purposes.

If, for instance, a {process_example()} (like the previous one) was created, in every frame of the game these processes would never manage to execute the action of the five seconds, as each of them would put the counter {timer[9]} at {0} at the beginning of their execution, thus invalidating the timing of the previous processes.

Keeping in mind that the counter timer[9] is {#1006,GLOBAL}, it is the same for all the game's processes, if a process puts it at {0}, it will be put at {0} for the rest of the processes.

{/}

{Note 3:} Finally, much care must be taken regarding the conditions similar to those of the previous example ({IF (timer[9]>=500) ... }), as these conditions
won't only be activated {once every 5 seconds}, but they will be activated
{always after the first 5 seconds}.

To understand the problem better, a process performing one action, {only once}, five seconds after the beginning of its execution, is now shown.

 {PROCESS process_example();}ú

 {PRIVATE}ú
     {action_performed=FALSE;}ú

 {BEGIN}ú
     {timer[9]=0;}ú
     // ...ú
     {LOOP}ú
         {IF (timer[9]>=500) AND NOT action_performed)}ú
             // Action to perform ...ú
             {action_performed=TRUE;}ú
         {END}ú
         // ...ú
         {FRAME;}ú
     {END}ú
 {END}ú

A private variable called {action_performed} which, at first, will be {false} is used. 
To perform an action now, it will be necessary that more than five 
seconds have passed and that {the action has not been performed yet}.
Therefore, after its performance the {action_performed} variable will become {true}.

For the previous example to execute the action {every five seconds}
(indefinitely), suffice will be to put the statement {timer[9]=0;} again after the
{action to perform}, not being necessary, in this case, the {action_performed} private variable, as other {5} seconds would be necessary for {timer[9]} to be again bigger than or equal to {500}.

{/}See: {#1200,Global data}

# -----------------------------------------------------------------------------

{.1106,GLOBAL text_z}

{text_z=-256;} // Texts' depth planes{/}.

The depth plane in which the texts must appear on screen is indicated in this global variable. It indicates what must appear above and below the text.

The depth planes can be any integer within the range ({#1177,min_int} ... {#1178,max_int}) and, the greater the number is, the deeper the text or graphic will be placed.

By default, the processes' graphics have their {#1125,local z} variable at {0} , the texts {text_z} at{ -256} and the mouse pointer has {#1100,mouse.z} at{ -512} by default.

That means that, by default, if these values are not modified,
the texts will appear above the processes' graphics and the mouse pointer above the texts.

If, for instance, the aim was that the texts appeared above the mouse pointer (opposite to which has been established by default), two things could have been done:

{a)} To place the pointer's plane lower than the texts' plane (a
greater number), such as, for instance: {mouse.z=-200;} (as{ -200} is a number
bigger than{ -256}).

{b)} To place the texts' plane upper that the pointer's plane such as,
for instance, {text_z=-600;} as{ -600} is a number lesser than{ -512} and,
thus, a less depth plane (less deep).

{/}

{Note 1:} The {text_z} variable is {#1006,GLOBAL} for all the texts. It is not possible to define texts in different depth planes.

{Note 2:} The texts can only be displayed with the {#171,write()}
(alphanumeric texts) function or with the {#172,write_int()} (variables' numeric values) function.

{/}See: {#1200,Global data} - {#171,write()} - {#172,write_int()}

# -----------------------------------------------------------------------------

{.1107,GLOBAL fading}

{fading=FALSE;} // Indicator of screen fading{/}.

This global variable indicates if a screen fading (a gradual change of the game's palette colours) is being performed at a specific moment. Its value will be:

{#1152,false (0)} - If a fading is {not} being performed.

{#1151,true (1)} - If a fading is being performed.

The purpose of this variable is to be able to determine the end of a screen fading started with the {#110,fade()} or {#112,fade_on()} functions.

On using these functions, a fading of the palette's colours will start, gradually coming closer to the definitive colours in the next frames of the game. In every {#1029,FRAME} statement a part of the fading will be performed.

When a fading is started, the {fading} variable will automatically become equal to {true} (1) and when it is finished, it will recover its original value, {false} (0).

{/}

{Note 1:} Generally, this variable is used to control the {#110,fade()} function,
and verify whether the fading has already been executed (performed). For instance, to stop the program's execution until the fading is finished, which can be done with a statement as follows (just after the call to the {#110,fade()} function):

  {WHILE (fading)}ú
      {FRAME;}ú
  {END}ú

Literally this statement defines: "{while the fading continues to be performed, a new frame must be displayed}".

{Note 2:} All the programs perform a fading ({#112,fade_on()}) at
the beginning of their execution (automatically). Therefore, this variable will be put at {true (1)} at the beginning of all the programs until this initial fading doesn't finish (while the screen "{fading on}" is being performed).

{/}See: {#1200,Global data} - {#110,fade()} - {#112,fade_on()}

# -----------------------------------------------------------------------------

{.1108,GLOBAL shift_status}

{shift_status=0;} // State of the special keys{/}.

The state of different special keys, such as [{ALT}], [{CONTROL}], etc. is indicated in this predefined global variable.

Each of these keys have the following code assigned:

Right SHIFT key        = {1}ú
Left SHIFT key         = {2}ú
CONTROL keys           = {4}ú
ALT and/or ALT GR keys = {8}ú
SCROLL LOCK key        = {16}ú
NUM LOCK key           = {32}ú
CAPS LOCK key          = {64}ú
INSERT key             = {128}ú

The {shift_status} variable will contain the {addition of all the codes of the pressed or activated keys}.

For instance, if the [{ALT}] key was pressed ant the [{CAPS LOCK}] was activated, the {shift_status} variable's value would equal {72} (8+64).

In order to verify whether a key like [{ALT}] is pressed, it is not possible to check that {shift_status} is equal to {8}, as it would imply that [{ALT}] is
the {only} pressed or activated special key.

A correct verification would be carried out as follows:

  {IF (shift_status AND 8 == 8)}ú
      // The [ALT] key is pressed ...ú
  {END}ú

{/}

{Note:} The {#128,key()} function is normally used to verify whether a key is pressed. But it is not possible to determine with this same function whether keys such as {CAPS LOCK} are activated, but only if they are pressed or not.

There are two variables containing the code of the last pressed key;
{#1110,scan_code} ({scan} code of the last pressed key) and {#1109,ascii}
({ascii} code of the last pressed key).

{/}See: {#1200,Global data} - {#128,key()} - {#1109,ascii} - {#1110,scan_code}

# -----------------------------------------------------------------------------

{.1109,GLOBAL ascii}

{ascii=0;} // ASCII code of the last pressed key{/}.

This global variable always indicates the ASCII code of the {last pressed key} in the last game's frame.

The {ascii} variable will be at {0} if no key has been pressed in the previous frame of the game.

The ASCII codes are a list of characters (letters, numbers and symbols)
numbered from {0} to {255} that have been standardised. The codes less than 32 are called control characters; from 32 to 127 appears the international set of characters; and from number 128, appears the expanded set of characters (according to the PC standard). The international and expanded ASCII characters are shown below.

{Summary of the standard PC ASCII codes.}{/}033 21{ !}³097 61{ a}³161 A1{ ¡}³225 E1{ á}ú
034 22{ "}³098 62{ b}³162 A2{ ¢}³226 E2{ â}ú
035 23{ #}³099 63{ c}³163 A3{ £}³227 E3{ ã}ú
036 24{ $}³100 64{ d}³164 A4{ ¤}³228 E4{ ä}ú
037 25{ %}³101 65{ e}³165 A5{ ¥}³229 E5{ å}ú
038 26{ &}³102 66{ f}³166 A6{ ¦}³230 E6{ æ}ú
039 27{ '}³103 67{ g}³167 A7{ §}³231 E7{ ç}ú
040 28{ (}³104 68{ h}³168 A8{ ¨}³232 E8{ è}ú
041 29{ )}³105 69{ i}³169 A9{ ©}³233 E9{ é}ú
042 2A{ *}³106 6A{ j}³170 AA{ ª}³234 EA{ ê}ú
043 2B{ +}³107 6B{ k}³171 AB{ «}³235 EB{ ë}ú
044 2C{ ,}³108 6C{ l}³172 AC{ ¬}³236 EC{ ì}ú
045 2D{ -}³109 6D{ m}³173 AD{ ­}³237 ED{ í}ú
046 2E{ .}³110 6E{ n}³174 AE{ ®}³238 EE{ î}ú
047 2F{ /}³111 6F{ o}³175 AF{ ¯}³239 EF{ ï}ú
048 30{ 0}³112 70{ p}³176 B0{ °}³240 F0{ ð}ú
049 31{ 1}³113 71{ q}³177 B1{ ±}³241 F1{ ñ}ú
050 32{ 2}³114 72{ r}³178 B2{ ²}³242 F2{ ò}ú
051 33{ 3}³115 73{ s}³179 B3{ ³}³243 F3{ ó}ú
052 34{ 4}³116 74{ t}³180 B4{ ´}³244 F4{ ô}ú
053 35{ 5}³117 75{ u}³181 B5{ µ}³245 F5{ õ}ú
054 36{ 6}³118 76{ v}³182 B6{ ¶}³246 F6{ ö}ú
055 37{ 7}³119 77{ w}³183 B7{ ·}³247 F7{ ÷}ú
056 38{ 8}³120 78{ x}³184 B8{ ¸}³248 F8{ ø}ú
057 39{ 9}³121 79{ y}³185 B9{ ¹}³249 F9{ ù}ú
058 3A{ :}³122 7A{ z}³186 BA{ º}³250 FA{ ù}ú
059 3B{ ;}³123 7B{ {{}}³187 BB{ »}³251 FB{ û}ú
060 3C{ <}³124 7C{ |}³188 BC{ ¼}³252 FC{ ü}ú
061 3D{ =}³125 7D{ {}}}³189 BD{ ½}³253 FD{ ý}ú
062 3E{ >}³126 7E{ ~}³190 BE{ ¾}³254 FE{ þ}ú
063 3F{ ?}³127 7F{ }³191 BF{ ¿}³255 FF{ ÿ}ú
064 40{ @}³128 80{ €}³192 C0{ À}ú
065 41{ A}³129 81{ }³193 C1{ Á}ú
066 42{ B}³130 82{ ‚}³194 C2{ Â}ú
067 43{ C}³131 83{ ƒ}³195 C3{ Ã}ú
068 44{ D}³132 84{ „}³196 C4{ Ä}ú
069 45{ E}³133 85{ …}³197 C5{ Å}ú
070 46{ F}³134 86{ †}³198 C6{ Æ}ú
071 47{ G}³135 87{ ‡}³199 C7{ Ç}ú
072 48{ H}³136 88{ ˆ}³200 C8{ È}ú
073 49{ I}³137 89{ ‰}³201 C9{ É}ú
074 4A{ J}³138 8A{ Š}³202 CA{ Ê}ú
075 4B{ K}³139 8B{ ‹}³203 CB{ Ë}ú
076 4C{ L}³140 8C{ Œ}³204 CC{ Ì}ú
077 4D{ M}³141 8D{ }³205 CD{ Í}ú
078 4E{ N}³142 8E{ Ž}³206 CE{ Î}ú
079 4F{ O}³143 8F{ }³207 CF{ Ï}ú
080 50{ P}³144 90{ }³208 D0{ Ð}ú
081 51{ Q}³145 91{ ‘}³209 D1{ Ñ}ú
082 52{ R}³146 92{ ’}³210 D2{ Ò}ú
083 53{ S}³147 93{ “}³211 D3{ Ó}ú
084 54{ T}³148 94{ ”}³212 D4{ Ô}ú
085 55{ U}³149 95{ •}³213 D5{ Õ}ú
086 56{ V}³150 96{ –}³214 D6{ Ö}ú
087 57{ W}³151 97{ —}³215 D7{ ×}ú
088 58{ X}³152 98{ ˜}³216 D8{ Ø}ú
089 59{ Y}³153 99{ ™}³217 D9{ Ù}ú
090 5A{ Z}³154 9A{ š}³218 DA{ Ú}ú
091 5B{ [}³155 9B{ ›}³219 DB{ Û}ú
092 5C{ \}³156 9C{ œ}³220 DC{ Ü}ú
093 5D{ ]}³157 9D{ }³221 DD{ Ý}ú
094 5E{ ^}³158 9E{ ž}³222 DE{ Þ}ú
095 5F{ _}³159 9F{ Ÿ}³223 DF{ ß}ú
096 60{ '}³160 A0{  }³224 E0{ à}{/}

Therefore, an ASCII code is referred to the {character that has been created with the last keystroke} (or keystroke combinations, in those cases such as letters bearing a stress mark).

{/}

{Important:} There is another predefined global variable, called {#1110,scan_code}, which also contains the code of the last pressed key. But, unlike {ascii}, this new variable stores the {scan code} of the key. This indicates {which key has been pressed} and not {which character has been generated} by it (like {ascii}).

There is a series of constants designating these {#1176,keys codes} (keytable scan codes). 
Access the help about these {#1176,keys codes}
to observe, moreover, a {sample program} with the {ascii} and {scan_code} variables.

The {#128,key()} function of the language is normally used in order to verify whether a key is being pressed or not. This function receives one of these {#1176,keys codes} as a parameter, and returns {0} if the key is not pressed or {1} if it is pressed.

{/}See: {#1200,Global data} - {#1110,scan_code} - {#128,key()}

# -----------------------------------------------------------------------------

{.1110,GLOBAL scan_code}

{scan_code=0;} // Scan code of the last pressed key{/}.

This global variable always indicates the scan code of the {last pressed key} in the last frame of the game.

The {scan_code} variable will be at {0} if no key has been pressed in the previous frame of the game.

This variable is often used to wait in a program for the user to press any key with a statement similar to the following one:

  {WHILE (scan_code == 0)}ú
      {FRAME;}ú
  {END}ú

This statement indicates that, while no key has been pressed in the previous frame (while {scan_code} equals {0}), the frames of the game must continue to be displayed.

The {scan codes} are simply a numeric list of the PC's keys. These codes can slightly vary (in any key) regarding different keytables, as there are keytables of different languages, with a varied number of keys, etc.

However, almost all the codes of the main keys remain constant. There is a predefined list 
of constants (synonymous for these codes)
in the language that can be seen by accessing the help about {#1176,keys codes} (or keytable scan codes). These numeric values will precisely be assigned to the {scan_code} variable when the respective keys are pressed in the program.

{/}

{Important:} There is another predefined global variable, called {#1109,ascii}, which also contains the code of the last pressed key. But, unlike {scan_code}, this new variable stores the {ASCII code} (character) generated by the key. This indicates {which character has been generated by the last pressed key} and not {which key has been pressed} (like {scan_code}).

Access the help about the {#1176,keys codes} to observe a {sample program} with the {ascii} and {scan_code} variables.

The {#128,key()} function of the language is normally used in order to verify whether a key is being pressed or not. This function receives one of these {#1176,keys codes} as a parameter, and returns {0} if the key is not pressed or {1} if it is pressed.

{/}See: {#1200,Global data} - {#1109,ascii} - {#128,key()}

# -----------------------------------------------------------------------------

{.1111,GLOBAL joy_filter}

{joy_filter=10;} // Filter applied to the joystick{/}.

This global variable is used to define the filter applied to the read
joystick's coordinates.

It is defined as a percentage from {0 %} to {99 %}. By default, {joy_filter}
will equal {10} (a 10% filter will be applied).

The purpose of applying this filter to the joystick's coordinates is to make its movements gentler and to avoid possible "{irregularities}" in the coordinates' reading. Those joystick's coordinates must be obtained with the {#122,get_joy_position()} function. The {joy_filter} variable will only be useful when the latter function is being used.

The bigger the filter applied to the joystick is, the gentler the movements of the latter will be. But, at the same time, its answer will take longer.

As the task performed by this "{filter}" is somewhat difficult to understand,
an example is now shown.

{#9999,Example program:}
PROGRAM example_joy_filter;
BEGIN
    write(0, 0, 0, 0, "joy_filter=");
    write_int(0, 70, 0, 0, offset joy_filter);
    write(0, 160, 180, 1, "The graphic is shown at the joystick's coordinates");
    write(0, 160, 190, 1, "Use the up/down keys to vary the filter");
    load_fpg("help/help.fpg");
    put_screen(0, 1);
    graph=100;
    LOOP
        IF (scan_code==_up AND joy_filter<99)
            joy_filter++;
        END
        IF (scan_code==_down AND joy_filter>0)
            joy_filter--;
        END
        x=get_joy_position(0);
        y=get_joy_position(1);
        FRAME;
    END
END
{-}

This program displays the graphic of a ball at the coordinates returned by the main joystick with the 
{#122,get_joy_position()} function.

It can be notice how, for small values of {joy_filter}, many "{irregularities}" appear in the reading, and for very big values (like 95%) the coordinates' read is much gentler and regular, but slightly slower.

{Note:} It is indispensable to have a joystick (or gamepad) connected to the computer for this variable to be useful. If the joystick is connected during the program's execution, the system won't detect it (it must be connected from the beginning). See the {#1112,joy_status} global variable.

{/}See: {#1200,Global data} - {#122,get_joy_position()} - {#1112,joy_status}

# -----------------------------------------------------------------------------

{.1112,GLOBAL joy_status}

{joy_status=0;} // State of the joystick{/}

The state of the joystick (or gamepad) connected to the computer is indicated in this global variable. These are the values that this variable takes by default:

{0} - If the joystick reading system is disabled. This value means that a joystick connected to the computer either has not been found at the beginning of the program's execution, or has been disconnected.

{1} - If the joystick reading system is active. This is the initial value by default, but if the joystick is disconnected (or there is no joystick connected), the reading system will be disabled (indicating {0} in the joy_status variable).

If the system is disabled, it can be reactivated by simply assigning {1} to {joy_status} (with the {joy_status=1;} statement). But if, after a limited time, no joystick is detected, the system will be disabled again.

{/}

There is a {special mode} in which the joystick reading system {won't be ever disabled}. This mode is simply defined by {assigning 2 to
joy_status}.

  {joy_status=2;} // Activates special modeú

Nevertheless, much care must be taken as, if the joystick reading system is activated in this way, and there is no joystick connected to the computer, {the game's execution may be slowed down}.

{/}

{Note:} To read the joystick in the programs, the {#1103,global joy structure} is normally accessed. This structure always indicates its offset and the state of its
buttons (whether they are pressed or not).

{/}See: {#1200,Global data} - {#1103,Joy structure} - {#1111,joy_filter}

# -----------------------------------------------------------------------------

{.1113,GLOBAL restore_type}

{restore_type=complete_restore;} // Restoring type{/}.

This global variable indicates the restoring type that must be performed after each frame on screen.

The term {background restoring} means to recover the screen zones in which graphics have been painted or texts have been written in the previous frame. 

There are three applicable restoring types which directly correspond to three constants that can be assigned to the {restore_type} variable.

{#1172,no_restore}       - The fastest one, the background is not restored (-1)ú
{#1173,partial_restore}  - Average, partial restoring (0)ú
{#1174,complete_restore} - The slowest one, complete restoring (1)ú

By default, the value of {restore_type} equals {complete_restore}. If a different value is not indicated in this variable, a complete screen restoring will take place after each frame of the game.

This restoring mode (complete) is the slowest one out of these three modes. Thus, it will surely be possible to gain speed in the game's execution (for it to be faster in slow computers), if a different value is assigned to this variable.
For instance, the following statement must be used to indicate a partial restoring:

  {restore_type=partial_restore;}

This statements orders the process' manager of DIV Games
Studio to partially restore the screen background (only those screen zones where graphics or texts have been put) after the following frames of the game.

The {no_restore} type (not restoring the screen background) is the fastest mode. However, it is only applicable when the game develops inside a scroll or mode 7 window occupying the entire screen. Otherwise, the graphics will leave signs (of the previous frames) on moving through the screen.

The restoring mode can be changed under a program's execution as often as necessary, according to the requirements of the stages (or sections) under execution at each moment.

{/}

{Note:} There is another global variable also related to DIV
Games Studio's management on screen. This is called {#1114,dump_type} and it defines the 
type of frames {dump} that must be performed (what information
must be sent to the monitor after every frame of the game).

{/}See: {#1200,Global data} - {#1114,dump_type}

# -----------------------------------------------------------------------------

{.1114,GLOBAL dump_type}

{dump_type=complete_dump;} // Type of dump{/}

This global variable indicates the frame dump on screen types that must be performed in every frame of the game.

The term {dump} means that the game's frames are sent to the monitor (to the video memory of the graphic card).

{/}

There are two applicable types of dump which directly correspond with two constants that can be assigned to the {dump_type} variable.

{#1170,partial_dump} - When indicated with the following statement, {partial dumps} will be performed:

  {dump_type=partial_dump;}

Only the graphics that are updated, that have changed with respect to the previous frame, will be dumped on screen in this mode. It is advisable to activate this dump {in order to gain speed} when a game (or one section of it) is programmed without a scroll or mode 7 window occupying the entire screen. 

{#1171,complete_dump} - When indicated with the following statement, {complete dumps} will be performed:

  {dump_type=complete_dump;}

In this mode, the entire screen will be dumped no matter whether the graphics have changed or not. This mode is slower than the {partial dump}. Nevertheless, it must be used when the game has a scroll or mode 7 window occupying all the screen.

{/}

By default, the value of {dump_type} is {complete_dump}. If no other value is indicated in this variable, {complete dumps} on the screen will be performed after each game's frame (which is normally {slower} than performing partial dump).

The dump type can be changed during a program's execution as often as necessary, according to the requirements of the stages (or sections) under execution at each moment.

{/}

{Note:} There is another global variable also related to DIV
Games Studio's management on screen. This is called {#1113,restore_type}  and it defines the type of {restoring} that must be performed on screen after every game's frame (which graphics or texts must be deleted).

{/}See: {#1200,Global data} - {#1113,restore_type}

# -----------------------------------------------------------------------------

{.1115,GLOBAL max_process_time}

{max_process_time=500;} // Maximum execution time{/}.

Programs are provided with an {anti-blocking} system that will make the manager of processes of DIV Games Studio interrupts its execution when a process exceeds the {maximum execution time} in a game's frame.

This maximum time is indicated in the {max_process_time} global variable in {hundredths of second}. By default, its value is {500 hundredths} ({5 seconds}).

When a process takes longer than the indicated time in
executing a {#1029,FRAME} statement (which indicates that the process
is ready for the following frame of the game), an execution error will arise.

{Note:} The utility of the possibility of changing this variable, assigning a new value to it, is to avoid this error in the programs in which there is a process that must be doing calculations for a long time.

The following statement must be used to order the process' manager, for instance, not to interrupt a process, unless its execution in a frame is longer that 30 seconds:

  {max_process_time=3000;}

As 30 seconds are 3000 hundredths of second.

{/}

{Important:} Keep in mind that the time used by every computer to do the program's calculations is different. Therefore, this value must be defined with a certain margin, in order to avoid to exceed  the {maximum execution time}
when the game is executed in slower computers.

{/}See: {#1200,Global data} - {#1029,FRAME statement}

# -----------------------------------------------------------------------------

{.1116,LOCAL STRUCT reserved}

{STRUCT reserved;}ú
    {process_id;}    // Identifier of the processú
    {id_scan;}       // Index of processesú
    {process_type;}  // Type of processú
    {type_scan;}     // Index of typesú
    {status;}        // State of the processú
    {param_offset;}  // Offset of the parametersú
    {program_index;} // Program counterú
    {is_executed;}   // executed processú
    {is_painted;}    // painted processú
    {distance_1;}    // Mode 7 reservedú
    {distance_2;}    // Mode 7 reservedú
    {frame_percent;} // Percentage of frameú
    {box_x0, box_y0;} // Beginning of the process' graphicú
    {box_x1, box_y1;} // End of the process' graphicú
    {m8_object;}      // Object inside the world m8ú
    {old_ctype;}      // Old Ctypeú
    {f_count;}        // Accumulating function counter ú
    {caller_id;}      // Process or function callerú
    {stack_pointer;}  // Stack pointer for the processú

{END}ú

In this structure, different {variables of internal use} (used by the {manager of processes of DIV Games Studio}) are stored.

They are local variables reserved for the system. It is not necessary to know these variables, as most of them are not useful to create programs.

{Important:} The modification of the values of these variables will probably provoke {crashing} the computer, an incorrect working of the {manager of processes} or problems on using many of the internal functions. Therefore, no responsibility is assumed for the problems derived from an incorrect use of the {reserved} structure.

{/}

A {brief description} of each of these fields is now shown, just for information.

{process_id} - {#1039,Identifying code} of the process. This value is normally obtained with the reserved word {#1092,ID} and the value of this field must not be modified.

{id_scan} - It is internally used for detecting collisions in order to save the {#1039,identifying code} of the last process that has collided with the current process.

{process_type} - Type of the current process, normally obtained with the operator {#1042,TYPE}, later indicating  the process name (see {#1042,Types of processes}).

{type_scan} - It is internally used to detect collisions or obtain identifying codes of processes of a specific type.

{status} - Present state of the process. The values that this field can adopt are the following ones:

  {0} - non-existent process.ú
  {1} - process that has received a signal {s_kill}.ú
  {2} - alive or awake process (s_wakeup).ú
  {3} - asleep process (s_sleep).ú
  {4} - frozen process (s_freeze).ú

{param_offset} - Offset of the computer's memory in which the parameters received by the process are located.

{program_index} - Program's counter. Offset of the computer's memory in which the first statement that must execute the process in the next frame is located.

{is_executed} - It indicates whether this process has already been executed in the current frame.

{is_painted} - It indicates whether the graphic of the process has already been painted in the current frame of the game.

{distance_1} - Vertical distance of the process (reserved for processes displayed in a mode 7 window).

{distance_2} - Horizontal distance of the process (reserved for processes displayed in a mode 7 window).

{frame_percent} - Percentage of the following frame completed by the process. This value will be useful when the {#1029,FRAME} statement is used indicating a percentage. Otherwise, it will simply be equal to 0 (0%) when the process has not been executed and 100 (100%) when it has already been executed.

{box_x0, box_y0} - Upper left coordinate of the graphic in the previous frame of the game (where the graphic was placed at screen coordinates).

{box_x1, box_y1} - Lower right coordinate of the graphic in the previous frame of the game.

{m8_object} - number of object inside the mode 8, indicates an ordinal
relative to the map of sectors.

{old_ctype} - old value of the local variable ctype, is used to
control changes in the coordinates of the process.

{f_count} - accumulation counter of the function, to control the number
of returns and level the battery for each process.

{caller_id} - identification code of the process or function which invoked
this.

{stack_pointer}  - pointer of local stack of each process, maintains
the direction of the stack at the start of the process, with the stacked parameters


{/}See: {#1201,Local data} - {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1117,LOCAL father}

{father;} // {#1039,Identifying code} of the father{/} process.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {father} variable.

This variable always contains the {#1039,identifying code} of the process that created (called) the current process (the one that has this variable).

Inside the language, father process is the name given to the process that calls another one. The process that has been called receives the name of son process. For further information, see the {#1041,hierarchies of processes} in the language.

The DIV's {manager of processes} is the process named {div_main}. Its function is to create the main process of the program ({PROGRAM}) at the beginning of the game's execution. Therefore, it will be the father of the main program, as well as the father of all the processes that become orphan (processes whose father has been killed or finished before them, see {#1040,states of a process}).

{/}

{Note:} The {#1039,identifying code} of the son process is indicated in the
predefined {#1118,son} local variable.

{/}See: {#1201,Local data} - {#1039,Identifying code} - {#1041,Hierarchies of processes}

# -----------------------------------------------------------------------------

{.1118,LOCAL son}

{son=0;} // {#1039,Identifying code} of the son{/} process.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {son} variable.

This variable always contains the {#1039,identifying code} of the {last} process  created (called) by the current process. 

Inside the language, father process is the name given to the process that calls another one. On the other hand, son process is the name given to the process that has been called. For further information, see the {#1041,hierarchies of processes} in the language.

By default, this variable will be equal to {0} until the process makes a call to another process. At this moment, the new process will be created indicating its {#1039,identifying code} in {son}.

{/}

{Note:} The {#1039,identifying code} of the father process is indicated in the predefined {#1117,father} local variable.

{/}See: {#1201,Local data} - {#1039,Identifying code} - {#1041,Hierarchies of processes}

# -----------------------------------------------------------------------------

{.1119,LOCAL smallbro}

{smallbro=0;} // {#1039,Identifying code} of the younger brother{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {smallbro} variable.

This variable always contains the {#1039,identifying code} of the {following} process  created by the father of the current process after it.

Inside the language, {younger brother} is the name given to this process. For further information, see the {#1041,hierarchies of processes} in the language.

By default, this variable will be equal to {0} until the father process makes a call to another process. At this moment, the new process (the younger brother of this one) will be created, indicating its {#1039,identifying code} in {smallbro}.

{/}

{Note:} The {#1039,identifying code} of the {elder brother} is indicated
in the predefined {#1120,bigbro} local variable.

{/}See: {#1201,Local data} - {#1039,Identifying code} - {#1041,Hierarchies of processes}

# -----------------------------------------------------------------------------

{.1120,LOCAL bigbro}

{bigbro=0;} // {#1039,Identifying code} of the elder brother{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {bigbro} variable.

This variable always contains the {#1039,identifying code} of the process  created by the father just before creating the current process after it. 

Inside the language, {elder brother} is the name given to this process. 
For further information, see the {#1041,hierarchies of processes} in the language.

By default, this variable will be equal to {0} if the father process (the one that called the current one) has not created any other process before. If it has created one, or more than one, {bigbro} will indicate the {#1039,identifying code} of the last one.

{/}

{Note:} The {#1039,identifying code} of the {younger brother} is indicated
in the predefined {#1119,smallbro} local variable.

{/}See: {#1201,Local data} - {#1039,Identifying code} - {#1041,Hierarchies of processes}

# -----------------------------------------------------------------------------

{.1121,LOCAL priority}

{priority=0;} // Level of priority of the process{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {priority} variable.

In the preparation of each frame, all the processes will be executed in
the priority order established by the {priority} local variable.

The higher the value of {priority} in a process is, the sooner it will be processed in each frame. The priority value may be established as any integer within the ({#1177,min_int} ... {#1178,max_int}) range. For instance, to establish the priority level of a process at {10}, the following statement must be used:

  {priority=10;}

All the processes active in the program having {the same level of priority} will be executed in a {undetermined order} that, moreover, may vary from some executions of the game to others.

By default, the {priority} local variable will be initialised at {0}
in all the processes created in the program. Thus, it will be possible to execute them in any order, if the value of this variable is not defined.

If the {priority} of a single process is fixed at a positive number, such as 1, it will be executed before the rest of the of the processes. On the other hand, if it is fixed at a negative number, such as -1, then it will be executed after the rest (supposing that the {priority} variable of the rest has not been modified, so its value is still equal to {0}).

{When the processes priority must be established?}{/}

When a process needs to use data of another process for its calculations, it is normally advisable to execute it after the latter, defining its lowest priority for the data of the second process to be updated when they are read.

For instance, if process {B} must place its graphic 8 pixels lower than the graphic of process {A}, the priority of {A} must be greater than that of {B}, for the latter to be executed first.

Thus, when process {B} obtains its {y} coordinate by adding 8 to the one of process {A}, this calculation is done with the {y} coordinate of process {A}
already updated for the following frame (to ensure that in each frame, the {y} coordinate of process {A} first, and then that of process {B} will be established).

For that purpose, suffice would be to define either the priority of {A} as {1} or the priority of {B} as{ -1}, since by default both priorities are at {0}.

{/}

{Note:} The priority level of the process has nothing to do with the depth plane in which its graphic appears on screen, as this plane is indicated in the {#1125,local z} variable.

{/}See: {#1201,Local data}

# -----------------------------------------------------------------------------

{.1122,LOCAL ctype}

{ctype=c_screen;} // System of coordinates{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its  {ctype} variable.

The {system of coordinates} used by the process is indicated in this variable. 

It is possible to use three different systems of coordinates, directly corresponding with three constants that can be assigned to the {ctype} variable.

  {#1167,c_screen} - Screen coordinatesú
  {#1168,c_scroll} - Scroll coordinatesú
  {#1169,c_m7}     - Mode 7 coordinatesú
  {#1412,c_m8}     - Mode 8 coordinatesú


{By default, the ctype value is} {#1167,c_screen}, used for the process' graphic coordinates to be interpreted as referred to the screen, where the upper left corner is (0, 0).

With the following statement, {#1168,c_scroll} will be assigned to {ctype}:

 {ctype=c_scroll;}

For the process' graphic coordinates to be interpreted as referred to a scroll window, with coordinates located above the foreground's graphic.

With the following statement, {#1169,c_m7} will be assigned to {ctype}:

 {ctype=c_m7;}

For the process graphic coordinates to be interpreted as referred to a mode 7 window, with coordinates located above the main graphic, three-dimensionally folded in that window.

{#1412,c_m8} will be assigned to {ctype} with the following statement:

 {ctype=c_m8;}

For the coordinates of the process graphic to be interpreted as referred 
a mode 8 window, with coordinates located above the main graphic, three-dimensionally 
folded in that window.

{/}

{Note:} There is another local variable that also affects the way in which the process coordinates must be interpreted, This variable is {#1135,resolution}, which establishes the resolution (scale) in which the coordinates are defined.

{/}See: {#1201,Local data} - {#1167,c_screen} - {#1168,c_scroll} - {#1169,c_m7} - {#1412,c_m8}

# -----------------------------------------------------------------------------

{.1123,LOCAL x}

{x=0;} // Horizontal coordinate of the graphic{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {x} variable.

The {x} and {#1124,y} local variables of the processes define where their graphic (defined in the {#1126,graph} local variable) must be placed.

The {x} local variable defines the process' {horizontal coordinate},
which may be defined as an integer within the range ({#1177,min_int} ...
{#1178,max_int}), putting the positive coordinates to the right and the negative ones, to the left.

By default, these coordinates will be specified in {pixels},
referred to screen coordinates, where the upper left corner is the point placed at ({0}, {0}).

{Type of coordinates.}{/}

There are several systems of coordinates that may be used by the processes and that are defined with the {#1122,ctype} local variable. The coordinates related to the screen are the system by default.

{Resolution of the coordinates.}{/}

The {#1135,resolution} local variable indicates the precision of the process coordinates. By default, this variable will be equal to {0} and the ({x}, {#1124,y}) coordinates will be specified in pixels.

The higher the value of {#1135,resolution} is, the smaller (and more precise) the drive in which the coordinates are interpreted will be. Some examples are now shown:

{resolution=1;} - The coordinates are specified in pixels.

{resolution=10;} - They are specified in tenths of pixels.

{resolution=100;} - They are specified in hundredths of pixels.

{resolution=2;} - They are specified in half pixel.

...

{/}

{Note:} A different type and resolution of coordinates may be either defined for each 
process or changed while executing if necessary.

{/}

{Important:} When a graphic is placed at some specific coordinates, it is the graphic {centre} that will normally be placed at these coordinates.

This can be changed by defining in the {graphic editor} the {#1136,control point} number {0} of the graphic of the process (whose {graphic code} is indicated in the {#1126,graph} variable).

If the control point has been defined, it will be placed at the specified coordinates.

For instance, if control point number {0} is placed in the upper left corner of the graphic, and then, the graphic is put at the (100, 100) coordinates, the upper left corner of the graphic will be placed at these coordinates.

{/}See: {#1201,Local data} - {#1122,ctype} - {#1135,resolution}

# -----------------------------------------------------------------------------

{.1124,LOCAL y}

{y=0;} // Vertical coordinate of the graphic{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {y} variable.

The {#1123,x} and {y} local variables of the processes define where their graphic (defined in the {#1126,graph} local variable) must be placed.

The {y} local variable defines the process' {vertical coordinate},
which may be defined as an integer within the range ({#1177,min_int} ...
{#1178,max_int}), placing the positive coordinates downwards and the negative ones, upwards.

By default, these coordinates will be specified in {pixels},
referred to screen coordinates, where the upper left corner is the point placed at ({0}, {0}).

{Type of coordinates.}{/}

There are several systems of coordinates that may be used by the processes and that are defined with the {#1122,ctype} local variable. The system by default defines the coordinates related to the screen.

{Resolution of the coordinates.}{/}

The {#1135,resolution} local variable indicates the precision of the process coordinates. By default, this variable will be equal to {0} and the ({#1123,x},{y}) coordinates will be specified in pixels.

The higher the value of {#1135,resolution} is, the smaller (and more precise) the drive in which the coordinates are interpreted will be. Some examples are now shown:

{resolution=1;} - The coordinates are specified in pixels.

{resolution=10;} - They are specified in tenths of pixels.

{resolution=100;} - They are specified in hundredths of pixels.

{resolution=2;} - They are specified in half pixels.

...

{/}

{Note:} A different type and resolution of coordinates may be either defined for each process or changed while executing if necessary.

{/}

{Important:} When a graphic is placed at some specific coordinates, it is the graphic {centre} that will normally be placed at these coordinates.

This can be changed by defining in the {graphic editor} the {#1136,control point} number {0} of the graphic of the process (whose {graphic code} is indicated in the {#1126,graph} variable).

If the control point has been defined, it will be placed at the specified coordinates.

For instance, if control point number {0} is placed in the upper left corner of the graphic, and then, the graphic is put at the (100, 100) coordinates, the upper left corner of the graphic will be placed at these coordinates.

{/}See: {#1201,Local data} - {#1122,ctype} - {#1135,resolution}

# -----------------------------------------------------------------------------

{.1125,LOCAL z}

{z=0;} // Depth plane of the process graphic{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {z} variable.

The {z} local variable defines the depth plane in which the process graphic must be placed on screen (the graphic is defined in the {#1126,graph} local variable). 

Any integer within the range ({#1177,min_int} ... {#1178,max_int}) may be used as a depth plane. The greater the number is, the deeper the graphic will be placed.

{/}

By default, the depth planes are arranged in the following way:

{ (+) Greater depth}

{ +512} - Scroll windows (see {#1101,scroll[].z})ú
{ +256} - Mode 7 windows (see {#1102,m7[].z})ú
{  0}   - Graphics of the processes (local {z})ú
{ -256} - Texts (see {#1106,text_z})ú
{ -512} - Mouse pointer (see {#1100,mouse.z})ú

{ (-) Less depth}

The {z} local variable that defines the depth plane of the processes' graphics will be initialised at {0}. The processes' graphics will be placed below the mouse pointer and texts, and above the scroll and mode 7 windows (if the values are not modified by default).

{/}

All the objects (texts, graphics, windows, ...) placed in the same depth plane will appear on screen (on being superimposed) in an {undetermined order}, that may vary from some program's executions to some others.

If the aim was, for instance, that the graphic of a process appeared above all the objects of the program, a depth plane could be fixed for it above the rest (as -1000}, with the following statement:

  {z=-1000;}

At the beginning, all the processes have their {z} variable at {0},
then the graphic of the processes will appear in any order if the plane in which 
each of them must be placed is not defined.

The depth plane of a process may be modified (by assigning a new value to its {z} 
variable) as often as necessary inside a program.

The depth planes of the rest of the objects (windows, texts
and mouse pointer) may also be modified at any stage of the program.

{/}

{Note 1:} The processes that belong to a {scroll window} (having its variable {#1122,ctype}{=}{#1168,c_scroll}) will be painted in the {depth plane of the scroll window}. Nevertheless, inside that window, all the graphics of the processes will appear {in order, according to their depth plane}.

The process' depth plane (indicated as usual in the {z} variable) will be {referred to the scroll window}
in which the process appears (see {#163,start_scroll()}).

{/}

{Note 2:} The processes that belong to a {mode 7 window} (having its variable {#1122,ctype}{=}{#1167,c_m7}) will appear in that window {in order, according to the depth order in the three-dimensional plane} ignoring the value of their {z} local variable.

The only sense of the {z} local variable in {mode 7} processes is to define the order in which the processes {exactly} placed at the same coordinates of the folded plane must be superposed. If two processes are placed in the three-dimensional plane at the same coordinates, then it will be possible to define, through the {z} variable, which one must appear above the other (see {#162,start_mode7()}).

{/}See: {#1201,Local data} - {#1100,mouse.z} - {#1101,scroll[].z} - {#1102,m7[].z} - {#1106,text_z}

# -----------------------------------------------------------------------------

{.1126,LOCAL graph}

{graph=0;} // Code of the process graphic{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process 
will have its own value in its {graph} variable.

Normally, most of the processes correspond with a graphic object
displayed on screen that will be placed at the indicated coordinates
in the {#1123,x} and {#1123,y} local variables. It is necessary to define which graphic corresponds with this process by assigning a {graphic code} to the {graph} local variable.

By default, this variable will be equal to {0}, which implies that no graphic will be displayed for this process.

The graphics must first be created in the {graphic editor} of DIV
Games Studio (with the option "{New...}" of the maps menu) and then, they can be 
saved in an {file MAP} (containing this graphic),
or in a {file FPG} together with other graphics (it is possible to create a new 
file with the option "{New...}" of the files menu).

The graphics used in a program may come from an {file MAP} (that contain just one graphic) or from a {file FPG}(that may contain many graphics).

{Note:} The same graphic may be used in a program by many processes at the same time.

{files MAP or PCX}{/}

In order to use a graphic from an {file MAP} in the program, it must be loaded by calling the {#174,load_map()}  or {#174,load_pcx()} function, which will return the {graphic code} that must be assigned to the {graph} variable.

A {#1006,GLOBAL} variable is normally used to save this {graphic code} and then, it is assigned to the {graph} variable.

{#9999,Example program:}
PROGRAM example_graph;

GLOBAL
    graphic1;

BEGIN
    graphic1=load_map("help/help.map");

    graph=graphic1; // The graphic of the process is defined.

    LOOP
        x=mouse.x;
        y=mouse.y;
        FRAME;
    END
END
{-}

Even if in the previous example, the {graphic1} global variable could have been omitted, having directly assigned the code returned by the {#174,load_map()} function to the {graph} variable with the following statement:

  {graph=load_map("help/help.map");}

the {graphic code} returned by this function are simply integers from {1000}.

{Files FPG}{/}

In order to include a graphic that has been done in the {graphic editor}
in a {file FPG}, it is necessary to {drag the graphic window to the file window} (click on the graphic, move to the file and release). Then, the program will ask for the {graphic code}, so an integer ranging from {1} and {999} must be included here.

Thus, to use the graphic in a program, the {file FPG} that contains it must first be loaded with the {#132,load_fpg()} function, assigning then the {graphic code} to the {graph} variable.

An example is now shown. Before, it is necessary to know that a {brown ball} graphic was stored in the {file HELP.FPG}
indicating the {graphic 100 code}.

{#9999,Example program:}
PROGRAM example_graph;
BEGIN
    load_fpg("help/help.fpg");

    graph=100; // The graphic of the process is defined.

    LOOP
        x=mouse.x;
        y=mouse.y;
        FRAME;
    END
END
{-}

{Several files FPG} can be loaded in a program. In this case, it will be necessary to indicate, besides the {graphic code} in the {graph} local variable, the {file code} returned by the {#132,load_fpg()} function in the {#1131,file} local variable.

It won't be necessary if only one file is loaded, as the {#1131,file} variable equals {0} by default in all the processes and {0} will always be the {first file's code} loaded in the program.

{/}

There are more local variables related to the graphic of a process. The most important ones are mentioned below:

  {graph}  - Graphic codeú
  {#1131,file}   - File codeú
  {#1123,x}, {#1124,y}   - Graphic coordinatesú
  {#1125,z}      - Depth planeú
  {#1129,angle}  - graphic angleú
  {#1128,size}   - graphic sizeú
  {#1127,flags}  - Mirrors and transparenciesú
  {#1130,region} - Display windowú

{/}See: {#1201,Local data}

# -----------------------------------------------------------------------------

{.1127,LOCAL flags}

{flags=0;} // Indicator of mirrors and transparency{/}.

This is a predefined {#1007,LOCAL} variable, which means that every process will have its own value in its {flags} variable.

The {flags} local variable indicates the mirrors and transparencies of the displayed graphic in the processes. The possible values are the following ones:

 {0}-Normal graphic.ú
 {1}-Horizontal mirror.ú
 {2}-Vertical mirror.ú
 {3}-Horizontal and vertical mirror (180ø).ú
 {4}-Transparent graphic.ú
 {5}-Transparent and horizontal mirror.ú
 {6}-Transparent and vertical mirror.ú
 {7}-Transparent, horizontal and vertical mirror.ú

By default, the value of the {flags} variable is {0}. If it is not modified, the graphic will be displayed opaque (not transparent or mirror).

The terms {mirror} and {transparency} are now defined:

- {Horizontal mirror}, the graphic will be horizontally flipped. If it was facing left, it will face now right and vice versa.

- {Vertical mirror}, the graphic will be vertically flipped. If it was facing up, it will face now down and vice versa.

- {Transparency} (or {ghost-layering}), the graphic will be displayed semi-transparent. It will be possible to see what is placed behind the graphic, as if it was a coloured window, unlike the opaque graphics normally displayed.

For instance, the following statement must be used to display a transparent graphic of a process:

  {flags=4;}

{/}

{Note:} The graphic of a process must be indicated assigning a {graphic code} to the {#1126,graph} local variable.

{/}See: {#1201,Local data}

# -----------------------------------------------------------------------------

{.1128,LOCAL size}

{size=100;} // Size (percentage) of the graphic{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {size} variable.

The {size} local variable defines the size in which the graphic of the process must be seen. This size is a percentage related to its original size.

By default, the value of this variable will be equal to {100} (100%) for all the processes, and when the graphic is modified, it will {scale} (reducing or expanding its size) to adjust to the new size.

To {double} the size of the graphic displayed, it will be necessary to specify {200%}. The following statement will be used for this purpose:

  {size=200;}

Therefore, if this value is lesser than {100}, the graphic will be seen smaller; otherwise, it will be seen bigger.

At first, there is no limit for the graphic size, but if the {size} local variable is put at {0} (0%), then the graphic of the process won't be seen.

{/}

{Note:} The graphic of a process must be indicated assigning {a graphic code} to the {#1126,graph} local variable.

{/}See: {#1201,Local data}

# -----------------------------------------------------------------------------

{.1129,LOCAL angle}

{angle=0;} // angle of the process' graphic{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {angle} variable.

The {angle} local variable defines the angle in which the graphic of the process must be seen, indicating an angle with regard to the original graphic in {degree thousandths} (see {#1044,Use of angles in the language}).

By default, the value of this variable will be equal to {0} (0 degrees) for all the processes, but when the graphic is modified, it will {rotate} to adjust to the new angle.

The angle may be defined as any integer within the range ({#1177,min_int} ... {#1178,max_int}).

Some examples of the angles that define certain values in the {angle} local variable are now shown (keep in mind that the angles are expressed in degree {thousandths}):

      ...ú
 { -180000} - {#1044,Angle} to the leftú
 {  -90000} - {#1044,Angle} downwardsú
 {  -45000} - {#1044,Angle} of the diagonal down/rightú
 {       0} - {#1044,Angle} to the rightú
 {  +45000} - {#1044,Angle} of the diagonal right/upú
 {  +90000} - {#1044,Angle} upwardsú
 { +180000} - {#1044,Angle} to the leftú
 { +270000} - {#1044,Angle} downwardsú
      ...ú

{Important:} When the aim is to rotate the graphic of a process,
{it is advisable to paint it orientated to the right}, as it will be displayed like this by default (with the {angle} local variable equal to {0}).

Thus, when another angle is specified, the graphic will appear exactly orientated towards it.

For instance, a graphic that has been drawn to the right can be seen orientated upwards (to the angle of 90 degrees) by indicating the following statement:

  {angle=90000;} // 90 degree thousandths (90 degrees).

If a graphic was painted orientated towards another angle,
(for instance, downwards), it would become orientated downwards by default,
{in the angle 0}, which can provoke confusions when it comes to orientating the graphic towards another angle.

{/}

To make the graphic of a process advance its coordinates ({#1123,x}, {#1124,y}) towards its angle (the one specified {angle} in the local variable of the process) a specific distance, the {#101,advance()} function can be used.

{/}

{Note:} The graphic of a process must be indicated assigning a {graphic code} to the {#1126,graph} local variable.

{/}See: {#1201,Local data} - {#1044,Use of angles in the language}

# -----------------------------------------------------------------------------

{.1130,LOCAL region}

{region=0;} // Screen region assigned to the process{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have it own value in its {region} variable.

The {region} local variable defines the zone of the screen in which the graphic of the process must be visible, indicating the {number of region}.

A region is a rectangular zone of the screen, such as a window,
associated to a number.

By default, this variable will be equal to {0} in all the processes, making reference to {region number 0} that is the {entire screen}.

By default the graphics of the process will be visible
in the whole screen (at any point of the screen in which they are placed).

At the beginning, only {region number 0} is defined.
To define new screen regions, it is necessary to use the {#106,define_region()} function.

{/}

For instance, for the graphic of a process  to be visible only inside a 100 by 100 pixel box placed in the upper left corner of the screen (at the coordinates 0, 0), first the new region should be defined in the following way, supposing that region number {1} is defined:

  {define_region(1, 0, 0, 100, 100);}

and then, the number of region ({1}) should be assigned to the {region} local variable of the process with the following statement:

  {region=1;}

The regions may be redefined at any moment inside a program.

{/}

{Note:} The graphic of a process must be indicated assigning a {graphic code} to the {#1126,graph} local variable.

{/}See: {#1201,Local data} - {#106,define_region()}

# -----------------------------------------------------------------------------

{.1131,LOCAL file}

{file=0;} // File code of the process' graphic{/}.

This is a predefined {#1007,LOCAL} variable, which means that every process will have its own value in its {file} variable.

In the case that several graphics files {files FPG} have been loaded in a program, the {file} local variable indicates which file contains the graphic that the process is using.

The graphic of a process must be indicated by assigning a {graphic's code} to the {#1126,graph} local variable.

If just one file has been loaded in the program, it won't be necessary
to assign any value to {file}, as the {code of the first loaded file}
will equal {0} and this is the value of the variable by default.

If the graphic has been loaded with the {#174,load_map()} or {#174,load_pcx()} function, it won't be necessary to assign any value to {file} either, as the graphics loaded with this function are used as if they belonged to file number {0}
(to the first one that is loaded in the program).

When more than a file is loaded, it is necessary to indicate in each process
in which one its graphic is stored. It is done by assigning
the {file code} returned by the {#132,load_fpg()} function
(on loading this {file FPG}) to the {file} local variable.

{Note:} Normally, if several files are sequentially loaded in a program,
the first one will have the code {0}, the second, the code {1}, the third, the code {2} and so on.

{/}

In general, if several files are used, it is a good practice to have the same number of global variables (named, for instance, {file1}, {file2}, ...) containing the code of each of the files, to use them in the processes when it comes to defining
its {file} variable (the {file FPG} that must be used).

The variables would be defined inside the section {#1006,GLOBAL} in the following way:

  {GLOBAL}ú
      {file1;} // First file's codeú
      {file2;} // Second file's codeú
      ...

Next, these variables would be assigned the {file codes}
on loading them with the {#132,load_fpg()} function in the following way (supposing that the names of the files is {name1.fpg},
{name2.fpg}, etc.):

  {file1=load_fpg("name1.fpg");} // Files loadingú
  {file2=load_fpg("name2.fpg");}ú
  ...

These files are generally loaded at the beginning of the program. Later, the used file would only have to be defined inside each process with the following statement (supposing that the process uses graphics stored in the file {name1.fpg}):

  {file=file1;} // The first file is usedú

{/}

{Note:} Keep in mind that defining the {file} local variable is futile,
unless a {graphic's code} is assigned to the {#1126,graph} local variable.

{/}See: {#1201,Local data}

# -----------------------------------------------------------------------------

{.1132,LOCAL xgraph}

{xgraph=0;} // OFFSET of the process' graphic table{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {xgraph} variable.

This is an advanced level variable. Thus, its use requires certain experience.

The {xgraph} local variable ({extended graphic}) allows us to use {multiple graphics}. This variable is used to define the graphic of a process as a {graphics set} among which it is necessary to see {the most appropriate with the process' angle} (specified in the {#1129,angle} local variable).

If the {xgraph} variable is defined, the {#1126,graph} local variable which normally defines the graphic of the process {will be ignored} and one graphic or another will be used depending on the {#1129,angle} variable.

Therefore, on changing the process' angle {the graphic of the process won't appear rotated}, but it will use this angle to select the process' graphic (inside the defined set).

By default the {xgraph} variable will equal {0} in all the processes,
which indicates that they are not going to use {multiple graphics}.

{/}

The utility of the multiple graphics lies on the possibility of creating games in {perspective}, where the change of an angle in the process doesn't implied
a rotation of its graphic, but the replacement of the graphic by another one painted in a different {perspective} (painted with another angle inside that perspective).

{How to use the multiple graphics.}{/}

1 - First, the different pictures that are going to represent the process' graphic have to be painted with different angles in perspective. The latter will be a finite number of graphic's views, such as {4}, {8}, {12}, etc., (or any other integer bigger than {1}).

Take into account that if 4 views are defined, a different view will be defined every 90 degrees, if 8 views are defined, every 45 degrees, etc.

2 - It is necessary to put these graphics in order according to their angles. First, the graphic corresponding with angle 0 (towards the right) and then, the rest in a clockwise direction.

3 - A table, generally {#1006,GLOBAL}, must be created and initialised with the following values:

  {Number of graphic's views},ú
  {Graphic's code for }angle {0 (first view)},ú
  {Code of the following angle (second view)},ú
  ...

{Note:} This table must contain simple data (of type {#1402,INT}, 32-bit whole numbers with sign).


The name given to this table makes no difference. For instance,
if a multiple graphic is defined with 4 views, which must be the graphics with the codes 10, 11, 12, and 13, the definition of the table could be as follows:

  {GLOBAL}ú
      {table_graphic1[]=4, 10, 11, 12, 13;}ú
      ....

4 - Finally, the offset of this table must be assigned inside the computer's memory to the {xgraph} local variable of the process, which is done with the following statement (inside the process in question):

  {xgraph=OFFSET table_graphic1;}

The {#1085,OFFSET} operator is used to obtain the offset of a program's variable in the memory.

{/}

Once the {multiple graphic} has been defined, in each frame of the game the system will use the graphic corresponding with the angle {closest to the process' angle} (the one indicated in its {#1129,angle} variable).

The {xgraph} variable must be put at {0} again in order to disable the {multiple graphic} system in a process,

{Important:} If any graphic's code is put with a {negative sign} inside the table that defines the set of graphics, then this graphic will appear {horizontally flipped}. If the graphic was facing right, it will appear facing left, and vice versa.

{/}

{Note:} The multiple graphic system is normally used in {mode 7 windows}, as in the folded three-dimensional plane the graphics must be seen in a different way, according to the angle from which they are observed.

For further information about this technique, see the {#162,start_mode7()} function used to activate a {mode 7 window} in the program.

{/}See: {#1201,Local data}

# -----------------------------------------------------------------------------

{.1133,LOCAL height}

{height=0;} // Graphic's height (in mode 7){/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {height} variable.

The local {height} variable is {exclusively} used in the processes that belong to
{mode 7 windows}. That is to say, processes that have their coordinates' system inside a three-dimensional window (its local variable {#1122,ctype}={#1169,c_m7}).

It is used to define the height at which the graphics of the processes must be placed above the three-dimensional plane. The {#1125,local z} variable is not used for this purpose, as it is used to define the depth plane of the graphics (even if it is now useful only for processes placed at the same coordinates).

The height of the process can be defined as any integer within the ({#1177,min_int} ... {#1178,max_int}) range, even if positive numbers are normally used, as the {height} of the bottom is {0} and processes are placed above it.

By default, the value of the {height} variable is {0} for all the processes, which means that if another value is not specified, the graphics of the processes will appear just above the bottom of the {mode 7} (above the plane three-dimensionally folded).

The {graphic's base} will first be placed in the indicated {height} of the process, unless {#1136,control point} number {0} is defined. In this case, this point will be placed in that height.

{Note:} For further information about the {mode 7 windows} and how to place graphics inside these windows, see the help about the {#162,start_mode7()} function, which is used to activate them in the program.

{/}

This variable can be used for any other purpose in the non {mode 7} processes, as the system will completely ignore it.

{/}See: {#1201,Local data} - {#162,start_mode7()}

# -----------------------------------------------------------------------------

{.1134,LOCAL cnumber}

{cnumber=0;} // Number of scroll or mode 7 windows{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {cnumber} variable.

The local {cnumber} variable is {exclusively} used when, in a game, several {scroll windows} or several {mode 7 windows} simultaneously appear on screen.

- For further information about the {scroll windows}, see the help about the {#163,start_scroll()} function, which is used to activate them in the program.

- For further information about the {mode 7 windows}, see the help about the {#162,start_mode7()} function, which is used to activate them in the program.

{/}

The {cnumber} utility lies on indicating {in which of these windows the graphic of the process must be seen}. Obviously, this variable must be defined only in processes visible inside the {scroll windows} or the {mode 7 windows}. This variable is useless for the rest of the processes (screen processes or processes with no graphics).

{If the process must be seen in all the windows}, then it won't be necessary to modify this variable, as the value of {cnumber} ({0}) by default precisely indicates so.

Up to {10} windows of both types may be activated, numbered from {0} to {9}. There are ten predefined constants used to define the value of {cnumber}. These are {#1175,c_0, c_1, c_2, ..., c_9} and directly correspond with the {10} possible windows of these types.

{cnumber} must be assigned {the addition of the constants} corresponding with the {windows in which the process must be visible}.

For instance, if there are {4 scroll windows} numbered {0}, {1}, {2} and {3} in a program, and the aim is to define that a specific process must be only visible in windows {0} and {2}, the following statement must be used:

  {cnumber=c_0+c_2;}

The value of {cnumber} can be changed during the process execution if necessary.

{/}

{Note:} Keep in mind that for the graphic of the process to be seen in all the windows, it is not necessary to do anything, as it is the option by default.

{/}See: {#1201,Local data} - {#1175,c_0...c_9}

# -----------------------------------------------------------------------------

{.1135,LOCAL resolution}

{resolution=0;} // Resolution of the process coordinates{/}.

This is a predefined {#1007,LOCAL} variable, which means that each process will have its own value in its {resolution} variable.

Normally, the coordinates of a process (indicated in the {#1123,x} and {#1124,y} local variables) are defined in screen pixels.

The {resolution} local variable must be used when the aim is to define the coordinates in {drives smaller} than the pixel.

That is to say, this variable indicates the precision of the process' coordinates.

By default, the variable will equal {0} and the coordinates will be specified in pixels.

The greater the value of {#1135,resolution} is, the smaller (and more accurate)
the drive in which the coordinates are interpreted will be. Some examples are show below:

{resolution=1;} - The coordinates are specified in pixels (similar to {resolution=0}, which is the value by default).

{resolution=10;} - They are specified in tenths of a pixel.

{resolution=100;} - They are specified in hundredths of pixels.

{resolution=2;} - They are specified in half pixels.

...

For instance, a process located at {160}, {100} with {resolution} equal to
{0} (or {1}), will be in the same position as a process located at
{1600}, {1000} and with {resolution} equal to {10}.

The value of {resolution} is normally defined as a {positive integer multiple of 10} (10, 100, 1000, ...).

{/}

In short, when the value of {resolution} is defined, the processes' manager of 
DIV Games Studio {will divide} the coordinates of the processes
between {resolution} when it comes to painting their graphics on screen.

{/}

{Important:} Much care must be taken when, in a program,
there are several processes with different resolutions of coordinates,
as some functions, such as {#117,get_dist()} (used to obtain the distance between two processes), will return {incorrect results}
when two processes using different resolution of coordinates are accessed.

It is normally advisable that all the processes active in the game,
at least all that interact (that are detected, modified or that can be collide) use the same resolution.

{/}See: {#1201,Local data}

# -----------------------------------------------------------------------------

{.1136,Control points.}

{+230,0}The {control points} are defined inside the {graphic editor}
with the bar of control points, indicated with this icon.{-}{+231,1}{-}{/}

In order to access the {graphic editor}, suffice will be to "{double-click}" with the left mouse button on a graphic inside the environment (on a map window).

The {control points} are simply points that can be placed inside a graphic for different purposes.

The {bar of control points} allows us to position up to {1000} different points inside a graphic. Each of them will be identified by its number (from {0} to {999}).

In order to position one of these points, suffice will be to select the {number of
point} with the {left arrow} and {right arrow} icons and then, to click on the graphic.

In order to {delete} (unselect) a control point, it is necessary to click on the same  graphic a second time.

{/}

The only {control point} used by the system is control point number {0} (the first one). This point defines which is the {virtual centre of the graphic} and has many applications inside the language.

When {control point number 0} is not defined, the system
will work as if the graphic's virtual centre was its {real centre} (a point located at half the width and height of the graphic).

{/}

{Note:} Once the control points have been defined, for them to have effect in a
program, it is necessary to save the {file MAP} or include the graphic again in the {file FPG} by dragging the former to the latter (depending on which one of both is loaded in the program).

# -----------------------------------------------------------------------------

{.1150,Videomodes}

Constants: {m320x200} ... {m1024x768}
{/}

These constants are used to indicate the videomode in the {#157,set_mode()} function. The whole list of constants is the following one:

    m320x200ú
    m320x240ú
    m320x400ú
    m360x240ú
    m360x360ú
    m376x282ú
    m640x400ú
    m640x480ú
    m800x600ú
    m1024x768ú

Each constant indicates the videomode in the following way: first,
the letter {m} and then, the horizontal and vertical resolution of the mode, separated by an {x}.

The values defined for these constants are the following ones.

    m320x200  = 320200ú
    m320x240  = 320240ú
    m320x400  = 320400ú
    m360x240  = 360240ú
    m360x360  = 360360ú
    m376x282  = 376282ú
    m640x400  = 640400ú
    m640x480  = 640480ú
    m800x600  = 800600ú
    m1024x768 = 1024768ú

{/}

{Note:} Besides these standard video modes, the global structure
{#1415,video_modes} contains a list of all modes compatible with the VESA standard
situated in the system's video adaptador.


{/}See: {#1202,Constants} - {#157,set_mode()} - {#1415,video_modes}

# -----------------------------------------------------------------------------

{.1151,true}

Constant: {true}
{/}

This constant is used to indicate {true} values, to initialise logical variables or
to define logical parameters. That is to say, it must be evaluated as a condition.

Its value is {1} and, as in the language all the {odd} numbers are interpreted as {true}, this constant will be evaluated as a condition that is always complied ({true}).

{/}

The {#1152,false} constant is opposite to this one, and it is used to indicate logical {false} values.

{/}See: {#1202,Constants} - {#1152,false}

# -----------------------------------------------------------------------------

{.1152,false}

Constant: {false}
{/}

This constant is used to indicate {false} values, to initialise logical variables or
to define logical parameters. That is to say, it must be evaluated as a condition.

Its value is {0} and, as in the language all the {even} numbers are interpreted as {false}, this constant will be evaluated as a condition that is never complied ({false}).

{/}

The {#1151,true} constant is opposite to this one, and it is used to indicate logical {true} values.

{/}See: {#1202,Constants} - {#1151,true}

# -----------------------------------------------------------------------------

{.1153,s_kill}

Constant: {s_kill}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {0}.

This signal transmits the imperative order {kill}
to the processes. It is used to eliminate processes in the program
(to make certain objects of the game disappear).

That is to say, on sending a signal {s_kill} to a process, the latter will be eliminated and will not appear any longer in the following frames of the game.

The constant {#1157,s_kill_tree} is directly linked to this constant, with the proviso that, on sending this signal, the former will eliminate the indicated process and its {sons}, which are the processes created by it.

The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

    {s_kill}ú
    {#1154,s_wakeup}ú
    {#1155,s_sleep}ú
    {#1156,s_freeze}ú
    {#1157,s_kill_tree}ú
    {#1158,s_wakeup_tree}ú
    {#1159,s_sleep_tree}ú
    {#1160,s_freeze_tree}ú

{/}See: {#1202,Constants} - {#158,signal()} - {#1157,s_kill_tree}

# -----------------------------------------------------------------------------

{.1154,s_wakeup}

Constant: {s_wakeup}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {1}.

This signal transmits the imperative order {wakeup}
to the processes. It is used to restore the processes that have been made dormant (with the signal {#1155,s_sleep}), or frozen (with the signal {#1156,s_freeze}) to their normal state.

That is to say, on sending a signal {s_wakeup} to a process, the latter will be reactivated in the following frames of the game (it will be seen and processed again).

The constant {#1158,s_wakeup_tree} is directly linked to this constant, with the proviso that, on sending this signal, the former will wake up the indicated process and its {sons}, which are the processes created by it.

The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

{#1153,s_kill}ú
    {s_wakeup}ú
    {#1155,s_sleep}ú
    {#1156,s_freeze}ú
    {#1157,s_kill_tree}ú
    {#1158,s_wakeup_tree}ú
    {#1159,s_sleep_tree}ú
    {#1160,s_freeze_tree}ú


{/}See: {#1202,Constants} - {#158,signal()} - {#1158,s_wakeup_tree}

# -----------------------------------------------------------------------------

{.1155,s_sleep}

Constant: {s_sleep}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {2}.

This signal transmits the imperative order {sleep} to the processes. It is used to make a process dormant. An asleep process will not appear in the following frames of the game, but it won't be eliminated, as it happens with the signal 
{#1153,s_kill}. Indeed, this kind of process may {wake up} at any moment with a signal {#1154,s_wakeup}.

That is to say, on sending a signal {s_sleep } to a process, the latter will not appear in the following frames of the game (until it is awaken or eliminated).

The constant {#1159,s_sleep_tree} is directly linked to this constant, with the proviso that, on sending this signal, the former will make dormant the indicated process and its {sons}, which are the processes created by it.

The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

    {#1153,s_kill}ú
    {#1154,s_wakeup}ú
    {s_sleep}ú
    {#1156,s_freeze}ú
    {#1157,s_kill_tree}ú
    {#1158,s_wakeup_tree}ú
    {#1159,s_sleep_tree}ú
    {#1160,s_freeze_tree}ú

{/}See: {#1202,Constants} - {#158,signal()} - {#1159,s_sleep_tree}

# -----------------------------------------------------------------------------

{.1156,s_freeze}

Constant: {s_freeze}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {3}.

This signal transmits the imperative order {freeze}
to the processes. It is used to freeze (immobilise) a process. A frozen process will continue to appear in the following frames of the game, but it won't be processed, so it will remain immobile. This process can be {reactivated} at any moment if a signal {#1154,s_wakeup} is sent to it.

That is to say, on sending a signal {s_freeze} to a process, the latter will stop processing (stop interpreting its statements) in the following frames of the game (until it is activated or eliminated with {#1153,s_kill}).

The constant {#1160,s_freeze_tree} is directly linked to this constant, with the proviso that, on sending this signal, the indicated process as well as its {sons} (which are the processes created by it) will be frozen.

The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

    {#1153,s_kill}ú
    {#1154,s_wakeup}ú
    {#1155,s_sleep}ú
    {s_freeze}ú
    {#1157,s_kill_tree}ú
    {#1158,s_wakeup_tree}ú
    {#1159,s_sleep_tree}ú
    {#1160,s_freeze_tree}ú

{/}See: {#1202,Constants} - {#158,signal()} - {#1160,s_freeze_tree}

# -----------------------------------------------------------------------------

{.1157,s_kill_tree}

Constant: {s_kill_tree}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {100}.

This signal is used to eliminate a process and all the process created by it, by sending the imperative order {kill} to them. This is a version of the signal {#1153,s_kill}, which eliminates a process, but not the processes that it had created.

That is to say, the signal {s_kill_tree} will eliminate the process and all its descendants. Thus, none of them will appear any longer in the following frames of the game.

The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

    {#1153,s_kill}ú
    {#1154,s_wakeup}ú
    {#1155,s_sleep}ú
    {#1156,s_freeze}ú
    {s_kill_tree}ú
    {#1158,s_wakeup_tree}ú
    {#1159,s_sleep_tree}ú
    {#1160,s_freeze_tree}ú

{/}See: {#1202,Constants} - {#158,signal()} - {#1153,s_kill}

# -----------------------------------------------------------------------------

{.1158,s_wakeup_tree}

Constant: {s_wakeup_tree}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {101}.

This signal is used to {wake up} a process and all the processes created by it, by sending the imperative order {wakeup} to them. This is a version of the signal {#1154,s_wakeup}, which wakes a process up, but not the processes that it had created.

That is to say, the signal {s_wakeup_tree} will {wake up} the process and all its descendants. Thus, all these processes will return to their normal state in the following frames of the game.

Processes that have been {made dormant} with the signal {#1159,s_sleep_tree} or {frozen} with the signal {#1160,s_freeze_tree} can be woken up (reactivated).

The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

    {#1153,s_kill}ú
    {#1154,s_wakeup}ú
    {#1155,s_sleep}ú
    {#1156,s_freeze}ú
    {#1157,s_kill_tree}ú
    {s_wakeup_tree}ú
    {#1159,s_sleep_tree}ú
    {#1160,s_freeze_tree}ú

{/}See: {#1202,Constants} - {#158,signal()} - {#1154,s_wakeup}

# -----------------------------------------------------------------------------

{.1159,s_sleep_tree}

Constant: {s_sleep_tree}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {102}.

This signal is used to {make} a process and all the processes created by it {dormant}, by sending the imperative order {sleep} to them. This is a version of the signal {#1155,s_sleep}, which makes a process dormant, but not the processes that it had created.

That is to say, the signal {s_sleep_tree} will make the process and all its descendants dormant. Thus, all these processes will disappear in the following frames of the game (but they won't be eliminated).

These {asleep} processes can be woken up (reactivated) with the signal {#1158,s_wakeup_tree}.

The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

    {#1153,s_kill}ú
    {#1154,s_wakeup}ú
    {#1155,s_sleep}ú
    {#1156,s_freeze}ú
    {#1157,s_kill_tree}ú
    {#1158,s_wakeup_tree}ú
    {s_sleep_tree}ú
    {#1160,s_freeze_tree}ú

{/}See: {#1202,Constants} - {#158,signal()} - {#1155,s_sleep}

# -----------------------------------------------------------------------------

{.1160,s_freeze_tree}

Constant: {s_freeze_tree}
{/}

This constant is used as a parameter of the {#158,signal()} function (to send signals to the processes).
Its value is {103}.

This signal is used to freeze (immobilise) a process and all the processes created by it, by sending the imperative order {freeze} to them. This is a version of the signal {#1156,s_freeze}, which freezes a process, but not the processes that it had created.

That is to say, the signal {s_freeze_tree} will {freeze} the process and all its descendants. Thus, all these processes will stop processing in the following frames of the game (they will remain immobile, as they won't execute their statements).

These {frozen} processes can be unfrozen (reactivated) with the signal {#1158,s_wakeup_tree}.
.
The whole list of the constants used as signals that can be sent to the different processes of a program is the following one:

    {#1153,s_kill}ú
    {#1154,s_wakeup}ú
    {#1155,s_sleep}ú
    {#1156,s_freeze}ú
    {#1157,s_kill_tree}ú
    {#1158,s_wakeup_tree}ú
    {#1159,s_sleep_tree}ú
    {s_freeze_tree}ú

{/}See: {#1202,Constants} - {#158,signal()} - {#1156,s_freeze}

# -----------------------------------------------------------------------------

{.1161,all_text}

Constant: {all_text}
{/}

This constant is used as a parameter of the {#107,delete_text()} function,
to delete {all} the texts displayed in the program with the {#171,write()} and {#172,write_int()} functions.

That is to say, the following statement must be executed in order to make disappear all the texts displayed on screen:

  {delete_text(all_text);}

The value assigned to this constant is {0}.

{/}See: {#1202,Constants} - {#107,delete_text()}

# -----------------------------------------------------------------------------

{.1162,all_sound}

Constant: {all_sound}
{/}

This constant is used as a parameter of the {#167,stop_sound()} function,
to stop {all} the sound effects previously activated with the {#159,sound()} function.

That is to say, the following statement must be executed in order to stop all the sound channels, active at a specific moment:

  {stop_sound(all_sound);}

The value assigned to this constant is{ -1}.

{/}See: {#1202,Constants} - {#167,stop_sound()} - {#159,sound()}

# -----------------------------------------------------------------------------

{.1163,g_wide}

Constant: {g_wide}
{/}

This constant is used as a parameter of the {#126,graphic_info()} function,
to ask for information about the {width} (in pixels) of a specific graphic.
Its value is {0}.

The constants that can be used as parameter of this function are the following ones:

    {g_wide}ú
    {#1164,g_height}ú
    {#1165,g_x_centre}ú
    {#1166,g_y_centre}ú

{/}See: {#1202,Constants} - {#126,graphic_info()}

# -----------------------------------------------------------------------------

{.1164,g_height}

Constant: {g_height}
{/}

This constant is used as a parameter of the {#126,graphic_info()} function,
to ask for information about the {height } (in pixels) of a specific graphic.
Its value is {1}.

The constants that can be used as parameter of this function are the following ones:

    {#1163,g_wide}ú
    {g_height}ú
    {#1165,g_x_centre}ú
    {#1166,g_y_centre}ú

{/}See: {#1202,Constants} - {#126,graphic_info()}

# -----------------------------------------------------------------------------

{.1165,g_x_centre}

Constant: {g_x_centre}
{/}

This constant is used as a parameter of the {#126,graphic_info()} function,
to ask for information about the {horizontal centre} of a specific graphic.
Its value is {2}.

The {horizontal centre} of a graphic will be half the width (in pixels),
if  {#1136,control point} number {0} (graphic centre) has not been defined in the painting tool.

The constants that can be used as parameter of this function are the following ones:

    {#1163,g_wide}ú
    {#1164,g_height}ú
    {g_x_centre}ú
    {#1166,g_y_centre}ú

{/}See: {#1202,Constants} - {#126,graphic_info()}

# -----------------------------------------------------------------------------

{.1166,g_y_centre}

Constant: {g_y_centre}
{/}

This constant is used as a parameter of the {#126,graphic_info()} function,
to ask for information about the {vertical centre} of a specific graphic.
Its value is {3}.

The {vertical centre} of a graphic will be half the height (in pixels),
if the {#1136,control point} number {0} (graphic centre) has not been defined in the painting tool.

The constants that can be used as parameter of this function are the following ones:

    {#1163,g_wide}ú
    {#1164,g_height}ú
    {#1165,g_x_centre}ú
    {g_y_centre}ú

{/}See: {#1202,Constants} - {#126,graphic_info()}

# -----------------------------------------------------------------------------

{.1167,c_screen}

Constant: {c_screen}
{/}

This constant is used to be assigned to the predefined {#1122,ctype} local variable used to define the type of coordinates that a process will have. Its value is {0}.

{This is the value by default of} {#1122,ctype}, used for the coordinates of the graphic of the process to be interpreted as if they were referred to the screen. The (0,0) coordinate is the upper left corner.

There are other constants used for other systems of coordinates.
The whole list is the following one:

    {c_screen} - Screen coordinatesú
    {#1168,c_scroll} - Scroll coordinatesú
    {#1169,c_m7}     - Mode 7 coordinatesú
    {#1412,c_m8}     - coordinates of mode 8ú


{/}See: {#1202,Constants} - {#1122,ctype}

# -----------------------------------------------------------------------------

{.1168,c_scroll}

Constant: {c_scroll}
{/}

This constant is used to be assigned to the predefined {#1122,ctype} local variable used to define the type of coordinates that a process will have. Its value is {1}.

This is the value assigned to {#1122,ctype}, used for the coordinates of the graphic of the process to be interpreted as if they were referred to a scroll window, to coordinates with respect to the foreground's graphic.

For further information about the {scroll windows}, it is possible to access the {#163,start_scroll()} function used to activate them.

There are other constants used for other systems of coordinates.
The whole list is the following one:

    {#1167,c_screen} - Screen coordinatesú
    {c_scroll} - Scroll coordinatesú
    {#1169,c_m7}     - Mode 7 coordinatesú
    {#1412,c_m8}     - coordinates of mode 8ú

{/}See: {#1202,Constants} - {#1122,ctype} - {#163,start_scroll()}

# -----------------------------------------------------------------------------

{.1169,c_m7}

Constant: {c_m7}
{/}

This constant is used to be assigned to the predefined {#1122,ctype} local variable used to define the type of coordinates that a process will have. Its value is {2}.

This is the value assigned to {#1122,ctype}, used for the coordinates of the graphic of the process to be interpreted as if they were referred to a mode 7 window, three-dimensionally folded in that window.

For further information about the {mode 7 windows}, it is possible to access the {#162,start_mode7()} function used to activate them.

There are other constants used for other systems of coordinates.
The whole list is the following one:

    {#1167,c_screen} - Screen coordinatesú
    {#1168,c_scroll} - Scroll coordinatesú
    {c_m7}     - Mode 7 coordinatesú
    {#1412,c_m8}     - coordinates of mode 8ú

{/}See: {#1202,Constants} - {#1122,ctype} - {#162,start_mode7()}

# -----------------------------------------------------------------------------

{.1170,partial_dump}

Constant: {partial_dump}
{/}

This  constant is used to be assigned to the predefined
{#1114,dump_type} global variable used to define the type of dump that will be performed on screen. Its value is {0}.

The following statement is used:

  {dump_type=partial_dump;}

This statement indicates to the manager of processes of DIV Games that the following dumps must be {partial}.

{Dump} is the name given to the system of sending the game frames to the monitor (to the video memory of the graphics card).

There are two types of dumps:

{Partial}: Only the graphics that are updated and that have varied with regard to the previous frame will be dumped on screen. It is advisable to activate this dump in order {to gain speed} when programming a game (or a section of it) without a scroll or mode 7 window occupying the whole screen. That is to say, either when the game shows graphics movements against a fixed  background or when the active scroll or mode 7 windows are smaller that the screen.

{Complete}: All the screen will be dumped, irrespective of whether the graphics have changed or not. This is the dump by default and it is {slower that the partial dump}. However, the complete dump must be used when the game has a scroll or mode 7 window occupying the whole screen.

{/}

The other constant used to designate the type of dump is {#1171,complete_dump} which, unlike this one, defines a {complete} dump.

{/}See: {#1202,Constants} - {#1114,dump_type} - {#1171,complete_dump}

# -----------------------------------------------------------------------------

{.1171,complete_dump}

Constant: {complete_dump}
{/}

This  constant is used to be assigned to the predefined
{#1114,dump_type} global variable used to define the type of dump that will be performed on screen. Its value is {1}.

This is the {value by default} of the {#1114,dump_type} variable.
To establish this value, it is necessary to use the following statement:

  {dump_type=complete_dump;}

This statement indicates that the following dumps must be {complete} to the manager of processes of DIV Games.

{Dump} is the name given to the system of sending the game frames to the monitor (to the video memory of the graphics card).

There are two types of dumps:

{Partial}: Only the graphics that are updated and that have varied with regard to the previous frame will be dumped on screen. It is advisable to activate this dump in order {to gain speed} when programming a game (or a section of it) without a scroll or mode 7 window occupying the whole screen. That is to say, either when the game shows graphics movements on a fixed  background or when the active scroll or mode 7 windows are smaller that the screen.

{Complete}: All the screen will be dumped, irrespective of whether the graphics have changed or not. This is the dump by default and it is {slower that the partial dump}. However, the complete dump must be used when the game has a scroll or mode 7 window occupying the whole screen.

{/}

The other constant used to designate the type of dump is {#1170,partial_dump} which, unlike this one, defines a {partial} dump.

{/}See: {#1202,Constants} - {#1114,dump_type} - {#1170,partial_dump}

# -----------------------------------------------------------------------------

{.1172,no_restore}

Constant: {no_restore}
{/}

This constant is used to be assigned to the predefined {#1113,restore_type} global variable used to define the type of restoration that must be applied to the screen background after each game frame.
Its value is{ -1}.

The name {background restoration} deals with the operation of restoring the screen areas in which graphics have been painted or texts have been written in the previous frame. That is to say, to delete both the painted graphics and the written texts.

The following statement must be used to establish this value:

  {restore_type=no_restore;}

This statement indicates to the manager of processes of DIV Games
Studio that, after the following game frames {it is not necessary
to restore the screen background}.

If the background is not restored,{speed will be gained} in the execution of the game (that will go faster in slow computers). But this mode of restoration ({no_restore}) can only be applied in games or in their sections in which {there is a scroll or mode 7 window occupying the whole screen}.

The three types of restoration that can be applied correspond with the following three constants:

{no_restore}       - The fastest; it doesn't restore the backgroundú
{#1173,partial_restore}  - Average, partial restorationsú
{#1174,complete_restore} - The slowest one, complete restorationú

{/}See: {#1202,Constants} - {#1113,restore_type}

# -----------------------------------------------------------------------------

{.1173,partial_restore}

Constant: {partial_restore}
{/}

This constant is used to be assigned to the predefined {#1113,restore_type} global variable used to define the type of restoration that must be applied to the screen background after each game frame.
Its value is{ 0}.

The name {background restoration} deals with the operation of restoring the screen areas in which graphics have been painted or texts have been written in the previous frame. That is to say, to delete both the painted graphics and the written texts. 

The following statement must be used to establish this value:

  {restore_type=partial_restore;}

This statement indicates to the manager of processes of DIV Games
Studio that, after the following game frames {only the screen areas in which graphics have been painted or texts have been written must be restored}.

This mode of restoration ({partial_restore}) is faster than a complete restoration (option by default), but it must only be applied in games, or in their sections, in which {there ISN'T a scroll or mode 7 window occupying the whole screen}.

The three types of restoration that can be applied correspond with the following three constants:

{#1172,no_restore}       - The fastest; it doesn't restore the backgroundú
{partial_restore}  - Average, partial restorationsú
{#1174,complete_restore} - The slowest one, complete restorationú

{/}See: {#1202,Constants} - {#1113,restore_type}

# -----------------------------------------------------------------------------

{.1174,complete_restore}

Constant: {complete_restore}
{/}

This constant is used to be assigned to the predefined {#1113,restore_type} global variable used to define the type of restoration that must be applied to the screen background after each game frame.
Its value is{ 1}.

The name {background restoration} deals with the operation of restoring the screen areas in which graphics have been painted or texts have been written in the previous frame. That is to say, to delete both the painted graphics and the written texts. 

{This is the value by default of the} {#1113,restore_type} {variable} and,
it is the {slowest} mode of the three available restoration modes.
The following statement must be used to establish this value:

  {restore_type=complete_restore;}

This statement indicates to the manager of processes of DIV Games
Studio that, after the following game's frames {the screen background must completely be restored}.

This mode of restoration ({complete_restore}) is the slowest one (and it is the option by default). Therefore, it can be changed by another one in order {to gain speed} in the execution of the game (so it will go faster in slow computers). 

As a matter of fact, this mode of restoration is only interesting for games (or for their sections) that {DON'T have} a scroll or mode 7 window occupying the whole screen, but that have a great number of graphics moving through the screen.

The three types of restoration that can be applied correspond with the following three constants:

{#1172,no_restore}       - The fastest; it doesn't restore the backgroundú
{#1173,partial_restore}  - Average, partial restorationsú
{complete_restore} - The slowest one, complete restorationú

{/}See: {#1202,Constants} - {#1113,restore_type}

# -----------------------------------------------------------------------------

{.1175,Numbers of window}

Constants: {c_0} ... {c_9}
{/}

These constants are used to be assigned to the predefined {#1134,cnumber} local variable that is used to define the scroll or mode 7 windows in which the graphic of a process must appear.

{This will only be necessary when several scroll or mode 7 windows have been activated, and it ISN'T aimed to display the graphic of the process in all of them.}

Up to 10 windows of these types may be defined, numbered from {0} to {9}, and that directly correspond with the constants
{c_0}, {c_1}, {c_2} ... {c_9}.

For the graphic of a process to appear in one of these windows only, the corresponding constant must be assigned to its 
{#1134,cnumber} local variable. For instance, if the aim was for the graphic of a process to appear only in (scroll or mode 7) window number 3, the following statement would be included in its code:

  {cnumber=c_3;}

If the aim for the graphic of a process is to appear in several of these windows, then the constants must be added.
For instance, for a process to appear in the windows 0, 4, and 5, the following assignment will be performed:

  {cnumber=c_0+c_4+c_5;}

For the graphic to appear in all the windows, suffice will be to assign {0} to the {#1134,cnumber} variable. It won't be necessary if this variable has not been modified, as it is its value by default.

The values equivalent to these constants correspond with the following powers of 2:

    {c_0} = 1   scroll / mode-7 number 0ú
    {c_1} = 2   scroll / mode-7 number 1ú
    {c_2} = 4   scroll / mode-7 number 2ú
    {c_3} = 8   scroll / mode-7 number 3ú
    {c_4} = 16  scroll / mode-7 number 4ú
    {c_5} = 32  scroll / mode-7 number 5ú
    {c_6} = 64  scroll / mode-7 number 6ú
    {c_7} = 128 scroll / mode-7 number 7ú
    {c_8} = 256 scroll / mode-7 number 8ú
    {c_9} = 512 scroll / mode-7 number 9ú

{/}See: {#1202,Constants} - {#1134,cnumber}.

# -----------------------------------------------------------------------------

{.1176,Key codes}

Constants: {Key codes}
{/}

These constants are normally used as a parameter of the {#128,key()} function, to indicate which key is the one that the user wishes to know whether it is pressed.

It can also be used to compare the {#1110,scan_code} global variable, that contains the code of the last key that has been pressed, with these values.

The character {_} (underlining) followed by the name of the key, is normally used to designate each constant. For instance, for the [{A}] key, the constant referred to its code will be {_a}.

The whole list of these constants, with their respective values,
is as follows (according to the standard arrangement of the keytable):

{_esc}         = 1   [ESC] or escapeú
{_f1}          = 59  [F1] or function 1ú
{_f2}          = 60  [F2] or function 2ú
{_f3}          = 61  [F3] or function 3ú
{_f4}          = 62  [F4] or function 4ú
{_f5}          = 63  [F5] or function 5ú
{_f6}          = 64  [F6] or function 6ú
{_f7}          = 65  [F7] or function 7ú
{_f8}          = 66  [F8] or function 8ú
{_f9}          = 67  [F9] or function 9ú
{_f10}         = 68  [F10] or function 10ú
{_f11}         = 87  [F11] or function 11ú
{_f12}         = 88  [F12] or function 12 (DEBUGGER)ú
{_prn_scr}     = 55  [PRINT SCREEN]ú
{_scroll_lock} = 70  [SCROLL LOCK]ú

{_wave}        = 41  [§] or [¦] keyú
{_1}           = 2   Number "1" keyú
{_2}           = 3   Number "2" keyú
{_3}           = 4   Number "3" keyú
{_4}           = 5   Number "4" keyú
{_5}           = 6   Number "5" keyú
{_6}           = 7   Number "6" keyú
{_7}           = 8   Number "7" keyú
{_8}           = 9   Number "8" keyú
{_9}           = 10  Number "9" keyú
{_0}           = 11  Number "0" keyú
{_minus}       = 12  Symbol "?" keyú
{_plus}        = 13  Symbol "¨" keyú

{_backspace}   = 14  Delete ( <- ) keyú
{_tab}         = 15  Tabulator [TAB] keyú
{_q}           = 16  Letter "Q" keyú
{_w}           = 17  Letter "W" keyú
{_e}           = 18  Letter "E" keyú
{_r}           = 19  Letter "R" keyú
{_t}           = 20  Letter "T" keyú
{_y}           = 21  Letter "Y" keyú
{_u}           = 22  Letter "U" keyú
{_i}           = 23  Letter "I" keyú
{_o}           = 24  Letter "O" keyú
{_p}           = 25  Letter "P" keyú
{_l_brachet}   = 26  Key [^] or [']ú
{_r_brachet}   = 27  Key [*] or [+]ú
{_enter}       = 28  [ENTER] (Enter or Return)ú

{_caps_lock}   = 58  [CAPS LOCK] or capitals lockú
{_a}           = 30  Letter "A" keyú
{_s}           = 31  Letter "S" keyú
{_d}           = 32  Letter "D" keyú
{_f}           = 33  Letter "F" keyú
{_g}           = 34  Letter "G" keyú
{_h}           = 35  Letter "H" keyú
{_j}           = 36  Letter "J" keyú
{_k}           = 37  Letter "K" keyú
{_l}           = 38  Letter "L" keyú
{_semicolon}   = 39  Letter "¥" keyú
{_apostrophe}  = 40  [{{}] keyú
{_backslash}   = 43  [{}}] keyú

{_l_shift}     = 42  [SHIFT] or left capitalsú
{_z}           = 44   Letter "Z" keyú
{_x}           = 45  Letter "X" keyú
{_c}           = 46  Letter "C" keyú
{_v}           = 47  Letter "V" keyú
{_b}           = 48  Letter "B" keyú
{_n}           = 49  Letter "N" keyú
{_m}           = 50  Letter "M" keyú
{_comma}       = 51  Key [;] or [,] keyú
{_point}       = 51  [:] or [.] keyú
{_slash}       = 51  [_] or [-] keyú
{_r_shift}     = 54  [SHIFT] or right capitalsú

{_control}     = 29  [CONTROL] keysú
{_alt}         = 56  [ALT] or [ALT GR] keysú
{_space}       = 57  [SPACE] or spacebarú

{_ins}         = 82  [INSERT]ú
{_home}        = 71  [HOME]ú
{_pgup}        = 73  [PGUP] or page upú
{_del}         = 83  [DEL] or deleteú
{_end}         = 79  [END]ú
{_pgdn}        = 81  [PGDN] or page downú

{_up}          = 72  Up cursorú
{_down}        = 80  Down cursorú
{_left}        = 75  Left cursorú
{_right}       = 77  Right cursorú

{_num_lock}    = 69  [NUM LOCK] or numeric lockú
{_c_backslash} = 53  Symbol [/] of the numeric keytableú
{_c_asterisk}  = 55  Symbol [*] of the numeric keytableú
{_c_minus}     = 74  Symbol [-] of the numeric keytableú
{_c_home}      = 71  [HOME] of the numeric keytableú
{_c_up}        = 72  Up cursor of the numeric keytableú
{_c_pgup}      = 73  [PGUP] of the numeric keytableú
{_c_left}      = 75  Left cursor of the numeric keytableú
{_c_centre}    = 76  [5] key of the numeric keytableú
{_c_right}     = 77  Right cursor of the numeric keytableú
{_c_end}       = 79  [END] of the numeric keytableú
{_c_down}      = 80  Down cursor of the numeric keytableú
{_c_pgdn}      = 81  [PG DN] of the numeric keytableú
{_c_ins}       = 82  [INS] of the numeric keytableú
{_c_del}       = 83  [DEL] of the numeric keytableú
{_c_plus}      = 78  Symbol [+] of the numeric keytableú
{_c_enter}     = 28  [ENTER] of the numeric keytableú

It is indifferent to use these constants or the numeric values that they represent. That is to say, it is possible to call the {#128,key()} function, to verify whether the [{A}] key is pressed, such as {key(_a)} or {key(30)} (in the previous list, it is possible to verify that {30} is the numeric value of the constant {_a}).

{/}

{Important:} Some of these codes can vary in certain keytables. In case of doubt it is possible to execute the following sample program, that shows a table on screen, corresponding to the {#128,key()} function (indicating the {codes of the keys that are pressed} at any moment), besides the values of the {#1110,scan_code}, {#1109,ascii} and {#1108,shift_status} variables (also related to the reading of the keytable).

{#9999,Example program:}
PROGRAM example_codes_of_the_keytable;

GLOBAL
    keys[128];

BEGIN
    write(0, 0, 0, 0, "Codes of the pressed keys, according to key()");
    FROM x=0 TO 127;
        write_int(0, (x%16)*20, (x/16)*10+20, 0, OFFSET keys[x]);
    END
    write(0, 0, 160, 0, "Code of the last key pressed (scan_code):");
    write_int(0, 320, 160, 2, OFFSET scan_code);
    write(0, 0, 180, 0, "Code ASCII of the last key (ascii):");
    write_int(0, 320, 180, 2, OFFSET ascii);
    write(0, 0, 190, 0, "State of the special keys (shift_status):");
    write_int(0, 320, 190, 2, OFFSET shift_status);
    LOOP
        FROM x=1 TO 127;
            IF (key(x))
                keys[x]=x;
            ELSE
                keys[x]=0;
            END
        END
        FRAME;
    END
END
{-}

This program may be used (by clicking on the text "{Example program:}" with the mouse and then, by pressing the [{F10}] key) to find out the code that any specific key has.

This numeric code can later be used as a parameter of the {#128,key()} function, to verify in the game whether this key is pressed at a specific moment.

{/}See: {#1202,Constants} - {#128,key()} - {#1110,scan_code} - {#1109,ascii} - {#1108,shift_status}

# -----------------------------------------------------------------------------

{.1177,min_int}

Constant: {min_int}
{/}

This constant defines the minimum value that any variable can store in this language. This value is{ -2147483648}.

All the data are 32 bit {integers} with sign in this language.
For that reason, only integers within the range
({ -2147483648} ...{ +2147483647} ) may be used.

When the result of an arithmetic operation exceeds that range,
the system won't report any error. In order to avoid this situation, much care must be taken.

{/}See: {#1202,Constants} - {#1178,max_int}

# -----------------------------------------------------------------------------

{.1178,max_int}

Constant: {max_int}
{/}

This constant defines the maximum value that any variable can store in this language. This value is{ 2147483647}.

All the data are 32 bit {integers} with sign in this language.
For that reason, only integers within the range
({ -2147483648} ...{ +2147483647} ) may be used.

When the result of an arithmetic operation exceeds that range,
the system won't report any error. In order to avoid this situation, much care must be taken.

{/}See: {#1202,Constants} - {#1177,min_int}

# -----------------------------------------------------------------------------

{.1179,pi}

Constant: {pi}
{/}

This constant defines the equivalence in {degree thousandths} of the mathematical constant {pi} (approximately {3.14159265} radians).

Its value is {180000} degree thousandths (180 degrees), equivalent to
{pi radians}.

It is normally used to define angles. For instance, {180 degrees} could be defined as {pi},{ -90 degrees} as{ -pi/2},
{45 degrees} as {pi/4}, etc.

{/}See: {#1202,Constants} - {#1044,Use of angles in the language}

# -----------------------------------------------------------------------------

{.1200,Predefined global data}

Each of the predefined global data are now described.

{#1413,STRUCT dirinfo}         - List of files in a directoryú
{#1414,STRUCT fileinfo}        - Information about the fileú
{#1103,STRUCT joy}             - Parameters of the joystickú
{#1102,STRUCT m7[9]}           - Control of the mode 7 windowsú
{#1411,STRUCT m8[9]}           - Control of the mode 8 windowsú
{#1100,STRUCT mouse}           - Parameters of the mouseú
{#1410,STRUCT net}             - Parameters of the net hardwareú
{#1101,STRUCT scroll[9]}       - Control of the scroll windowsú
{#1104,STRUCT setup}           - Control of the sound cardú
{#1415,STRUCT video_modes[31]} - Modes of video disposedú

{#1409,argc}             - Number of argumentsú
{#1409,argv[]}           - Arguments of the programú
{#1109,ascii}            - Reading of keytable ASCII codesú
{#1416,channel[31]       - Sound Channelsú
{#1418,draw_z}           - Depth plane of the drawingú
{#1114,dump_type}        - Dump type of the screenú
{#1107,fading}           - Fading indicator of the screenú
{#1426,fps}              - Number of frames per secondú
{#1111,joy_filter}       - Filter applied to the joystickú
{#1112,joy_state}        - State of the joystickú
{#1115,max_process_time} - Max time of execution of the processú
{#1419,num_video_modes}  - Number of detected video modesú
{#1113,restore_type}     - Restore type of the screenú
{#1110,scan_code}        - Reading of codes of the key-boardú
{#1108,shift_state}      - State of the special keysú
{#1106,text_z}           - Depth plane of the textsú
{#1105,timer[9]}         - time counterú
{#1420,unit_size}        - Size of the unity of reading/writingú
{#1417,vsync}            - vertical synchronisationú

{/}See: {#1202,Constants} - {#1201,Local data} - {#1000,Syntax}

# -----------------------------------------------------------------------------

{.1201,Predefined local data}

Each of the predefined local data are now described.

{#1116,STRUCT reserved} - Internal parameters of the processesú
{#1117,father}          - Identifier of the process' fatherú
{#1118,son}             - Identifier of the process' sonú
{#1119,smallbro}        - Identifier of the process' younger brotherú
{#1120,bigbro}          - Identifier of the process' elder brotherú
{#1121,priority}        - Priority of the process' executionú
{#1122,ctype}           - Type of coordinates used by the processú
{#1123,x}               - Horizontal coordinate of the processú
{#1124,y}               - Vertical coordinate of the processú
{#1125,z}               - Depth plane of the process' graphicú
{#1126,graph}           - Code of the graphic assigned to the processú
{#1127,flags}           - Indicators of mirror and transparencyú
{#1128,size}            - Size of the process' graphicú
{#1129,angle}           - angle of the process' graphicú
{#1130,region}          - Screen region assigned to the processú
{#1131,file}            - File code of the process' graphicú
{#1132,xgraph}          - OFFSET of the graphic table of the processú
{#1133,height}          - Height of the process in mode 7 windowsú
{#1134,cnumber}         - Numbers of scroll or mode 7 windowsú
{#1135,resolution}      - Resolution of the process' coordinatesú
{#1424,m8_nextsector}   - Sector where the process is going nextú
{#1423,m8_sector}       - Number of sector the process is inú
{#1425,m8_step}         - Height which the process can riseú 
{#1422,m8_wall}         - Wall number of map of sectors opposite with which you collidedú
{#1421,radius}          - Radius of the mode 8 processesú

{/}See: {#1202,Constants} - {#1200,Global data} - {#1000,Syntax}

# -----------------------------------------------------------------------------


{.1202,Constants predefined}

Each of the predefined constants are now described.

{#1150,m320x200 .. m1024x768} - Videomodesú
{#1151,true}                  - True valueú
{#1152,false}                 - False valuesú
{#1153,s_kill}                - Signal to kill processes ú
{#1154,s_wakeup}              - Signal to wake processes upú
{#1155,s_sleep}               - Signal to make processes dormantú
{#1156,s_freeze}              - Signal to freeze processesú
{#1157,s_kill_tree}           - Signal to kill processes and sonsú
{#1158,s_wakeup_tree}         - Signal to wake processes and sons upú
{#1159,s_sleep_tree}          - Signal to make processes and sons dormantú
{#1160,s_freeze_tree}         - Signal to freeze processes and sonsú
{#1161,all_text}              - Indicator of all the textsú
{#1162,all_sound}             - Indicator of all the soundsú
{#1163,g_wide}                - Indicator of widthú
{#1164,g_height}              - Indicator of heightú
{#1165,g_x_centre}            - Indicator of horizontal centreú
{#1166,g_y_centre}            - Indicator of vertical centreú
{#1167,c_screen}              - Screen coordinatesú
{#1168,c_scroll}              - Scroll window coordinatesú
{#1169,c_m7}                  - Mode7 window coordinatesú
{#1170,partial_dump}          - Partial background dumpú
{#1171,complete_dump}         - Complete background dumpú
{#1172,no_restore}            - Disabled screen restorationú
{#1173,partial_restore}       - Partial screen restorationú
{#1174,complete_restore}      - Complete screen restorationú
{#1175,c_0 .. c_9}            - Indicators of windowsú
{#1177,min_int}               - Minimum value of dataú
{#1178,max_int}               - Maximum values of dataú
{#1179,pi}                    - Mathematical value of piú

{#1176,Key codes}     - Keytable codesú

{#1400,_case_sensitive}       - Distinguish capital and small lettersú
{#1400,_extended_conditions}  - Extended conditionsú
{#1400,_free_syntax}          - Free syntaxú
{#0231,_hidden}               - Hidden fileú
{#1400,_ignore_errors}        - Ignore all errorsú
{#1400,_max_process}          - Max number of processesú
{#1400,_no_check}             - Do not check execution errorsú
{#1400,_no_id_check}          - Do not check the identifiersú
{#1400,_no_null_check}        - Do not  check accesses to NULLú
{#1400,_no_optimization}      - Do not optimise the codesú
{#1400,_no_range_check}       - Do not check the rankú
{#1400,_no_strfix}            - Do not enlarge the text stringsú
{#0231,_normal}               - file normalú
{#1400,_simple_conditions}    - Simple conditionsú
{#0231,_subdir}               - Subdirectoryú
{#0231,_system}               - system fileú
{#0231,_volid}                - Volume etiquetteú
{#0250,all_drawing}           - Indicator of all drawingsú
{#0227,seek_cur}              - Current position of the fileú
{#0227,seek_end}              - Final position of the fileú
{#0227,seek_set}              - Beginning of fileú



{/}See: {#1200,Global data} - {#1201,Local data} - {#1000,Syntax}

# -----------------------------------------------------------------------------


{.1260,Program debugger}
See: {#3,Index} - {#1250,Help about the menus system}{/}

The programs debugger is an advanced tool, whose use first requires a correct understanding of all the programming concepts explained from chapter number 5 of the DIV Games Studio's book (User's Handbook).

{+70,0}The debugger is a dialog box that can be activated in programs' run time for one of the following reasons:

* The program was entered with the option {programs \ debug program}.

* The {F12} key was pressed in a program's run time.

* An {error of execution} arose in the program.

* A {debug} statement was found in the executed program.

This tool allows us to execute the program statement by statement, verifying the value taken by the different program's data when necessary. It is useful because, on checking the program's execution step by step, it can find the mistakes eventually made by the programs.

As it is a dialog with a great deal of information, each of its sections are now described separately.{-}

{/}

{Upper information line}

Two messages are reported in the upper part of the window. To the left, there is one indicating the {number of processes active in the program} out of the {total that can be created}. For instance, if it reports 23/3201, it means that there are 23 processes active in the program and that up to 3201 could be created before
using up the available memory for processes.

The maximum number of processes vary from some programs to others, depending on the number of their local and private variables.

The {identifying code} of the process selected in the list, as well as its current state (normal, killed, asleep or frozen) are indicated to the right.

{/}

{List of active processes}

This list appears in the upper left part of the debugger with a scrolling bar to its right. All the active processes in the program are shown in it. By active processes we mean the processes that have been created and that still have not been disappear. The following information appears for each process:

* The process name in the program.

* Its identifying code in brackets (occasionally, there is no space to put it entirely).

* A letter indicating its state ({A}-Normal, {K}-killed, {S}-Asleep and
{F}-Frozen).

* The percentage of accomplished execution for the following frame.

The scrolling bar must be used to move through the processes' list.

{Important}: One of the processes appears with a white tip arrow pointing out its name. This is the process that {is being executed} in the program currently. Therefore, the next statement of the program will belong to this process.

One of the processes appears tagged with a black band. This is the process about which information is shown in the right part of the window (close to this list of processes). This process may be selected with the mouse, by clicking on the list.

It is very important to distinguish between the process in execution and the
process about which the information is shown, as they don't have to necessarily be equal. For the information about the process in execution to be shown, it is necessary to select it (that of the white arrow) by clicking on the list with the left mouse button.

{/}

{Information box about the indicated process}

To the right of the previous list, information about the program tagged with a black band in the list (not the process in execution) is shown. Its identifying code and its state was shown in the uppermost line.

The complete process name is shown in a dark background's box. Below it
there is another box with the graphic of this process (when it is bigger, it will be reduced to fit this box).

The button {See data} appears to the right of the graphic. This button allows us to access another dialog box in which all the data of the process must be consulted and modified. It will be later explained in the section {Inspecting data}.

The ({x},{y}) coordinates of the process, the system of coordinates used by it (referred to the {screen}, to a {scroll} or to  a {mode 7}) and the mirrors or transparencies applied to the graphic of the process are always shown following this button..

Finally, four buttons allow us to access the {father} process (the
process that called the one is selected), the {son} process (last process called by the selected one), the younger brother ({smallbro}, the last one called by the father before it) and the elder brother ({bigbro}, the following one called by the father after it). If these buttons don't lead to any other process, that is because there is no process with that relationship.

{/}

{Partial execution controls}

Two buttons called {Exec.Process} and {Next FRAME} below the previous information box allow us to execute the program partially.

{Execution of the process}. This first button allows the program to continue
just to the end of the process currently under execution (the one pointed with the white arrow in the list). All its statements will be executed until it reaches the next {FRAME} (until the process is ready for the next frame of the game).

{Next FRAME}. The second button will execute the program to its next frame, first executing all the pending processes and displaying the next frame of the game (in the debugger's background). The debugger will stop in the first statement of the first process to be executed in the new frame. It is possible to displace the dialog box with the debugger (by dragging its title bar) in order to contemplate the result of the previous frame of the game.

{/}

{Debugging box of the program's listing}

The code of the program is shown in the lower part of the debugger.
The identifying code of the process under execution (again, the one pointed with the white arrow in the list) appears in the left upper corner.
Below it, there are three buttons and, to its right, the code window.

In the {code window}, another white arrow indicates the line including the next statement to be executed by the process. It can be notice how the statement also appears highlighted in white from the rest of the code.

This window's contents can be displaced with the {cursors} keys. The program's lines can be tagged with a black band. Nevertheless, it is not possible to modify the program from the debugger. Indeed, to modify the program it is necessary to finish its execution (which can be done by pressing {ALT+X}) and return to the editor of the environment.

The first button called {Process} allows us to go in the code window to one of the processes of the program directly. A list containing all the processes found in the program will appear, being necessary to select the desired process with the mouse. However, it won't change the process currently under execution, which will continue to be the same.

The second button allows us to establish a {Breakpoint} in the program. For that, it is first necessary to tag the line of the listing with the black band. On reaching this line (with the cursors), the program must stop. Then, this button must be activated, appearing the line in red.

Breakpoints can not be established in all the lines of the program,
but only in those for which the executable code has been generated
(in which any action is performed).

Many breakpoints can be established in the program. To execute the program until it reaches one of these points, suffice will be to close the debugger or press the {ESC} key.

To {disable} a breakpoint, it is necessary to select the line and click on the same button again.

The last button, {Debug}, is the one that really allows us to debug the program statement by statement. Every time it is clicked on, one of the program's statements will be executed. When a process finishes its execution, or
completes a frame, you will pass to the first statement to be executed of the next process.

{/}

{Inspecting data}

{+71,0}By clicking on the button {See data} of the programs' debugger it is possible to access this other dialog box, in which the values of the program's data can be consulted (and even modified) in the point in which it has stopped,
normally with the aim of carrying out tests in it.

Most of this box is occupied by the data list. Each of them are shown with their name and numeric value. This list always appears in alphabetical order.

The data set appearing in this list can be selected through a series of switches. The two upper switches define the two following sets.

* {Predefined}. When this switch is activated, all the data predefined in the language will be included in the list. Thus, it will be possible to access the predefined local data (such as x, y, angle, size, ...), the predefined global data and the predefined constants.

* {Defined by the user}. This switch selects all the new data defined in the program. These are the specific constants, variables, tables and structures of every program.

Besides selecting the data depending on whether they are predefined or new, they can be selected according to the sphere in which they have been declared,
with the following switches.

* {CONST}. This switch is used to include the constants in the list, even if the constants are not data, but synonymous of a numeric value. Therefore, they can not be modified.

* {GLOBAL}. On activating this switch, all the global data (accessible
by all the processes) will be included in the list.

* {LOCAL}. When this switch is activated, the local data (the data that all the processes of the program have) will be included in the list.

* {PRIVATE}. This switch selects the specific data of the process tagged in the debugger window to include them in the list. These data exclusively are for the program's internal use.

The list of data can be displaced with the vertical scrolling bar
or with the {cursors} and {Pg.Up / Pg.Dn} keys.

The button {Change} allows us to modify the value of the selected data; only the constants can not be modified. A new dialog will appear with a text box in which the new value of the variable must be input. Any variable of the list can be selected with the {cursors} or clicking on it.

Below this button, there are other two buttons with the symbols{ -} and{ +}. They are used to {modify the index of tables and structures}, which can also be done with the {right cursor} and {left cursor} keys. The table or structure whose index is intended to change must previously be selected in the list.
This is the way to observe or modify any element of a table or structure

Finally, a series of buttons appears in the lower part of this dialog. These buttons, mentioned below, allow us to display the value of a variable in a  specific way:

* {Angle}. This button allow us to display the variable as an angle. The angles are specified internally (in the programs) in degree thousandths. The
value of the variable will be displayed as an angle in degrees and radians.

* {Process}. If the variable is the {identifying code} of a process, on selecting this display filter, the name of this process will appear in the list as a value of the variable.

* {Text}. When the variable is a text or a pointer oriented to a text (to a literal
of the program), that text will be displayed in the list by clicking on this button.

* {Logical}. If a variable contains a logical value, on applying this filter to it, in the upper list will be shown whether it is {false} or {true}.
In the language, on evaluating them as logical conditions, the odd numbers are considered true, and the even numbers are considered false.

Once the display filter of a variable has been established, it will remain during the rest of the program's execution. The same button must be double-clicked to display again the contents of the variable as a numeric value.{-}

# -----------------------------------------------------------------------------

{.1291,Commands in the graphic environment}

{Commands in the graphic environment}

{/}

{ALT+X}         - To exit from the graphic environment to the operative system.ú
{ESC+Control}   - To exit the environment and programs directly.ú

{ALT+S}         - To execute a session of the MS-DOS operative system.ú

{ESC}           - To cancel a dialog box.ú
{TAB}           - To chose the selected control of a window or box.ú
{Enter}         - To activate the selected control.ú

{F1}            - To invoke the help window.ú

{F2}            - To save the selected program.ú
{F4}            - To open a program.ú
{F10}           - To save and execute the selected program.ú
{F11}           - To compile the selected program.ú
{F12}           - To save and debug the selected program.ú

{Control+ALT+P} - To save a snapshot of the graphic environment (DIV_*.PCX)ú

# -----------------------------------------------------------------------------

{.1292,Common commands in the games}

{Common commands in the games}

{/}

{ALT+X}        - To exit the game.ú
{ESC+Control}  - To exit the game.ú

{Control+ALT+P} - To save a snapshot of the game (SNAP*.PCX)ú
{F12}          - To invoke the programs' debugger.ú
{Pause}        - To stop the game immediately.ú

# -----------------------------------------------------------------------------

{.1293,Commands in the programs' debugger}

{Commands in the programs' debugger}

{/}

{Cursors.}  - Shift through the listing.ú
{Pg.Up.}    - Previous page.ú
{Pg.Dn.}    - Following page.ú

{F4}        - Execute until the selected line is reached.ú
{F5}        - To see the listing of a process.ú
{F6}        - To execute the current process.ú
{F7}        - To see or edit data.ú
{F8}        - To debug a statement.ú
{F9}        - To set a breaking point.ú
{F10}       - Execute the following statement or call a process.ú
{F11}       - To see the timing profiles of the program.ú
{F12}       - To invoke the debugger / To advance frames.ú

{F}         - To execute to the following frame.ú

{TAB}       - To select a button.ú
{Enter}     - To activate a button.ú
{ESC}       - To exit the debugger.ú

# -----------------------------------------------------------------------------

{.1294,Commands in the programs' editor}

{Commands in the programs' editor}

{/}

{Generic commands.}

{/}

{F5}        - To go to the beginning of a program's process.ú
{Control+Z} - To zoom the selected program's window.ú

{/}

{Basic movement and edit commands.}

{/}

{Cursors}                   - Basic movement of the cursor.ú
{Home}                      - To go to the beginning of the line.ú
{End}                       - To go to the end of the line.ú
{Pgdn}                     - Following page.ú
{Pgup}                     - Previous page.ú
{Insert}                    - To toggle between insert and overwrite.ú
{Delete}                    - To delete the cursor character.ú
{Clear}                     - To delete the character previous to the cursor.ú
{TAB}                       - To go to the following tabulation.ú
{Shift+TAB}                 - Distabulate.ú
{Control+Delete, Control+Y} - To delete the current line.ú
{Control+Right}             - Following word.ú
{Control+Left}              - Previous word.ú
{Control+Pgup}             - To go to the beginning of the program.ú
{Control+Pgdn}             - To go to the end of the program.ú
{Control+Home}              - To go to the beginning of the page.ú
{Control+End}               - To go to the end of the page.ú

{/}

{Search and replacement commands.}

{/}

{ALT+F, Control+F}     - To search for a text.ú
{ALT+N, F3, Control+L} - To repeat search.ú
{ALT+R, Control+R}     - To replace a text.ú

{/}

{Blocks commands of type Q EDIT.}

{/}

{ALT+A}        - To tag the beginning or the end of a permanent block.ú
{ALT+U}        - To untag the permanent block.ú
{ALT+C}        - To copy the block to the current position.ú
{ALT+M}        - To move the block to the current position.ú
{ALT+D, ALT+G} - To delete the block.ú

{/}

{Blocks commands of type EDIT.}

{/}

{Shift+Movement keys}    - To tag the volatile block (Movement keys:
{Cursors, Control + Right, Control + Left, Pg.Up, Pg.Dn, Home, End}).ú

{Shift+Insert}      - To paste block.ú
{Control+Insert}    - To copy block.ú
{Shift+Delete}      - To cut block.ú

{Control+X}         - To cut block.ú
{Control+C}         - To copy block.ú
{Control+V}         - To paste block.ú

{Delete}            - To delete block.ú

# -----------------------------------------------------------------------------

{.1295,Commands in the graphic editor}

{Commands in the graphic editor}

{/}

{Generic commands.}

{/}

{F1}                - To invoke the help window.ú

{ESC}               - To exit the graphic editor.ú

{Cursors, OP/QA}    - Movement of the cursor.ú
{Space bar}         - Equivalent to clicking with the left mouse button.ú
{Shift+Movement}    - 8 by 8 pixels movement.ú
{Shift+Left button} - To take the colour from the screen.ú

{W, S}              - To choose colour within the current range.ú
{Shift+W, S}        - To choose current range.ú
{Control+Cursors}   - To choose colour and range.ú

{Backspace}         - To undo.ú
{Shift+Delete}      - To repeat action (redo).ú

{0}                 - To select the transparent colour.ú
{B}                 - To highlight the transparent colour.ú
{C}                 - colours window.ú
{M}                 - Mask window.ú
{T}                 - Select a paintbrush.ú
{U}                 - Select a texture.ú
{X}                 - visualise a texture.ú
{Z}                 - To change the zoom percentage.ú

{/}

{Commands of selecting tool.}

{/}

{F2}             - Pen, for hand drawing.ú
{F3}             - Straight lines.ú
{F4}             - Multi line, stringed lines.ú
{F5}             - Curves b‚zier.ú
{F6}             - Multi curve, stringed curves.ú
{F7}             - Rectangles and boxes.ú
{F8}             - Circles and circumferences.ú
{F9}             - Paint spray.ú
{F10}            - Filling of surfaces.ú
{F11}            - Blocks edit.ú
{F12}            - Undo and redo actions.ú
{Shift+F1}       - To write texts.ú
{Shift+F2}       - To position control points.ú
{Shift+F3}       - Dotting bar.ú

{/}

{Specific commands.}

{/}

{Control}  - To move selection (bar: to select a block).ú
{D}        - To stump (bars: pen, lines, curves and spray).ú
{H}        - To hide the cursor (bar: offset block).ú
{K}        - Copy window (bar: select block).ú
{ +, -}    - To vary the strength (bar: multi curve).ú
{ +, -}    - Change the checkpoint (bar: checkpoints).ú

# -----------------------------------------------------------------------------

{.1300,Common help/ questions about DIV}
 
{Where can I find information about DIV?}

The DIV Games Studio Environment has its own dedicated web site {WWW.DIV-ARENA.COM},
from here you can download upgrades and utility packages, get technical support, review / submit 
Games designs and chat to other DIV users about cool new games, hints on obtaining the best from DIV etc..
in fact talk about whatever you wish.

{How can I obtain help about ... ?}

All options accessible from options menus are described
exclusively in the {user manual} for DIV Games Studio 2.

{How can I resolve a configuration problem ?}

For sound problems, incomplete installations, etc., see the chapter
{#2003,resolution of problems} of this electronic help.

{What improvements have been made for this version?}

They are divided in two groups: the {#2001,new language capabilities}
(explained in this {help}), and the {#2002,new environment} (explained in the {user's manual}).

{Why did I get the error message "Can't recognise the file type"?}

It is possible that you are attempting to load a file with an incorrect menu, which means,
the palette menu serves only to load palettes, the files menu only loads
graphics files (groups of graphics), the programs menu loads programs or text files, etc.

You may also be attempting to load a PCX or BMP Map in true colour,
this version of DIV can work only with 256 colour graphics, so these types of 
files are impossible to import. The graphics which you want to load
into DIV must first be converted into 256 colours with another application.

{How can I stretch a graphic?}

To stretch a graphic you must press the left mouse button in the
map window, not on the bar with its name, but on the proper graphic
contained in the window. Then move the mouse to the position
in which you want leave the graphic and let go of the left mouse button 
(you can stretch maps in files, to the trash, to the background, in other maps
or in the fonts generator).

{How can I drag a graphic contained in another graphic out?}

{+126,0}You must select the part of the graphic which you want to drag out from
the section blocks. The new section could be represented as a rectangle, 
painting contours, etc.{-}

{+133,0}Once the selection has been extracted many new icons  will appear 
on the toolbar, including the icon {cut the window}.
After pressing on this the desktop {creates a new map window}
{and inserts the selected zone} into it.{-}

{How can I cut and copy the graphics?}

{+126,0} See also the last question. To cut and move graphics you must access
the {toolbar}, inside the picture window, selecting the icon which shows cutters.

From the desktop some operations can be achieved, such as copying
one graphic into another, this can be made by dragging the first one
into the second. Also a copy of a graphic can be created if you drag
it to the background (area of the desktop which doesn't contain any windows).

{What must I do if the system becomes unstable?}

DIV Games Studio is a very complex program and, although it is stable
in its execution, it is possible that a module makes an error
after completing a determined action, or crashes the PC.

If this happens, to return the system to its original state, you must load
DIV from the MSDOS prompt indicating the parameter{ /SAFE} (introducing the command 
D.EXE /SAFE from the directory where the program was installed), to enter DIV 
in  "debug mode".

{What must I do to learn the programming language ?}

The basic concepts are not explained in this help file, but in the user's 
manual for DIV Games Studio 2, in the chapters 4, 5 & 6.

Also you can learn a lot from the Examples of the language functions 
(See the list of functions in the language help)
and the tutorials, which are simple mini-games 
designed to simplify the learning of the language (you can find these tutorials
in the directory PRG/TUTOR of DIV Games Studio 2).

{How are the graphics loaded into the games?}

In a game the graphics contained in the map (MAP or PCX files) can be used, 
loading them using the functions {#174,load_map()} or {#174,load_pcx}, 
or placing some graphics in FPG file of several graphics and then loading them 
with the function {#132,load_fpg()}, this last option has an advantage because 
many graphics can be loaded at the same time in the game.

Often the graphics are assigned to the variable
{#1126,LOCAL graph} of the processes of the game.

{How to show a new graphic in the game?}

To create a new graphic or "sprite" in a game, first a new process ({#1016,PROCESS}) 
must be created with the commands which will manage
its conduct in the game, then every time you want
to create a process of this type, you must call the process
(See how to make a {#1033,call to a process}).

{How to undo a process?}

To undo or "kill" a process of the game, you can execute
a {#1028,RETURN} statement from itself or, to kill a process from another process, 
send a signal s_kill (See the function {#158,signal()}, which is used for this).

{Which are the functions that manage the mouse?}

The mouse is not controlled by any function, but by the global structure
{#1100,mouse}, you can access the help file about {language} / {global data}
to see the other structures which control other important aspects of the games.

{Where are all DIV files loading from ?}

When the function load_fpg( ... ) is called in a program 
the internal manager of DIV attempts to locate this file following this
method (supposing that it intends to load the file "DIR/file.EXT"):

- First it checks where the executable (EXE) of the game is,
or in the main directory of DIV (where D.EXE is) in case the game
will be executed from this environment.

- Then the program attempts to open the file from the directory 
specified in the function ("DIR/file.EXT").

- If the program has still failed to open the file, it will attempt to load the
file inside a directory which has the same extension as the one specified, 
such as "EXT/DIR/file.EXT".

- If this is still not found, the program will try to load the file
without a specific path, meaning "file.EXT".

- Finally, if the file was not found in any of those directories, the program will
attempt to find the file in the directory whose name coincides with the extension 
of the file, ignoring the path passed to the function, such as "EXT/file.EXT".

# -----------------------------------------------------------------------------

{.1301,Help about the calculator}

{How it functions?}

The calculator included in the environment functions differently from conventional
calculators, it is made for programmers, and therefore functions as an evaluator 
of expressions.

Its use is very simple, you write the mathematical expression and press
the {Enter} key. Pressing {F1} will always take you to this help page.

For example, you can type in the calculator the expression 2+2 and press {Enter};
the value 4 will appear in the results window. To introduce a new expression
the previous one must first be rubbed out, this can be done by pressing the {ESC} key.

It is possible to introduce complex expressions, using parentheses {( )} to indicate
the priorities in the calculations.

{/}

The {operators} which can be used in the calculator expressions are
the following (indicates all symbols accepted in each operator):

{ + -}      Addition and Subtraction.ú
{ * /}      Multiplication and division.ú
{ % MOD}    Modulus, or remainder from whole division.ú
{ < <<}     Binary rotation to the left.ú
{ > >>}     Rotation to the right.ú
{ ^ ^^ XOR} OR exclusive binary.ú
{ | || OR}  OR binary.ú
{ & && AND} AND binary.ú
{ ! NoT}    Binary negation.ú
{ SQRT}     Square root.ú

{/}

The calculator has two cells which can change their {mode of
functioning}. Their options are the following:

{Int} - If this cell activates, all operations will be rounded down 
to whole number values,  as in the language DIV. For example, the result 
of the division 8/3 will be 2.

{Hex} - When this cell is activated, the result will be shown in
the hexadecimal system. Also numbers in this system can be introduced 
inside the expressions preceded by '{0x}' (as in the language).

{/}

{Note:} On the desktop as many calculators as necessary can be opened, 
so many different expressions can be visible simultaneously .

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1400,compilation options}

These options modify the form in which DIV interprets a program and the code
which it generates for DIVl. Normally it is not necessary to specify any options.

To add one or more of these options to program the word {COMPILER_OPTIONS} must 
be specified as the initial statement of the program (commentaries in margin) 
followed by the names of the included options.

If many options are included, they must appear separated by commas, adding
always a semicolon at the end (after the last option).

{/}

{disposed compilation options :}

{_max_process=x}

Where x is a whole positive number. This defines the max number of
 simultaneous processes permitted during execution. This can be set
when a program is completed (when it is known how many 
processes it will have in one moment), to optimise memory during execution. 
When this value isn't defined, a min of 1 Mb (and a max of 2 Mb) will be reserved 
for the program memory.

{_extended_conditions}

Allows you to use assignations inside a condition (such as:{IF(id2=get_id(...))...)}; 
it was permitted by default in the first version. It may be necessary to declare this 
option in order to ensure that programs written with DIV1 function in DIV2.

{_simple_conditions}

Interprets the symbol = as a comparison, when it appears inside a condition. 
This is the opposite case to previously (and incompatible with l), 
once this option is included you will be able to make comparisons like 
{IF(x=0)...}, instead of interpreting them as an assignation of the value 0 to 
the variable x.

{_case_sensitive}

This option Differentiates between capital and small letters.
If this option is active {Abc} and {abc} will be
two different names. It is important to know that, if activated,
all reserved words of the language such as ({program}, {loop},
{frame}, {if}, ...) must be put in small letters.

{_ignore_errors}

Forbids the appearance of error messages during the
execution of the program. The majority of errors will be ignored
(such as memory errors, file not found, divisions by zero, etc.) , 
we don't advise you use this option but, if you want it to be included, 
then do so only if the programs are finished, sufficiently checked, and without known
errors, before compiling the installation (See the final considerations).

{_free_syntax}

Permits you to use free syntax. With this option the symbols {;} (semicolon) 
at the end of the statements will no longer be necessary and parentheses are no 
longer required in statements like {IF}, {WHILE} or {UNTIL}. For example, in
this mode statements such as: {IF a<0 a=0 END} (See before final considerations) 
will be valid.

{_no_strfix}

Will not finish automatically text strings. When
you put a character in a variable of type {#1406,STRING}, normally the program 
inserts the character after the end of the string,
and adds white spaces with the character {NUL} (ascii 0) at the end of the string. 
This option disables this characteristic.

{_no_optimization}

Do not optimise the generated code. By default the programs are optimised. 
This option can be included to disable these optimisation processes. This means,
if this option is specified, the programs will go slower and will occupy more memory.

{_no_range_check}

Doesn't check that values accessed are out of the range of tables and structures. 
The compiler generates code to check during the execution that expressions used as indexes
of a table or structure are in the permitted limits,
and to show an error when a value is out of range. This option prevents this code being 
generated.

{_no_id_check}

Do not check the validity of the identification code. The
compiler also generates code to check the validity of the
identifier when it is used to access a local variable
from another process (as in {id2.graph}). If this option is specified
at the beginning of the program, then this checking will not be done.

{_no_null_check}

Do not check the accesses to null pointers ({NULL POINTER}). 
This disables the checking of attempts to access memory with null pointers 
or undefined pointers. Including this option means the code 
to protect these accesses of reading or writing in memory will not be generated .

{_no_check}

Does not allow any security checking.
This option unites the three previous options, and forbids the compiler
to generate code to check any type of anomalous operation during the execution. 
The programs will run faster, but it is not recommended to use these options
until the programs have been tested and are without errors.

{/}

To use these options, for example, the program can be begun with the following statement:

{COMPILER_OPTIONS _max_process=64,_no_id_check;}

In this case the compiler is set to reserve memory for 64 simultaneous processes in the 
execution of the program, and no validity checks on the identifiers to local variables of other
processes will be made (it is useful to switch off these checks,
when the programmer has sufficient experience to know what he's doing).

{/}

{Important: considerations about some of the options.}

{1.} New users of DIV or those with little programming experience can
simplfy a little the conditions with the option {_simple_conditions}, so that 
two values with the symbol {=} (also with the symbol {==}) can be compared. 
In contrast, users who have more experience, will probably prefer to activate 
the option {_extended_conditions} so that more complex conditions can be created, 
with assignations inside of them.

{2.} The options {_ignore_error} and all variants of {_no_check} must be used only
by experienced programmers, and only in the finished version of the program. 
Otherwise we don't recommend you use it, because major execution errors
can be produced, and it will be more difficult to find the cause without these error 
messages.

{3.} In general the programs are already optimised (the generated code is {60%}
faster than in the previous version), but any of these options will significantly change  the
speed of execution. The {profiles of time} of the debugger can be used to see the 
repercussions of each option.

{4.} The option {_ignore_errors} is often not the best, nearly always it is better to use
the function {#240,ignore_error()} to ignore selectively some predetermined errors the 
program is known to generate during execution.

{5.} The use of free syntax (with {_free_syntax}) also has many dangers. Because
there is no differentiation between lines and white spaces, and in some cases 
incorrect interpretations can be produced . For example, in the
statement: {IF right ++x END}, the compiler will interpret that the symbol{ ++} is the
post increment of {right}, instead of the pre increment of {x} (although this symbol
is united with this last variable). Another similar anomaly can happen using C programming
style pointers, for instance, with these two consecutive assignations:  {a=1 *ptr=2}, the compiler
will interpret them as: {a=(1*ptr)=2} (although they were in different phrases).
But in general, if you are not using preincrements or C programming style pointers, 
there will be no problems with the free syntax (also parentheses or
semicolons can be used in concrete cases, to resolve these small problems).

{6.} However, the option {_max_process} (which is the only one which must be followed by the
the symbol {=} and a number value) is strongly recommended. If the 
number of processes which the program can have running simultaneously is known,
then less memory needs to be reserved (leaving this free for graphics, sounds, etc.).

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1401,types of data}

In DIV there exists data of the types {#1402,INT}), {#1406,STRING} (text strings), {#1403,WORD} 
(16 bit whole positive values), {#1404,BYTE} (8 bit whole positive values) and {#1405,POINTER} (pointers, of all
these types). Also tables and structures (also of any types) of 2 or 3 dimensions 
(see the {#1011,declaration of a table})can be defined. 

{#1402,INT} - whole numerical data between -2147483648 and +2147483647 ({#1177,min_int} ... {#1178,max_int}).

{#1403,WORD} - whole numerical data between 0 and 65535 (whole of 16 bit without sign).

{#1404,BYTE} - whole numerical data between 0 and 255 (whole of 8 bit without sign).

{#1405,POINTER} - Pointers to data of any type.

{#1406,STRING} - strings of text (tables of 8 bit characters without sign, between 0 and 255)

{/}

{Note:} The reserved word {INT} can be omitted, because all data will be of this type by default
(32 bit whole numbers with sign).

{/}See: {#1009,Declaration of data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1402,data of type INT}

Whole numerical data between -2147483648 and +2147483647 (values defined
in the constants {#1177,min_int} ... {#1178,max_int}).

This is the basic data type of the language, when the
{type of the data} is not otherwise specified , it will be {INT} by default.

{/}See: {#1401,types of data} - {#1009,Declaration of a data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1403,data of type WORD}

Numerical whole data between 0 and 65535 (16 bit whole value without sign).

Tables of type {WORD} can signify a big saving of memory,
with respect to tables of type {#1402,INT}(which occupy {twice as much} memory). 
But {the fastest will be operations with data of type} {#1402,INT}.

See the {#1407,adjustment of data in memory}, where the amount of memory 
occupied with the different types of data is shown.

{/}See: {#1401,types of data} - {#1009,Declaration of a data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1404,data of type BYTE}

Whole numerical data between 0 and 255 (8 bit whole value without sign).

The tables of type {#1404, BYTE} can signify a big saving of memory,
with respect to the tables of type {#1402,INT} (which occupy {4 times more} memory). But
{the fastest operations will be with data of type} {#1402,INT}.

See the {#1407,adjustment of data in memory}, where the amount of memory 
occupied with the different types of data is shown.


{/}See: {#1401,types of data} - {#1009,Declaration of a data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1405,data of type POINTER}

Pointers to data of any type ({#1402,INT}), {#1403,WORD},
{#1404,BYTE} and {#1406,STRING}).

The pointers in the DIV language are different to
other programming languages, for one thing they are more simple to use.

These pointers are used as if they were mobile tables, that is, tables which can be defined
where they are situated, assigning them an {#1085,OFFSET} (to the data). 
So you can access the data situated in this position from
{pointer[index]}, for reading and writing of the values.

{/}

{different data of type pointer:}

{INT POINTER} - Pointer to whole number data. The word INT can be omitted, declaring
a pointer to data of type {INT} as {POINTER name;}.

{WORD POINTER} - Pointer to a list or table of data of type {WORD}.

{BYTE POINTER} - Pointer to a list or table of data of type {BYTE}.

{STRING POINTER} - Pointer to a string of text contained in a {STRING}.

{STRUCT POINTER} - Pointer to a structure, which must be declared as {STRUCT
POINTER name_structure <name>;}. Where {<name>} will be the pointer to the structure.

{/}

For example, if in a program there exist different tables of type {WORD} (declared as
{WORD t1[9], t2[9], t3[9];}), then a denominated pointer {ptr}can be defined 
which permits you to access to any of the tables (as {WORD POINTER ptr};). In addition
you must assign the direction or location of the specific table to the pointer
(such as {ptr = OFFSET t1;}) to access it. From then on you can access the
values of the table with the pointer (you can access {t1[n]} using the term {ptr[n]}).

The functioning of the pointers {#1402,INT}), {#1403,WORD} and {#1404,BYTE} are practically identical
(they allow you to access a list of consecutive data).

The pointers {#1406,STRING} permit you to access only one string of text (all
characters contained in that string).

In the declaration of the pointers of type {#1012,STRUCT}, the name of the structure
to which the pointers refer must be declared. The pointers can give access to only one structure
but, after assigning the {#1085,OFFSET} of the structure (or of any register)
you than have access to all fields and successive registers, as if the pointer were
a conventional structure.

{Note:} To declare a pointer to a structure it is necessary to have previously defined the structure.
It's enough to define the different fields, but it is not
necessary to define the number of registers of the structure.

{/}

{Limitation in the access of the pointers.}

You can't access the written data before the {OFFSET of the pointer}is established. 
This {OFFSET} can't be assigned in the declaration of the pointer,
it must be done in a statement of the program, until this statement is reached the pointer
will value 0 ({pointer zero}). The access to data with the pointer zero will provoke an
execution error.

It is possible {to limit the range of access of a pointer}, indicating in its declaration the
max value from the index permitted for it. For it must be only
indicated in brackets, after the name of the pointer. For example, the following
declaration:

{STRING POINTER s[32];}

Defines the pointer to one string of text, but it will stop to access
directly to its 33 (from 0 to 32) firsts characters. If it is intended
to access out of these limits, the program will advert it indicating an access
out of the rank.

{/}See: {#1401,types de data} - {#1009,Declaration of a data} - {#1085,OFFSET}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1406,data of type STRING}

The {STRING} tables are different to the other data types, for one thing their data can only 
be {strings of text} and they can only have {1 dimension}. If a literal is not assigned to them, 
the string will stay initiated as {""} ({empty string}).

If a string is defined as {STRING s="abc";}, then when it is accessed by its
name ({s}), it will refer to the contained string ({"abc"}). Also you can 
access any character of the string as if it were an element of a table
(for Example, the statement {s[3]="d";} would add a {"d"} to the string).

{Note:} It is not necessary to declare in brackets the length of the text strings 
(by default 256 characters will be set aside for the string).

{/}

{operations with strings of text.}

Inside a program, supposing the data {s} and {r} are of type {STRING}, then 
the following operations can be performed on the data.

{1.} data of type {STRING} can be used in all functions which require
text (such as {#171,write}(0,0,0,0,s), {#132,load_fpg}(r), ...).

{2.} It is also possible to assign literals to a string by writing 
{s="any text...";} or assigning one string to another, as {s=r;}.

{3.} the strings Can be summed with statements such as {s+="text to be added";} or
{s=r+"ho"+"the";}.

{4.} Also a character can be added to a string with statements such as {s+=ascii;}
or {r+="a";}.

{5.} A character can be deleted (from the end) of the string with {s--;}, {s-=1;} 
or {r=s-1;}.

{6.} Strings can be compared with conditions such as {(s=="hello")}, {(s>=r)},
{(s<"0"+r)}, etc.

{7.} And, finally, a great number of functions for text management exist (See the {#1032,
list of functions of the language}).

{/}

{Literals of many lines.}

It is possible to define literals over many lines, for this you only need to divide the
text into many texts, and place them one after the other (without any separation with symbols). 
For example, a constant can be defined as:

{greetings="­Ho"}ú
{       "the!";}

This can also be used to initiate data of type {STRING}. There is no limit
in the number of lines allowed. Between two following literals only {#1002,commentaries}
can appear.

{/}See: {#1401,types of data} - {#1009,Declaration of data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1407,Adjustment of data in memory}

It is important to stress that all data in this language will be adjusted to {4 bytes} 
of memory (the size of data of type {INT}. This means that the {OFFSET} of all data will 
always be situated in one area of absolute memory {multiple of picture}.

It has direct implications for data of types {WORD} and {BYTE}. Because
they occupy respectively {2 bytes} and {1 byte}. therefore, if you define a variable of
type {WORD}, so, 2 bytes of memory won't be used, and if you define a variable of type
{BYTE} 3 bytes won't be used (because the following data will also be adjusted to 4 bytes).

Therefore, to use the PC memory better, we recommend you use these two types of data as 
tables (see the {#1011,declaration of a table}), because the different elements of a table
always save as the following, and don't adjust in memory.

{/}

{Examples of occupation of memory:}

{BYTE b1;} - required memory 1, occupied memory 4.

{WORD w1;} - required memory 2, occupied memory 4.

{INT i1;} - required memory 4, occupied memory 4.

{BYTE b2[7];} - required memory 8, occupied memory 8.

{WORD w2[2];} - required memory 6, occupied memory 8.

{BYTE b3[2];} - required memory 3, occupied memory 4.

{WORD w3[3]} - required memory 8, occupied memory 8.

{/}

As you can see, the occupied memory (in bytes) by data 
will always be a multiple value of 4.

You must also remember this in the fields of the {#1012,structures of data} because
for example; two consecutive variables of type {WORD} will occupy {8 bytes},
while a {WORD} table with two elements occupies only {4 bytes}.

{/}See: {#1401,types of data} - {#1009,Declaration of data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1408,The FUNCTION blocks }

The new {FUNCTION} blocks behave the same way as the functions of any
other programming languages, they execute sequentially (not in parallel
as the {#1016,PROCESS} blocks do), not returning before they are finished.

{FUNCTION} {#1001,<name>} {(} {#1018,<parameters>} {)}ú
{#1008,<Declaration of private data>}ú
{#1086,BEGIN}ú
    {#1017,<statement>} {;}ú
    ...ú
{#1091,END}

These blocks will continue to function in a similar way as the normal processes,
but with one important difference: they will halt the calling process until the function
has finished, in other words, the process which called these functions will be sleeping, 
until these functions return or their process will be finished.

If the function doesn't use the statements {#1029,FRAME}, it will behave as
a normal process, but if a function executes the statement {#1029,FRAME}, it will not return
to the block from which it was called (as it would do in a normal process).

Therefore, a function can always return a value with {#1028,RETURN}{(}<expression>{)},
including after executing one or more {#1029,FRAME} statements.

{/}

{successive programming.}

It is not recommended to program only with functions in a successive way, but it is useful to 
know how it is possible to simplify the understanding of programming DIV for programmers 
of other languages.

It is possible to make a program in the traditional programming style using
exclusively {FUNCTION} blocks, this way at each moment in the execution there will only 
be one process.

After programming in this way, the statement {#1029,FRAME} converts in exactly the same order
as it {converts to video}. Logically, if there is only one process executing, when it executes 
this order the system will show the following frame of the program.

But, programming this way, could different graphics be shown on screen?.

The answer is yes, because mini-processes can be created which will function as
an instruction of the type "paint the graphic for the following frame" (different to
functions such as {#146,put()}, which paint a graphic forever).

To show a graphic in the following frame a process must be constructed which receives
the necessary visual parameters and only executes the {#1029,FRAME} statement, for example:

{PROCESS paint_graphic(x,y,graph)}ú
{BEGIN}ú
{    FRAME;}ú
{END}ú

After calling this process {a temporal process will be created which will be painted
in the next frame} and then disappear. Other parameters can be sent to this process
(besides {#1123,x}, {#1124,y}, such as {#1131,file}, {#1128,size},
{#1129,angle}, {#1125,z}, ... (See the {#1201,predefined local data}).

It is clear that, after programming this way, a table of sprites needs to be created 
(normally in a global {#1012,structure}) in such way that the program could manage
all the graphics. This may seem difficult, but is the normal way games are programmed
in any other language other than DIV.

{/}

{Applications in the main program.}

The statements which appear between the words {#1086,BEGIN} and {#1091,END} of the main program 
(after the declarations of data), control the {#1015,main process of the program}. 
It initiates the program, draws the images and graphics, controls the menu loops , the game loops 
(creating necessary processes), and closes the program.

From the main program, it can be very useful to call the {FUNCTION} blocks. Because this way
the main program will be temporarily stopped while the program executes the contents of this function.

For example, the presentation sequence can be made in a function, the menu options in other, etc. 
Also, remember that functions can always, after finishing,
return a value with the {#1028,RETURN}{(}<expression>{)}, which can be useful,
for example in the menu to return the option number that was selected.

{Note:} Reaching the end of execution of the main code doesn't mean the execution of the
program is finished, so it will continue if any other processes are still active; if you want to force the 
program to close after this code has finished, you can use, for example, the
function {#129,let_me_alone()} just before the {#1091,END} of the {#1015,main code}, or also the function
{#109,exit()} (in any point of the program).

{/}See: {#1016,Los blocks PROCESS} - {#1000,syntax}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1409,GLOBAL argv[], GLOBAL argc}

{argv[];} // Arguments of the programú
{argc;}   // Number of arguments{/}

You can access the last parameters of the program (normally after executing it from MS-DOS), 
in a similar way to how it is done in the programming language C, in the global predefined 
data {argc} and {argv[]}.

The variable {argc} will contain, after executing the program, a number of parameters.
the min number of parameters is {1}, because the program always counts as a parameter the name 
of the game executable.

The table {argv[]} is a list of {text strings}, and will contain as many elements
as are indicated in the variable {argc}, but the name of the program will always be 
stored in {argv[0]}.

{/}

{Note:} When a program executes from the DIV environment, it will not receive any more 
parameters, just the name of the executable. Therefore these variables will be useful
only for the versions already installed in the programs.

{/}See: {#1200,global data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1410,GLOBAL STRUCT net}

{STRUCT net;}ú
    {device;}      // Connection mechanismú
    {com;}         // communications Portú
    {speed;}       // Speed of connectionú
    {number;}      // Telephone numberú
    {init;}        // Modem initiation stringú
    {mode;}        // Mode (press or tone)ú
    {server;}      // Indicates if the PC is a serverú
    {max_players;} // Max number of playersú
    {num_players;} // Current number of playersú
{END}

This data structure requires you to have extensive programming experience 
to know how to create a game oriented for net connection (you can find out 
more information in the {user's manual}).

It contains data about your PC's net hardware, which are needed in conjunction
with the functions {#180,net_join_game()} and {#181,net_get_games()}.

The structure {net} has only one register. In its different fields
are established the parameters which define the type of connection.

{/}

{device} - Mechanism with which the connection will be established,
it can be one of three values:

 {1} - Connection in one {local net}, with protocol IPX.

 {2} - Connection by cable (only two crews).

 {3} - Modem connection (only two crews).

For the connection mechanism to function the fields of the structure {net} must be initiated, 
because many of these parameters are needed to control the mechanism.

{/}

{com} - communications port used for the connection, it means, the
number of COM mechanism (from COM1 to COM4), indicating it as numerical value between {1} and {4}.

This field only needs to be defined for connections by cable or modem.

{/}

{speed} - speed in bauds (number of bits per second), up to 115000.
This speed must correspond to the cable or modem's capabilities,
and to the amount of data the program requires to run.

This field only needs to be defined for cable or modem connections.

{/}

{number} - Telephone number, of course this field is necessary only for
modem connections.

For example, the telephone number which the modem needs to dial must be assigned with a statement
like the following: {net.number="912345678";}.

{/}

{init} - Initiation string, it is a field only required for modem connections; for example a statement like: {net.init="ATZ";}.

{/}

{mode} - mode in which the modem connection must be established (also only for this connection mechanism), the values can be one of the following:

 {0} - Pulse.

 {1} - Tones.

{/}

{server} - indicates if a PC (computer) is the server. This (field is only for reading, it can't 
be modified).

In a connection, only one PC will have the field {net.server} being the value {1}, this
PC will be the server of the game, and will coordinate and control the most important actions
of the program.

{/}

{max_players} - The max number of players which is allowed per game,
from {2} to {16}. This field is useful only for LAN (local area network) connections,
because in cable or modem connections the max number of players will always be {2}.

This number must coincide with the max number of registers the global
structure has used in its communication parcels between the different PCs.

{/}

{num_players} - The current number of players connected to the game,
from {1} to {net.max_players}. This is a dynamic value, which  changes as (players connect
 and disconnect from the current game) in real time.

The game program must predetermine if players can dynamically enter and exit
from the game as they wish, or if all of them must be connected before the game starts.

{/}See: {#1200,global data} - {#180,net_join_game()} - {#181,net_get_games()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1411,GLOBAL STRUCT m8}

{STRUCT m8[9];}ú
    {z;}      // Priority of impressionú
    {camera;} // Camera identifierú
    {height;} // Camera heightú
    {angle;}  // Vertical angleú
{END}ú

This structure of {10} registers contains certain fields concerning 
the modifiable parameters for {mode 8 windows }. The ten
registers have the same field names, but each one of them
modifies the parameters of a mode 8 window differently
(because up to 10 mode 8 windows can be activated).

A {mode 8 window} can be defined as a region of the screen which shows a three-dimensional
map of sectors.

For a register (from {0} to {9}) of the {structure m8} to have any sense or purpose,
you must first activated its corresponding {mode 8window} (from {0} to {9}) with the
function {#190,start_mode8()} (see this function for more information about mode 8
windows}.

The fields of this structure are complementary to the call parameters for this last 
function. To see a practical example of a mode 8 window, you can look up help about 
the function {#189,load_wld()} or about {#190,start_mode8()}.

{/}

{form of use for an m8 structure :}

To access these fields the name of the field must be preceded 
by the word {m8}, the register number in brackets and the symbol {#1063,. (full stop)}.

For example, if two mode 8 windows are initiated, the number 0 and the number 1, 
you can access to the {camera} variable of both windows with the terminology
{m8[0].camera} and {m8[1].camera}, respectively. When you access mode 8 window number 0 
you can also omit the brackets around the window number, this means, that the variable 
{m8.camera} and the variable {m8[0].camera} are, to all purposes, the same.

{/}

{In continuation a detailed description of each field is shown}

{z} - priority of impression of the mode 8 window, where the plane of depth (layer)that this window 
must be painted in is indicated, with respect to the rest of the processes. By default, this
variable has the value {256} which means that, as processes by default have their {#1125,local z} variable 
set to layer {0}, the mode 8 window will be painted to a plane of further depth, or more to the background, 
with the processes' graphics being displayed in front of the window. To change this situation you can modify the
variable {z} of the window (for example change it to { -1}) or the variable {z} of
processes (for example place it at {257}), then the process graphics will be hidden behind the window.

{/}

{camera} - {#1039,Identifier code of the process} where the camera is situated. To move
the camera which controls the visible region of the mode 8, all you need to do is create a mode 8 process,
 in other words one which has its local variable {#1122,ctype} {=} {#1412,c_m8}, and put its
{#1039,identifier code} in the {camera} variable of this structure.
Then, in order to move the camera's position you only need to modify the local variables {#1123,x}, 
{#1124,y}, {#1125,z} and {#1129,angle} of this process and, for instance, use the function 
{#101,advance()} to move the camera forward.

{/}

{height} - camera height with respect to the process, by default this field
is initialised as {32}. The mode 8 process will be positioned on screen in its vertical
coordinate {z}, its local variable {height} determines the height of the main process, 
and the field ({m8.height}) determines the height of the camera (the user's viewpoint of the process 
with respect to its base).

{/}

{angle} - vertical angle of the camera, the value of this angle is between { -128} and {128}.
It defines whether the camera is pointing upwards or downwards. When {m8.angle} values {0},
which is the default value, the camera will be looking horizontally.

The horizontal angle will be the local variable {angle} of the main process
which is used as the window  camera (which identifier is contained in {m8.camera}).

{/}

See also these other {local variables} with respect to {mode 8}.

  {#1421,LOCAL radius}ú
  {#1422,LOCAL m8_wall}ú
  {#1423,LOCAL m8_sector}ú
  {#1424,LOCAL m8_nextsector}ú
  {#1425,LOCAL m8_step}ú

{/}See: {#1200,global data} - {#190,start_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1412,c_m8}

constant: {c_m8}
{/}

This constant is used to assign to the predefined local variable {#1122,ctype} which 
serves to define the type and number of coordinates (dimensions) a process will have. 
Its value is set to {3}.

This value (3) is the value the variable {#1122,ctype} understands 
as meaning the graphic coordinates are contained in a mode 8 window, a three-dimensional 
sector map which the graphics are shown.

For more information about  {mode 8 windows}, you can access
the function {#190,start_mode8()}, used to activate them.

Other constants exist which are used for other coordinates systems,
here is the complete list :

    {#1167,c_screen} - coordinates of screenú
    {#1168,c_scroll} - coordinates of scrollú
    {#1169,c_m7}     - coordinates of mode 7ú
    {c_m8}            - coordinates of mode 8ú

{/}See: {#1202,constants} - {#1122,ctype} - {#190,start_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1413,GLOBAL STRUCT dirinfo}

{STRUCT dirinfo;}ú
    {files;}      // Number of files in listú
    {name[1024];} // File namesú
{END}ú

This global predefined structure is used as the return value of the function
{#231,get_dirinfo()}, to contain the list of files in a directory (or folder).

It consists of one structure register, which groups one variable
{files} and one table of pointers in the {text strings} ({name[]}).

{/}

{In continuation a detailed description of each field is shown}

{name[]} - The function {#231,get_dirinfo()} only returns the {total number} of files listed;
the names of these files are saved in the global structure, in the table {name[]}
(the first name of file is saved in {dirinfo.name[0]}, the second in {dirinfo.name[1]}, etc.).

{/}

{files} - The {total number} of files listed which this function returns are also saved in this field 
(in {dirinfo.files}).

{/}

The list of file names are always saved in alphabetical order, the function {#213,qsort()} 
can be used to order the structure by other criterion.

{/}See: {#1200,global data} - {#231,get_dirinfo()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1414,GLOBAL STRUCT fileinfo}

{STRUCT fileinfo;}ú
    {string fullpath[254];} // Full nameú
    {drive;}                // Drive letterú
    {string dir[254];}      // Directoryú
    {string name[7];}       // Nameú
    {string ext[3];}        // Extensionú
    {size;}                 // Size (in bytes)ú
    {day;}                  // Dayú
    {month;}                // Monthú
    {year;}                 // Yearú
    {hour;}                 // Hourú
    {min;}                  // Minuteú
    {sec;}                  // Secondú
    {attrib;}               // Attributesú
{END}ú

This global predefined structure is used as the return value of the function
{#232,get_fileinfo()}, to contain the attributes of a file (or subdirectory).

It is a one register structure, which groups different strings of text (data of 
type {#1406,STRING}) and numeric variables (data of type {#1402,INT}).

{/}

{Below is a detailed description of each field is shown}

{fullpath} - Full name (including the path). The file path can be specified completely (beginning with
the root directory of the drive, such as "C:\WINDOWS\...") or relative to the current directory
(starting from where the game executes, such as "MAP\MIOS\...").
In all cases, {fileinfo.fullpath} always returns the full path
from the root directory, including the drive letter.

{/}

{drive} - Drive disk where the file is situated.
The drive disk is returned not as its corresponding letter, but as a number, 
establishing the following correspondence: {1} for {A:}, {2} for {B}:, {3} for {C:}, etc.

{/}

{dir} - The directory where the file is situated. This string not only returns 
the name of the folder or directory where the file is, but also the full path,
beginning with the current directory and listing all the directories in the path (for example "\DIV\MAP\")
relative to the directory of the program executable. 
The return value always has an inverted bar (\) at the beginning and at the end.

{/}

{name} - the filename, this field ({fileinfo.name}), returns the
name of the file, without its suffix/extension, up to a maximum of {8 characters}.

{/}

{ext} - Extension of the file. The extension of the file is returned in this field, 
in a string which includes the point which separates the filename from its extension.

{/}

{size} - file size, this value will be {0} if the information refers to a directory. 
The size returns as a number of simple data, this means, as a multiple of data like 
{#1402,INT} (number of bytes in multiples of four (4,8,12,16 etc...)). It is possible to 
change this relationship by modifying the global variable {#1420,unit_size}).

{/}

{day} - Day of the month of the last actualisation of the file.

{month} - Month of the last actualisation of the file.

{year} - Year of the last actualisation of the file.

{hour} - Hour of the last actualisation (from {0} to {23}).

{min} - Minute of the hour.

{sec} - Second of the minute.

{/}

{attrib} - Attributes of the file, they indicate the characteristics of the
file, if it is a system file, a read-only file, an archive file ,etc. 
This value is the sum of the following constants:

  {0} - Normal file.ú
  {1} - Read-only file.ú
  {2} - file archive.ú
  {4} - System file.ú
  {8} - Volume Label.ú
 {16} - Subdirectory.ú
 {32} - file speed.ú

For example, for a system and archive file, the value of {fileinfo.attrib}
would be {6} (2 archive + 4 system).

{/}See: {#1200,global data} - {#232,get_fileinfo()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1415,GLOBAL STRUCT video_modes}

{STRUCT video_modes[31];}ú
    {width;}  // Width of modeú
    {height;} // Height of modeú
    {mode;}   // Number of modeú
{END}ú

In the global predefined structure {video_modes}, at the beginning of all programs, 
the {list of VESA modes} supported by the PC's video adaptor are detailed (all of them 
of {256 colours}), up to a {maximum of 32} (from [0] to [31]).

The number of found VESA modes is saved in the global variable {#1419,num_video_modes}.

This information is generated by the system automatically, so you don't need
to call any function. For all found modes the following information is registered :

{width} - Number of horizontal pixels of the video mode.

{height} - Number of vertical pixels of the video mode.

{mode} - Number of mode. This value can be used directly as a parameter for the function {#157,set_mode()}.

Once the {width} and {height} of the video mode which you want to activate has been selected,
and therefore the {number of registers} its structure shall consist of has been defined, 
you must then activate it by calling the function with :

  {set_mode(video_modes[}<number of register>{].mode);}

{/}

{Note:} Besides the registered modes in this structure, there also exists a list
of standard video modes, which numbers are contained in the constants
{#1150,m320x200 ... m1024x768}.

{/}See: {#1200,global data} - {#1419,num_video_modes} - {#157,set_mode()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1416,GLOBAL channel[]}

{channel[31];} // Use of sound channels{/}

The global table {channel} maintains information about the use
of the different (up to 32) sound channels of the audio system.

Each time when you play a sound with the function {#159,sound()}, it is sent 
to one of these channels. And if the playback of one musical module with the 
function {#216,song()} is initiated, a determined number of channels (up to 24) 
are reserved for it.

In this table, each position represents one of these sound channels,
and the system sets the value of each position to {1} when its respective channel is used.

The function {#256,change_channel()} allows you to modify the parameters of
each one of these channels.

{/}

{Note:} The system will never automatically set the value of the positions of the table {channel} to {0},
this must be done with the program code, and similarly the program must determine
when a channel is used once more.

{/}See: {#1200,global data} - {#256,change_channel()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1417,GLOBAL vsync}

{vsync=0;} // Wait the vertical retrace{/}

The global predefined variable {vsync} defines a logical value (0 or 1) which
indicates if it is necessary to wait before doing a {vertical retrace} the following
frame is converted to video (when all processes execute the statement {#1029,FRAME}).

By default this variable will be set to {0}, which means, the process does not delay the
vertical retrace before converting each frame to video.

To indicate to the system that it must delay the vertical retrace you must set
this variable to {1} (with the statement {vsync=1;}).

{/}

{Note:} Delaying the vertical retrace can make movements more soft to the eye 
(this effect is visible most of all in the panoramic effects, see {#163,start_scroll()}), 
 but delaying the retrace will also slow the programs down in the great majority of cases.

{/}See: {#1200,global data}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1418,GLOBAL draw_z}

{draw_z=-255;} // plane of depth of the primitive graphics {/}

The {primitive graphics} are such things as straight lines, rectangles, circles,
etc., which are painted with the function {#249,draw()}.

In this global variable the plane of depth in which the primitive graphic must appear
on screen is indicated, this means what must appear in front and what must appear behind
on screen.

The plane of depth can be any whole number inside the range ({#1177,min_int} ... {#1178,max_int}), 
the bigger the number the more to the background the frame will be situated .

The process' graphics have their {#1125,local z} variable set to {0} by default, 
the texts {#1106,text_z} are set to { -256} and the mouse pointer has its z - value
{#1100,mouse.z} set to { -512} by default.

This means, that by default, if these values are not modified,
the primitive graphic will appear in front of the processes, but behind the mouse pointer 
and the texts.

{/}

{Note 1:} The variable {draw_z} is {#1006,GLOBAL} for all primitive graphics, in other words, 
they cannot be represented in different planes.

{/}See: {#1200,global data} - {#249,draw()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1419,GLOBAL num_video_modes}

{num_video_modes;} // Number of detected video modes{/}

The global variable {num_video_modes} contains the number of VESA video modes
which were detected in the system's graphics adaptor.

The parameters of each one of these modes are registered in the global structure
{#1415,video_modes}, therefore the variable {num_video_modes}
defines the total number of registers defined in this structure.

{/}

{Note:} Besides the modes registered in this structure, there exists a list
of {10 standard video modes}, which numbers are contained in the constants 
{#1150,m320x200 ... m1024x768}.

{/}See: {#1200,global data} - {#1415,STRUCT video_modes} - {#157,set_mode()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1420,GLOBAL unit_size}

{unit_size=4;} // Minimum unit of reading/writing{/}

The global predefined variable {unit_size} indicates the minimum
unit of reading and writing for the functions of files situated in {handles}.

By default it always has the value {4}, because 4 bytes is the unit size 
of the standard data {#1402,INT} (32 bit whole number), and each piece of  data 
has 4 bytes assigned in memory (see the {#1407,assignation of data in memory}).

The functions which count up the number of these {unit_size} blocks a variable contains 
are the following:

  {#225,fread()}ú
  {#226,fwrite()}ú
  {#227,fseek()}ú
  {#228,ftell()}ú
  {#229,filelength()}ú

And also the field {size} of the global structure {#1414,fileinfo}.

{/}

The minimum size of 4 implies that it is impossible to write to or to read from any files
whose length is not a multiple of this number.

This size can be changed; for example assigning {1} to {unit_size} (with the
statement {unit_size=1;}). By doing this, all {lengths} of the
previous functions will be indicated in bytes (and not in units of data).

However, after changing the unit size, you must remember the following:

- {#1094,SIZEOF()} will continue to return the data length (in units of 4 bytes).
For example, to save a table on the drive it will be not enough to indicate {sizeof(}<table>{)}
as its length, you will also need to multiply this value by 4 (if its {unit_size} is 
defined  as {1}).

- The functions of files {#155,save()} and {#130,load()} (which are not functions
based on the file {handles}) will continue to indicate file length in data.

- The functions of dynamic memory {#257,malloc()} and {#258,free()} also
will continue to work with the length in data, therefore adjustments must be made 
to cater for working with both groups of functions.

{/}See: {#1200,global data} - {#1407,Alignment of data in memory}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1421,LOCAL radius}

{radius;} // Radius (width) of the mode 8 processes {/}

This predefined variable is {#1007,LOCAL}, that means that each
process will have their own value in its variable {radius}.

This local variable is used exclusively in mode 8  processes (which have assigned 
{#1412,c_m8} to {#1122,ctype}).

{radius} indicates the radius, or horizontal size, of the process.
The system requires this value to calculate any collisions with the limits outlining 
the borders of the sectors of the three-dimensional map.

The smaller the value of {radius} is for a process, the nearer it can be to its walls 
and, therefore, the bigger the pixels (or texel) of its textures will be.

{/}

{Note:} For more information about mode 8 windows, see the global structure
{#1411,m8} and the function {#190,start_mode8()}, which is used to initiate regions of this type.

{/}See: {#1201,local data} - {#190,start_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1422,LOCAL m8_wall}

{m8_wall;} // Wall number of the sector map {/}

This predefined variable is {#1007,LOCAL}, that means that each
process will have its own value in its variable {m8_wall}.

This local variable is used exclusively in mode 8 processes 
(which have assigned the value {#1412,c_m8} to {#1122,ctype}).

the system stores in the variable {m8_wall}, the number of the wall
the process has just collided against.

This information can be useful to detect distinct active zones
inside a map of sectors (such as ports, interrupts, etc.).

{/}

{Note:} For more information about mode 8, see the global structure
{#1411,m8} and the function {#190,start_mode8()}, which is used to
set up regions of this type.

{/}See: {#1201,local data} - {#190,start_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1423,LOCAL m8_sector}

{m8_sector;} // Number of sector in where the process is{/}

This predefined variable is {#1007,LOCAL}, that means that each
process will have its own value in its variable {m8_sector}.

This local variable is used exclusively in mode 8  processes 
(which have assigned the value {#1412,c_m8} to {#1122,ctype}).

In {m8_sector} the system automatically saves the number of
the sector over which the process is situated, inside the map.

The information about the sector number can be useful to program events
where a process enters the specific sector.

{/}

{Note:} For more information about mode 8, see the global structure
{#1411,m8} and the function {#190,start_mode8()}, which is used to
initiate regions of this type.

{/}See: {#1201,local data} - {#190,start_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1424,LOCAL m8_nextsector}

{m8_nextsector;} // Sector the process is directed towards{/}

This predefined variable is {#1007,LOCAL}, that means that each
process has its own value in its {m8_nextsector} variable.

This local variable is used exclusively in mode 8  processes 
(which have assigned the value {#1412,c_m8} to {#1122,ctype}).

In {m8_nextsector} the system automatically saves the
sector a process is directed towards. This means that, when the
process collides with one of the map walls (borders), the system checks 
to see if any other sectors exist beyond this boundary, and if so, will store 
its number in this variable.

This information can be useful, for example, to obtain the
heights at which this sector is situated (See {#193,get_sector_height()})
and, in this way, can check if the program must adjust its height, and by how much,
to proceed to the named sector.

{/}


{Note:} For more information about mode 8, see the global structure
{#1411,m8} and the function {#190,start_mode8()}, which is used to
initiate regions of this type.

{/}See: {#1201,local data} - {#190,start_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1425,LOCAL m8_step}

{m8_step;} // height to which can lift the process{/}

This predefined variable is {#1007,LOCAL}, that means that each
process will have its own value in its variable {m8_step}.

This local variable is used exclusively in mode 8 processes 
(which have assigned the value {#1412,c_m8} to {#1122,ctype}).

In {m8_step} the maximum height which the process can be raised to reach the sectors is given, 
as "the height of step" which this process can rise by.

When a process comes across a more elevated sector, the system
checks with help of this variable to see if the process can reach this elevated sector, 
if the answer is yes the new height of the process will be set automatically and, 
but in the contrary case, the process will stop (it will collide with the boundary that
separates both sectors).

{/}

{Note:} For more information about mode 8, see the global structure
{#1411,m8} and the function {#190,start_mode8()}, which is used to
initiate regions of this type.

{/}See: {#1201,local data} - {#190,start_mode8()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.1426,GLOBAL fps}

{fps;} // Number of frames per second{/}

The global predefined variable {fps} (frames per second) maintains the
number of frames per second which the program shows.

This variable is set by the internal processes of DIV Games
Studio automatically. It doesn't determine this value in an instant, but
rather takes an average over the last few seconds.

The function {#156,set_fps()} allows you to set the number of frames
per second of the program, but this establishes the ideal number
of frames and not the actual (which is stored in {fps}).

This means, that this variable serves as a counter to determine how many frames
per second, on average, are converted to video.

{/}

{Note:} The variable {fps} contains data only for reading, and its value cannot be
modified by the program.

{/}See: {#1200,global data} - {#156,set_fps()}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2000,Welcome to DIV 2015!}{+1,1}{-}

This help file outlines the basic concepts required in the usage of the DIV Games Studio
development environment.

Using this electronic help you can access a lot of information about
this environment, but even so, the learning of the programming language and the menu options
are described only in the {User's manual}.

{/}

{Note:} If you are using the DIV programming environment for the first time,
you should know that in order to exit from DIV (or any game created with DIV),
you should use the key combination {ALT}+{X}.

{/}

  {What's new in DIV3?}

  - {#2001,New language commands and variables}ú
  - {#2002,New environment aspects}ú

  {introductory chapters}

  - {#1,How to use the help system}ú
  - {#1300,Frequently asked questions (FAQ)}ú
  - {#2003,Resolution of configuration problems}ú

  - {#2004,What is DIV Games Studio?}ú
  - {#2005,Working with windows}ú
  - {#2006,Types of windows}ú
  - {#2010,Fixing a video mode}ú
  - {#2011,The configuration window}ú
  - {#2012,First contact with the language}ú
  - {#2013,Debugging your program}ú

{/}

DIV Games Studio appeared on the market in December 1998 as the first development environment 
with a programming language designed exclusively for games programming.

In the beginning, our wish as developers was not the creation of a
professional environment, but more to create a simple and interesting environment which
could serve as an introduction to the fascinating world of games development;
something like a "game to make games" in which any person could learn how to program.

The very good response to DIV1 leads us to make this second version of the environment,
in which the same philosophy is maintained.

A great number of received opinions, criticism and wishes permitted us to create 
the new DIV Games Studio with improvements in all areas. We intended to improve, although only 
a little, all areas of the environment. In this sense there are major differences with the 
previous version, (and they are very practical and logical ones).

We would like to thank everyone who has supported our ideas and this product.
At the time of releasing this second version we don't know if an alternative to the DIV environment
exists, which although on the one hand seems regretful, it does give us pride in the knowledge
that such an environment exists here.


{The DIV Games Studio team.}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2001,New language commands etc.. in DIV version 3.0}{+6,1}{-}

{More extensive programming language.} The programming language has been enlarged, including
many new characteristics and internal functions, the more prominent of which are detailed
below.

{/}		

{+150,0}The {compilation options} are a new characteristic of this version, 
which allow you to adapt the process of compilation to the individual requirements of
each project (see {#1400,Compiler_options}).{-}

{+150,0}In addition to the first version's data (which are now known as {#1402,INT}), 
there now also exists data of the types {#1406,STRING} (strings of text), {#1403,WORD} (16 bit 
positive whole number values), {#1404,BYTE} (8 bit positive whole number values) and {#1405,POINTER} 
(pointers, to all these types).{-}

{+150,0}Also 2 or 3 dimensional {tables} and {structures} (also of any of these
types) can be defined (see the {#1011,declaration of a table}), and
the structures can be initiated globally (see {#1012,declaration of a structure}).{-}

{+150,0}The new {#1408,FUNCTION blocks} behave in a similar way to the functions of
other programming languages, they execute sequentially (and not parallel as the processes do),
not returning until they are finished.{-}

{+171,0} Different aspects of the {program debugger} have been improved, with new functions and
support for new types of data. Also new are the {time profiles}, which you can access from the 
debugger using the keyboard command {F11}, here you can observe the time taken in the 
execution and painting of each process.{-}

{+152,0}The {error control system} for the programs has been improved, creating a 
more stable and better executable, there also now exists the possibility
to ignore certain execution errors to allow the program to continue running 
(see the function {#240,ignore_error()}.{-}

{+157,0}{new functions of file management} have been added, which give you 
much more flexibility and potential over the way a program handles files; 
see for example {#223,fopen()}, {#227,fseek()}, {#231,get_dirinfo()}, {#235,chdir()}, 
{#237,remove()}) or {#238,disk_free()}.{-}

{+158,0}Besides support for CD-Audio music and digital effects, there now exist
different functions for the reproduction / playback of music modules {MOD}, {S3M} and {XM}
(see {#214,load_song()}, {#216,song()} or {#218,set_song_pos()}).{-}

{+163,0}{Optimised code generator.} The code generated for the programs is better and
faster (at least 60%) than the previous version. Also the created programs {EXE}
are much smaller.{-}

{+164,0}{Functions for playing games over the internet or other network.} With DIV Games
Studio 2, it is possible to create games to play by {cable}, {modem} and 
{local net IPX}. This functionality is very simply controlled by the functions 
{#180,net_join_game()} and {#181,net_get_games()}.{-}

{+165,0}Also new is the integration into the language of the ability to 
manipulate strings of text, with data of type {#1406,STRING}, many new
functions (such as for example {#203,strcat()}, {#206,strchr()}, {#209,upper()}
or {#211,strdel()}) have been added along with adapted syntax to work with 
string expressions directly in the language.{-}

{+166,0}{Dynamic memory support}. It is possible to ask for and free up memory
dynamically whilst a program is running, thanks to the functions {#257,malloc()} and
{#258,free()} (complemented with the new data type {#1405,POINTER}).
Also the function {#239,memory_free()} allows you to determine the free disposed memory 
in the system at a certain point in the program.{-}

{+167,0}You can also now {order} and {disorder} data,
with the simple function {#213,qsort()} which permits you to order
and disorder data structures, taking any field as its index.{-}

{+168,0}Another new feature is the ability to {search for a path}. This is achieved with 
different functions (see {#185,path_find()}) which, for instance, allow you to find the shortest
and best available routes between two points, avoiding any obstacles.{-}

{+169,0}{Compression of data.} Everything is more compact; the
executables and installed data (can be created as {compact and protected installations}).
Also functions of compression are included in the language (see {#262,compress_file()}).{-}

{+170,0}{New mode 8.} A new mode with up to 10 screen regions, which allows you to visualise 
maps of three-dimensional sectors. These three-dimensional environments also include an 
integrated editor in the environment and many specific functions (see for example
{#190,start_mode8()}, {#192,set_sector_height()}, or {#196,set_fog()}).{-}

{/}

{+176,0}{And much more.} What's new in the language doesn't stop here,
there are many other improvements and functions (besides the bugs in the original version
which have been fixed). Outlined below we describe what else is new in the DIV programming
language.{-}

- A new function, called {#266,force_pal()}, allows all {graphics loaded in a program 
to adapt automatically to a palette} at the time of execution.

- Functions for data encryption also exist, such as {#259,encode()}, 
{#260,encode_file()} and {#261,decode_file()}.

- The {library declarations} reside now in the headline of the program,
just after the {PROGRAM} statement (see {#1014,IMPORT}).

- It is now possible to create programs in {much more video modes}, because the available
VESA modes can also be detected (See {#1415,video_modes}).

- In this new version {assignations inside a condition} are prohibited, 
to simplify the programming for less advanced users. However this can be changed 
(see {#1400,_extended_conditions and _simple_conditions}).

- Now it is possible to define the {max number of processes} which can be active in the 
program during execution (see {#1400,_max_process}).

- It is now possible to define {literals over many lines}, to do this the text must only be 
divided into distinctive literals, and put successively (see the {#1047,limitation symbols of literals}).

- The {sound system} is completely new, and it is now possible to play back {OGG and WAV files of better quality} 
in the programs (See {#134,load_sound()} and new fields of the structure {#1104,setup}). 
Also new sound functions such as {#256,change_channel()} or {#221,is_playing_sound()} have been added.

- Also it is now permitted to use directly {frames of PCX format} in the
programs (See {#174,load_pcx()}), and to save these files (See {#241,save_map/pcx()}).

- Functions now exist to fix {a colour of the palette}, such as ({#179,set_color()}) and also
to localise colours ({#264,find_color()}).

- Trigonometric {mathematical functions} as {#242,sin()}, {#243,cos()}, {#244,tan()},
{#245,asin()}, ... have been added.

- Also a {primitives painting tool} has been included to create distinct graphics on screen:
such as lines, rectangles and boxes, circles, ... (See {#249,draw()}).

- {other functions} have been added which increase the existing possibilities
in the creation of programs, such as {#212,screen_copy()}, {#253,write_in_map()},
{#254,calculate()}, {#265,load_screen()}, {#183,xadvance()}, {#188,new_map()}, ...

- Also you can count the {frames per second} (See {#1426,fps}), obtain the {parameters of the program} (See
{#1409,argv[]}), delay the {vertical retrace} (See {#1417,vsync}), control the
mouse in the programs better (See {#1100,mouse.cursor} and {#1100,mouse.speed}), etc.

{/}

And of course, all functions, data and possibilities which were available in the first
version of DIV Games Studio, still remain! {:)}

{/}{See also:} {#2002,New graphical environment changes}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2002,New additions to the environment in version 3.0}{+6,1}{-}

{More flexibility and simplicity in use.} The development environment of DIV Games
Studio has evolved into several smaller modules, and together they form
a more intuitive structure than in the previous version.

{/}

{+151,0}{A new help.} The help section has been restructured, and of course covers
 everything that's new in the DIV language. The window includes a new navigation bar.{-}

{+154,0}{Multiple paintbrush sizes.} In the graphical editor paintbrushes of various 
sizes and forms can now be selected, either in monochrome or in greyscale. 
By pressing the key {T} you access the new dialogue; new paintbrushes can also be added, 
adding them to the file {BRUSH.FPG} of the {SYSTEM} directory.{-}

{+155,0}{Cover a Picture with coat or textures.} In the graphical editor using the
key {U} you can access the new dialogue where you can select any
of the maps from the desktop as a texture to paint onto the surface of an image 
(with the key {X} you can see and allocate this texture). The {aerosol} tool has
been improved, as has the bar of shade {checkpoints}, and also {new keyboard commands}
were added (such as {K} to copy a graphic in a window, or{ +/-} to change the checkpoint).{-}

{+156,0}{Graphical visualisers.} Almost all windows to open files
can display a square window {thumbnail} which allow you to view the contents
of these files before they are loaded. It is also possible {to load different
files at once} highlighting them with the mouse while the {control} key is held down
(the {Shift} key allows you to highlight isolated consecutive graphics).{-}

{+157,0}{Developed system of files.} In this version the internal management of the FPG files 
has been improved; errors have been eliminated, thumbnails of the contained maps can be viewed,
lists can be printed, a complete FPG file transferred to a map and vice versa.{-}

{+159,0}{Sound effects editor.} The audio has been completely revised, permitting many more 
operations, formats and including a {mixer} and {effects editor} of the sound. You can access 
this editor from the sounds menu.{-}

{+160,0}{Evaluation of expressions.} Now you can access the new {calculator} windows
(from the system menu) to evaluate numerical expressions while programming, without 
having to exit from the DIV environment.{-}

{+161,0}{Sprite Generator.} The character generator is also a new characteristic of this version.
It was made to create a base on which the realistic pictures of humans and animations can be 
realised. These photo-images can then be modified in the graphical editor.{-}

{+162,0}{Three-dimensional maps editor.} A menu for 3D maps, their editor
and all functions related to them in the programming language, are also a new characteristic of 
this version of DIV Games Studio.{-}

{+171,0}{Time profiles.} From the program debugger you can access, by pressing F11, the time 
profiles of the program. These statistics indicate the time consumption of a process during 
the executing of the program, and allow the manual optimisation of the speed of these programs.{-}

{+153,0}{New examples.} Several sample games and programs
developed by users of the previous version of DIV Games Studio are included in this version.
Also, on the CD-ROM you can find multiple shareware utilities available for free use in this 
development environment.{-}

{+172,0}{Facility of impression.} This version of DIV Games Studio allows you to print,
in addition to a program list, lists of the graphics contained in the FPG file
and the electronic help pages.{-}

{+173,0}{Volume Controls.} Amongst the improvements included in the audio system,
there now exists a better volume level control, in the environment and the program. 
In the CD player window there is a small button which gives you access to the mixer.{-}

{+174,0}{Library of graphics.} The library of graphics included in the program has been
enlarged and better structured. Also now maps can be imported of any colour depth in the 
formats BMP, PCX or JPG.{-}

{+175,0}{New installation system.} The installation system of the program
has been completely re-done, generating a more compact and protected installation, 
and using a {more intuitive and graphical adaptable interface}.{-}

{/}

{+176,0}{And much more.} Many more small improvements in the environment  exist,
many of them imperceptible, but they make the environment more powerful and easy to use. 
Outlined below you can see in detail the more relevant of these.{-}

- {The process of entering and exiting} from the environment {has been optimised}, as has
the execution of programs from it, also the environment loads faster and all delays between processes 
are shorter.

- The program editor is now {in colour}, highlighting the key-words of the language, 
also you can define more clearly, for example, the tabulation size.

- Now, after loading the environment, you have the option to {continue with the previous
session} or {start a new one}.

- It is possible to select {more visualisation modes} for the environment, depending on the modes
supported by the installed video-card and VESA adaptator.

- A {colour palette editor} simplifies the generation of explosions (which
can now be aborted) and the preparation of the background (a preview is now shown).

- The {speed of the mouse pointer} can be configured using the small bar
presented in the configuration window of the system menu.

- In the fonts windows {a sample of letters appears}, which indicate which collection 
of characters are selected.

- It is possible to generate fonts of {letters with shadows or outlines}, by simply creating them with
an outline of 1 pixel of the background colour.

{/}{See also:} {#2001,New features of the programming language}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2003,Resolution of configuration problems}

{General resolution of audio problems.}

If the audio system couldn't be initiated, it is most likely because of a sound card
conflict. This problem is often produced by one of these causes :

- The card is being used at the same time by {another program}. It cannot
initiate the sound if any other program is reading or writing
data via the card (such as an  MP3 player or sound capture device).

- A problem can occur with the {auto-detection} of the soundcard's parameters.
You must execute the sound configuration program or define these values in the 
variable BLASTER or ULTRASND of the system environment (you can find
more information in the user's manual for DIV Games Studio 2).

- Because the soundcard is {incompatible} with DIV. 
If the card is not a GRAVIS (tm) or SOUND BLASTER (tm), it may be incompatible
with DIV Games Studio. The majority of commercial cards are compatible
with SOUND BLASTER, but may not be 100% compatible and may present some problems.

If your particular problem doesn't fit into any of these three cases,
you must first execute the sound configuration program. This can be
called from DIV by pressing {F4}, or loading the program {SETUP.PRG} from the
{SETUP} directory , and executing it with the key command {F10}.

In this program you must input the parameters of your sound card.
To obtain these parameters in MS Windows it is probably best to consult
the soundcard's handbook, but normally you can also access them the following way: 
pressing with the right mouse button in "My Computer", activating the Properties menu \
Device Manager \ Sound, video and games Controllers,
selecting your audio card (normally one compatible with "Sound Blaster" or "SB") 
and pressing the Properties button. Then a dialogue will appear with the 
characteristics of your sound card where, in the Resources pane you'll find:

{1.} The IRQ number of your card as an "interrupt request value".

{2.} The DMA and of DMA2 (also denominated as HDMA or DMA16) numbers 
which are the two "direct memory access" values.

{3.} The port number as the initial value of the first "enter/exit value".

Also you can try to configure the sound system indicating in the 
configuration program a simpler card (previous to yours). For example, if you
have a soundcard compatible with a {Sound Blaster AWE 64} or {128} and cannot
get the sound system to initiate; try to configure the system as if it were
a {Sound Blaster 16}, or {Sound Blaster Pro} card.

As the last recourse, if it is not possible to configure the sound in your system,
you must deactivate it. For this you must execute the configuration program
and select the value {<Without sound>} in the field which defines the type of card.
Then press the {<Save>} button to establish this configuration and deactivate
the sound in DIV Games Studio 2.

If you are unable to hear the sound effects in your program on your PC, you probably have a sound 
card which is not 100% compatible with the Sound Blaster or Gravis Ultrasound family of cards. 
Consult your dealer.

{Note:} The reproduction of CD-Audio is independent of the digital sound system
whose configuration is described here; therefore CD music will be reproduced
although the sound system may not have been correctly initialised.

{/}

{Video or Graphics card Problems.}

If at any time DIV enters a resolution which cannot be displayed properly, the first thing which 
must be done is to exit from the environment by pressing the key combination {ESC+control} 
(or {ALT+X} and {Enter} in succession) and, then, re-enter the program in safety mode. To enable this 
mode you must, from the {MS-DOS} command prompt and in the directory (FOLDER) in which the program 
was installed , execute the following command:

{  D /SAFE}ú

This way you will load up the environment in a low resolution (in 320x200, the most compatible mode),
from this mode you can attempt to put in other resolutions which will be
compatible with your graphics card and with your monitor.

On those PCs where the graphics card is not compatible with the standard
VESA system you must install VESA driver for the card. For this, you must contact your 
card supplier or technical support of your hardware for the driver. ( A driver is a small program 
which must be installed on the PC to give support for some hardware or utilities such as, 
in this case, your video or graphics card).

{/}

{Problems with the mouse.}

If the mouse is jumping on the screen, instead of moving smoothly from point to point, 
it is because you're using an incorrect or out of date mouse handler (the mouse driver is not
functioning properly). You can resolve this problem in one of these ways:

{1.} Contact with the supplier of your PC to obtain the latest driver for your mouse.

{2.} Change the resolution of the program (with the option {system\video mode})
to another which does not produce this problem.

{3.} (MS-DOS, only for advanced users). Comment out the line in your autoexec.bat file 
in which the mouse driver is loaded. This can be done from the DIV environment, by loading this file 
(situating on the root directory of your hard disk) with the key command F4 
and adding the word REM at the beginning the line which loads the mouse driver 
(a line which normally finishes with the text ...  mouse.com). Then press
F2 to save the file, close it (pressing on the upper left corner
of the text window), exit from DIV (ALT+X) and re-start your PC. If
you then have problems with another program which requires this driver,
return to edit the same autoexec.bat file and remove the word REM which was added.

{/}

{Solution of possible installation problems.}

If you find any problem, check the minimum requirements indicated in the program. 
If you have doubts about one of the elements consult the technical support of your PC 
or your PC supplier.

The most likely problem is reading from the CD-ROM drive; for this, clean the surface of the 
DIV Games Studio CD carefully with a clean and dry duster, and attempt the installation of the 
program once more.

{Manual installation}

If you couldn't install the program correctly and have a lot of free space on the 
hard disk of your PC (sufficient to allow a maximum installation) you can attempt a manual 
installation of the program, by following these steps:

{MS-DOS users} - Supposing that your CD-ROM disk drive is the letter D:, select the CD-ROM 
drive with the following command:

{  D:}

And press Enter. Then introduce the following commands (supposing that your hard disk is the C:
drive):

{  XCOPY DATA\*.* C:\DIV\*.* /S}ú
{  C:}ú
{  CD \DIV}ú
{  DEL INSTALL*.*}ú

Pressing Enter after each one of these commands. If you have sufficient space the
program will be installed without any problem, introduce this command to execute it afterwards:

{  D /SAFE}ú

For the next steps in executing the program, follow the conventional instructions.

{Users of Windows 95/98} - Open the MS-DOS prompt (double clicking on its icon, or via
start menu \ programs \ ms-dos) and follow the instructions for MS-DOS users. For 
the remaining executions of the program you can use the instructions that come with the
operating system, remembering that the program will be installed in the DIV folder
of your hard disk.

{/}

If you cannot get the program to function correctly with these suggestions, then contact
your FastTrak Technical Support, its tel. is (44) 1923 495497 (01923 495497 for UK users) 
during normal office hours {Monday to Friday} from {09:00 to 17:30} or go to {http://www.div-arena.com}
and try the message forums or the live chatroom.

Remember though, that as DIV Games Studio is a big selling product with limited technical support
facilities, it is best to first try and follow carefully all instructions and check the website 
before making a call to this service.

{Important:} This technical support service does not provide any consultation regarding
the programming language, because we could not give any more advice than is contained in the 
{help file} and the {user's manual} of the program. With these you can find a solution 
for any doubts regarding the programming language you have.

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2004,What is DIV Games Studio?}{+1,1}{-}

It is a graphical environment which integrates a new programming language
for videogames together with other utilities such as a painting tool, 
tools to create fonts, palettes, etc.

The programming language was made exclusively for the creation
of games and, as you can see, allows you to obtain very good results with
very short and simple programs.

It is not necessary to know how to program to use it, DIV was designed so that the user 
could learn to program with it. 
It has a user-friendly environment to make you lose the fear of the word "programming" ...

{/}See: {#2005,Working with the IDE windows} - {#2000,Introduction to DIV 3.0}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2005,Working with windows}

The windows, can be moved to any position on screen if you press
on the title bar with the mouse and drag it to the new position.

{Title bar.} - Is the top zone of the window, where the name of the window is shown 
in white against a blue background. When the name of the window appears in grey scale,
it is because the window is not selected (as another window is currently selected ), 
to select it press on it.

{Drag.} - This term is applied inside the graphical environment to mean the action of holding 
the mouse button down over an object, moving it to the new position, and finally releasing the
mouse button.

To ask the system to place the window automatically, you must double click
with the mouse on the title bar of the window. If the system
finds a better position for the window, it will move it there.

The windows can be in {different modes}, and therefore their functions and operations will
be distinct from each other. These modes are described below :

{1. Active windows:} Are those which, normally, have an illuminated title bar, in white letters 
against a blue background and are situated foremost on the desktop.

{2. Inactive windows:} These type of windows have a dark title bar, in black
letters against a dark grey background. To activate one of these windows simply click
on them with the mouse.

{3. Windows in the second plane:} These are windows which are obscured; this is because
they are at least partially, covered by other windows. With these windows you can't 
interact with them until they come into the foremost plane by clicking on them with the mouse.

{4. Icons:} The icons are the minimised windows, this means, the windows which were
reduced temporarily. The icons don't have a picture, just a button
with the sign "+" followed by the title of the window.

{Note:} To drag the graphics (to a file, to the desktop, etc.) don't press
on the title bar of the window, but on the contents of the window. This means, 
you must press the mouse button in the middle of the window and, without releasing
the mouse button, move it to the new position.

{/}See: {#2006,Types of windows} - {#2000,Introduction a DIV 2}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2006,Types of windows}

 The windows can be classified by their function, into the following groups:

{1. Interactive dialogues:} These are windows which are used to impart
information to the user; there exists a huge variety of them, which you'll see in 
the respective options.

{2. Error message Windows :} Are the dialogues in which the title bar appears in white
against a red background and inform the user about the problem which has arisen.

{3. Options Menus :} These menus contain the list of options which call other
menus, windows or dialogues after they have been clicked on. All these menus stem from the
main menu. Some menus may have certain options disabled (a pointer is shown with the 
prohibited symbol if you place the  mouse over it); this is because
these options interact only with the specific types of windows, and there is no
window of this type currently active (it must be created or loaded beforehand).

{4. Programs:} In these windows the programs are created and are effectively text windows.
To edit a program its window must be activated (only one program window can be activated at 
any one time). The text is similar to that of other text editors (supports the standard DOS 
command EDIT).

To ask for help in a program about a specific word of the programming language you must 
place the blinking cursor (not the mouse pointer) on it and, then,
press the key {F1}. These windows can be changed in size by pressing on the
their lower right button and dragging with the mouse or by pressing the keys {control}+{Z}.

{5. Maps or graphics:} These windows are those which contain a map (bitmap) or
graphic and are controlled with help of the menu of maps.
They can be loaded from a MAP file (proper format), or imported from
a PCX, BMP or JPG file. To edit the graphics you must double click with the mouse  button 
in the centre of these windows thus opening, in this way,
the graphics editor (described in the {user's manual}). These graphics can
be dragged to the background (to make a copy), to another graphic (to insert in them), 
to a file of graphics (to include them) or to the trash (to delete them), to drag them you
must drag from the centre of the windows, and not from the title bar.

{6. 3D Maps:} These are vector maps created in the 3D maps editor,
how a collection of closed polygons is shown in their window representing the 
vertical section of a plan. Its creation is not a trivial matter, and is explained in
the {user's manual}. These maps are saved on disk in files with the extension WLD.

{7. FPG or graphics library files :} These windows show the contents of one
file on the drive. These files are libraries or collections of graphics used in the
game. Their purpose is to load a large quantity of maps into a game. They have two
basic modes of function, activated with the help of buttons named "Info" and "Images" 
along the bottom of the window. When the "info" button is not activated (by default), graphics
can be created and moved, or dragged (to the background, to other files, maps or the trashcan).
When the  "info" button is activated, the graphics codes and their
descriptions are displayed with a thumbnail image. These FPG files are always 
controlled from the FPG file menu.

The FPG file windows are always just a reflection of the "graphics file"
contained on the hard disk of the PC, and therefore can be closed at any time,
without need to save them before. Their contents will never be lost.
The option {Files \ Save} allows you to make a copy of the FPG saving it under another
name (as temporary or security copy).

{8. Fonts of letters:} The fonts or letter types are small windows which
display the current typography. You must click on them with the mouse to see an
example of the font in real size. They correspond to FNT files (official font format)
and are controlled by the fonts menu, from which you can access the fonts generator, 
which is the tool used to create new fonts of letters. The fonts of letters are used 
inside the painting program and in the programs to write texts.

{9. Sound effects:} These windows represent on screen a PCM file (press code
modulation), WAV or OGG file with a sound effect. They are controlled with the sounds menu, so 
you can create new effects (with the sound recorder) or edit them. You can find a 
library of sound effects already prepared for use in the games. To hear these
sound effects you must have a sound card compatible with the Gravis Ultrasound or
Sound Blaster family, correctly configured and then click over one of these windows.

{10. Musical modes:} Songs in the formats MOD, S3M and XM can be loaded . 
They are represented in a small window which allows you to activate or stop its
playback. You cannot compose new modules from the environment though.

{11. Help window :} It is controlled mainly with the mouse, but you can also use
the cursors, and the PageUp, PageDown and BackSpace keys to return to the previous page. 
In the help windows the texts are shown in white which make reference to
other help pages. You must click on these references to access to these pages.
In the help windows are also shown example programs which can be selected by clicking on 
their title, executed with the key F10 and closed by clicking ALT+X.

{12. Calculators:} The calculators windows function as evaluators of
mathematical expressions, in the style of expressions presented in the programs.
Their functioning is very simple, because you need only introduce an expression and
press Enter to see the result. You can use parentheses to indicate subexpressions.

{Note:} The trash window must be activated first from the system menu, with the 
corresponding option ({System \ Trash}).

{/}See: {#2010,Fixing the video mode} - {#2000,Introduction to DIV 2}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2007,Demo Session}{+1,1}{-}

This is a version of DIV Games Studio 2 designed for evaluation purposes only, and is limited  
to 31 executions of the program.

This demo version is completely functional, and was created with the aim that
you could evaluate the possibilities of the program and its compatibility with 
your system, before obtaining the full registered copy.

There are only two restricted functions in this version:

- The {program size} which can be compiled is limited by the
maximum number of objects allowed in this version.

- All finished programs (after creating an EXE independent from DIV with the option
{Programs} \ {Create installation}) will be marked with a message stating this is a demo 
version only.

These restrictions don't exist in the commercial version of the program, but in addition remember
that the full version also contains a {User's manual} which is essential
to access all the functions of the program and to effectively learn the programming 
language of DIV 2.

{/}

{Note:} The information contained in the User's manual of DIV Games Studio 2
(about what's new in the environment, the program options, a tutorial for the new
language, ...) cannot be found in this electronic help.

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2008,conflict with the sound system}

The audio system of DIV Games Studio was not initiated because of
a conflict with your sound card. This problem is often produced for these reasons:

- The card is being used at the same time by {another program}. It cannot
reproduce the sound if any other program exists which reading or writing
data to the card (such as an MP3 player or sound capture device).

- A problem with the {auto-detection} of the card's parameters can occur.
You must execute the sound configuration program or define
these values in the variable BLASTER or ULTRASND of the system environment (you can find
more information on this in the user's manual of DIV Games Studio 2).

- Because of the {incompatibility} of the card. If the card is not a
mark GRAVIS (tm) or SOUND BLASTER (tm), it may be incompatible
with DIV Games Studio. The majority of commercially available cards are compatible
with SOUND BLASTER cards, but they still may not be 100% compatible and may
present some problems.

{/}

{General solution of the audio problems.}

If your particular problem doesn't fit into any of these three cases,
you must first execute the sound configuration program. This can be accessed
from DIV by pressing {F4}, loading the program {SETUP.PRG} from the
{SETUP} directory, and executing it with the key command {F10}.

In the first chapter of the {user's manual} you can find the information 
about how to obtain the parameters of your sound card.

Also you can try the configure the sound system indicating in the configuration 
program as if your card was a simpler one (previous to yours). For example, if you
have a card compatible with a {Sound Blaster AWE 64} or {128} and cannot
initiate the sound system; try to configure the system as a
 {Sound Blaster 16}, or {Sound Blaster Pro} card.

As the last recourse, if it still wasn't possible to configure the sound in your system,
you must deactivate it. To do this execute the configuration program
and select {<Without sound>} in the field which defines the type of card.
Then press the {<Save>} button to establish this configuration and deactivate
the sound in DIV Games Studio 2.

{/}

{Note:} The playback of CD-Audio is independent of the digital sound system
which configuration is described here; therefore CD music will continue to be played
although the sound system has not been initiated properly.

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2009,The sound system is not working}

Digital sounds cannot be played back inside DIV Games Studio 2 if the sound system is 
deactivated.

Probably, in the configuration program the option {<Without sound>} was selected, 
instead of indicating the type of card you have installed on your PC (or one 
compatible with it).

{/}See: {#2008,conflicts with the sound dispositive}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2010,Fixing a video mode}

The option {System \ Video mode} gives access to the dialogue window which permits
you to modify the resolution used by the graphical environment of DIV Games Studio 2.

The video resolutions are indicated as the number of horizontal and vertical pixels 
the video will be displayed in on screen in this mode and will be a value between 320x200 
(low resolution) and the max resolution which your video card permits. To select
a new resolution you must click on the list which appears in the window over the resolution
desired and then select the button {Accept}.

{Note:} Some of these video modes can be visualised incorrectly
(for example, a resolution which is permitted by your video card but not by your
monitor); in this case you must wait {15 seconds} for the environment to
restore the previous resolution. Don't press any key, don't do anything, just be 
patient and wait.

{Selection of the system font.}

There are two settings allowed to select the font used by the system, which not only 
have differences in the size of the letters but, also in the
size of the windows of the environment. They are :

{1. Small font (and small windows).} In this mode all windows,
menus and pictures are seen in a small size, being ideal for low modes
of resolution or a PC with a big monitor (17" or more).

{2. Big font (and big windows).} This mode can be activated
only in resolutions from 640x480 up and is ideal for small monitors (15" or less).

{Note:} The font of letters used in the programs and in the help window is
independent from that selected for the system, and is defined in the configuration
window, also accessible from this system menu.

{/}See: {#2011,The window of configuration} - {#2000,Introduction to DIV 2}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2011,The configuration window}

With help of the option {System\Configuration} you can access the following dialogue window
divided into sections, which are outlined below.

{Colours windows}

This first section establishes the colours used by the environment; the colours for 
background of the windows, the colour of letters / fonts and the colour of the title 
bar can be selected. To change these colours click on the boxes. The system not
only uses these three colour windows but, starting from them, generates a gamma array
of colours used for texts, cursors, buttons, etc.

{Programs Editor}

This establishes the appearance of the program windows. Different colours for different objects
(words or symbols) presented in the program can be selected.

{1.} Background of the edition window.ú
{2.} General colour of letters.ú
{3.} Cursor.ú
{4.} Commentaries of the programs.ú
{5.} Symbols and operators of expressions.ú
{6.} Reserved words of the language.ú
{7.} Numbers inside the program.ú
{8.} Literals, or texts in inverted commas.ú

The text blocks marked inside the editor are seen with the interchanged colours of paint
and background.

A text box allows you to define the size (n number of spaces) of the tabulator in the
programs editor, as a number between 1 and 16. By default the program tabulates every 
4 columns.

It is also possible to select here the size of the letters of the programs and the help,
from 6x8 up to 9x16 points. All fonts of letters are fixed for a particular setup.

{Painting Program }

Defines the quantity of memory reserved to carry out operations in the graphics editor,
the speed of the mouse pointer and its representation.

The quantity of "memory" is specified in Kbytes, and by default is set at
1088Kb (more than one megabyte), but it is not necessary to modify this value even if 
an operation can't be realised in the graphical editor because of not enough memory available
(in this case the program will divert more memory to it). Please note though, that the more memory
reserved for graphics, the  less memory will be disposed in the system for the rest of the actions.

The speed of the mouse pointer is defined with the small horizontal bar (faster
to the left and slower to the right), and affects the mouse in all window environments,
not only the painting program.

{Global options of the environment}

{1. Emergent windows.} Indicate all windows effects to be visualised, 
when they are opening, closing, minimising, etc. If this option is deactivated,
the environment will lose these effects but will gain a faster response speed.

{2. Move complete windows.} With this option enabled, windows will show their 
complete content whilst being dragged, otherwise only the outline will be shown.
It can be useful to deactivate this option on slower PCs.

{3. Always save session.} Means that when exiting from DIV Games Studio, the contents
of the desktop and all its objects (programs, maps, sounds,etc.) must be saved. 
If this option is deactivated then entering and exiting from the environment will be faster,
but there is a risk of losing the work which was not saved prior to exiting from DIV.

{4. Colour of the lists.} Indicates that, when a file with the extension PRG is being edited, 
all colours previously selected for the editor must be applied. Alternatively only the colours 
of the background and cursor will be applied. The same applies when you are editing a file 
which is not a PRG {div source program} file.

{Note:} If you close the configuration window or press the key ESC all changes you have just made
will be lost, and the values of the previous configuration will be restored.

{/}See: {#2012,First contact with the language} - {#2000,Introduction to DIV 2}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2012,First contact with the language}

In this section it is explained how to execute the Sample games of DIV Games Studio and
quick instructions how to start learning about DIV, receiving the first notions about 
this programming language.

{General instructions}

All included games are simple examples, they don't pretend
to compete with the commercial games which can be created with this tool.
Although we're talking about complete games, the majority of them are very simple 
or very short.

The aim was to demonstrate the techniques which are used and how the programs are
made, by use of examples, instead of huge lists of instructions in which the user gets
easily confused.

{Note:} These games can never show the true capabilities of this environment, 
because practically no single game uses all of them. The majority of the new
and potential capabilities of this version of DIV Games Studio weren't used
in these example, giving you the opportunity to be the first persons who
attempt, or maybe manage, to explore these possibilities to the full.

To execute any of these examples you must, first, load the program with the
option {Programs\Open program}, and then a window will appear with a list
of the loaded programs.

{The help system}

One of the best ways of learning the DIV environment; after placing the cursor
on a reserved word, constant, variable, function, etc., of the language you can 
press the key F1 to see a help page about this subject.

If, after pressing F1, help about the subject doesn't appear (but instead the general index
appears) it is because this is not a specific word of the DIV language, and the data or process 
is not directly from the game language (processes are functions which control the behaviour 
of the graphics, or 'sprites', in the games).

{Note:} We recommend you begin by learning with simple games, as tutorials or, better still,
with the examples included in the electronic help; to access them you must press
the Functions button in the help window and, from this page, access the different explanations 
of the functions of the programming language, from where small examples can be viewed by 
pressing on their headline or title.

Texts which begin with the symbol // (double bar) are explanation comments,
they don't form part of the program, but only consist of "explanatory notes"
about the internal functioning of the program. These comments are often a big
help in understanding the functioning of the programs. The comments can also
appear between the symbols /* and */ (covering many lines of the program).

To go to one of the program processes (one of the program blocks used to control a graphic 
or sprite of the game), you must press the F5 key and select the name of the process with 
the help of the mouse.

{Execution of the examples}

To execute one of the loaded programs, press with the mouse on its
window and then with the key F10 (this action can also be instigated with the option 
programs \ execute).

The contents of the games are different, but the majority of them allow you to exit
by pressing the ESC key and are managed with the cursor and control keys (See the 
{#1292,general commands in the games}).

The Pause key can be used in all games to immediately stop the execution of the program. 
All programs can be aborted at any point, independent of their programming, if the 
combination of keys ALT+X is pressed.

{/}See: {#2013,Debugging your program} - {#2000,Introduction to DIV 2}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2013,Monitoring or debugging the programs}

The more active people can find out more detail about the progress of the games during runtime
by pressing the key F12 (from the game itself, during its execution), that allows you to access
the program debugger, which permits you to execute  the games step by step.
Here you can observe all processes and modify their data (if you have convenient data,
all dynamic parameters of the game can be changed, the phase number, the lives left, 
ammunition left ...).

In the upper part of this window there appears a list with the processes currently active at 
any moment (such as toys or graphics which are being used by program). They can be selected 
with the mouse and, by pressing the button {see data}, all variables, counters, etc. which the 
process is using will be seen.

In the lower part of the screen appears the lists of the program, which basically
are the order in which the PC must action things whilst the game is running. It is
normally divided into small blocks which begin with the word {PROCESS} (one of the reserved words 
of the programming language). In each one of these blocks the orders for a main element of the
game are specified (for example, for a shot being fired, an enemy or an explosion).

{General functioning of the programs}

In short, the games always consist of a sequence of frames. Each frame is composed of
different elements (or processes)of the game. All these elements must, in each frame,
complete a series of operations or calculations (normally very simple) to determine 
what their appearance  must be in the following frame (which picture or graphics the 
frame must show, in which position, of which size, which orientation etc.)

The PC is realising the orders specified for each process until it
comes to the orders for the {FRAME} (frame or fotogram) itself. This order indicates that a
process is already prepared to be shown in the following frame, which means, all the parameters 
which will define its appearance in the following frame have already been allocated.

{Note:} The orders specified in a program are denoted as statements. Each one of these
statements indicates an operation or calculations which the PC must realise.

In this way, the PC continues realising all these operations and calculations
which the orders of each process have specified, until all active processes
have reached the order statement {FRAME}. At this moment, the PC stops executing 
orders and will focus instead on composing the following frame which must be displayed 
on screen.

In the games these two tasks are consistently alternating, first the orders are executed,
and then the frames are composed and displayed.

{Basic controls of the debugger}

This can be viewed from the program debugger, with the help of different buttons
which allow the actions of the program or game to be realised step by step, 
visibly on screen. These main buttons are the following:

{1. Step.} Indicates to the PC to execute the following order of the next process. The
next process appears in white in the most prominent list of the debugger, and the following 
order to be realised (by this process) appears in the program list in the same colour.

{2. Exec.process.} This button instructs the PC to execute all
instructions of the following process until it  reaches the order FRAME, this means, it must
realise all necessary operations required before the next process can be
displayed in the next frame.

{3. Foll.Frame.} This button is used to advance the game frame by frame.
Each time it is pressed, all necessary orders of all active processes will be executed, 
the new frame will be composed, and finally the frame will be converted to video 
(the term "convert to video" means that the action of one frame of the
is composed in the video / graphics card, and thus will be displayed on the
monitor of the PC).

When a program is realised, all its aspects can be controlled: the order in which the different processes 
are executed, the order in which the graphics are displayed on screen, the interactions of the processes
on screen (when they "are touching" one another, for instance), when sound effects must be played,
the reactions of each process on the keyboard, mouse, etc ...

{/}See: {#2000,Introduction to DIV 2}

# ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

{.2047,The last possible term inside this hypertext}
