diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/audio.org | 26 | ||||
| -rw-r--r-- | docs/entities.org | 14 | ||||
| -rw-r--r-- | docs/guide.org | 22 | ||||
| -rw-r--r-- | docs/input.org | 8 | ||||
| -rw-r--r-- | docs/physics.org | 10 | ||||
| -rw-r--r-- | docs/scenes.org | 16 | ||||
| -rw-r--r-- | docs/tweens.org | 4 |
7 files changed, 50 insertions, 50 deletions
diff --git a/docs/audio.org b/docs/audio.org index 7d83e44..464e2c8 100644 --- a/docs/audio.org +++ b/docs/audio.org @@ -3,7 +3,7 @@ Downstroke's audio stack is a thin wrapper around SDL2's =SDL_mixer= library. It gives you two things: short /sound effects/ (one-shots triggered on input, collisions, pickups, etc.) and a single streaming /music/ track (a looping -background song). The friendly API lives in the =downstroke-sound= module and +background song). The friendly API lives in the =(downstroke sound)= module and is the only thing most games ever need to touch. Audio is deliberately kept outside the [[file:guide.org][=game= record]]. The sound module @@ -15,8 +15,8 @@ manage audio for you. * The minimum you need #+begin_src scheme -(import downstroke-engine - downstroke-sound) +(import (downstroke engine) + (downstroke sound)) (define *music-on?* #f) @@ -54,25 +54,25 @@ Four calls cover ~95% of real usage: Audio is split into two modules, and you pick the one that matches what you are doing: -- =downstroke-sound= — the friendly, high-level API. Symbolic sound names, an +- =(downstroke sound)= — the friendly, high-level API. Symbolic sound names, an internal registry, volume given as =0.0..1.0=, music that just loops. This is what the rest of this document documents, and what every demo uses. -- =downstroke-mixer= — raw FFI bindings to =SDL_mixer= +- =(downstroke mixer)= — raw FFI bindings to =SDL_mixer= (=Mix_OpenAudio=, =Mix_LoadWAV=, =Mix_PlayChannel=, =Mix_LoadMUS=, =Mix_PlayMusic=, =Mix_VolumeMusic=, …). No registry, no convenience, no type conversions. Values are raw C-level integers (volumes are =0..128=, channels are integers, loops is an integer count with =-1= for forever). -Reach for =downstroke-mixer= only when you need something the high-level +Reach for =(downstroke mixer)= only when you need something the high-level wrapper does not expose — for example, playing more than one concurrent music -track via channel groups, or fading effects. In practice, =downstroke-sound= -covers 99% of cases; you almost never =import downstroke-mixer= directly in +track via channel groups, or fading effects. In practice, =(downstroke sound)= +covers 99% of cases; you almost never =import (downstroke mixer)= directly in game code. *** Module-level state (be aware of this) -=downstroke-sound= keeps two global variables inside the module: +=(downstroke sound)= keeps two global variables inside the module: - =*sound-registry*= — an association list of =(symbol . Mix_Chunk*)= pairs populated by =load-sounds!=. @@ -87,7 +87,7 @@ This means: alist. - Calling =load-music!= replaces =*music*= without freeing the previous track — use =cleanup-audio!= if you need to swap tracks cleanly, or drop - into =downstroke-mixer= and call =mix-free-music!= yourself. + into =(downstroke mixer)= and call =mix-free-music!= yourself. - Two games in the same process would share this state. That is not a supported configuration; one =game-run!= per process is the expectation. @@ -175,7 +175,7 @@ and null chunks are silently ignored. SDL_mixer defaults to 8 simultaneous channels. If all channels are busy, the new sound is dropped. For most 2D games this is plenty; if you need -more, use =downstroke-mixer= directly and call =Mix_AllocateChannels=. +more, use =(downstroke mixer)= directly and call =Mix_AllocateChannels=. Volume on individual effects is not exposed by the high-level API — every chunk plays at the mixer's current chunk volume. If you need per-sound @@ -294,10 +294,10 @@ A full on/off toggle, as seen in the audio demo, looks like this: To change songs cleanly, halt the current one, free it, and load the new one. The high-level API does not free for you, so either call =cleanup-audio!= (which also closes the device — probably not what you want -mid-game) or drop to =downstroke-mixer=: +mid-game) or drop to =(downstroke mixer)=: #+begin_src scheme -(import downstroke-mixer) +(import (downstroke mixer)) (define (swap-music! path volume) (stop-music!) diff --git a/docs/entities.org b/docs/entities.org index 94e572c..2e97782 100644 --- a/docs/entities.org +++ b/docs/entities.org @@ -9,9 +9,9 @@ are no classes, no inheritance, no hidden state. You build entities either by hand as a plist and converting with =plist->alist=, or from a *prefab* data file that composes named mixins with inline fields. -The module that owns this vocabulary is =downstroke-entity= (all the +The module that owns this vocabulary is =(downstroke entity)= (all the =entity-*= procedures and the =define-pipeline= macro). The companion -module =downstroke-prefabs= loads prefab data files and instantiates +module =(downstroke prefabs)= loads prefab data files and instantiates them. Most games will touch both. * The minimum you need @@ -21,7 +21,7 @@ From the getting-started demo (=demo/getting-started.scm=): #+begin_src scheme (import (only (list-utils alist) plist->alist) - downstroke-entity) + (downstroke entity)) (define (make-player) (plist->alist @@ -144,7 +144,7 @@ Because everything is immutable, update chains are usually written as ** Prefabs and mixins Hand-writing a long plist for every enemy gets old fast. The -=downstroke-prefabs= module loads a data file that declares reusable +=(downstroke prefabs)= module loads a data file that declares reusable *mixins* (named bundles of keys) and *prefabs* (named entities built by combining mixins and inline overrides). @@ -205,7 +205,7 @@ Load a prefab file once at =create:= time, then instantiate as many entities as you need: #+begin_src scheme -(import downstroke-prefabs) +(import (downstroke prefabs)) (define registry (load-prefabs "demo/assets/animation-prefabs.scm" @@ -253,7 +253,7 @@ The predicate is =entity-skips-pipeline?=: #+end_src Every built-in step is defined with the =define-pipeline= macro -(=downstroke-entity=), which wraps the body in the skip check. The +(=(downstroke entity)=), which wraps the body in the skip check. The macro has two shapes: #+begin_src scheme @@ -363,7 +363,7 @@ reach for =define-pipeline= instead of writing a plain function. A minimal example: #+begin_src scheme -(import downstroke-entity) +(import (downstroke entity)) ;; A decay step. Users can skip it with #:skip-pipelines '(decay). (define-pipeline (apply-decay decay) (scene entity dt) diff --git a/docs/guide.org b/docs/guide.org index 1b16d92..21a70bc 100644 --- a/docs/guide.org +++ b/docs/guide.org @@ -14,7 +14,7 @@ The smallest Downstroke program you can write opens a window, runs the main loop #+begin_src scheme (import scheme (chicken base) - downstroke-engine) + (downstroke engine)) (game-run! (make-game @@ -53,9 +53,9 @@ In the ~create:~ hook you typically build a scene and hand it to the game with ~ #+begin_src scheme (import scheme (chicken base) - downstroke-engine - downstroke-world - downstroke-scene-loader) + (downstroke engine) + (downstroke world) + (downstroke scene-loader)) (game-run! (make-game @@ -108,7 +108,7 @@ Compile and run, and you should see a light-blue 32×32 square on a dark backgro ** Reading input -Input in Downstroke is organised around /actions/ rather than raw keys. The engine ships with a default input config (~*default-input-config*~ in ~downstroke-input~) that maps the arrow keys, WASD, a couple of action buttons, and game-controller buttons to a small set of action symbols: +Input in Downstroke is organised around /actions/ rather than raw keys. The engine ships with a default input config (~*default-input-config*~ in ~(downstroke input)~) that maps the arrow keys, WASD, a couple of action buttons, and game-controller buttons to a small set of action symbols: | Action | Default keys | |----------+-------------------| @@ -123,7 +123,7 @@ Input in Downstroke is organised around /actions/ rather than raw keys. The engi | ~quit~ | =Escape= | -Inside ~update:~ you reach the input state with ~(game-input game)~, and then query it with three predicates from ~downstroke-input~: +Inside ~update:~ you reach the input state with ~(game-input game)~, and then query it with three predicates from ~(downstroke input)~: - ~(input-held? input 'left)~ — ~#t~ while the player holds the action down. - ~(input-pressed? input 'a)~ — ~#t~ only on the first frame the action goes down (edge). @@ -193,11 +193,11 @@ Here is the full =demo/getting-started.scm= source. Read it top to bottom — ea (import scheme (chicken base) (only (list-utils alist) plist->alist) - downstroke-engine - downstroke-world - downstroke-entity - downstroke-input - downstroke-scene-loader) + (downstroke engine) + (downstroke world) + (downstroke entity) + (downstroke input) + (downstroke scene-loader)) (define +speed+ 2) diff --git a/docs/input.org b/docs/input.org index 81ff65e..a7f7fc5 100644 --- a/docs/input.org +++ b/docs/input.org @@ -15,10 +15,10 @@ through =game-input=. * The minimum you need #+begin_src scheme -(import downstroke-engine - downstroke-input - downstroke-world - downstroke-entity) +(import (downstroke engine) + (downstroke input) + (downstroke world) + (downstroke entity)) (game-run! (make-game diff --git a/docs/physics.org b/docs/physics.org index 9cf9b96..233ffc8 100644 --- a/docs/physics.org +++ b/docs/physics.org @@ -149,7 +149,7 @@ All per-entity steps have the signature =(step scene entity dt)=. - *Reads*: =#:gravity?=, =#:vy= (default 0) - *Writes*: =#:vy= (set to =(+ vy *gravity*)=) - *Guard*: only runs when =#:gravity? #t= -- =*gravity*= is exported from =downstroke-physics=; its value is +- =*gravity*= is exported from =(downstroke physics)=; its value is =1= pixel/frame². Gravity accumulates until =resolve-tile-collisions-y= zeroes =#:vy= on contact with the floor. @@ -294,7 +294,7 @@ pair walk. *** =#:skip-pipelines= per-entity override Every per-entity step is also gated by =entity-skips-pipeline?= (from -=downstroke-entity=). If the entity's =#:skip-pipelines= list contains +=(downstroke entity)=). If the entity's =#:skip-pipelines= list contains the step's *symbol*, the step returns the entity unchanged. The symbols match the second name in each =define-pipeline= form: @@ -335,7 +335,7 @@ collisions, and still detect ground under it. *** =define-pipeline= (how steps are declared) All per-entity pipeline steps are declared with =define-pipeline= from -=downstroke-entity= (see =docs/entities.org=). The shape is: +=(downstroke entity)= (see =docs/entities.org=). The shape is: #+begin_src scheme (define-pipeline (procedure-name skip-symbol) (scene entity dt) @@ -391,7 +391,7 @@ per-pixel collision are not supported. *** Tile collision algorithm -Tiles come from a =downstroke-tilemap= parsed from a TMX file (Tiled +Tiles come from a =(downstroke tilemap)= parsed from a TMX file (Tiled editor). The tilemap stores a grid of tile ids across one or more layers; =tilemap-tile-at= returns =0= for an empty cell and a positive id for a filled cell. Only *empty vs non-empty* is checked — there is @@ -604,7 +604,7 @@ push-apart: With ='none=, nothing in =physics.scm= runs unless you call it yourself. You still have access to every physics procedure as a library: =apply-velocity-x=, =aabb-overlap?=, =resolve-tile-collisions-y=, -and so on are all exported from =downstroke-physics= and usable +and so on are all exported from =(downstroke physics)= and usable individually. ='none= just disables the *automatic* orchestration. ** Reading =#:on-ground?= to gate jumps diff --git a/docs/scenes.org b/docs/scenes.org index da62291..87b9256 100644 --- a/docs/scenes.org +++ b/docs/scenes.org @@ -15,10 +15,10 @@ The smallest scene is a sprite-only one with a single entity, built inside the ~ (import scheme (chicken base) (only (list-utils alist) plist->alist) - downstroke-engine - downstroke-world - downstroke-entity - downstroke-scene-loader) + (downstroke engine) + (downstroke world) + (downstroke entity) + (downstroke scene-loader)) (define (make-player) (plist->alist @@ -43,7 +43,7 @@ That is all that is required to put a blue square on a dark background. ~make-sp ** The scene record -~scene~ is a record type defined with ~defstruct~ in ~downstroke-world~. Its fields map one-to-one onto the things the engine needs to know about the current frame: +~scene~ is a record type defined with ~defstruct~ in ~(downstroke world)~. Its fields map one-to-one onto the things the engine needs to know about the current frame: | Field | Type | Purpose | |-------------------+--------------------------------+--------------------------------------------------------------------------------------------------| @@ -101,7 +101,7 @@ This is the form the ~shmup~ and ~scaling~ demos use to turn off the physics pip *** ~make-sprite-scene~ — convenient sprite-only scenes -~make-sprite-scene~ lives in ~downstroke-scene-loader~ and wraps ~make-scene~ with sensible defaults for sprite-only games: +~make-sprite-scene~ lives in ~(downstroke scene-loader)~ and wraps ~make-scene~ with sensible defaults for sprite-only games: #+begin_src scheme (make-sprite-scene @@ -175,7 +175,7 @@ This pattern — load once in ~preload:~ (or early in ~create:~), retrieve many ** Manipulating scene entities -All scene transformers in ~downstroke-world~ are /functional/: they take a scene and return a new one. Nothing is mutated; the idiomatic pattern inside an ~update:~ hook is always +All scene transformers in ~(downstroke world)~ are /functional/: they take a scene and return a new one. Nothing is mutated; the idiomatic pattern inside an ~update:~ hook is always #+begin_src scheme (game-scene-set! game (<transformer> (game-scene game) ...)) @@ -197,7 +197,7 @@ or, when composing multiple transformations, a ~chain~ form from ~srfi-197~. ~(scene-map-entities scene proc ...)~ applies each ~proc~ in sequence to every entity in the scene. Each ~proc~ has the signature ~(lambda (scene entity) ...) → entity~ — it receives the /current/ scene (read-only, snapshot at the start of the call) and one entity, and must return a replacement entity. Multiple procs are applied like successive ~map~ passes, in argument order. -This is the workhorse of the physics pipeline; see ~default-engine-update~ in ~downstroke-engine~ for how it is chained to apply acceleration, gravity, velocity, and so on. In game code you use it for per-entity updates that do not need to see each other: +This is the workhorse of the physics pipeline; see ~default-engine-update~ in ~(downstroke engine)~ for how it is chained to apply acceleration, gravity, velocity, and so on. In game code you use it for per-entity updates that do not need to see each other: #+begin_src scheme (scene-map-entities scene diff --git a/docs/tweens.org b/docs/tweens.org index d1ee966..063a485 100644 --- a/docs/tweens.org +++ b/docs/tweens.org @@ -7,7 +7,7 @@ up for use inside your =update:= hook. You build a tween with engine advances it for you every frame. When it finishes, it removes itself. -This doc covers the =downstroke-tween= module: =make-tween=, the +This doc covers the =(downstroke tween)= module: =make-tween=, the =step-tweens= pipeline step, and every easing curve shipped in the =*ease-table*=. @@ -16,7 +16,7 @@ This doc covers the =downstroke-tween= module: =make-tween=, the A one-shot slide to the right, 500 ms, linear ease: #+BEGIN_SRC scheme -(import downstroke-tween) +(import (downstroke tween)) (let ((e (entity-set (make-entity 0 100 16 16) #:type 'slider))) (entity-set e #:tween |