Frogatto & Friends is an action-adventure game, starring a certain quixotic frog. Give it a try!
We're trying to push 2D platforming, pixel-art, and music into uncharted territory. We hope you like the results!
Also, Frogatto has a very flexible game engine you can use to make your own creations.

Frogatto Formula Language (FFL) is the language used to customize Frogatto and control its behavior. I’ve talked about how Frogatto’s event handling system works before, right here.

Today I’m going to talk more about how FFL works, giving an overview of the language.

Getting Started

Becoming familiar with FFL is easy. Just start Frogatto and press ctrl+d to enter the debug console. The debug console allows you to type FFL statements and have them evaluated right then and there. Try some basic commands:

--> 4 + 5
9
--> 7*3 + 9
30
--> 7*(3 + 9)
84
-->

Accessing an Object

When an FFL formula is executed, it has an object it is operating on. When you first open the debug console, that object is the player. Let’s try some basic formulas that find information about the player:

You can output the entire player object by entering self as a command — it will show you all the fields the player has to offer!

Where Clauses

For convenience, FFL supports where clauses that appear at the end of an expression to define additional values:

--> 2*n + n*n where n = 5
35

Object Mutation

So far we’ve seen how to query the values from an object. If you enter a formula that returns a command, the debug console will execute the command on the object. It might be a good idea to pause the game, by pressing ctrl+p before executing commands, so you can clearly see what’s going on.

Remember, what you are executing here in the debug console is the same kind of thing you would execute in an event handler when it is executed.

When the debug console is open, you can click on objects to select them, and they will become the focused object — they will be the context of any formulas you enter. For instance, you could click on a door, and then start typing commands to modify it.

Basic data types

As we’ve seen, Frogatto can handle manipulation of integers. You may have noticed it also supports strings. e.g.

--> type
'frogatto_playable'

Strings can be concatenated, just as integers can be added:

--> 'abc' + 'def'
'abcdef'

You can also multiply a string by an integer:

--> 'abc' * 4
'abcabcabcabc'

Other types, such as integers, can be concatenated to a string using +:

--> 'you have ' + 5 + ' coins'
'you have 5 coins'

FFL also supports decimal numbers:

--> 4.25 * 0.3
1.275
--> 10.8 + 5
15.8
--> -0.5 - 0.8
-1.3

FFL decimals are not floating point numbers. They use fixed point arithmetic and store up to six decimal places. Their behavior is consistent across machines.

FFL also supports the boolean types, true and false as well as the value null to represent no object.

Basic Operators

FFL supports the following basic operators:

+ – * /: arithmetic operations

and or not: boolean operators

%: modulo operator. e.g. 9%8 -> 1

^: exponentiation operator. e.g. 2^8 -> 256

= != <>=: comparison operators

Note that unlike many languages, = is used to test for equality, as FFL doesn’t have built-in assignment. Assignment is done by returning a set() object from a formula, requesting the game engine to perform the equivalent of an assignment.

You can find the number of elements in a list using the size() function:

--> size(a) where a = [1,2,3]
3

Lists can be compared using = and != operators, and also using the relational operators,=. For instance,

--> [2,3,4] < [5,6]
true
--> [2,3,5] false

You can find if an item is in a list using the in operator:

--> 3 in [2,3,4]
true

Functions for Operating on Lists

FFL supplies a range of functions for operating on lists. One such function is the map function:

map(list, expression): evaluates expression once for each item in list, giving 'value' as the name of the item.

This is perhaps best explained with an example:

--> map([1,2,3,4], value*value)
[1, 4, 9, 16]

Note how the expression value*value is evaluated once for each item in the list, with value containing that item. One thing that might seem strange to experienced programmers is how the parameter passed to the function is not eagerly evaluated, but rather, the function chooses when to evaluate it, and even what context to evaluate it in.

The map function can take an additional argument specifying the name of the parameter, to something other than value. For instance,

The filter function is useful for taking certain elements of a map that pass a certain criteria:

filter(list, expression): evaluates expression once for each item in list, and returns a list of all the items for which the expression was true.

For instance,

--> filter(range(10), value%2 = 1)
[1, 3, 5, 7, 9]

Map + Filter + Range: Example

The spawn function can be used to create an object. For instance, spawn('coin_silver', x, y-80, 1) will create a silver coin 80 pixels above Frogatto’s head. Let’s suppose we wanted to create ten coins in a row, we could do this:

Now suppose we wanted to move all these coins up by 20 pixels. level.chars holds a list of all the objects in the level. We could filter by type to find all the coins in the level, and then use map to map these objects to set commands:

List Comprehensions

Frogatto supports a convenient way to build lists, known as list comprehensions. Let’s start with an example:

[n^2 | n

This is equivalent to saying "for each n in range(10), generate a list with n^2". A list comprehension can also contain filtering conditions on the input list. For instance, if we wanted to square only even numbers, we could do this:

[n^2 | n

A list comprehension can take multiple input lists, in which all the combinations of elements in each list are used. For instance:

[a + ' ' + b | a

List comprehensions are a convenient alternative to using map and filter. This formula from earlier can be re-written using list comprehensions:

map(range(10), spawn('coin_silver', (x - 200) + value*30, y - 80, 1))

As a list comprehension:

[spawn('coin_silver', (x - 200) + n*30, y - 80, 1) | n

Dictionaries

FFL supports dictionaries, also known as maps. A dictionary is a series of key:value pairs written within curly brackets. For instance,

--> {y: 5, x: 2}
{'x': 2, 'y': 5}

Note how the keys are assumed to be strings, rather than x and y being interpreted as expressions. Also, keys in a map are always sorted.

Any FFL type may be a key in a map. Integers, booleans, lists, and even other maps are valid keys:

--> {[3,4,5]: 7, {a: 5}: 9}
{[3, 4, 5]: 7, {'a': 5}: 9}

Elements in maps can be looked up either using the . operator, or using []:

The . operator only works on string keys that are valid identifiers (a valid FFL identifier begins with a letter or underscore and consists of letters, underscores, and digits). The [] operator can be used for all types of keys.

Objects

FFL supports objects as data types. An object looks and behaves similar to a dictionary, however an object may have additional behavior or properties to a regular dictionary. FFL doesn't have support for directly creating objects, but an FFL formula might be given access to an object, or have an object returned by a function.

One example of an object is the game object that represents Frogatto. When you start the debugger, you have access to the player's game object. That is why you can enter a formula such as x or y or type and see a result. The level itself is exposed as an object, and all objects have access to it through their level property.

Another example of objects are command objects. Command objects are created and returned when you call a function like set() or spawn(). These types of objects don't actually have any interesting values that can be queried from FFL. That is why you see a result like this:

--> spawn('coin_silver', 10, 10, 1)
(0xb825640){}

This formula returns a spawn command object, but the contents of the object are opaque to FFL, so all FFL knows about it are the address and then has an empty {} properties map. FFL doesn't need to know how to query or manipulate a command object though, since the entire idea is to return it to the game engine, and the game engine knows how to execute the command and make the object get spawned.

This is a general tutorial on FFL, so I'm not going to get too into the different types of objects available. The crucial thing to understand, though, is that FFL is a pluggable language that can be used in different contexts. The most common use for FFL right now is to write Frogatto event handlers with, however it's designed to be used in different contexts -- we also use it to write editor scripts with, gui scripts, and scripts to manipulate FSON documents. Depending on how and where you use FFL you will have access to different types of objects.

Functions

You can define your own functions in FFL:

--> def f(n) n^2 + 5; f(5) + 2
32

Functions are themselves variables that can be passed to functions and otherwise treated as regular values. For instance,

--> def f(fn, x) fn(5, x); def add(a, b) a + b; f(add, 2)
7

Note: Built-in functions currently cannot be treated as values or passed around. We are looking to fix that in a future release.

Functions can have default arguments specified:

--> def f(a, b=5) a+b; [f(1,1), f(2)]
[2, 7]

Recursion

Functions can call themselves. As an example, suppose you wanted to write a function index(list, item) -> returns the index of the first occurrence of item in list, or -1 if item is not in list

True or False?

At certain times, FFL will test whether a value is considered 'true' or 'false'. The following values are considered false:

false

null

0

0.0

[]

{}

All other values are considered true. Note that the and and or operators have particularly interesting behavior: or will evaluate to its first argument if its first argument is a true value, otherwise it will evaluate to its second argument. Likewise, and will evaluate to its first argument if its first argument is a false value, otherwise it will evaluate to it second argument.

--> 5 or 2
5
--> false or 8
8

Wrap-Up

I hope this FFL overview has been helpful. Please post any feedback or comments below!

For part 3 of the tutorial on developing a game with the Frogatto engine, I’ve decided to do a series of videos demonstrating how to add walking, jumping, and crouching to Elisa. I recommend watching the videos in as high resolution as you can. Here are the videos:

I’ve been a bit remiss in posting these regularly, so here’s getting back into it: I’ve recently redrawn the cave tiles.

There were a number of haphazard bits to the old effort, probably the single biggest thing that was poorly improvised was the side-wall tiles, which had stalagmites jutting out at an angle. I wasn’t yet comfortable enough with our crazy panoply of tiletile combinations to attempt continuous columns of stone that carried through from tile to tile, and instead tried to hide the tile transitions with organic noise. This time around, I’ve improved enough to grapple with that, so I’m able to make the tiles look much more like the basaltic columns I’d intended for them to look like. (We’ve also moved to a more deliberate use of a small amount of perspective on the upper surface of solid areas, so this change also incorporated that.)

Hello.
Over the past half-year or so, I’ve made a game using the Frogatto engine called Cube Trains. It’s a 3D puzzle game based around building tracks in the confines of the city. You can visit the website over here: http://ddr0.github.com. A picture is worth a thousand words, they say, and I’m not very talkative. Let’s make this post 2153 words long, shall we?

Just a side note, in the 0.2.0 release for windows and linux, you’ll need to remove any Frogatto save-files you have saved from their save folder. Cube Trains expects there to be none there when it starts up the first time, though you can rename the save-files and put them back when you’re done. (save.cfg -> save1.cfg, save1.cfg -> save2.cfg, and so on) This problem does not affect Mac users.

The code is available in the cube_trains module of Frogatto, in the more recent git versions.

I’m going to take a little detour from my series on how to make a game in Frogatto to discuss in detail an important topic to anybody who wants to develop using Frogatto: how event handling works.

Frogatto’s game objects receive ‘events’ frequently. They receive a create event in the first frame they run, a collide_side event when the object runs into a wall, a collide_feet event when landing on the ground, and a jumped_on event when another object lands on top of the object. They even receive a process event that is triggered every frame. There are around 30 built-in events, and more types of events can be added.

Events are the big chance you, as a game developer, have to customize an object’s behavior. When an event occurs on an object, you get to specify any actions the object should make in response.

Frogatto’s event handlers are written in Frogatto Formula Language (FFL). FFL is very different from many other computing languages, such as Python or Lua or Javascript in that FFL is a pure functional language. What this means is that FFL’s entire purpose is to run some calculations and return the results of these calculations. An FFL formula has no ability to directly change the game state.

Huh? How does this work then? What use is writing some code if it can’t actually change anything? Here is how it works: when an event occurs, the game engine evaluates the FFL formula — during this evaluation the game state is completely frozen — and the formula returns one or more command objects. After the FFL has finished running and returned its results, the game engine steps through these commands that FFL returned and executes them.

This might seem like a distinction without a difference, but it’s very important. Note the difference between when the game engine evaluates FFL (without allowing modification of the game) and then, once the FFL is done, executes the commands that FFL gave it. This has the huge benefit of making it so an FFL formula runs in an environment where nothing changes, where everything can be viewed as a mathematical model of the current game state — where one doesn’t have to keep track of the possibility of variables changing during the evaluation of a formula.

Anyhow, enough theoretical talk! Let’s get down to a concrete example. We’ll start with a simple one. Suppose we have an object which steadily moves upwards by 2 pixels every frame, here is how we could make it work:

on_process: "set(y, y-2)"

Every frame, the process event gets fired. The FFL code, set(y, y-2) is evaluated. What is this ‘set’ thing? It’s a built-in function that returns a set command. If the object’s y position was 100 before the event was triggered, the FFL will evaluate to a set command with the information encoded to set the value of ‘y’ to 98.

After the FFL returns this command and has finished, the game engine will execute the command. Executing the command will result in setting the object’s y value to 98, shifting it up 2 pixels. Note that the process of evaluating the formula is part of FFL. Executing the command takes place within the game engine, and there is no FFL involved.

The set function is the most often used function out of an extensive suite of functions FFL has available for generating commands. There are commands for playing sound and music, for spawning new objects, for different graphical effects, for debugging, and so forth.

Note that it is important to understand the difference between an FFL function that returns a value that is useful in FFL, and an FFL function that returns a command. For instance, FFL includes the sin function, which returns a value that is useful in intermediate calculations but doesn’t make much sense to return to the game engine. The spawn function gives us a command which, when executed by the game engine, spawns a new object and is exactly the kind of thing we might return to the game engine.

FFL is a full-fledged programming language, and we can include complex logic in it. Let’s say we wanted to make the object reverse direction every two seconds (i.e. every 100 frames). We could write the event like this:

on_process: "if((cycle/100)%2 == 0, set(y, y-2), set(y, y+2))"

Note how, in FFL, if is just a function. It looks at its first argument, and if its first argument is true, it’ll evaluate to its second argument (the ‘then’ clause) otherwise it’ll evaluate to its third argument (the ‘else’ clause).

I want to dive much deeper into how FFL works, and what can be done with it, but that will wait until a later post. Right now, I want to talk more about the event handling mechanism Frogatto uses.

Like I said, an event handler is evaluated and then after the FFL has returned its results, those results are executed by the game engine. This has some interesting implications. Firstly, FFL can return multiple commands in a list, like this:

on_process: "[set(y, y-2), if(y < 0, set(x, x+2))]"

This will return commands to decrement y by 2, and if y is less than 0, increment x by 2. Note though that since the entire formula is evaluated before any execution occurs, the value for y throughout the formula is the value at the start of the event. This means that if y is 1 before the event occurs, the if condition will fail, because the set(y, y-2) will not be executed until after the event returns.

Consider this code:

on_process: "[set(y, 5), debug(y)]"

debug evaluates to a command that outputs its arguments, in the game window and the console. Very useful for debugging. Note though that it will output the value of y as it was before the event was fired. If you wanted it to output 5, you might do something like this:

Pretty silly code, right? But what does it do? Say y was 100 before the event was called. We will return three set commands, the first will be encoded to set y to 0, the second to set y to 95, and the third to set y to 98. The game engine executes commands in a list in order, so the last command will set y to 98, and the first two commands will in effect do nothing.

One special function is the fire_event function. It returns a command that explicitly fires an event. For instance,

When the process event occurs, commands will be returned to decrement x and y, and then a command to fire an 'output_state' event. These commands will be executed in sequence. x and y will be set, and then output_state will be fired, causing on_output_state to be evaluated. Finally, the debug command returned by on_output_state will be executed, causing the updated x, y to be output.

Note that fire_event is very useful in some situations, but should be used judiciously. Its main purpose is NOT to allow chaining of events like this, but to allow us to fire_events on other objects (e.g. if we hit another object we might want to fire an event on them to know they've been hit).

Hopefully this gives us a nice overview of how the Frogatto event system works. Hopefully, soon, I'll write more about all the features FFL has to offer. In the meantime, you might like to check out our FFL FAQ.