@database Shuffle.guide @node Main " This Guide is a Referance to the Shuffle_2.9 Extention." ----------------------------------------------------------- This is VERSION ( 2.9 ) of the AMOS Club/Shuffle Extension. ----------------------------------------------------------- @{" INTRODUCTION by Aaron Fothergill " link Intro} ================= TABLE OF CONTENTS ================= The "Forgotten Commands" Section. ================================= These commands should have been built into AMOS, but Francois forgot, or didn't know about them! @{"=Range(a,b to c)" link Range} @{"=Mkb$(n)" link Mkb}...................... Also: =Mki$(n), =Mkl$(n) =Cvb(n$), =Cvi(n$), =Cvl(n$). The "Other Commands" Section. ============================= @{"Case$" link Case}......................... Also: String$ Case Var, Of string$ result Of var, result =Case. @{"Void" link Void} @{"=Library Open(libname$)" link CallLib}....... Also: =Library Call(Libbase,offset) =Library Close(Libbase). @{"Sam Speed chan,speed" link Sound} @{"=Busy Printer" link Printer}................. Also: =No Paper. @{"Bank String bnk,string$,pos" link Bank}... Also: =Bank Str Ptr, =Bank Name$(bank) Bank Str End n, Bank Name bank,name$ @{"List Bobs" link list}..................... Also: List Bobs n1 to n2,xsize,ysize List Bobs n1 to n2, List Palette @{"=Ch Key State" link Ch}................. Also: =Ch Scancode, =Ch Key Scan Analyse string @{"=B Height(n)" link Bob}.................. Also: =B Width(n) =I Height(n), =I Width(n) =B Colours(n), =I Colours(n) =H Spot X(n), =H Spot Y(n) @{"Exchange Bob Colours n,c1,c2" link Ex}.. Also: Exchange Icon Colours n,c1,c2 @{"Change Bob Colours n,c1,c2" link Chan}.... Also: Change Icon Colours n,c1,c2 @{"Make Bob Colour n,col" link Make}......... Also: Make Icon Colour n,col The "Float Cammands" Section. ============================= @{"Float Bob Clear" link Float}............... Also: Float Bob Reset =Last Float Bob Float Bob n,x,y,i Float Offset x,y Float Planes bitmap Float Back b =First Col(bobfirst To boblast) =Nxt Col @{"=In Screen Bob(n,i,mx,my,x,y)" link Inscr}. Also: =In Screen(mx,my,x,y) The "How did I survive before these commands" section. ====================================================== Most of these commands were requested by AMOS Club members, and are intended to make life a lot easier. Not all of them will be directly useful to you, but no doubt you will end up using some of them in some your programs! @{"Shuffle bank,range,seed" link Shuf}....... Also: =Rand(bank,n) @{"Analog Scan" link Anal}............ Also: =Analog X(n) =Analog Y(n) The "Weird and Wonderful" section. ================================== These commands are all for specific tasks, mostly for the advanced programmers out there, although Key Scan, =In screen and Game Area will tend to find their way into a lot of games! @{"=Wrap(String$,width)" link Wrap} @{"=Key Scan" link Kscan} @{"Game Area x1,y1 To x2,y2" link Game} @{"Splot x,y,c,scr" link Splot}............... Also: =Spoint(x,y,screen) @{"Push a,b" link Push}...................... Also: Push a,b,c Push a,b,c,d Push a,b,c,d,e Push a,b,c,d,e,f =Pull(n) @{"=Fmod(mod,n)" link Fmod} @{" ENDING " link End} @endnode ----------------- End - Of - MAIN - Node ----------------- @node Intro A WARM HELLO TO ALL AMOS CLUB MEMBERS. ====================================== The AMOS Club or "Shuffle" extension started off with just the Shuffle, =Rand and =Range commands way back in October/November 1991 and was released on the TOME Goodies Disk 1 and as a source code listing in Volume 1, Issue 5/6 of the AMOS Newsletter. Using extension number 9, it was intended to be a general purpose extension for AMOS Club members and TOME users, to be expanded whenever anyone needed or suggested a particular group of commands that were missing in AMOS or would be useful to AMOS programmers. At the time of writing this report, there are around 70 commands in this extension! @endnode @node Range Range Forcing. ============== =Range(a,b to c) ---------------- There are many times when you will find you need to force a number into a set range. For instance, when you want to make sure that the X co-ordinate of an object stays within the 0-319 pixel range of a low resolution screen. The Range function forces the value a into the range of b to c, equivalent to: =Max(b,Min(c,a)), so doing, X=Range(X,0 To 319) Will force the value of X into the range of 0-319 @endnode @node Mkb Number/String Conversion functions. =================================== =Mkb$(n) =Mki$(n) =Mkl$(n) -------- -------- -------- =Cvb(n$) =Cvi(n$) =Cvl(n$) -------- -------- -------- These functions are classic Basic instructions, designed primarily for use with Random Access Files, where everything has usually to be stored as strings. These commands convert integer numbers in Byte, Word and Longword format into 1, 2 and 4 character strings and back again. =Mkb$(n) -------- Converts n to a 1 byte string, n can be from -128 to 127 or 0-255 =Mki$(n) -------- Converts n to a 2 byte string, n can be from -32768 to 32767 or 0-65535 =Mkl$(n) -------- Converts n to a 4 byte string, n can be any integer variable =Cvb(n$) -------- Converts 1 byte string n$ to a numeric value from -128 to 127 =Cvi(n$) -------- Converts 2 byte string, n$ to a numeric value from -32768 to 32767 =Cvl(n$) -------- Converts 4 byte string n$ to a numeric value @endnode @node Case Case Commands. ============== These commands are generally popular with retired Pascal programmers and come in quite handy sometimes. The AMOS Club extension version is slightly different from the Pascal version, but is a little more versatile. First you have to specify the variable that the case is to be based on.. Case$ String$ ------------- Checks the value in String$ Case var -------- Checks the value in var Then you use the Of command to compare this variable with your "in Case Of" checks. Of string$,result ----------------- Compares the Case'd string with String$, if equal puts result in the Case variable Of var,result ------------- Compares the Case'd variable with var, if equal puts result in the Case variable If the variable matches any of these "in Case Of" checks, the check number will be put into a reserved variable called CASE (logical enough !). =Case ----- Result of Case...Of comparisons You can now use this variable to do On Case Gosub/Proc/Goto, or simply use it mathematically. @endnode @node Void Void ---- Void is possibly the most stupid looking command in BASIC, as it does absolutely nothing ! However, it comes in handy, as it is used to call functions where normally you would have to use a dummy variable. e.g Void Free --------- To garbage collect the variable buffer. @endnode @node CallLib Calling Libraries. ================== =Library Open("libname") ------------------------ =Library Call(Libbase,offset) ----------------------------- =Library Close(Libbase) ----------------------- These commands allow you to open and use any library from AMOS (similar to the AMOS Pro commands, but these actually work, and were in use way before Pro was out). First you must open the required library and store its base address (returned by the Library Open command) ICBASE=Library Open("Icon.Library") You can then call any of the routines in that library with the Library Call function. X=Library Call(ICBASE,-222) : Rem 'not a working example!' When you have finished with the library for the day, shut it down with Void Library Close(ICBASE). @endnode @node Sound Sound Frequency Controlling. ============================ Sam Speed chan,speed -------------------- Sam Speed directly controls the frequency of a sound coming from the sound chip. Normally it is used to control the pitch of a sample being played, say as an engine sound, but it can also be used to control the pitch of any sound coming out of the Amiga, as it talks directly to the chip. The chan parameter is similar to that of the Play command, in that it is a bitmap representing the four channels available. e.g. 15 is all 4 channels (8+4+2+1), 3 is channels 1 & 2 (2+1) etc. The Speed is the required frequency in Hz (cycles per second). @endnode @node Printer Checking the Printer. ===================== =Busy Printer ------------- =No Paper --------- These two functions simply tell you if a printer is on line and ready to print (Busy Printer=0) and if it has paper (No Paper=0). @endnode @node Bank Putting Strings in Banks. ========================= Bank String bnk,string$,pos --------------------------- =Bank Str$(bnk,pos) ------------------- =Bank Str Ptr ------------- Bank Str End n -------------- These commands allow you to put strings into a bank and pull them out again. The Bank String command requires a bank number (reserved of course), a string to put into the bank, and the position (in bytes) to put it in the bank. The string will then be copied into the bank at this position, and a Chr$(10) (line feed) will be added to the end of it. To pull a string out of a bank, you use the =Bank Str$(bank,position) function, which will start at the specified position and copy the string until it reaches a Chr$(10). Both of these functions update a reserved variable called Bank Str Ptr (Bank String Pointer), which will hold the position of the next string in the bank, so you can do the following to pull a series of strings from a bank.. F$="Read_Me.Asc" : Rem name of 'ASCII file to read.' Open in 1,F$ L=Lof(1) Close 1 Reserve as Work 5,L A$=Bank Str$(5,0) Print A$ While Bank Str Ptr-1 PrintCollided with Bob;B B=Nxt Col Wend Endif This function allows the scanning of the Col() array at high speed. Bobfirst and boblast are the range of bobs to be checked. If no bobs collided in this range with the primary bob, then -1 will be returned. Otherwise up to 8 bob collisions are recorded in a special buffer area. =First Bob defines the range to check, and returns the first Bob Number collided with, or a -1 if no collisions. =Nxt Col -------- (See above Example) If more than one collision occurred, =Nxt Bob will return the Next Bob Number to be collided with, otherwise it returns -1. @endnode @node Inscr =In Screen Bob(n,image,mx,my,x,y) --------------------------------- If x,y are within screen boundaries (defined by Game Area) bob n with Image will be floated at x-mx,y-my, also a true value will be returned =In Screen(mx,my,x,y) --------------------- As with above, but it doesn't float a bob @endnode @node Shuf How to go Shuffling numbers. ============================ Shuffle bank,range,seed ----------------------- =Rand(bank,n) ------------- These commands were the first ones written for this extension, along with the =Range function. They are intended for use in any situation where you need to "Shuffle" a group of numbers, for instance in card or bingo games, and also when doing random looking screen disolves. The Shuffle command shuffles the range of numbers at very high speed, and using the same seed number (an amount to randomise the shuffle) will produce exactly the same results, useful for those experimental Card and probability mathematicians out there. To use the Shuffle commands, you first need to reserve a bank to 4*the range of numbers you wish to shuffle. So if you want to shuffle the numbers 1-52 to represent a pack of cards (I always shuffle 1-53 for the extra Ace I always have tucked up my sleeve. Never play cards with me !) you would need to reserve a bank to 52*4 or 208 bytes. Easy Reserve as work 5,208 You then use the Shuffle command to shuffle the numbers, to make the seed a little more random, you can make use of the AMOS Rnd() and Timer functions. Shuffle 5,52,Rnd(Timer) The =Rand(bank,n) Function allows you to pick a shuffled number from any point in the stack. For instance: A=Rand(5,0) would pull the first number from those shuffled in bank 5. "Ah !", you ask, "so how do I shuffle a set of numbers that doesn't go from 1-range, say 1,2,3,8,9,19, or a set of strings ?" Dead easy, you work out how many numbers or strings are in your set, dimension an array to hold them, chuck em in it and shuffle that number. You then use the results of =Rand() to point to the array. The following program will shuffle an imaginary pack of cards and let you pick them a card at a time: Dim CARD$(52),SUIT$(3),NUM$(12) SUIT$(0)="Hearts" : SUIT$(1)="Spades" SUIT$(2)="Diamonds" : SUIT$(3)="Clubs" For A=0 To 12 Read NUM$(A) Next A Data "Ace","2","3","4","5","6","7","8","9","10" Data "Jack","Queen","King" For A=0 To 3 For B=0 To 12 CARD$(A*13+B)=NUM$(B)+" Of "+SUIT$(A) Next B Next A Reserve As Work 5,208 Shuffle 5,52,Rnd(Timer) N=0 While N<52 Print "Press a Key to see the next card" Wait Key C=Rand(5,N) Print CARD$(C) Inc N Wend @endnode @node Anal Using Analog Joysticks. ======================= Analog Scan ----------- =Analog X(n) ------------ =Analog Y(n) ------------ This set of commands was written for those of you who wanted to do flight and driving simulators in AMOS and wanted slightly better control for them. You first use the Analog Scan command to set the little demon inside the Amiga into counting the resistance values from the joystick ports (Commodore had to use demons to do the counting as elves weren't compact enough to fit inside an Amiga). You have to wait at least one VBL before the demon will have finished his count and be prepared to give you a report. Once he is ready, the =Analog X(n) and =Analog(y) functions will return the values (range 0-255) of the two axis. n can range from 0-1 so you can use two analog joysticks, or four paddles (for those of you out there who can remember game paddles!) @endnode @node Wrap Wrapping Text. ============== =Wrap(String$,width) -------------------- O.k, so you're trying to print text to the screen without it wrapping around the edge of the screen, splitting your words. The =Wrap() function will tell you how much of the string you can print without any words going over the edge of your screen. It basically searches for the most convenient point in the string (punctuation or spaces) to split the string before it hits the end of the line. Parameter wise the String$ is your string to be printed and width is the width of the area you are printing to (in characters). You use =Wrap() to find out how much you can print, print that part of the string and remove it from the start of the string and do it all over again with the remainder. Those of you who are using CText will be glad to know that CText V2.5 has an equivalent =Ct Wrap() function which does the same for CText fonts but takes account of CText's proportional character widths and is accurate to pixels instead of characters. @endnode @node Kscan =Key Scan --------- This function directly reads the keyboard hardware and returns the Keyscan number of the key being pressed. Use Print Ch Key Scan from direct mode to find the Key Scan codes. This command has the major advantage that it works when the Forbid multi task command is active (which normally stops you reading the keyboard and mouse). @endnode @node Game Game Area x1,y1 To x2,y2 ------------------------ Defines area of screen that bobs will be active in. X1 & Y1 are subtracted from the left of the screen, and X2,Y2 define the Width+ Right edge & Height+Bottom Edge. @endnode @node Splot Just for Speed! =============== The following commands enable you to speed up your routines... Splot x,y,c,screen ------------------ This is the Plot command with its usual x,y,colour paramters and a Screen number. Working this way, it plots direct to the specified screen, without you having to do a Screen n command and then returning to the previous screen with another Screen n command (The Screen command is REALLY slow). =Spoint(x,y,screen) ------------------- This is the equivalent point command, again working directly to a screen. In tests, Splot and Spoint managed to run 2-4 times faster than Plot and Point alone, and up to 10 times faster when you take into account the Screen commands eliminated! @endnode @node Push Pushing Variables. ================== Push a,b Push a,b,c Push a,b,c,d Push a,b,c,d,e Push a,b,c,d,e,f -------- ---------- ------------ -------------- ---------------- =Pull(n) -------- The Push command pushes from 2-6 parameters (integers only) onto a stack. These can then be returned again with the =Pull(n) function. When used to replace procedure calls which have parameters with a gosub command, they speed up the call from 3-4 times! e.g was... MYPROC[FLOZ,NEZ,GAZ] ... ... Procedure MYPROC[A,B,C] ... ... Endproc replace with... Push FLOZ,NEZ,GAZ Gosub MYSUB ... ... MYSUB: A=Pull(2) B=Pull(1) C=Pull(0) ... ... Return Thus eliminating any Global (i.e bugged) variables and a slow procedure. @endnode @node Fmod Using Modulus. ============== =Fmod(modulus,n) ---------------- This is a high speed (4 times faster) version of the MOD mathematical function. It is limited to a modulus of 1-65535, but is much faster. So replace: A=B Mod C with A=Fmod(C,B) For Modulus values of 16, use e.g. A=B And $F as it is slightly faster. @endnode @node End Hopefully I will soon have enough time to put together the FULL Shuffle Manual (printed as a booklet), along with the latest version of Shuffle and a load of examples! Obviously, those of you who have already ordered the Shuffle manual in advance will be first on the list to receive it! @endnode