Library Reference

These are the optional modules, some of which make up the Standard Packet. They are located in lib/. Some libraries depend on other libraries.

2D Arrays (array2d.f)

2D Arrays are either statically allocated, or, exist as "header" information about an arbitrary block of memory.

You could use a 2D array header to perform operations on a section of a static 2d array, or allocate a 2d array from the OS heap, which is what's done in buffer2d.f .

struct %array2d
    %array2d int svar array2d.cols
    %array2d int svar array2d.rows
    %array2d int svar array2d.pitch
    %array2d int svar array2d.data

2move ( src /pitch dest /pitch nrows /bytes -- ) clip ( col row ncols nrows ndestcols ndestrows -- col row ncols nrows ) array2d-head, ( cols rows -- ) create a 2d array header in dictionary array2d ( numcols numrows -- ) create a 2d array in dictionary count2d ( array2d -- addr #cells ) get address and total number of all cells dims@ ( array2d -- #cols #rows ) get array2d's dimensions loc ( col row array2d -- addr ) get address of cell at col, row pitch@ ( array2d -- /pitch ) get array2d's pitch in bytes addr-pitch ( col row array2d -- addr /pitch ) some2d ( ... col row #cols #rows array2d XT -- ... ) ( ... addr #cells -- ... ) iterate some2d> ( col row #cols #rows array2d -- ) ( addr #cells -- ) iterate fill2d ( val col row #cols #rows array2d -- ) fill each cell of 2d array with value

Warning: As of 1.7, the following words in array2d.f are untested. They were tested and working before they were brought into Ramen from a previous engine, but it's possible that some may be broken due to API changes. 2MOVE CLIP BATCH WRITE2D

2D Buffers (buffer2d.f)

2D buffers are 2D arrays that are allocated from the system heap.

2D buffer declaration example:

256 256 buffer2d: mytable

Audio (audio1.f)

Provides basic audio.

play ( sample -- ) Play sample asset. (Not ALLEGRO_SAMPLE structs.)

stream ( addr c loopmode -- ) Stream audio file. You can stream only one file at a time.

Loop modes: once bidir looping

The audio files supported are the same as the ones supported by Allegro. (WAV, AIFF, OGG, MP3, MOD, S3M, IT, XM, possibly more).

variable strm points to the current playing ALLEGRO_AUDIO_STREAM.

Collision Grid (cgrid.f)

Fast collisions suitable for shootemups, simulations, and large open worlds. It works by giving each object a hitbox (of type cbox), breaking up the game world into a grid, and only checking the other objects in the same grid space.

To use it, you first create a collision grid. Then at some point you "bin" the objects you want to check an object against. You can do this once, such as for background objects when you load a map, or every frame, in the case of moving objects. (Note that when you want to bin objects every frame, you must clear the grid first.) Finally you check an object against the grid, upon which a given XT will be executed upon any collisions.

An object can be binned into only one cgrid at a time.

Before you bin an object, you have to set ahb , a struct that describes the object's rectangle. (structure: x1,y1,x2,y2)

Note: By default, the size of rectangles can't be bigger than 512x512 pixels. To get around this limitation you can break up larger rectangles using break2d, found in stride2d.f

Collision grid declaration example:

256 256 cgrid: mycgrid

ahb ( -- cbox ) "absolute hitbox" cbox! ( x y w h cbox -- ) cbox@ ( cbox -- x y w h ) resetcgrid ( cgrid -- ) addcbox ( cbox cgrid -- ) checkcgrid ( cbox1 xt cgrid -- ) check a cbox against checkcbox ( cbox1 xt cgrid -- ) cgrid-size ( cgrid -- w h )

See rectland.f for a complete example.

Draw (draw.f)

See Drawing.

Numeric Range Tools (rangetools.f)

Tools for working with 1D and 2D ranges.

Rectangles (rect.f)

Generic data structure representing a rectangle.

Radix Sort (rsort.f)

struct %rect
    %rect 0 svar rect.x
    %rect 0 svar rect.y
    %rect 0 svar rect.w
    %rect 0 svar rect.h

Here is a list of the operations for working with rectangles. Their stack effects are self-explanatory.

Note: The following words also work with vectors - x@ y@ x! y!

x@ y@ w@ h@ xy@ wh@ rect. xywh@ x2@ y2@ xy2@

x! y! w! h! xy! wh! xywh! x2! y2! xy2!

Fast radix sort routine. The algorithm is specially tailored for sorting fixed point integers from 0 to 65535. Used by zsort.f.

Sprites (sprites.f)

rsort ( addr n xt - ) ( addr -- n ) destructively sort an array of values.

Note: Any decimal portions will be ignored, and values above 65535 will be sorted incorrectly.

area ( x y w h - x1 y1 x2 y2 ) lowerupper ( n n - lower higher ) between ( n n - n ) pick random value between 2 values. (inclusive) vary ( n rnd - n ) randomize a value N by range RND 2vary ( n n rnd rnd - n n ) either ( a b - a | b ) randomly return one of two values 2ratio ( x y w h xfactor yfactor - x y ) find a point within a rectangle, proportionally. middle ( x y w h - x y ) get center of rectangle 2halve ( x y - x/2 y/2 ) center ( w1 h1 x y w2 h2 - x y ) center a rectangle (1) in the middle of another one (2). returns x/y of top-left corner of centered rectangle. 2rnd ( x y - x y ) somewhere ( x y w h - x y ) find a random point in a rectangle overlap? ( x1 y1 x2 y2 x3 y3 x4 y4 - flag ) check if two areas overlap inside? ( x y x1 y1 x2 y2 - flag ) check if a point is in an area

See Sprites.

Stage (stage.f)

Simple scrolling 2D game framework. Use as-is, or as a template to copy and customize.

Features:

• Predefined game object list

• Camera object

• Camera can be set to follow an object

• Camera "flyby" mode

Note: When using tilemap scrolling, you need to compensate for the camera position, Otherwise set the tilemap's width and height to the size of the entire source map and don't use scrollx and scrolly.

Round-robin Multitasking (task.f)

In games you will often want to have your characters do different actions in sequence or in response to things. Some examples of where this technique is indispensible is platforming games, cutscenes, enemy attack patterns, boss fights, and A.I.

Programming objects to do different things over time in conventional engines isn't trivial. You have to use state machines, counters and state checks and flags or yield signals.

Ramen's approach makes it very easy, allowing you to use natural structured programming to define complex object behavior.

...

Tiled (tiled.f)

Tiled map format support.

See Tiled Support

2D Vectors (v2d.f)

Generic data structure representing a 2D vector in space and accompanying storage and math words.

Depth-sorting (zsort.f)

Extends game objects with a zdepth field and provides a routine for rendering an object list sorted by this value.