'                                           LA OROYA Software, 1993. 
'                                           ------------------------   
' Document for the Yachting programme, by Stephan Scholz 
' The programme >>> Yachting <<< is public domain.     
'  
'                      C O M M E N T S :     
'                      =================   
'  
' This programme intends to show the relationship between wind speed 
' and direction, sail-boom angle and yacht heading and speed, turning
' this into a playable simulator game. 
'
' On loading, a screen showing a circular wind graph appears:           
' The darker blue zone shows the maximum traveling speeds for modern   
' yachts, according to the direction the wind is coming from. The            
' light blue area shows speeds with raised spinnaker for rear winds.       
'  
'
'              Improvements on the first version:  
'              ----------------------------------  
'
' - The rather messy printed numbers for the yacht speed have now
' been converted into a speedometer dial, and the heading is now given   
' by a smooth mini-scrolling compass. The dashboard now boasts the name
' of the programme, and the pseudonym logo "La Oroya" - taken from a 
' mountain-town in the Andes I had always wanted to visit but never  
' got round to.      
'  
' - Some calculations have been taken out of the main loop and some
' numbers converted into variables - scrounging milliseconds...
'
' - Also, compiling it did seem to improve things a bit, thank heavens!
'  
' - The background scrolling speed has been improved, making the whole
' programme perform more smoothly. The culprit was that I was copying    
' the whole background instead of a third of the strip! My sincere
' apologies for any hassle caused.
'
' - The race is done in three separate laps. Before starting, you can  
' point your yacht in the desired direction, i.e. depending on the wind  
' angle, you can choose your course by clicking on the rudder chevrons 
' "<" or ">". Press space to start the lap. You will have to keep your   
' space bar down a few seconds, as the routine only reads the keyboard     
' between waves, when the horizon is up. This part also lets you quit      
' by pressing "Q". 
' You will win if you've won two out of three laps,
' Wind direction changes a bit from lap to lap.  
'
' Once you've started the radar-scanner indicates a green dot near the 
' buoy you should be heading for.  
'    
' - An ocean sound, changing with speed, adds atmosphere...  
' If you are stealing the other's wind this sound will change into a 
' swishing sound. If your wind is being stolen, your speedometer will
' tell you, and the ocean sound becomes quieter. 
'  
' - The creacking noises are when you move your sail or raise or lower 
' the spinnaker. The latter now takes a few seconds - 5 creaks!  
'
' - Collisions are accompanied by a violent crashing sound, and you
' are spun off course violently! 
'
' Future versions might have a damage control. 
'  
'                   Possible improvements :        
'                   -----------------------    
'
' - Instead of having an automatic competitor getting sailing speeds   
' from a wind angle table called AUTOS in the SAILDATA procedure,
' one could have a version where a second computer were linked up  
' and a second operator controlled the other ship in the same fashion
' as Object 0 (the viewpoint - your ship, in effect) is controlled.  
'              
' - One could also set up a championship routine, perhaps with 
' different models that behaved differently under different weather  
' conditions, and hall of fame to enter one's name.    
'  
'
'                      Further comments: 
'                      ----------------- 
'
' A mathematical co-processor would probably be a grateful additive  
' to use with this trigonometry and decimal-places ridden programme !!!
'  
' An accellerator is also convenient, giving faster screen update and    
' smoother movement, as the processor has a lot of work with all the 
' calculations. I have tried to keep these to a minimum, using data
' tables as much as possible, and I haven't included a jib (the
' fore-sail), or the turning effect that can be achieved by letting
' out or bringing in only one of the two sails. A trigonometrical
' drift calculation for each sail is necessary, similar to the 
' propulsion calculation (which would have to be done for each sail
' too), so you can guess what will happen without an accellerator!     
' Hence also the lack of lateral drift. Normally, depending on your  
' speed, your true course can drift upto 5 degrees leeward of your   
' heading with winds forward of the beam. This sideways drift could
' be included, but would slow down the programme and make it harder      
' to sail than it already is.  
'  
' So at present the YACHTING programme supposes that your course is your   
' heading, and this is kept constant unless you move your rudder, i.e. 
' you have a jib that someone is attending to, thus maintaining the ship   
' balanced and on course. This way you are spared the never-ending rudder
' operations necessary to keep single-sailed craft on course, or balancing 
' the jib and the mainsail all the time.     
'
'
'                  INSTRUCTIONS ON HOW TO SAIL:    
'                  ----------------------------  
'  
' On the starting line, choose which direction to face when you start.       
' Take care you are not heading squarely into the wind - you won't get 
' any speed at all! Click on the rudder chevrons "<" and ">" to rotate.    
'          
' Your yacht will move forward if the wind catches the sail. In the  
' main navigation instrument in the lower center, there is a light blue    
' line indicator in the green ring, indicating where the wind is coming
' from, relative to your ship. If you turn your ship, this line will 
' turn, moving round in the green ring as the wind angle changes with
' respect to your ship. This line is the apparent wind, which will move  
' forwards as you gather speed, so you will have to adjust the sail boom   
' accordingly, to maintain optimum sail angle with respect to the wind.  
'  
' Inside the green circle, is a drawing of your ship. You have a boom    
' indicator which can be moved outwards on inwards by clicking on the
' chevrons "^" and "v". The boom will be light blue if optimum sail  
' efficiency is achieved, although this is not possible for very rear
' winds. It will be green if the wind is pushing the sail - meaning less   
' efficiency, as no laminar flow is being achieved. Laminar flow happens 
' happens with a wind incidence of 10 to 25 degrees on the sail, as a
' suction force is ceated, similar to an aircraft wing.  
'  
' If the boom indicator is grey, however, it means the sail is 
' flapping loosely in the wind, and you are getting no push at all.
' In this case you should draw in the boom, clicking on the red "v"
' to the right of the instrument, until the boom slowly moves in.
' It may take a while to start moving if it has been out far - all   
' that loose rope has to be collected..! 
'
' If you are headed straight into the wind, i.e. the blue wind line  
' is near the nose of your ship, taking in the boom will be to no  
' avail, and you will have to turn the yacht right or left, clicking   
' on the red ">" or "<" below the instrument - the yellow line is your   
' rudder. Turning will be very sluggish indeed if you have no speed, so  
' DON'T turn into the wind without speed ! - i.e. for tacking - doing  
' a zig-zag course for a route against the wind.           
'
' Even if your boom indicates laminar flow, i.e. it is light blue, 
' there is a certain optimum position within the 10-25 degree angle
' of incidence range, which is 22 degrees. Move the boom in or out 
' just a little to get this best push! Your speed will tell you. 
' Of course, depending on where the wind is coming from your optimum 
' speed will vary. There are no random factors affecting wind, boom  
' or steering. It's difficult enough without those!  
'
' If your competitor is too fast for you you might like to reduce
' the A#*2.1 value to A#*1.7 in the SAILDATA procedure in the READ A#  
' instruction just before the AUTOS data section. (These values give       
' the speed for the automatic ship, based on the wind graph data table). 
'    
' Your own ship's speed table is different: Your speed depends on wind   
' incidence angle on the sail - this table is SAILS data section, and  
' is complemented by the SPINNAKER data section further on). Don't change  
' these, as it will probably ruin your yacht's performance. Your     
' adversary's ship and your own ship behave differently: 
' Yours is a bit faster and sails closer to the wind, although your  
' competitor accellerates and turns faster, and runs very well before
' the wind.  
' You will find it very useful to get round the other boat on the                  
' windward side, steal the other's wind. Watch out you don't get on    
' the leeward side - you'll lose your speed. 
'        
' If you are heading into the wind you can do so only at an angle. 
' Watch your speed indicator, which is to the left of the main   
' instrument. With a 12 knot wind your yacht (which is very
' efficient and fast and behaves somewhat like a catamaran even!), 
' will sail forwards at about 8 knots with a real wind coming from 
' the side (90 deg.) and 3 or 4 knots heading into the wind at angles  
' of 40 or 45 degrees. 
'
' The real wind angle cannot be "seen" from your yacht, only the   
' apparent wind, which changes with your speed. Should you want to 
' see the real wind on the wind instrument, there is a line you can  
' use: Draw H(WW,3),H(WW,4) to H(WW,5),H(WW,6). Write this in, just    
' below Draw H(AWA,3),H(AWA,4) to H(AWA,5),H(AWA,6) in the main loop.
' You may find it interesting to see how your ship's apparent wind         
' behaves with respect to the real wind, depending on your speed.  
'
' If you are sailing with rear winds, your boom should be let out as 
' far as possible, clicking on the red "^", and you can achieve a speed
' of about 4 kts. without spinnaker.   
'      
' If you click on the little box inside the speed instrument, this will
' slowly raise or lower the spinnaker. The symbol in the box will tell 
' you if it is stowed (v), raised (^) or being raised or lowered (*).    
' The spinnaker gives you increased push for any real winds coming from
' anywhere behind the beam (90 to 180 degrees). If you raise the spinnaker 
' with forward winds, this will bring you to a halt. With a spinnaker, the 
' maximum yacht speed, just over 10 knots, will be achieved with a real  
' wind at 135 degrees. If at 180 degrees, speed is about 6 knots.  
'
' For the moment, the program has a fixed real wind speed of 12 knots    
' but the wind direction is random.  
'
' Watch out with hitting the buoys or the other ship! It will send you 
' spinning violently off course! It may happen that the other one will 
' hit you too, so watch out! Keep an eye on the radar-scanner. The blue
' dot tells you where the other ship is. You are the yellow dot. Even if 
' you or the other boat leave the boundary of the scanner, a dot remains 
' in the blue fringe on the margin to tell you in what direction that
' ship is. The red dots are the three buoys, and a little green dot
' near one of the buoys will indicate which buoy you should be heading 
' for. 
'
' Starting off, sail for the north buoy, which lies ahead and to the 
' left of where you are, (the other ship will set off, so you can    
' follow it - you are faster, and can overtake it).      
' Sail round the north buoy, (don't collide with it), and as soon as 
' you hear the bell, or you see the green dot on your scanner disappear
' from the north buoy, you can set course for the Southwest buoy, and  
' then the East one, which is the "finish line". 
'  
' To keep track of the route, the programme has to detect if you've
' entered an area 5000 VLU's in diameter which touches the north buoy    
' on the north side. The west buoy also has such an area to the south west.
' During the race, rounding the buoy without hitting it is easy enough.
'        
' IMPORTANT: 
' If you don't enter these areas, i.e. if you give the buoy too wide a 
' berth, the programme can't detect that you have rounded the buoy, and  
' won't finish the race - the other ship will continue sailing past the  
' last buoy ad-infinitum... During the race it is easy enough to round 
' the buoys  close enough without danger of hitting them.  
'  
' The finish "line" is an area 5000 VLU's in diameter, touching the  
' last buoy on the south east (This is the buoy you started the race from).        
' You can enter the finishing area from any direction south of the buoy.   
' The program detects who is first to enter this area and will tell    
' you if you've won the lap - and the times you've bumped into something.    
'  
'  
' Have fun!  
'  
' Stephan Scholz