================================================================================
                    TVC XBASIC PROGRAMOZÁSI DOKUMENTÁCIÓ
================================================================================
                    Videoton TV Computer - Extended BASIC
                    Készült: 2025. december 18.
================================================================================

TARTALOMJEGYZÉK
---------------
1. Bevezetés
2. Fejlesztői környezet
3. Alapvető szintaxis szabályok
4. Graphics módok
5. Képernyő kezelés
6. Változók és tömbök
7. Vezérlési szerkezetek
8. Billentyűzet kezelés
9. Hang
10. Memória kezelés
11. Gyakori hibák és megoldások
12. Példaprogramok
13. Hasznos tippek

================================================================================
1. BEVEZETÉS
================================================================================

Az XBASIC (Extended BASIC) a Videoton TVC számítógép kibővített BASIC 
programozási nyelve. Ez a dokumentáció az XBASIC nyelv használatát és a 
fejlesztés folyamatát mutatja be gyakorlati példákon keresztül.


================================================================================
2. FEJLESZTŐI KÖRNYEZET
================================================================================

SZÜKSÉGES FÁJLOK:
-----------------
- xbas.exe          - XBASIC fordító
- xbas2cas.exe      - Kazetta formátum konvertáló
- WinTVCx64.exe     - TVC emulátor
- xpause.exe        - Billentyű várakozás segédprogram

PROJEKT STRUKTÚRA:
------------------
MyProject/
  ├── myprogram.xbas     (forrás fájl)
  ├── myprogram.bat      (build script)
  └── myprogram.cas      (kazetta kimenet)

BUILD SCRIPT SABLON (myprogram.bat):
------------------------------------
@echo off
set CSOURCE=%~n0

:loop
rem Compile and run
..\bin\xbas.exe %CSOURCE%.xbas
..\bin\xbas2cas.exe -o %CSOURCE%.bas
..\wintvcx64.exe -a %CSOURCE%.cas
del %CSOURCE%.bas_temp

echo Press any key to recompile! (ESC to exit)
..\bin\xpause.exe 
if errorlevel 27 (
    exit /b
)
goto loop


================================================================================
3. ALAPVETŐ SZINTAXIS SZABÁLYOK
================================================================================

KOMMENTEK:
----------
// Ez egy komment
// FONTOS: Kommentek CSAK a sor elején használhatók!
// NEM lehet kód után komment ugyanabban a sorban!

HELYES:
    // Ez egy komment
    x = 10

HELYTELEN:
    x = 10  // Ez hibát okoz!

CÍMKÉK (LABELS):
----------------
§cimke:
    // Kód ide

FONTOS SZABÁLYOK:
- Címkék CSAK a sor elején állhatnak (nincs tab/space előttük)
- § jellel kezdődnek
- Kettősponttal végződnek
- Pont (.) használható bennük (pl. §menu.wait)

HELYES:
§menu:
    cls
    goto §menu

HELYTELEN:
    §menu:      // Nem lehet beljebb!

DEFINE (KONSTANSOK):
-------------------
#define §konstans érték

Példa:
#define §width 30
#define §height 20

INDENTÁLÁS:
-----------
- Minden kód ami NEM címke: 1 TAB-bal beljebb!
- Címkék: sor elején (0 indentálás)

Példa:
§start:
    cls
    x = 10
    goto §loop

§loop:
    x = x + 1
    goto §loop


================================================================================
4. GRAPHICS MÓDOK
================================================================================

GRAPHICS 16 MÓD:
----------------
- Felbontás: 16×16 karakter
- Egyedi karakterek definiálhatók
- Színes grafika

Használat:
    graphics 16

GRAPHICS 4 MÓD:
---------------
- Felbontás: 32×24 karakter (szélesség: max 30-31 használható)
- Több karakter elfér a képernyőn
- Egyszerűbb szöveges megjelenítés

Használat:
    graphics 4

FONTOS:
- A printat koordináták 1-től kezdődnek (NEM 0-tól!)
- Ha 0 koordinátát használsz: SYSTEM ERROR!


================================================================================
5. KÉPERNYŐ KEZELÉS
================================================================================

CLS - KÉPERNYŐ TÖRLÉS:
----------------------
    cls

SETPAPER - HÁTTÉRSZÍN:
----------------------
    setpaper 0      // Fekete háttér

SETINK - ELŐTÉR SZÍN:
---------------------
    setink 15       // Fehér
    setink 14       // Sárga
    setink 10       // Zöld
    setink 6        // Barna
    setink 11       // Világoskék

PRINTAT - KURZOR POZICIONÁLÁS ÉS KIÍRÁS:
-----------------------------------------
SZINTAXIS:
    printat sor, oszlop: "szöveg"
    printat sor, oszlop: változó
    printat sor, oszlop: chr$(kod)

FONTOS:
- Koordináták 1-től kezdődnek!
- sor: 1-24 (graphics 4 módban)
- oszlop: 1-30 (graphics 4 módban, 32-nél sortörés!)

Példák:
    printat 1, 1: "Hello TVC!"
    printat 10, 5: score
    printat 5, 10: "X=" x " Y=" y

SETCHARACTER - EGYEDI KARAKTER (graphics 16):
----------------------------------------------
    setcharacter kod, byte1, byte2, ..., byte11

Példa (8x8 pixel + 3 extra byte):
    setcharacter 180, 60, 102, 231, 255, 255, 254, 124, 56, 0, 0

CHR$() - KARAKTER KÓD:
----------------------
    printat 5, 10: chr$(65)     // "A" betű
    printat 5, 10: chr$(180)    // Egyedi karakter


================================================================================
6. VÁLTOZÓK ÉS TÖMBÖK
================================================================================

VÁLTOZÓK:
---------
    x = 10
    y = 20
    nev$ = "TVC"        // String változó: $ jellel végződik
    eredmeny = x + y

TÖMBÖK:
-------
DEKLARÁLÁS:
    dim tomb(100)       // 0-100 elemű tömb (101 elem)
    dim nevek$(50)      // String tömb

HASZNÁLAT:
    tomb(0) = 5
    tomb(i) = x + 10
    ertek = tomb(5)

FONTOS:
- A tömbök 0-tól indexelődnek
- dim paranccsal kell deklarálni használat előtt


================================================================================
7. VEZÉRLÉSI SZERKEZETEK
================================================================================

GOTO - FELTÉTEL NÉLKÜLI UGRÁS:
-------------------------------
    goto §cimke

IF - FELTÉTELES VÉGREHAJTÁS:
----------------------------
EGYSZERŰ IF (EGY SOR):
    if feltetel then parancs

TÖBB PARANCS EGY SORBAN:
    if feltetel then parancs1: parancs2: parancs3

EGYMÁSBA ÁGYAZOTT IF (EGY SORBAN):
    if feltetel1 then if feltetel2 then parancs

FONTOS: A TVC NEM ISMERI AZ ENDIF KULCSSZÓT!
    - Csak egysoros if használható
    - Többsoros if-blokk NINCS
    - Egymásba ágyazott feltételeket egy sorba kell írni

HELYES:
    if k$ = "w" then if y > 1 then y = y - 1
    if x = 10 then gosub §action

HELYTELEN (NEM MŰKÖDIK):
    if feltetel then
        parancs1
        parancs2
    endif

IF-ELSE (nincs else kulcsszó, goto-val kell megoldani):
    if feltetel then goto §igaz
    // hamis ág
    goto §vege
§igaz:
    // igaz ág
§vege:

FELTÉTELEK:
    =       egyenlő
    <>      nem egyenlő
    <       kisebb
    >       nagyobb
    <=      kisebb vagy egyenlő
    >=      nagyobb vagy egyenlő
    and     ÉS
    or      VAGY

Példák:
    if x = 10 then y = 20
    if x < 0 or x >= §width then goto §hiba
    if k$ = "w" and dy = 0 then dx = 0: dy = -1

FOR - CIKLUS:
-------------
    for valtozo = kezdet to veg
        // parancsok
    next

Példa:
    for i = 1 to 10
        printat i, 1: i
    next

    for i = 0 to §width - 1
        x = x + i
    next

GOSUB - VISSZATÉRŐ UGRÁS (SZUBRUTIN):
-------------------------------------
    gosub §szubrutin
    // folytatás itt

§szubrutin:
    // kód
    return

END - PROGRAM VÉGE:
-------------------
    end


================================================================================
8. BILLENTYŰZET KEZELÉS
================================================================================

INKEY$ - BILLENTYŰ LEKÉRDEZÉS:
------------------------------
    k$ = inkey$

FONTOS:
- NEM vár billentyűre! Azonnal visszatér
- Ha nincs billentyű: üres string ("")
- Ha van: a lenyomott karakter

HASZNÁLAT:
    k$ = inkey$
    if k$ = "w" then y = y - 1
    if k$ = "s" then y = y + 1
    if k$ = " " then goto §start
    if k$ = chr$(27) then goto §exit    // ESC

GYAKORI MINTÁK:

VÁRAKOZÁS BILLENTYŰRE:
§wait:
    k$ = inkey$
    if k$ = "" then goto §wait
    // folytatás

MENÜ:
§menu.wait:
    k$ = inkey$
    if k$ = "1" then goto §level1
    if k$ = "2" then goto §level2
    goto §menu.wait

JÁTÉK VEZÉRLÉS:
    k$ = inkey$
    if k$ = "w" or k$ = "W" then gosub §move.up
    if k$ = "s" or k$ = "S" then gosub §move.down


================================================================================
9. HANG
================================================================================

SOUND - HANGEFFEKT:
-------------------
SZINTAXIS:
    sound pitch hangmagassag, volume hangerő, duration időtartam

PARAMÉTEREK:
    - hangmagassag: 100-2000 (minél nagyobb, annál magasabb)
    - hangerő: 1-15 (15 a legerősebb)
    - időtartam: 1-10 (relatív érték)

PÉLDÁK:

ÜTÉS HANG:
    sound pitch 800, volume 8, duration 1

FAL ÜTÉS:
    sound pitch 400, volume 5, duration 1

GAME OVER:
    sound pitch 200, volume 15, duration 5

ÉTEL MEGSZERZÉS (Snake):
    sound pitch 800, volume 10, duration 1


================================================================================
10. MEMÓRIA KEZELÉS
================================================================================

POKE - BYTE ÍRÁS MEMÓRIÁBA:
---------------------------
    poke cim, ertek

Példa:
    mapaddr = 30000
    poke mapaddr + 5, 1

PEEK - BYTE OLVASÁS MEMÓRIÁBÓL:
-------------------------------
    valtozo = peek(cim)

Példa:
    cell = peek(mapaddr + y * 16 + x)
    if cell = 1 then goto §collision

TIPIKUS HASZNÁLAT (JÁTÉKOK):
    // Memóriában tárolt pálya (pl. Snake)
    mapaddr = 30000
    
    // Pálya inicializálás
    for i = 0 to 319
        poke mapaddr + i, 0
    next
    
    // Érték írása
    addr = mapaddr + y * 16 + x
    poke addr, 1
    
    // Érték olvasása
    cell = peek(addr)
    if cell = 1 then goto §collision


================================================================================
11. GYAKORI HIBÁK ÉS MEGOLDÁSOK
================================================================================

HIBA: SYSTEM ERROR 245, PRINTAT 2, 1
------------------------------------
OK: 0-val indexeltél printat-ban!
MEGOLDÁS: Koordináták 1-től kezdődnek!

HELYTELEN:
    printat 0, 5: "Hiba"
    for i = 0 to 10
        printat 2, i: "-"    // i=0 esetén hiba!
    next

HELYES:
    printat 1, 5: "Jó"
    for i = 1 to 10
        printat 2, i: "-"
    next

HIBA: SORTÖRÉS / TÚLCSORDULÁS
------------------------------
OK: Túl széles a képernyő!
MEGOLDÁS: Graphics 4 módban max 30-31 karakter széles legyen!

HELYTELEN:
    #define §width 32    // Sortörést okoz!

HELYES:
    #define §width 30

HIBA: CÍMKE NEM TALÁLHATÓ
--------------------------
OK: Címke nincs a sor elején!
MEGOLDÁS: Címkék 0 indentálással!

HELYTELEN:
    §menu:        // TAB-bal beljebb - HIBA!

HELYES:
§menu:
    // Kód ide

HIBA: KOMMENT HIBA
------------------
OK: Komment nem a sor elején van!
MEGOLDÁS: Kommentek csak a sor elején!

HELYTELEN:
    x = 10  // Ez hiba

HELYES:
// Ez jó
    x = 10


================================================================================
12. PÉLDAPROGRAMOK
================================================================================

PÉLDA 1: HELLO WORLD
---------------------
graphics 4
cls
setink 15
printat 10, 10: "Hello TVC!"
k$ = inkey$
if k$ = "" then goto 5
end

PÉLDA 2: EGYSZERŰ MENÜ
-----------------------
graphics 4
cls

§menu:
    setink 14
    printat 5, 10: "M E N U"
    setink 15
    printat 8, 8: "1 - Start"
    printat 9, 8: "2 - Kilépés"

§menu.wait:
    k$ = inkey$
    if k$ = "1" then goto §game
    if k$ = "2" then goto §exit
    goto §menu.wait

§game:
    cls
    printat 10, 10: "Játék indul..."
    // Játék kód
    end

§exit:
    cls
    printat 10, 8: "Viszlát!"
    end

PÉLDA 3: MOZGÓ LABDA
--------------------
graphics 4
cls

x = 15
y = 10
dx = 1
dy = 1

§loop:
    // Régi pozíció törlése
    printat y, x: " "
    
    // Mozgatás
    x = x + dx
    y = y + dy
    
    // Falütközés
    if x <= 1 or x >= 30 then dx = -dx
    if y <= 1 or y >= 20 then dy = -dy
    
    // Új pozíció
    setink 15
    printat y, x: "O"
    
    // Kis várakozás
    for d = 1 to 3
    next
    
    goto §loop

PÉLDA 4: PONTSZÁMLÁLÓ
----------------------
graphics 4
cls
score = 0

§loop:
    printat 1, 1: "Pont:"
    printat 1, 7: score
    
    k$ = inkey$
    if k$ = " " then score = score + 1
    if k$ = chr$(27) then goto §exit
    
    goto §loop

§exit:
    cls
    printat 10, 8: "Vége! Pont:"
    printat 10, 19: score
    end


================================================================================
13. HASZNOS TIPPEK
================================================================================

KÓDOLÁSI STÍLUS:
----------------
1. Használj beszédes címkeneveket (§menu, §game.loop, §draw.border)
2. Kommentezz bőségesen!
3. Csoportosítsd a kódot logikai blokkokba
4. Használj üres sorokat a jobb olvashatósághoz

OPTIMALIZÁLÁS:
--------------
1. Kerüld a felesleges printat hívásokat
2. Csak akkor rajzolj, ha változott valami
3. Használj változókat a gyakran használt értékekhez

HIBAKERESÉS:
------------
1. Kis lépésekben fejlessz
2. Tesztelj gyakran
3. Kommentezd ki a gyanús részeket
4. Használj printat-ot debug-oláshoz:
   printat 1, 1: "Debug: x=" x " y=" y

KOORDINÁTA RENDSZER:
--------------------
Graphics 4 mód:
    ┌─────────────────────────────┐
  1 │ (1,1)              (30,1)   │
    │                             │
    │                             │
    │         (15,10)             │
    │                             │
    │                             │
 20 │ (1,20)             (30,20)  │
    └─────────────────────────────┘
      1                          30

MEMÓRIA LAYOUT (16 széles pálya):
----------------------------------
    y=0: 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15
    y=1: 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
    
    addr = mapaddr + y * 16 + x

GYAKORI JÁTÉK MINTÁK:
---------------------

JÁTÉK LOOP:
§loop:
    // 1. Input kezelés
    k$ = inkey$
    
    // 2. Játék logika
    x = x + dx
    y = y + dy
    
    // 3. Ütközések
    if collision then goto §gameover
    
    // 4. Rajzolás
    printat y, x: "O"
    
    // 5. Késleltetés
    for d = 1 to speed
    next
    
    goto §loop

ÉLETEK RENDSZER:
    lives = 3

§lose.life:
    lives = lives - 1
    if lives <= 0 then goto §gameover
    // Restart pozíciók
    x = 15
    y = 10
    return

PONTSZÁMOLÁS:
    score = 0

§add.points:
    score = score + 10
    printat 1, 10: score
    return


================================================================================
TOVÁBBI INFORMÁCIÓK
================================================================================

Ez a dokumentáció gyakorlati tapasztalatok alapján készült TVC XBASIC 
programozás során. A példák működőképesek és teszteltek.

Projekt példák:
- Snake játék (SnakeAI könyvtár)
- Pong játék (Pong könyvtár)

Készítette: GitHub Copilot
Dátum: 2025. december 18.

Jó programozást! 🎮

================================================================================
