Language Introduction

So, you want to make stuff with the Frogatto engine? I like the way you think. Skim GeneralGameMakingFAQ, it's a very quick start guide. Don't worry if you don't understand all of it (or indeed, any of it), that's what this page is for. Now, have you played the original game?

yes	no
Well, that was fun. Proceed to the next section.	Go play the game. It lives here: http://www.frogatto.com/. It will help to see what has been done already when you go to start your own project. When you're done, proceed to the next section.

For this page, we'll be using Frogatto at version 1.1.2 or later.

The Test Object

For a starting project, let's make something we can place in the editor. This is fairly straight-forward, but it does involve finding a bit of stuff. Are you using an Apple operating system?

yes	no
Well, um, the data is sort of 'in' the file that you run to play Frogatto, somehow. Maybe if you [cmd]-click it you can view the contents? (I don't own a Mac, myself.) Anyway, view the files for the game now.	Find the folder you installed Frogatto in and open it.

Are you looking at several folders and some files? There should be some folders called 'data', 'images', and 'music' in there. If not, you're looking in the wrong place. If you answered 'yes' to the previous two questions, however, you should make a note of where you are. This is the 'root' folder of Frogatto. When I refer to the folder ~/, that means this folder, right here.

Now check ~/images/effects/particles.png.

This is a source image for the game. See that red target symbol near the bottom-left corner? We'll be using that as our test object. It's easy to spot. It's rectangle is 23, 197, 28, 28, top-left-corner x, top-left-corner y, width, and height. Check for yourself — it's good practice, and I might have copied it wrong.

In ~/data/objects/experimental (here), create a new file called test_target.cfg. We can't call it target, because there is already a 'target' object in existence over in the controllers folder (here). In this file, opened with your favourite plain text editor, put:

[object_type]
	id=test_target

	[editor_info]
		category=experimental
	[/editor_info]

	[animation]
		id=normal
		image=effects/particles.png
		x=23
		y=197
		w=28
		h=28
		frames=1
	[/animation]
[/object_type]

Save the file, start Frogatto, press [ctrl]-[e] to access the level editor, select the object tool, select the experimental category, and place your target. See?

yes	no
So red and targety.	Well, bother. Is the test_target.cfg file saved in ~/data/objects/experimental? Yes? Well, make a post in the mod forum about it. They'll help.

Congrats, you made something! Next,

Motion Test

Back in test_target.cfg, between [/editor_info] and [animation], let's put a bit of code to move our object to the right. Type on_process = "set(x, x+1)". Save the file, and run Frogatto again. Now the target moves slowly to the right. This works by setting the x variable of our object to itself plus one. (A list of every single variable you can set can be read over here, but - again - it's kind of technical.)

For reference, test_target.cfg now looks like this:

[object_type]
	id=test_target
	
	[editor_info]
		category=experimental
	[/editor_info]
	
	on_process = "set(x, x+1)"
	
	[animation]
		id=normal
		image=effects/particles.png
		x=23
		y=197
		w=28
		h=28
		frames=1
	[/animation]
[/object_type]

You just added an event and a function, and you did it using two different languages! The first language -- bear with me -- is called the Frogatto Markup Language. FML, as I shall now call it, is everything that's not Frogatto Formula Language. FFL is what's inside the quotes in FML. So, the FML we just wrote makes the on_process event to be equal to set(x,x+1), and then the game engine executes on_process. If you're feeling curious, a list of all the FML events is here, and a list of all the FFL functions is over here. Of course, those are Serious Reference Pages, and make rather dense reading, but at least you know where they are now.

Enough of that junk! Let's make our little target object move diagonally up, because just going right is starting to get so last paragraph. To do this, we'll subtract one from y, but we'll have to keep the original bit that subtracts from x in there too. To do this, we'll use another function to set the value of y. Replace on_process = "set(x, x+1)" with

	on_process = "[
		set(x, x+1),
		set(y, y-1),
		]"

So, you say, those square bracket thingies appeared, and now there's commas too... that must mean it's a list of set()s? Smart cookie, you're exactly right. Moving on, let's make the target move up and left. Add this element to the list (keeping the two that are already there): set(x, x-1). (Yes, just minus one.) test_target.cfg now looks like

[object_type]
	id=test_target
	
	[editor_info]
		category=experimental
	[/editor_info]
	
	on_process = "[
		set(x, x+1),
		set(y, y-1),
		set(x, x-1),
		]"
	
	[animation]
		id=normal
		image=effects/particles.png
		x=23
		y=197
		w=28
		h=28
		frames=1
	[/animation]
[/object_type]

Run the game to see the results. The object should move up and to the right. ...

What the heck?	That makes sense, but why is it like that?	Meh, next bit?
According to basic intuition, and some grade one math, our little target should be going straight up. We added one to x, then we subtracted one from x, so we should have a total of zero movement on the x variable. WHAT YOU SMOKING, LITTLE FROG? ... to explain what is happening, first we set x to itself plus one, then we did y, then we set x to itself less one. However, you remember how I said that we made on_process equal to the contents of our quotation marks, THEN the game engine executed on_process? Well, by the time we got to figuring out what set(x, x-1) was, in our function, the game had not actually set x to x+1. So, x is the same value for both functions. Now, the game happily sets x the first time, then it does y, then it sets x a second time and overwrites the change from the first x.	The engine behaves bizarre manner because: In your computer, you probably have between two and eight processors, all of which can run Frogatto. However, if core #1 is processing the first set(x) command, and core #2 is processing the set(y) command, and then core #3 is figuring out the results of the second set(x) command... since core #1 hasn't actually figured out the results of set(x) yet, core #3 can't know the answer to the first set(x) when it figures out the value of the second set(x). So that core #3 doesn't have to wait, neither of the set(x)s are applied to x until after everyone is done figuring out what x should be. Since the results of the set commands are applied in sequential order, though, x ends up being the results core #3 figured out. If we didn't do this, we could only use one core to compute results. (I never said we did use more than one core, here, but still. We could.)	Be aware of this behavior - in a big function, it'll introduce bugs that are a bit tricky to find if you don't know about it.

If you have any further questions, or if you're having problems, please let us help on the forum. We've got a little thing that Gambit set up that alerts us on our IRC channel (irc://freenode/frogatto) whenever anyone posts, so we're usually pretty snappy when it comes to a response.

The Next Section

Which has yet to be written. Bug DDR on the forums or something.