Module Reference
Structs (struct.f)
Ramen uses a simple data structure facility. Provisions for type information are there but aren't currently being used.
word | stack diagram | description |
struct | ( -- <name>) ) | Declare a struct |
sfield | ( struct bytes valtype -- <name> ) ( adr -- adr+n ) | Declare a struct field |
svar | ( struct valtype -- <name> ) | Short for |
The naming convention for fields is <struct>.<fieldname>. This will help with readability and avoid name collisions. It's a good idea to give your structs short, simple names.
Example:
Fixed-point operators (fixops.f)
See Fixed-Point Numbers on AllegroForthKit's documentation for more info.
These are low-level words for working with fixed-point numbers.
Fixed-point numbers in Ramen have a 20-bit integer part and a 12-bit fractional part. They're meant to enable sub-pixel motion of objects and rough geometrical calculations. If you need more mathematical precision, use floats and convert, bit shifting, or fractions (e.g. */.)
The need to work with integers is infrequent, so many Forth words are redefined to use fixed-point numbers. This, combined with fixed-point literal support, makes working with fixed-point in Ramen almost transparent. An easy way to remember if you need a fixed-point word or an integer word is if the number is a quantity of bytes or not.
These words are really important for you to learn as they're used everywhere in Ramen.
Conversion
word | stack diagram | description |
1p | ( i -- n ) | Convert int to fixed |
2p | ( i i -- n n ) | Convert 2 int(s) to fixed's |
3p | ( i i i -- n n n ) | Convert 3 int(s) to fixed's |
4p | ( i i i i -- n n n n ) | Convert 4 int(s) to fixed's |
1i | ( n -- i ) | Convert fixed to int |
2i | ( n n -- i i ) | Convert 2 fixed's to ints |
3i | ( n n n -- i i i ) | Convert 3 fixed's to ints |
4i | ( n n n n -- i i i i ) | Convert 4 fixed's to ints |
1f | ( n -- f: n ) | Convert fixed to float |
2f | ( n n -- f: n n ) | Convert 2 fixed's to floats |
f>p | ( f: n -- n ) | Convert float to fixedp |
Math
word | stack diagram | description |
pfloor | ( n -- n ) | Round down |
pceil | ( n -- n ) | Round up |
2pfloor | ( n n -- n n ) | |
2pceil | ( n n -- n n ) | |
* | ( n n -- n ) | Multiply |
/ | ( n n -- n ) | Divide |
/mod | ( n n -- r q ) | Slash-mod (returns remainder and quotient) |
- and + work with integers and fixed-point numbers already so those are left alone.
External library conversion
word | stack diagram | description |
1af | ( n -- sf ) | Convert fixedp to float on data stack. |
2af | ( n n -- sf sf ) | Convert fixedp to float on data stack. |
3af | ( n n n -- sf sf sf ) | Convert fixedp to float on data stack. |
4af | ( n n n n -- sf sf sf sf ) | Convert fixedp to float on data stack. |
Advanced Math
word | stack diagram | description |
cos | ( deg -- n ) | Cosine |
sin | ( deg -- n ) | Sine |
acos | ( n -- deg ) | Inverse Cosine |
asin | ( n -- deg ) | Inverse Sine |
lerp | ( src dest factor -- ) | Interpolate |
sqrt | ( n -- n ) | Square root |
atan | ( n -- n ) | Arctangent |
atan2 | ( n n -- n ) | |
tan | ( n -- n ) | Tangent |
log2 | ( n -- n ) | Logarithm |
>rad | ( n -- n ) | Convert degrees to radians |
rescale | ( n min1 max1 min2 max2 -- n ) | Rescale a number proportionally from one range to another |
anglerp | ( src dest factor -- ) | Interpolate angles |
Integers
word | description |
i* | Integer multiply |
i/ | Integer divide |
Color unpacking
word | stack diagram | description |
>rgba | ( val -- r g b a ) | Unpack hex RGBA to fixedp components (0 ~ 1.0) |
>rgb | ( val -- r g b ) | Unpack hex RGB to fixedp components (0 ~ 1.0) |
On-stack vectors
word | stack diagram | description |
2+ | ( x y x y -- x y ) | Two-Add |
2- | ( x y x y -- x y ) | Two-Sub |
2* | ( x y x y -- x y ) | Two-Multiply |
2/ | ( x y x y -- x y ) | Two-Divide |
2mod | ( x y x y -- x y ) | Two-Mod (modulus) |
2+ and 2- are redefined in AFKIT in roger.f. (The standard's versions aren't useful in the engine's program domain.) Other double number words are provided in the standard.
Modes
Generally you shouldn't be writing code that depends on the current base, but on occasion it's convenient, for instance when compiling standard Forth code into a Ramen project.
word | description |
fixed | Switch to fixed point mode. |
decimal | Switch to decimal mode. |
Fixed-point literals (fixedp.f)
This file is actually packaged with AllegroForthKit.
Fixed-point literal support is required by Ramen. At the moment Forth systems must have a mechanism for extending the interpreter for Ramen to compile.
All numbers that aren't qualified by a base prefix such as $ are interpreted as fixed point. To force integer, prefix numbers with #.
The theory behind this is that you can write literals naturally, with no requirement to use a decimal point, making fixed-point number use almost transparent.
The quickest way to understand is to try it. After loading Ramen into Forth, type 1.5 3 + . and press <enter>. Notice that the decimal point is optional.
Assets (assets.f)
The asset system lets you declare assets in your code which will get automatically loaded when your game starts. The assets are loaded immediately at compile-time when declared.
In order for the publish facility to find your assets, you should place your assets in a subfolder of your project root called data/. (You can organize files within this folder however you like.)
Miscellaneous asset-related words:
word | stack diagram | description |
assets> | ( -- ) ( asset -- ) | Run code body on each asset in the order they were declared. |
#assets | ( -- n ) | Total number of declared assets. |
.asset | ( asset -- ) | Print some info about an asset |
.assets | ( -- ) | List all assets |
findfile ( path c -- path c ) Search for an asset's file first in these locations, in this order:
Relative to the current working directory (project root)
Relative to the current source file being compiled.
If an asset isn't found, it aborts and throws an error message.
Defining an asset type
You can add new asset types. An asset type is a struct that extends the header described above. Defining an asset type is largely the same as defining a struct.
All assets have the following fields:
field | type | description |
srcfile | cstring | Path of source file |
<reloader> | xt | "Reloader" XT |
The reloader is a unnamed field. You can, however, directly reload ( asset -- )
You will also need to define the asset loader and asset declaration word.
See the asset definition source files for examples.
word | stack diagram | description |
defasset | ( -- ) | Define an asset type (or "asset definition") |
register | ( reloader-xt asset -- ) | Add asset to the preload list and assign its reloader. |
Load triggers
Load triggers are executed by the preloader in addition to assets. They are just XT's without any associated files.
loadtrig ( xt -- ) Add a load trigger.
The preloader
Ramen has a modifiable preloader that runs when published games start.
defer initdata ( -- ) Runs the preloader
The standard preloader loads all assets synchronously. When your game starts, it will display a blank screen while the assets load. The more assets you have declared, the longer the preload takes.
Redefine initdata with :is or is.
Images (image.f)
Asset that stores info about an Allegro bitmap, as well as information necessary to address "subimages" in the bitmap - that is, to treat it as an image strip, commonly used in games.
All of the fields are public.
field | type | description |
image.bmp | ALLEGRO_BITMAP address | Bitmap pointed to by the image |
image.subw | fixedp | Subimage width |
image.subh | fixedp | Subimage height |
image.fsubw | float | Same as |
image.fsubh | float | Same as |
image.subcols | fixedp | Number of subimage columns |
image.subrows | fixedp | Number of subimage rows |
image.subcount | fixedp | Total number of subimages |
image.orgx | fixedp | Origin X (to be treated by a game as the center of rotation and scaling) |
image.orgy | fixedp | Origin Y |
Image management
word | stack diagram | description |
imagew | ( -- ) | Get image width |
imageh | ( -- ) | Get image height |
imagewh | ( -- ) | Get image dimensions |
/origin | ( -- ) | Set image's origin to its center. |
reload-image | ( image -- ) | Load bitmap from its stored path and initialize the origin. |
init-image | ( path c image -- ) | Initialize image (calling |
image: | ( path count -- ) | Declare an image, loading it at compile-time. |
>bmp | ( image -- bitmap ) | Get Allegro bitmap |
load-image | ( path count image -- ) | Load a new bitmap into an image and change its path. The old bitmap is not destroyed. |
free-image | ( image -- ) | The bitmap is destroyed. Note that the pointer is not cleared. |
Subimages
word | stack diagram | description |
subdivide | ( tilew tileh image -- ) | Initialize the subimage fields. |
subxy | ( n image -- x y ) | Get the coordinates of the top left of a subimage. |
subxywh | ( n image -- x y w h ) | Get the top-left coordinates, and the dimensions of a subimage. |
afsubimg | ( n image -- ALLEGRO_BITMAP fx fy fw fh ) | Get the bitmap and the rectangle values as floats of a subimage. (Useful for passing to the Allegro library.) |
imgsubbmp | ( n image -- subbitmap ) | Create an ALLEGRO_SUBBITMAP that stores info about a subimage. |
Buffers (buffer.f)
Buffers are memory allocated from the OS heap at game start. This frees the programmer from the confines of the dictionary, which is typically a small and static size.
Buffer declaration example:
See the source for more.
Fonts (font.f)
Font assets. See the source for details. All font formats supported by Allegro 5 are supported.
Font declaration example:
See the source for more.
Samples (sample.f)
Sample assets for playing sound effects.
Sample declaration example:
Playing a sample: (Standard Packet)
See the source for more.
Colors (color.f)
A simple color struct. Just a barebones struct for now.
Objects (obj.f)
Ramen's special data structure for game objects. See Objects
Stacks (stack.f)
Stacks are arrays of a predetermined size that you can push and pop values to and from. You can address the items by index. All items are one cell wide.
Publish (publish.f)
See Publishing
Last updated