diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..917c4ff --- /dev/null +++ b/README.md @@ -0,0 +1,136 @@ +# 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. + + (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) + + +## 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<sub>mixer</sub> 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 [macroknight](https://genepasquet.itch.io/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 list below). Macroknight is not yet switched to depend on the published egg — that remains the final validation step. + +**Milestones:** + +- [DONE] **1–10** — Core refactoring and API stabilization + - 1: Zero-risk module extraction + - 2: Configurable input system + - 3: Data-driven entity rendering + - 4: Renderer abstraction + - 5: Asset preloading + - 6: Scene loading via `create:` hook + - 7: `make-game` / `game-run!` API + - 8: Camera follow + - 9: Named scene states + - 10: Tag-based entity lookup +- [rc] **11** — Package as Chicken egg (v1.0.0rc1) +- [pending] **12** — Macroknight ported to use the egg + +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): + + chicken-install sdl2 sdl2-image sdl2-ttf expat matchable defstruct list-utils \ + srfi-1 srfi-13 srfi-69 srfi-197 simple-logger + +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 + + 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/ + +Single test module (from repo root; space after each `-I` is required by `csi`): + + csi -I "$(pwd)" -I "$(pwd)/bin" -s tests/physics-test.scm + +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 + +**Modules:** + +- `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<sub>mixer</sub> 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: + + '((#: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))))) + +Entity types are composed from mixins declared in a data file: + + (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)) + + +## 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 [macroknight](https://genepasquet.itch.io/macroknight) (Spring Lisp Game Jam 2025). + +- Code: Gene Pasquet +- Demo Levels: Owen Pasquet +- Demo Art: [Kenney](https://kenney.nl) (1-bit pack) |