From ba6218d2177e35e0aa0d0303785c470f64896ede Mon Sep 17 00:00:00 2001 From: Zsolt Tasnadi Date: Sat, 18 Jul 2026 20:43:18 +0200 Subject: [PATCH] docs to english --- .clangd | 4 +- .gitignore | 8 +-- Makefile | 6 +- README.md | 199 +++++++++++++++++++++++++++-------------------------- 4 files changed, 111 insertions(+), 106 deletions(-) diff --git a/.clangd b/.clangd index 1d95253..e034e79 100644 --- a/.clangd +++ b/.clangd @@ -1,4 +1,4 @@ -# IDE (clangd) segédkonfig: az Oscar64 vendorolt headerjeit így találja -# meg a nyelvi szerver; a tényleges fordítást az oscar64 végzi (Makefile). +# IDE (clangd) helper config: lets the language server find the vendored +# Oscar64 headers; the actual compilation is done by oscar64 (see Makefile). CompileFlags: Add: [-Ioscar64/include, -I../oscar64/include, -Wno-unknown-pragmas] diff --git a/.gitignore b/.gitignore index ec565c3..abc0b8d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,11 @@ -# a demo fordítási kimenete (demo.prg + generált .asm/.map/.lbl/.int) +# demo build output (demo.prg + generated .asm/.map/.lbl/.int) build/ -# a vendorolt Oscar64 lokálisan épített binárisa és köztes objektumai -# (a Makefile első futáskor újraépíti: make -C oscar64/make compiler) +# locally built binary and intermediate objects of the vendored Oscar64 +# (the Makefile rebuilds it on first run: make -C oscar64/make compiler) oscar64/bin/ oscar64/build/ -# szerkesztő / OS szemét +# editor / OS junk .DS_Store *.swp diff --git a/Makefile b/Makefile index 3bd6dd7..a50373d 100644 --- a/Makefile +++ b/Makefile @@ -11,11 +11,11 @@ all: build deps: ifeq ($(UNAME_S),Darwin) - @command -v brew >/dev/null 2>&1 || { echo "Homebrew kell ehhez. Telepitsd: https://brew.sh"; exit 1; } + @command -v brew >/dev/null 2>&1 || { echo "Homebrew is required. Install it: https://brew.sh"; exit 1; } brew install vice else - @echo "A 'deps' target csak macOS-en (Darwin) automatikus. Detektalt OS: $(UNAME_S)" - @echo "Telepitsd kezzel a VICE emulatort (x64sc). Az Oscar64 vendorolt, magatol epul." + @echo "The 'deps' target is only automated on macOS (Darwin). Detected OS: $(UNAME_S)" + @echo "Install the VICE emulator (x64sc) manually. Oscar64 is vendored and builds itself." @exit 1 endif diff --git a/README.md b/README.md index fcb87a8..ab66188 100644 --- a/README.md +++ b/README.md @@ -1,138 +1,143 @@ # C64 Demo — Teletype Games slide show (Oscar64) -A Commodore 64 slide show, C-ben, az [Oscar64](https://github.com/drmortalwombat/oscar64) -fordítóval. Az eredetileg 6502 assemblyben (ACME) írt [c64-demo](../c64-demo) -portja: öt slide váltakozik automatikusan, slide-onkénti átmenetekkel feketén -keresztül, és a show billentyűzetről is vezérelhető. +A Commodore 64 slide show written in C, built with the +[Oscar64](https://github.com/drmortalwombat/oscar64) compiler. A port of the +[c64-demo](../c64-demo) originally written in 6502 assembly (ACME): five slides +rotate automatically with per-slide transitions through black, and the show can +also be driven from the keyboard. -## A slide-ok +## The slides -1. **TTG logó + credits scroller** — óriás TTG betűk 8×8-as bitmapekből, arany - színfutással, pulzáló **TELETYPE GAMES** felirat, sima pixel-scroller a - stáblistával. -2. **Az első játékunk** — *DEFINITELY NOT AN IMPOSTOR* nagy 3×5-ös - blokkbetűkkel, arany wash-sal, „introduced on TIC-80". -3. **A második játékunk** — *IS COMING* nagybetűkkel, vetett árnyékkal; - a raszterbárok csak a kereten futnak, így a szöveg olvasható marad. -4. **Kapcsolat** — pulzáló *CONTACT* cím, web / BBS / IRC sorok, 12 cellás - háromrétegű parallax csillagmező és hat hardveres sprite (négyágú csillagok) - szinusz-pályán a szöveg mögött. -5. **Az assembly vallomás** — sorkizárt szöveg arról, hogy ez a slide show egy - kis AI-segítséggel készült; a törzs élőben gépelődik be (karakterenként egy - frame, fehér blokk-kurzorral), a záró sor a gépelés végén jelenik meg és pulzál. +1. **TTG logo + credits scroller** — giant TTG letters built from 8×8 bitmaps + with a gold color wash running across them, a pulsing **TELETYPE GAMES** + title, and a smooth pixel scroller with the crew credits. +2. **Our first game** — *DEFINITELY NOT AN IMPOSTOR* in big 3×5 block letters + with the gold wash, "introduced on TIC-80". +3. **Our second game** — *IS COMING* in big letters with a drop shadow; raster + bars run on the border only, so the text stays readable. +4. **Contact** — pulsing big *CONTACT* title, web / BBS / IRC lines, a 12-cell + three-layer parallax starfield, and six hardware sprites (four-pointed + stars) floating on sine-wave paths behind the text. +5. **The assembly confession** — a justified-text piece about how this slide + show was written with a little help from an AI; the body types in live (one + character per frame with a white block cursor), and a closing line appears + and pulses when the typing is done. -Minden slide 8 másodpercig látszik (`SLIDE_TIME` a `src/defs.h`-ban, PAL -frame-ekben); az 5-ös slide 9 másodpercet kap (`S5_TIME`), hogy az írógép végezzen. +Each slide is shown for 8 seconds (`SLIDE_TIME` in `src/defs.h`, PAL frames); +slide 5 gets 9 seconds (`S5_TIME`) to let the typewriter finish. -## Vezérlés +## Controls -| Billentyű | Funkció | -|-----------|---------| -| `SPACE` | következő slide azonnal | -| `INST/DEL` (backspace) | előző slide | -| `P` | pause — a visszaszámlálás megáll, fehér `P` jelző a jobb felső sarokban; az effektek futnak tovább, SPACE/DEL működik | -| `M` | némítás — a SID zene ki/be | +| Key | Action | +|-----|--------| +| `SPACE` | next slide immediately | +| `INST/DEL` (backspace) | previous slide | +| `P` | pause toggle — the countdown freezes and a white `P` marker appears in the top-right corner; effects keep running, and SPACE/DEL still work while paused | +| `M` | mute/unmute — toggles the SID music on or off | -A billentyűket közvetlenül a CIA1 mátrixból olvassuk (a KERNAL IRQ le van tiltva). +Keys are read directly from the CIA1 keyboard matrix (the KERNAL IRQ is +disabled). -## Fordítás és futtatás +## Build and run ```sh -make build # fordítás -> build/demo.prg (első futáskor a fordítót is megépíti) -make run # futtatás VICE emulátorban (x64sc kell hozzá) -make rebuildrun # tiszta újrafordítás + futtatás -make clean # build mappa törlése -make deps # macOS-en: VICE telepítése Homebrew-val +make build # compile -> build/demo.prg (builds the compiler too on first run) +make run # build + launch in VICE (requires x64sc) +make rebuildrun # clean rebuild + run +make clean # remove the build directory +make deps # on macOS: install VICE via Homebrew ``` -Ugyanezek a `.vscode/tasks.json`-ból VS Code taskként is futtathatók -(a `build` az alapértelmezett build task). +The same targets are available as VS Code tasks from `.vscode/tasks.json` +(`build` is the default build task). -Betöltés igazi vagy emulált C64-en: +Loading the `.prg` on a real or emulated C64: ``` LOAD"*",8,1 RUN ``` -## Forrás-elrendezés +## Source layout -| Fájl | Tartalom | +| File | Contents | |------|----------| -| `src/main.c` | főciklus, slide-szekvenszer, billentyűolvasás (SPACE / DEL / P / M), slide-táblák | -| `src/defs.h` | hardvermutatók, színek, elrendezés/időzítés konstansok, screen code charmap | -| `src/transitions.c` | átmenet-motor: show/hide, három átmenettípus (fade, dissolve, wipe), `wait_frame` raszter-szinkron, színsnapshot | -| `src/common.c` | közös rutinok (`clear_screen`, `print_text`, `draw_big`), közös táblák (sor×40, 3×5 blokkfont, wash/pulse/fade rámpák) | -| `src/music.c` | SID zenemotor: háromszólamú pattern-lejátszó (basszus, dob, echo lead) az *Impostor* dallam adataival | -| `src/slide1.c` … `slide5.c` | slide-onként egy fájl: `sN_init` (képernyőrajzolás), `sN_update` (frame-enként egyszer fut) + slide-lokális adatok | +| `src/main.c` | main loop, slide sequencer, keyboard scanning (SPACE / DEL / P / M), slide tables | +| `src/defs.h` | hardware pointers, colors, layout/timing constants, the screen-code charmap | +| `src/transitions.c` | slide transition engine: show/hide, three transition types (fade, dissolve, wipe), `wait_frame` raster sync, color snapshot | +| `src/common.c` | shared routines (`clear_screen`, `print_text`, `draw_big`), shared tables (row×40 lookup, 3×5 block font, wash/pulse/fade color ramps) | +| `src/music.c` | SID music driver: three-voice pattern player (bass, drums, echo lead) with the note/pattern tables of the *Impostor* tune | +| `src/slide1.c` … `slide5.c` | one file per slide: `sN_init` (draws the screen), `sN_update` (runs once per frame), plus slide-local data | -A fordítási egységeket az Oscar64 `#pragma compile("file.c")` mechanizmusa fűzi -össze: minden header behúzza a hozzá tartozó `.c`-t, ezért a `make`-nek elég a -`src/main.c`-t átadni. +The translation units are tied together by Oscar64's +`#pragma compile("file.c")` mechanism: every header pulls in its matching +`.c` file, so `make` only needs to pass `src/main.c` to the compiler. -## Hogyan működik +## How it works -### Slide-keretrendszer +### Slide framework -Minden slide egy **init** rutinból (megrajzolja a teljes képernyőt), egy -**update** rutinból (frame-enként egyszer hívódik, pontosan egy frame-et fut) -és egy frame-ben mért időtartamból áll. A `main.c` főciklusa hívja az aktuális -update-et, számolja vissza a frame-eket, és lejáratkor — vagy SPACE/DEL-re -azonnal — a következő slide-ra lép. +Every slide consists of an **init** routine (draws the whole screen), an +**update** routine (called once per frame, runs exactly one frame) and a +duration in frames. The main loop in `main.c` calls the current update, counts +the frames down, and steps to the next slide when time runs out — or +immediately on SPACE/DEL. -### Időzítés +### Timing -Nincs megszakítás: a kód a raszterregisztert (`$D012`, `vic.raster`) pollozza, -és minden képernyőfrissítést az alsó keretben végez (`RAS_BOTTOM`). Az 1-es -slide ezen felül képközépen megbontja a frame-et, hogy csak a scroller sorára -kapcsolja be a vízszintes finomscrollt (`vic.ctrl2`); a 3-as slide a sugarat -üldözve 4 soronként átszínezi a keretet a raszterbárokhoz. +There are no interrupts: the code polls the raster register (`$D012`, +`vic.raster`) and does all screen updates while the beam is in the lower border +(`RAS_BOTTOM`). Slide 1 additionally splits the frame mid-screen to enable +horizontal fine scrolling (`vic.ctrl2`) for the scroller row only; slide 3 +chases the beam down the frame, recoloring the border every 4 lines to draw +the raster bars. -### Átmenetek +### Transitions -Minden slide-nak saját be- és kilépő átmenete van (`tin_tbl` / `tout_tbl` a -`main.c`-ben), három típusból: +Each slide has its own in-transition and out-transition, chosen from three +types via `tin_tbl` / `tout_tbl` in `main.c`: -- **Fade** — minden color RAM cellát a `fadetbl` rámpán léptet (minden szín → - egy árnyalattal sötétebb; minden lánc legfeljebb 4 lépésben fekete). Az új - slide kikapcsolt képernyővel rajzolódik, színei a `$C000`-es bufferbe - mentődnek és feketére váltanak, majd a fade-in cellánként visszasétál a - mentett színre. -- **Dissolve** — egy 10 bites Galois LFSR (periódus 1023) minden cellát pontosan - egyszer, álvéletlen sorrendben jár be. 25 cella/frame = 40 frame (~0,8 s). -- **Wipe** — oszloponkénti söprés balról jobbra, oszloponként egy frame. +- **Fade** — steps every color RAM cell through `fadetbl` (each color → one + shade darker; every chain hits black within 4 steps). The new slide is drawn + with the display off, its colors are snapshotted to the buffer at `$C000` + and blanked, then the fade-in walks each cell back up to its snapshot color. +- **Dissolve** — a 10-bit Galois LFSR (period 1023) visits every screen cell + exactly once in pseudo-random order. 25 cells per frame = 40-frame (~0.8 s) + full reveal. +- **Wipe** — column-by-column sweep from left to right, one column per frame. -Minden átmenet rövid fehér-szürke keretvillanással indul. +All transitions start with a short white-to-grey border flash. -### Zene +### Music -A `src/music.c` háromszólamú SID pattern-lejátszó; a dallam az *Impostor* -TIC-80 cart 0-s trackje („room work"), kézzel konvertálva 128 soros -pattern-ráccsá (basszus: 50% pulzus, dob: zaj, echo-kánon: háromszög pluck -3 oktávval feljebb, 2 sorral késleltetve). Egy sor egy bájt szólamonként: -`$00` = semmi, `$01` = key off, `$80|n` = n. hang. A `music_play` frame-enként -egyszer tickel: a főciklusból és a `wait_frame`-ből is, így az átmenetek alatt -sem áll meg. +`src/music.c` is a three-voice SID pattern player; the tune is track 0 +("room work") of the *Impostor* TIC-80 cart, converted by hand into a 128-row +pattern grid (bass: 50% pulse, drums: noise, echo canon: decaying triangle +pluck 3 octaves up, delayed by 2 rows). Rows are one byte per voice: +`$00` = nothing, `$01` = key off, `$80|n` = play note *n*. `music_play` is +ticked once per frame: from the main loop and from `wait_frame`, so the music +keeps playing through transitions. -## Memóriatérkép +## Memory map ``` -$0801 .. ... BASIC stub + gépi kód (Oscar64 alapértelmezés) -$0340 .. $037E sprite-alakzat (kazettabuffer, 64-re igazított) -$0400 .. $07E7 képernyő RAM (közvetlen írás) -$C000 .. $C3E7 color RAM snapshot buffer az átmenetekhez -$D000 .. $D02E VIC-II regiszterek (kép, sprite-ok, raszter) -$D400 .. $D418 SID regiszterek (zene) +$0801 .. ... BASIC stub + machine code (Oscar64 defaults) +$0340 .. $037E sprite shape (cassette buffer, 64-aligned) +$0400 .. $07E7 screen RAM (written directly) +$C000 .. $C3E7 color RAM snapshot buffer for transitions +$D000 .. $D02E VIC-II registers (display, sprites, raster) +$D400 .. $D418 SID registers (music) $D800 .. color RAM -$DC00 / $DC01 CIA1 billentyűmátrix +$DC00 / $DC01 CIA1 keyboard matrix ``` -## Az eredetihez képest +## Differences from the original -- A szövegek a `#pragma charmap(97, 1, 26)` révén fordítási időben - screen code-dá alakulnak, így a C string literálok közvetlenül a képernyőre - írhatók. -- Az önmódosító vektorok és zeropage-mutatók helyett függvénypointerek és - normál C tömbindexelés; a viselkedés (időzítés, effektek, zene) megegyezik. -- A fordítás `-n -O2`-vel történik (teljes natív 6502 kód), hogy a - raszter-pollozó részek elég gyorsak legyenek. +- Texts are converted to screen codes at compile time via + `#pragma charmap(97, 1, 26)`, so plain C string literals can be written + straight to the screen. +- Self-modifying vectors and zero-page pointers are replaced by function + pointers and ordinary C array indexing; the behavior (timing, effects, + music) is unchanged. +- Compiled with `-n -O2` (fully native 6502 code) so the raster-polling parts + are fast enough to fit in the frame.