# Algemene game-library 0.1 (proefversie)

Deze API geeft je een eigen spellus. Tekenen, sprites, schermbuffers en
keyboardstatus zitten in dezelfde native C-kern voor BASIC en MicroPython.
Spelregels en botsingsafhandeling bepaal je zelf. De nieuwe Sprite Lab-demo
gebruikt geen ingebouwde platformphysics. De bestaande Copper Courier-scene
met `game.open/row/run` blijft beschikbaar.

## Python starten

Zet STGAME.PY naast je programma in C:\TTPY en gebruik `import stgame as
pg`.
STGAME.PY is de leesbare Python-laag boven de ingebouwde `game`-module;
er is geen losse game.py. Start PLAY.PY met F5 voor een volledig
platformspel.
STGAME.PY hoeft alleen naast het programma te staan, niet apart uitgevoerd.
In TTCON: `import PLAY`; later opnieuw starten met `PLAY.main()`.
ROBOT.SPR is een klein voorbeeld voor `pg.image.load("ROBOT.SPR")`.
Alleen de ingebouwde module en de STGAME.PY van dezelfde preview combineren.

```python
import stgame as pg
screen = pg.display.set_mode((320, 200))
try:
    clock = pg.time.Clock()
    player = pg.image.from_rows([".EE.", "E44E", ".EE."])
    x = 20
    running = True
    while running:
        for event in pg.event.get():
            if event.type == pg.QUIT:
                running = False
        keys = pg.key.get_pressed()
        if keys[pg.K_RIGHT]:
            x = min(316, x + 2)
        screen.fill(0)
        screen.blit(player, (x, 100))
        pg.draw.text(screen, "HELLO ATARI", (8, 8), 14)
        pg.display.flip()
        clock.tick(25)
finally:
    pg.quit()
```

Het gevraagde tempo is een maximum, geen gegarandeerde beeldsnelheid. Bij
veel
Python-code of veel tekenaanroepen kan een ST/TT/Falcon aanzienlijk trager
zijn. Gebruik voor spelregels een vaste tijdstap, zoals PLAY.PY en PLAY.BAS.
Dit is een functionele eerste versie; de renderer/interpreter vraagt nog
performancewerk. Dit pakket is geen vervanging van desktop-pygame.

## Scherm en kleuren

Intern altijd320x200, zonder de Atari-schermmodus te veranderen. De fysieke
modus moet minstens320x200 en planar1..8 bitplanes zijn. De Studio zelf
vraagt
minstens640x400; een zelfstandige BASIC-PRG of TTCON kan op ST Low starten.
TOS2.00+,68000 zonder FPU, voor de Studio's minimaal4MiB. Fysieke
hardwaretests
staan nog open. Falcon truecolour16-bit en externe videokaarten niet
ondersteund.

De logische kleuren0..F zijn vaste paletindices:0 blauw,1 donkerblauw,
2 groen,3 lichtgroen,4 goud,5 bruin,6 oranje,7 bijna wit,8 donkerblauwgrijs,
9 rood,A lichtblauw,B lichtgrijs,C zeer donker,D donkergroen,E wit,F paars.
Bij vier fysieke kleuren worden ze benaderd. In monochroom zijn0/1/8/C
donker
en de overige indices licht. Geen eigen RGB-paletten in deze eerste API.

`display.set_mode((320,200))` opent en geeft de display-Surface terug.
Optionele flags moeten0 zijn; depth is0 of16 (logische kleuren, geen16-bit).
`display.open(320,200,colors=16)` is een alias. `display.get_surface()`
geeft
het scherm terug of None. `display.flip()` presenteert de buffer; tekenen
blijft onzichtbaar tot flip. `display.zoom(1)` toont compact;2 is alleen
beschikbaar als het fysieke scherm minstens640x400 is. Default:2 waar
passend,
behalve ST High waar1 wordt gebruikt. Er is geen automatische F-sneltoets.
`pg.quit()`/`display.quit()` herstelt scherm, palet, toetsenbord en muis.
Gebruik altijd try/finally. Bij interpreter-einde wordt ook native
opgeruimd.
Open geen GEM-dialogen of andere game-scene tijdens een open display.

## Tekenen en sprites

- `screen.fill(color)`: hele tekenbuffer vullen.
- `pg.draw.rect(screen,color,(x,y,w,h),width=0)`: gevuld; width>0 tekent een
rand.
- `pg.draw.text(screen,text,(x,y),color=14)`: ingebouwd5x7-font,6pixels per
letter,
  maximaal127tekens, hoofdletters/cijfers/spatie/minteken/slash. Kleine
letters
  worden hoofdletters; andere tekens zijn leeg. y moet0..193 zijn.
- `pg.image.from_rows(rows)`: sprite, iedere regel even breed;1..64
bij1..64.
  `0123456789ABCDEF` zijn kleuren, `.` is transparant. Kleine hexletters ook
goed.
- `pg.image.load("ROBOT.SPR")`: hetzelfde patroon uit een gewoon
tekstbestand;
  een rij per regel. Nog geen PNG, BMP, PI1 of gecomprimeerde afbeeldingen.
- `pg.Surface((w,h))`: lege, transparante sprite; `sprite.fill(color)` vult
hem.
- `screen.blit(sprite,(x,y))`: transparante sprite op displaybuffer tekenen.
  Coo?rdinaten zijn gehele pixels. Buiten beeld wordt geclipt. Retourneert
Rect.
- `surface.get_size()`, `surface.get_rect()` en `surface.close()` zijn
beschikbaar.

Maximaal16 gelijktijdige sprites. Vrijmaken met close; alle slots worden bij
het volgende display vrijgegeven. Geen automatisch vrijmaken via GC, dus
hergebruik sprites in een spellus. Surface-verwijzingen zijn ongeldig na
quit
of opnieuw set_mode. Deze versie ondersteunt alleen sprite-naar-display-
blits;
geen rotatie, scaling, alpha, sprite-naar-sprite-blits of spritegroepen.
Tekenbereik -16000..16000; kleur0..15. Gebruik normale kleine
schermcoo?rdinaten.

Voorbeeld ROBOT.SPR:

```text
.EE.
E44E
.EE.
```

## Invoer en tijd

`pg.event.get()` pompt de Atari-toetsenbordberichten en geeft Event-
objecten.
`event.type` is pg.KEYDOWN, pg.KEYUP of pg.QUIT; `event.key` is een Atari
scancode.
Escape levert ook QUIT. `pg.event.pump()` pompt zonder events op te halen.
`pg.key.get_pressed()[scancode]` leest de huidige ingedrukte toestand. Poll
die
voor vasthouden/lopen; gebruik KEYDOWN voor een enkele sprong. Native queue:
63 gebeurtenissen; haal events iedere frame op. Bij overloop kunnen events
wegvallen; actuele key-status blijft werken en Escape blijft een exit-
signaal.
Geen muis-/joystick-events in deze eerste versie.

Constanten: K_ESCAPE1, K_LEFT75, K_RIGHT77, K_UP72, K_DOWN80, K_SPACE57,
K_a30, K_d32, K_w17, K_r19. Dit zijn Atari-scancodes, niet pygame/SDL-
keycodes.
`pg.time.get_ticks()` geeft milliseconden. `pg.time.wait(ms)`
wacht0..1000ms.
`clock=pg.time.Clock(); dt=clock.tick(fps)` wacht zo nodig en retourneert
verstreken milliseconden; fps0 = niet begrenzen, geldig0..200.

## Rechthoeken en botsingen

`r=pg.Rect(x,y,w,h)` of `pg.Rect((x,y,w,h))` bewaart x,y,w,h. `r.right` en
`r.bottom` lezen/schrijven de rechter-/onderrand; `r.size` geeft(w,h).
`r.copy()`, `r.move(dx,dy)` en `r.move_ip(dx,dy)` zijn beschikbaar.
`r.colliderect(other)` accepteert Rect of tuple. Alleen echte overlap telt:
randen die elkaar raken botsen niet. Een lege/negatieve afmeting botst niet.
`r.collidepoint(x,y)` omvat links/boven, sluit rechts/onder uit.
Dit is rechthoekdetectie; je schrijft zelf de reactie op een botsing.

## BASIC: dezelfde native kern

Open PLAY.TBP voor dezelfde speelbare Sprite Lab-demo in BASIC.
Game.Canvas()
is de algemene API; Game.Open/Row/Run blijft de aparte Copper Courier-scene.
Native spritehandles zijn alleen geldig tot Free/Close/volgende Canvas;
hergebruik geen oude handles na het openen van een nieuw canvas.

| BASIC-aanroep | Betekenis |
| --- | --- |
| Game.Canvas() | Open320x200 tekenbuffer; geen level nodig |
| Game.Fill(kleur) | Hele buffer vullen |
| Game.Rect(x,y,w,h,kleur) | Gevulde rechthoek |
| Game.Text(x,y,kleur,tekst) |5x7-tekst in buffer |
| Game.Sprite(w,h) | Nieuwe transparante spritehandle1..16 |
| Game.SpriteRow(handle,rij,tekst) | Rij0..h-1, exacte breedte, hex/dot |
| Game.Blit(handle,x,y) | Sprite naar buffer |
| Game.Free(handle) | Spriteslot vrijgeven |
| Game.Flip() | Buffer presenteren |
| Game.Zoom(schaal) |1 of2 als fysieke resolutie dat toelaat |
| Game.Poll() | Berichten pompen; False na Escape, anders True |
| Game.Key(scan) | True als toets nu ingedrukt is |
| Game.Event() | Volgende gebeurtenis,0 als leeg |
| Game.Ticks() | Milliseconden |
| Game.Wait(ms) | Wachten0..1000ms |
| Game.Collide(x,y,w,h,x2,y2,w2,h2) | True bij rechthoekoverlap |
| Game.Close() | Alles herstellen en sluiten |

Event getal: bit8=keydown, bit9=keyup, onderste7bits=scancode. Voorbeeld:
333=keydown rechts,589=keyup rechts. BASIC-True is-1; False is0.
Ook Collide werkt zonder Canvas. Ticks/Wait vereisen geen open canvas.

```vb
Try
    Game.Canvas()
    While Game.Poll()
        Game.Fill(0)
        Game.Rect(20,100,12,14,4)
        Game.Text(8,8,14,"HELLO ATARI")
        Game.Flip()
        Game.Wait(40)
    Wend
Finally
    Game.Close()
End Try
```

Python-fouten laten een open canvas staan zolang je ze zelf opvangt. Sluit
het
in finally; BASIC sluit bij run-einde/fout, maar ook daar verdient Finally
de
voorkeur. De huidige library heeft geen geluid-/mixer-API, tilemapbestanden,
netwerk of volledige pygame-compatibiliteit. Die zijn niet stilzwijgend
aanwezig.
