@nataliapc/mcp-openmsx 1.1.14 → 1.2.2

package/resources/programming/basic_wiki/SET_VIDEO.md

@@ -0,0 +1,49 @@
+# SET VIDEO
+
+## Effect
+
+Sets superimposition and digitization modes.
+
+## Syntax
+
+`SET VIDEO <Mode>,<ScreenLuminance>,<ColorBus>,<Synchro>,<AudioSource>,<VideoOutput>,<A/V>`
+
+_Note: Each parameter is optional except the last specified. Do not put a comma after this parameter._
+
+## Parameters
+
+`<Mode>` is a value between 0 and 3 to set video mode.
+- 0 for computer screen (internal synchronization).
+- 1 for computer screen - digitize mode (external synchronization).
+- 2 for superimpose (external synchronization).
+- 3 for external video (external synchronization).
+
+`<ScreenLuminance>` is 0/1 for normal/half tone.
+
+`<ColorBus>` is to set the direction for VDP's color bus. 0 for IN, 1 for OUT.
+
+`<Synchro>` is to set the type of synchronisation, 0 for internal,  1 for external.
+
+`<AudioSource>` is to set the type of audio source.
+- 0 = only computer.
+- 1 = mix computer + external source only on right side.
+- 2 = mix computer + external source only on left side.
+- 3 = mix computer + external source on both sides.
+
+`<VideoOutput>` is to set the type of video output, 0 for RGB, 1 for composite.
+
+`<A/V>` is to select or not the RGB output for audio and video, 0 is not selected, 1 is selected.
+
+## Related to
+
+`CALL IMPOSE`, `COPY SCREEN`, `SCREEN`
+
+## Compatibility
+
+MSX-BASIC 2.0 or higher
+
+_Note: This instruction is available on all MSX2 and higher computers. The parameters will be ignored on machines without corresponding option (digitizing unit, superimposition capacity, etc). All parameters are effective with the Panasonic FS-UV1 cartridge._
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SET_VIDEO"

package/resources/programming/basic_wiki/SGN().md

@@ -0,0 +1,38 @@
+# SGN()
+
+## Effect
+
+Returns the sign (positive of negative) of a variable.
+
+## Syntax
+
+`SGN (<Expression>)`
+
+## Parameter
+
+`<Expression>` can be a value, a numeric variable or an mathematical expression.
+
+## Example
+
+```basic
+10 PRINT "The sign of -7 is ";SGN(-7)
+20 PRINT "The sign of 0 is ";SGN(0)
+30 PRINT "The sign of 7 is ";SGN(7)
+ 
+RUN
+The sign of -7 is -1
+The sign of 0 is 0
+The sign of 7 is 1
+```
+
+## Related to
+
+`ABS()`, `FIX()`, `INT()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SGN()"

package/resources/programming/basic_wiki/SIN().md

@@ -0,0 +1,36 @@
+# SIN()
+
+## Effect
+
+Returns the sine of a variable in radians.
+
+## Syntax
+
+`SIN(<Number>)`
+
+## Parameter
+
+`<Number>` can be a value, a numeric variable or an expression.
+
+## Example
+
+```basic
+10 D1 = ATN(1)*8/360
+20 PRINT "The sine of a 45 degree angle is ";SIN(45*D1)
+30 PRINT "The sine of a 0 degree angle is ";SIN(0)
+RUN
+The sine of a 45 degree angle is .70710678118655
+The sine of a 0 degree angle is 0
+```
+
+## Related to
+
+`ATN()`, `COS()`, `TAN()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SIN()"

package/resources/programming/basic_wiki/SOUND.md

@@ -0,0 +1,188 @@
+# SOUND
+
+## Effect
+
+Writes a value in a specific PSG register.
+
+Sound registers 14 and 15 and the two highest bits of register 7 are not accessible with this instruction.
+
+## Syntax
+
+`SOUND <PSGregister>,<Value>`
+
+## Parameters
+
+`<PSGregister>` is the register number (0-13) to write. It can be a variable or an expression.
+
+`<Value>` is a value whose limits depend on the register to write (see Registers Description below). It can be a variable or an expression.
+
+_Recommendation for maximum compatibility: when you write register 7 it is good habit to set bit 7 and reset bit 6 although these potentially harmful values should not end up to PSG in any case. That's why only the values 128 to 191 are mentioned below for this register._
+
+## Registers Description
+
+|Register|Description|Values|
+|---|---|---|
+|0|Least significant bits of channel A frequency|0~255|
+|1|Most significant bits of channel A frequency|0~15|
+|2|Least significant bits of channel B frequency|0~255|
+|3|Most significant bits of channel B frequency|0~15|
+|4|Least significant bits of channel C frequency|0~255|
+|5|Most significant bits of channel C frequency|0~15|
+|6|Noise generator frequency|0~31|
+|7|Mixer setting|128~191|
+|8|Volume of channel A|0~16|
+|9|Volume of channel B|0~16|
+|10|Volume of channel C|0~16|
+|11|Least significant bits of envelope period|0~255|
+|12|Most significant bits of envelope period|0~255|
+|13|Envelope shape|0~15|
+
+### About registers 0 to 5
+
+- The value indicating the frequency to be produced on a channel is 12 bits. It is therefore divided into two registers. The value to be written is obtained using the following expression:
+
+`Value = Fi / (16 x Fn)`
+
+`Fi` = Internal frequency of PSG (1789772.5 Hz on MSX).  
+`Fn` = Frequency of the sound to be produced (varies between 27 and 111.860 Hz).
+
+Additional math:
+
+`Note + Octave = Note/2`
+
+`Note + HalfNote = Note/2^(1/12)`
+
+For simplicity, here is ready table of musical notes by octave obtained according to the value indicated in the registers 0~1, 2~3 or 4~5:
+
+|Note|O1|O2|O3|O4|O5|O6|O7|O8|
+|---|---|---|---|---|---|---|---|---|
+|C|D5Dh|6AFh|357h|1ACh|0D6h|06Bh|035h|01Bh|
+|C#|C9Ch|64Eh|327h|194h|0CAh|065h|032h|019h|
+|D|BE7h|5F4h|2FAh|17Dh|0BEh|05Fh|030h|018h|
+|D#|B3Ch|59Eh|2CFh|168h|0B4h|05Ah|02Dh|016h|
+|E|A9Bh|54Eh|2A7h|153h|0AAh|055h|02Ah|015h|
+|F|A02h|501h|281h|140h|0A0h|050h|028h|014h|
+|F#|973h|4BAh|25Dh|12Eh|097h|04Ch|026h|013h|
+|G|8EBh|476h|23Bh|11Dh|08Fh|047h|024h|012h|
+|G#|86Bh|436h|21Bh|10Dh|087h|043h|022h|011h|
+|A|7F2h|3F9h|1FDh|0FEh<sup>*</sup>|07Fh|040h|020h|010h|
+|A#|780h|3C0h|1E0h|0F0h|078h|03Ch|01Eh|00Fh|
+|B|714h|38Ah|1C5h|0E3h|071h|039h|01Ch|00Eh|
+
+<sup>(*)</sup> 0FEh is the note produced by a tuning fork.
+
+### About register 6
+
+The value indicating the frequency of the white noise generator is 5 bits. The value to be written is obtained using the following formula:
+
+`Value = Fi / (16 x Fb)`
+
+`Fi` = Internal frequency of PSG (1789772.5 Hz on MSX).  
+`Fb` = Noise frequency master to be produced (varies between 3.608 and 111.860 Hz).
+
+### About register 7
+
+This register is used to activate or deactivate the tone generator as well as the noise generator. The format of the value is as follows:
+
+|PSG I/O ports<br>Bit7 - Bit6|Disabling noise<br>Bit5 - Bit4 - Bit3|Disabling tone<br>Bit2 - Bit1 - Bit 0|
+|:-:|:-:|:-:|
+|B=1 - A=0|channelC - channelB - channelA |channelC - channelB - channelA|
+
+Bits 7 and 6 serves to specify the direction of PSG I/O ports. Always set bit 7 and reset bit 6. Otherwise some devices connected to the joystick ports may malfunction.
+
+### About register 8 to 10
+
+The format of these registers is as follows:
+
+|Bit 7|Bit 6|Bit 5|Bit 4|Bit 3 - Bit 2 - Bit 1 - Bit 0|
+|:-:|:-:|:-:|:-:|:-:|
+|-|-|-|V/A|Volume / Amplitude of the channel|
+
+Reset bit 4 (V/A) to adjust the volume of the corresponding channel, if set the volume will vary in proportion to the envelope shape defined by register 13.
+
+### About register 11 to 13
+
+The registers 11 and 12 control the envelope period. The value is on 16 bits (0~65535). It is calculated with the following expression:
+
+`Value = Fi / (256 x T)`
+
+`Fi` = Internal frequency of PSG (1789772.5 Hz on MSX).  
+`T` = Period of the envelope (in μs)
+
+The register 13 defines the envelope shape. Here are the possible shapes:
+- 0~3	＼＿＿＿＿＿＿＿
+- 4~7	／＿＿＿＿＿＿＿
+- 8	＼＼＼＼＼＼＼＼
+- 9	＼＿＿＿＿＿＿＿
+- 10	＼／＼／＼／＼／
+- 11	＼￣￣￣￣￣￣￣
+- 12	／／／／／／／／
+- 13	／￣￣￣￣￣￣￣
+- 14	／＼／＼／＼／＼
+- 15	／＿＿＿＿＿＿＿
+
+## Examples
+
+```basic
+5 ' Initializes the sound registers of the PSG
+10 FOR R=0 TO 13
+20 IF R=7 THEN SOUND R,&B10111111 ELSE SOUND R,0
+30 NEXT
+40 ' Plays the note C on channel A with a volume of 12
+50 SOUND 0,&hAC ' 8 least significant bits of frequency on channel A
+60 SOUND 1,1 ' 4 most significant bits of frequency on channel A
+70 SOUND 8,&b1100 ' Sets the volume to 12 on channel A
+80 SOUND 7,&b10111110 ' Activates the sound generator on channel A
+```
+
+Same example in decimal mode for the values:
+```basic
+5 ' Initializes the sound registers of the PSG
+10 FOR R=0 TO 13
+20 IF R=7 THEN SOUND R,191 ELSE SOUND R,0
+30 NEXT
+40 ' Plays the note C on channel A with a volume of 12
+50 SOUND 0,172 ' 8 least significant bits of frequency on channel A
+60 SOUND 1,1 ' 4 most significant bits of frequency on channel A
+70 SOUND 8,12 ' Sets the volume to 12 on channel A
+80 SOUND 7,190 ' Activates the sound generator on channel A
+```
+
+Legendary Finnish sauna-effect (_Source: MikroBitti 12/1987_):
+```basic
+10 REM SAUNONTA-TEHOSTE
+20 SOUND 7,&B10110111
+30 SOUND 8,16
+40 SOUND 6,2
+50 SOUND 12,160
+60 SOUND 13,0
+70 FOR T=1 TO 3500:NEXT
+80 KO=INT(RND(1)*7)+2
+90 SOUND 6,KO
+100 M=INT(RND(1)*2)+3
+110 SOUND 12,M
+120 SOUND 13,4
+130 AV=INT(RND(1)*50)+250
+140 FOR T=1 TO AV:NEXT
+150 N=N+1:IF N<LL THEN 80
+160 N=0:LL=INT(RND(1)*15)+10
+170 FOR T=1 TO 1000:NEXT
+180 GOTO 40
+```
+
+## Related to
+
+`BEEP`, `PLAY`, `PLAY()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Links
+
+- [General Instrument AY-3-8910 application manual](http://map.grauw.nl/resources/sound/generalinstrument_ay-3-8910.pdf)
+- [Yamaha YM2149 SSG application manual](http://map.grauw.nl/resources/sound/yamaha_ym2149.pdf)
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SOUND"

package/resources/programming/basic_wiki/SPACE$().md

@@ -0,0 +1,38 @@
+# SPACE$()
+
+## Effect
+
+Generates a string with a specified number of spaces.
+
+This instruction is equivalent to `STRING$` used with the ASCII code 32.
+
+## Syntax
+
+`SPACE$(<Number>)`
+
+## Parameter
+
+`<Number>` is the number of spaces, it must be between 0 and 255.
+
+## Example
+
+```basic
+10 PRINT "A";SPACE$(5);"B"
+20 PRINT SPACE$(5);"AB"
+ 
+RUN
+A     B
+     AB
+```
+
+## Related to
+
+`SPC()`, `STRING$()`, `TAB()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SPACE$()"

package/resources/programming/basic_wiki/SPC().md

@@ -0,0 +1,34 @@
+# SPC()
+
+## Effect
+
+Inserts a variable amount of spaces in a `PRINT` or `LPRINT` instruction.
+
+## Syntax
+
+`SPC(<Number>)`
+
+## Parameter
+
+`<Number>` is the number of spaces, it  must be between 0 and 255.
+
+## Example
+
+```basic
+10 PRINT "MSX";SPC(3);"Forever!"
+ 
+RUN
+MSX   Forever!
+```
+
+## Related to
+
+`LPRINT`, `PRINT`, `SPACE$()`, `STRING$()`, `TAB()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SPC()"

package/resources/programming/basic_wiki/SPRITE$().md

@@ -0,0 +1,50 @@
+# SPRITE$()
+
+## Effect
+
+Defines a sprite's outlook (also known as 'pattern') and works like a regular 1-dimensional string array.
+
+It can also be used to return the sprite's pattern data in the form of a string.
+
+## Syntaxes
+
+`SPRITE$(<PatternNumber>)=<String>`
+
+`SPRITE$(<PatternNumber>)`
+
+## Parameters
+
+`<PatternNumber>` is a number ranging from 0 to 63 (for sprite size 16x16) or to 255 (for sprite size 8x8) that specifies the sprite pattern number.
+
+`<String>` is a string of 8 or 32 characters according the sprites size (8x8 or 16x16).
+
+Each character represents an 8x1 area in the sprite where "1"-bits represent visible dots and "0"-bits represent invisible dots. 
+
+The characters are given in order from up to down and left to right. Upper left corner in 16x16 sprite is therefore bit 7 of character 1, bottom right corner is bit 7 of character 16, upper right corner is bit 0 of character 17 and bottom right corner is bit 0 of character 32.
+
+In case defined the string is shorter than required (8 or 32 characters) the rest of the sprite string is filled with 0.
+
+## Example
+
+```basic
+10 COLOR 15,1,7: SCREEN 2,0
+20 B$=""
+30 FOR I=0 TO 7: READ A: B$=B$+CHR$(A): NEXT
+40 SPRITE$(0)=B$
+50 PUT SPRITE 0, (100,100),15,0
+60 A$=INPUT$(1)
+70 SCREEN 1: PRINT SPRITE$(0)
+80 DATA 24,60,126,255,36,36,66,129
+```
+
+## Related to
+
+`CHR$()`, `COLOR SPRITE()`, `COLOR SPRITE$()`, `ON SPRITE GOSUB`, `PUT SPRITE`, `SPRITE`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SPRITE$()"

package/resources/programming/basic_wiki/SPRITE.md

@@ -0,0 +1,31 @@
+# SPRITE
+
+## Effect
+
+Changes the way BASIC sprite collision interrupts are handled.
+
+## Syntax
+
+`SPRITE ON|OFF|STOP`
+
+## Parameters
+
+This instruction is always combined with `ON SPRITE GOSUB`.
+
+With `SPRITE ON`, the computer will check if two sprites have collided during the last screen draw and if a collision is detected the subroutine specified with `ON SPRITE GOSUB` is executed immediately.
+
+With `SPRITE OFF`, this checking is disabled.
+
+With `SPRITE STOP`, the checks are done, but the execution of the subroutine specified with `ON SPRITE GOSUB` will be postponed until the `SPRITE ON` instruction is executed later in the program.
+
+## Related to
+
+`ON SPRITE GOSUB`, `PUT SPRITE`, `SPRITE$()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SPRITE"

package/resources/programming/basic_wiki/SQR().md

@@ -0,0 +1,32 @@
+# SQR()
+
+## Effect
+
+Returns the square root of a variable.
+
+## Syntax
+
+`SQR(<Variable>)`
+
+## Parameter
+
+`<Variable>` must be a numeric variable or a value between 0 and 65535.
+
+## Example
+
+```basic
+10 PRINT "The square root of 16 is ";SQR(16)
+20 PRINT "The square root of 64 is ";SQR(64)
+ 
+RUN
+The square root of 16 is 4
+The square root of 64 is 8
+```
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SQR()"

package/resources/programming/basic_wiki/STICK().md

@@ -0,0 +1,70 @@
+# STICK()
+
+## Effect
+
+Returns the direction of the cursor keys or the joysticks.
+
+## Syntax
+
+`STICK(<ControllerNumber>)`
+
+## Parameter
+
+`<ControllerNumber>` is a value between 0 and 2 to define the controller used.
+
+|Controller|Description|
+|---|---|
+|0|Cursor keys|
+|1|Joystick 1|
+|2|Joystick 2|
+
+## Returned values 
+
+|Value|Description|
+|---|---|
+|0|Inactive|
+|1|Up|
+|2|Up + Right|
+|3|Right|
+|4|Down + Right|
+|5|Down|
+|6|Down + Left|
+|7|Left|
+|8|Up + Left|
+
+## Examples
+
+```basic
+10 PRINT "Press the cursor keys"
+20 PRINT STICK(0)
+30 FOR I=0 TO 300:NEXT I
+40 GOTO 20
+```
+
+```basic
+10 ' Move sprite to 8-directions by using cursor keys (by NYYRIKKI)
+20 FORI=2TO8:XD(I)=SGN(5-I):YD(8-I)=XD(I):NEXT: SWAP YD(0),YD(8):SCREEN2,1:SPRITE$(0)="0HH0"
+30 FORI=0TO1:S=STICK(J):I=-STRIG(J):X=X+XD(S):Y=Y+YD(S):PUTSPRITE0,(X,Y),8:NEXT
+```
+
+```basic
+10 ' Move sprite to 8-directions by using cursor keys
+20 SCREEN2,1: SPRITE$(0)="0HH0": FORS=1TO8: READ X(S),Y(S):NEXT
+30 S=STICK(0): Y=Y+Y(S): X=X+X(S)
+40 IF Y<0 THEN Y=0 ELSE IF Y>183 THEN Y=183
+50 IF X<0 THEN X=0 ELSE IF X>246 THEN X=246
+60 PUTSPRITE0,(X,Y),8: IF NOTSTRIG(0)GOTO30
+70 DATA 0,-2,2,-2,2,0,2,2,0,2,-2,2,-2,0,-2,-2
+```
+
+## Related to
+
+`INKEY$`, `ON...GOTO`, `ON...GOSUB`, `PAD()`, `PDL()`, `STRIG()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/STICK()"

package/resources/programming/basic_wiki/STOP.md

@@ -0,0 +1,70 @@
+# STOP
+
+## Effect
+
+Stops the execution of a program.
+
+Enables/Disables/Stops calling to a subroutine by simultaneous pressing of `CTRL`+`STOP`.
+
+## Syntaxes
+
+`STOP`
+
+`STOP ON|OFF|STOP`
+
+## Parameters
+
+Used without parameter, `STOP` is not required if the last line of the program has been reached by the BASIC interpreter. If this is not the case, then `STOP` is used as a break in the program and you can enter the `CONT` instruction to continue the program execution on the next line.
+
+`STOP` used with `ON`, `OFF`, `STOP` is always combined with `ON STOP GOSUB`.
+
+With `STOP ON`, the computer will check if the `CTRL` and `STOP` keys are pressed simultaneously and the subroutine specified with `ON STOP GOSUB` is executed immediately.
+
+With `STOP OFF`, this checking is disabled.
+
+With `STOP STOP`, the checking is made, but the execution of the subroutine specified with `ON STOP GOSUB` will happen only when a `STOP ON` instruction is executed later in the program.
+
+_Remark: With `ON STOP GOSUB`, `STOP ON` and `RETURN` (see the third example), it is possible to prevent the exit from the program with `CTRL`+`STOP`. However, if you have enabled a Debug warm start with `POKE &HFBB0,1` (for example in line 20), the user will be able to re-start MSX-BASIC by pressing simultaneously `CTRL`+`SHIFT`+`GRAPH`+`CODE`/`KANA`._
+
+## Examples
+
+```basic
+10 PRINT "Test"
+20 STOP
+30 PRINT "CONT was used"
+40 END
+```
+
+```basic
+10 ON STOP GOSUB 100 : STOP ON
+20 CLS: PRINT "ON STOP ENABLED"
+30 FOR I = 1 TO 2000 : NEXT
+40 STOP OFF
+50 PRINT: PRINT "ON STOP DISABLED"
+60 FOR I = 1 TO 2000 : NEXT
+70 STOP ON : GOTO 20
+80 PRINT: INPUT A$
+90 IF A$="END" THEN STOP OFF:END ELSE 80
+100 PRINT "Enter END and press Return":RETURN 80
+```
+
+```basic
+10 ON STOP GOSUB 100 : STOP ON
+…
+30 CLS
+…
+90 GOTO 30
+100 RETURN
+```
+
+## Related to
+
+`CONT`, `END`, `ON STOP GOSUB`, `RUN`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/STOP"

package/resources/programming/basic_wiki/STR$().md

@@ -0,0 +1,37 @@
+# STR$()
+
+## Effect
+
+Returns a string representation of a numeric variable.
+
+## Syntax
+
+`STR$(<Value>)`
+
+## Parameter
+
+`<Value>` must be an expression, a numeric variable or a value.
+
+## Example
+
+```basic
+10 A$=STR$(1.23)
+20 PRINT A$
+30 PRINT LEFT$(A$,2)
+ 
+RUN
+ 1.23
+ 1
+```
+
+## Related to
+
+`VAL`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/STR$()"