From 30033ae20d569c51b4481855f0407cbf1f03c65f Mon Sep 17 00:00:00 2001 From: Gene Pasquet Date: Mon, 20 Apr 2026 13:47:18 +0100 Subject: Documentation improvements --- README.org | 138 ------------------------------------------------------------- 1 file changed, 138 deletions(-) delete mode 100644 README.org (limited to 'README.org') diff --git a/README.org b/README.org deleted file mode 100644 index a474ff7..0000000 --- a/README.org +++ /dev/null @@ -1,138 +0,0 @@ -* Downstroke - -A 2D tile-driven game engine for Chicken Scheme, built on SDL2. Targets old-school platformer and arcade games — NES-style and beyond. The API is inspired by Phaser 2: one call to start, lifecycle hooks to fill in. A minimal game is ~20 lines of Scheme. - -#+begin_src scheme -(define my-game - (make-game - title: "My Game" width: 320 height: 240 - preload: (lambda (game) ...) ; load assets - create: (lambda (game) ...) ; set up scene - update: (lambda (game dt) ...))) ; per-frame logic (physics runs first) - -(game-run! my-game) -#+end_src - -** Features - -- Tweens with easing helpers -- Tile-based physics: gravity, velocity, AABB collision against TMX tilemaps -- Built-in update pipeline (before your =update:= hook): tweens → acceleration → gravity → velocity → tile collisions → ground detection → entity collisions → group sync → animation; input is polled each frame and available to hooks and your own logic -- Entities as association lists (alists) — purely functional, no classes; prefab data is often written as plists and converted when loaded -- Data-driven prefab/mixin system for composing entity types -- Configurable input: keyboard, joystick, and controller -- Asset registry with =preload:= lifecycle hook -- Scene and camera management -- Sprite animation with frame/tick tracking -- SDL2_mixer audio via a thin FFI binding - -** Status - -The engine lives in this repository as modular Chicken units, with demos, docs, and an egg spec (=downstroke.egg=). It still powers [[https://genepasquet.itch.io/macroknight][macroknight]] (Spring Lisp Game Jam 2025). The tree is at release candidate =1.0.0rc1= (=VERSION= in the =Makefile=, same string in the egg and the table below). Macroknight is not yet switched to depend on the published egg — that remains the final validation step. - -| Milestone | Description | Status | -|-----------+------------------------------------+----------| -| 1 | Zero-risk module extraction | DONE | -| 2 | Configurable input system | DONE | -| 3 | Data-driven entity rendering | DONE | -| 4 | Renderer abstraction | DONE | -| 5 | Asset preloading | DONE | -| 6 | Scene loading via =create:= hook | DONE | -| 7 | =make-game= / =game-run!= API | DONE | -| 8 | Camera follow | DONE | -| 9 | Named scene states | DONE | -| 10 | Tag-based entity lookup | DONE | -| 11 | Package as Chicken egg (v1.0.0rc1) | rc | -| 12 | Macroknight ported to use the egg | pending | - -Milestones 1–6 were pure refactoring. Milestone 7 was the API pivot (=make-game=, =game-run!=, pipeline). Milestones 11–12 are packaging and proving the egg against macroknight. Finer-grained planning may live outside this repo (for example in =downstroke.org= or macroknight's historical =TODO-engine.org=). - -** Dependencies - -System libraries: =SDL2=, =SDL2_image=, =SDL2_mixer=, =SDL2_ttf= - -Chicken eggs (mirrors =downstroke.egg=; install what you do not already have): -#+begin_example -chicken-install sdl2 sdl2-image sdl2-ttf expat matchable defstruct list-utils \ - srfi-1 srfi-13 srfi-69 srfi-197 simple-logger -#+end_example - -From a git checkout, run tests with the =test= egg (=make test= runs =csi -s= on each suite). - -Games that ship their own FSM logic (for example with the =states= egg) declare that egg themselves; Downstroke does not depend on it. - -** Building - -#+begin_src sh -make # compile all modules to bin/ -make test # run unit tests (=test= egg) -make demos # build demo games (verifies they compile) -make clean # remove bin/ -#+end_src - -Single test module (from repo root; space after each =-I= is required by =csi=): -#+begin_src sh -csi -I "$(pwd)" -I "$(pwd)/bin" -s tests/physics-test.scm -#+end_src - -The canonical version string is =VERSION= at the top of the =Makefile=; it must match =((version "…")= in =downstroke.egg= and the =v…= marker in the milestone table. Bump all three with =make bump-version NEW=1.2.3= (POSIX =sed=; =NEW= must not contain =&=, backslash, or =#=). - -** Architecture - -Modules live at the project root. Each compiles as a Chicken unit (=csc -c -J -unit=). Compile order follows the dependency graph: - -: entity → tween → tilemap → world → input → physics → renderer → assets → animation → engine → mixer → sound → prefabs → scene-loader - -| Module | Responsibility | -|----------------+---------------------------------------------------| -| =entity= | Alist accessors: =entity-ref=, =entity-set= | -| =tilemap= | TMX/TSX parsing (expat), tileset loading | -| =world= | Scene struct, entity list ops, camera | -| =physics= | Gravity, velocity, AABB tile + entity collisions | -| =input= | SDL2 events → action mapping, configurable binds | -| =animation= | Frame/tick tracking, sprite ID mapping | -| =prefabs= | Mixin composition, entity instantiation | -| =renderer= | =draw-sprite=, =draw-tilemap-layer=, =draw-text= | -| =assets= | Asset registry for the =preload:= hook | -| =scene-loader= | =game-load-scene!=, =instantiate-prefab= | -| =mixer= | SDL_mixer FFI (no Scheme deps) | -| =sound= | Sound registry, music playback | -| =engine= | =make-game=, =game-run!=, lifecycle orchestration | - -Entities are alists at runtime — no classes, purely functional: - -#+begin_src scheme -'((#:type . player) (#:x . 100) (#:y . 200) (#:width . 16) (#:height . 16) - (#:vx . 0) (#:vy . 0) (#:gravity? . #t) (#:on-ground? . #f) - (#:tile-id . 29) (#:tags . (player)) - (#:anim-name . walk) - (#:animations . (((#:name . walk) (#:frames . (27 28)) (#:duration . 10)) - ((#:name . idle) (#:frames . (28)) (#:duration . 10))))) -#+end_src - -Entity types are composed from mixins declared in a data file: - -#+begin_src scheme -(mixins - (physics-body #:vx 0 #:vy 0 #:gravity? #t #:on-ground? #f) - (has-facing #:facing 1)) - -(prefabs - (player physics-body has-facing #:type player #:tile-id 29)) -#+end_src - -** LLM (AI) disclosure - -Some engine code was written or refactored with an LLM (aka AI) prior -to the initial release. I don't intend to keep using AI for engine -code after that. - -The =docs/= tree is LLM-generated, and that is expected to continue. - -** Credits - -Engine extracted from [[https://genepasquet.itch.io/macroknight][macroknight]] (Spring Lisp Game Jam 2025). - -- Code: Gene Pasquet -- Demo Levels: Owen Pasquet -- Demo Art: [[https://kenney.nl][Kenney]] (1-bit pack) -- cgit v1.2.3