So you want to make a game, and you think the Frogatto engine might be for you? This is the first in hopefully a series of posts which document just how to do that. These posts are targeted at people with some technical knowledge — who know how to run Frogatto from the command line and pass command line arguments to it, know how to edit text files, and have some coding knowledge or who are eager to learn. I will also assume that you have some level of familiarity with the Frogatto Editor (accessible by pressing ctrl+e while in a game of Frogatto).

I’m going to develop a simple platform game, featuring a sword-wielding heroine, Elisa, which I’m calling Elisa’s Quest.

To begin with, Frogatto features a module system. You can put your game in its own module, and then when you run Frogatto, you can specify which module you want to use. This allows you to develop your own game without interfering with the core Frogatto game.

To create a module for Elisa’s Quest, we make a new directory under the Frogatto install, in modules/elisa. Then we create a basic configuration file for our module, in modules/elisa/module.cfg using our favorite text editor. We enter this into the file:

{
id: "elisa"
}


This file is the main module configuration file. For now the only setting is to specify the ID of the module, but we are likely to add more settings here later.

Game Objects

In our game, we will want our sword-wielding heroine to jump from platform to platform, battling vampire bats, collecting coins, and avoiding traps of spikes. Each of these things — the heroine herself, platforms, bats, coins, and spikes, are examples of game objects (often just called ‘objects’) that we must define to the game engine.

An object’s appearance and behavior is specified in a single .cfg file that will be placed under modules/elisa/data/objects. It can be placed directly in this directory or in any sub-directory, so if you’re making a substantial game, it’s a good idea to categorize the different objects into different directories.

An object needs a sprite sheet, a png file which contains its art. Multiple objects can share a single sprite sheet, or one complex object might have its images split across multiple sprite sheets. All images will go under modules/elisa/images — which is the directory Frogatto searches for images in.

We’re going to start by defining our heroine, Elisa. Here is the sprite sheet for her, which I will put in modules/elisa/images/characters/elisa-spritesheet1.png :

Note that both the background color and the color of the red rectangles around the sprites are special colors (#6f6d51 and #f9303d) which the engine treats as fully transparent. This allows you to organize your sprite sheets, and indicate frame boundaries, though isn’t strictly necessary. The Frogatto engine also fully supports alpha channels, which you can alternatively use for transparency.

Note also the size of the image. All that extra space around it isn’t just arbitrary. Widths and heights of images provided to the Frogatto engine should be powers-of-2 (i.e. 2, 4, 8, 16, 32, 64, 128, 256, 512, or 1024). Here, we’ve padded the image out to make it a 512×512 image. If Elisa was a little shorter, we could have made it a 512×256 image.

Now it’s time to start defining Elisa’s behavior. We create a file in modules/elisa/data/objects/characters/elisa.cfg:


{
id: "elisa",
is_human: true,
editor_info: { category: "elisa" },
animation: [
{
id: "stand",
image: "characters/elisa-spritesheet1.png",
rect: [4,4,57,57]
}
]
}


This is a fairly bare-bones definition of an object. Let’s see what it tells us:

• The object’s ID is elisa. This must correspond to the filename (elisa.cfg)
• elisa is ‘human’. That is, she is controlled by the player. In a single player game, there may only be one object in existence at a time that has this flag. Many games will only have one object that has is_human: true.
• elisa goes into an editor category called ‘elisa’. This means when you want to add an elisa object to a level in the Frogatto editor, you will find her under a category called elisa.
• All objects must have a list of one or more animations. An animation consists of one or more frames. Right now we just have a single frame animation for elisa. Note that the rect: [4,4,57,57] specifies the top-left most sprite in her sprite-sheet.

This definition of Elisa is written in Frogatto’s Object Notation (FSON) — basically JSON with a few additional features. FSON is used extensively throughout Frogatto as a data language to define the properties of objects.

Adding Elisa Using the Editor

Now we can try out the Elisa object in-game. One of the nice things about Frogatto’s module system is when you run a module you still have access to Frogatto core game data, when you’re first testing your game you can do so, mixing it with Frogatto’s assets, before all yours are fully developed.

We invoke the game with the --module command line argument: frogatto --module=elisa. This runs the game, loading our module. We press ctrl+e to open the editor, and then we can easily find and add the elisa object to a game of Frogatto:

Now, at the moment, all the elisa object does is stand there, frozen still. We haven’t given her any other behavior yet. If we look at the Elisa spritesheet, we notice that the top three images are all part of a standing animation, meant to make Elisa move a little, even when standing.

Note how the frames are of uniform size and spacing. This is how the engine expects frames of the same animation to be laid out. An animation definition may contain a specification of how many frames there are in the animation, along with the duration, in game cycles, of each frame. A padding may be specified to show how many empty pixels there are between the frames on the sprite sheet. In this case we have three pixels between frames.

This animation also isn’t meant to be played to the end, and then started over. Instead, it’s meant to be played forward (Elisa inhaling) then played in reverse (Elisa exhaling). Some animations are designed to be played forwards and then backwards, and the engine provides a special reverse property to allow for that.

A little note at this point: we can continue to edit Elisa’s code using our text editor of choice. We can also use Frogatto’s built-in editor by pressing the “Code” button in the editor. If we use the in-game code editor, we will see Elisa update instantly as we make changes to the code. Even if we use an external editor, the game engine will update the changes we make without us having to exit and restart Frogatto! This feature is enabled as long as we are in the Frogatto editor.

Here is the code to turn the still standing frame into a proper animation:


{
id: "elisa",
is_human: true,
editor_info: { category: "elisa" },
animation: [
{
id: "stand",
image: "characters/elisa-spritesheet1.png",
rect: [4,4,57,57],
pad: 3,
duration: 5,
frames: 3,
reverse: true
}
]
}


After making this change, when we play the game, Elisa will play through her animation, but only once. Then she will freeze again, staying in the last frame of her animation. The game engine doesn’t know what to do with her next without some instruction. It might seem obvious: “she should start the animation over again!” — but it’s not so obvious. When elisa finishes an animation involving swinging a sword, we wouldn’t want her to just play that animation over again. Instead, we must provide instruction on what to do, and we provide that instruction through events.

Events

When we think about the behavior we want to specify for an object, much of it revolves around us wanting to specify how the object behaves when something happens. What should the object do when it lands on the ground? When it collides with a bat? When the player presses a button? When an amount of time elapses? When the level starts? These are all events. In this case, we are interested in what elisa should do when her ‘stand’ animation finishes.

We specify what should happen when an event occurs in an event handler. An event handler is a property in FSON which contains a formula that is evaluated when the event occurs. The formula is written in Frogatto Formula Language (FFL). This formula is able to query the current state of the game, and then return some commands. These commands that the formula returns will be executed by the game engine.

In this case, all we want to do is specify that when the animation finishes, it should be played over from the start. That, is quite simple:

{
id: "elisa",
is_human: true,
editor_info: { category: "elisa" },
on_end_stand_anim: "set(animation, 'stand')",
animation: [
{
id: "stand",
image: "characters/elisa-spritesheet1.png",
rect: [4,4,57,57],
pad: 3,
duration: 5,
frames: 3,
reverse: true
}
]
}


Whenever the ‘end_stand_anim’ event occurs on this object, the event handler is invoked, and it returns a command to set the object’s animation to ‘stand’ — which will start the stand animation over from scratch.

Now, let’s make it so Elisa can swing her sword. To do this, we’ll need to define her sword swing animation. We’ll also need to have an event to make her enter the animation. A ‘ctrl_tongue’ event will be sent when the ‘s’ button is pressed (due to this normally being the button which activates Frogatto’s tongue in Frogatto). We will use is to make Elisa swing her sword. However, Elisa can’t swing her sword any time. For instance, if she’s already swinging her sword, another press of ‘s’ should be ignored, so we’ll add some logic to make it so she can only swing her sword if she’s currently in her ‘stand’ animation:


{
id: "elisa",
is_human: true,
editor_info: { category: "elisa" },
on_end_stand_anim: "set(animation, 'stand')",
on_end_attack_anim: "set(animation, 'stand')",
on_ctrl_tongue: "if(animation = 'stand', set(animation, 'attack'))",
animation: [
{
id: "stand",
image: "characters/elisa-spritesheet1.png",
rect: [4,4,57,57],
pad: 3,
duration: 5,
frames: 3,
reverse: true
},

{
id: "attack",
image: "characters/elisa-spritesheet1.png",
rect: [5,180,93,240],
pad: 3,
duration: 5,
frames: 6,
frames_per_row: 3
}

]
}


Note how ctrl_tongue has its code enclosed in an if statement, so the event handler will only cause anything to happen if Elisa is in her stand animation. If she’s already in her attack animation, the event won’t do anything. This is a simple example of the logic capabilities of FFL. Next time I want to explore FFL in much more detail.

I think this is enough for our first lesson — we’ve added an object, and made her perform a few basic actions. We are a little lacking in documentation on the Frogatto engine right now, and I’m hoping this series can improve it, so please feel free to reply with any questins or comments!

→ Next Page
↑ Table of Contents
← Previous Page