Modding Guide

[Derek]

We were originally going to include some documentation with the game itself, but time constraints meant that we didn't get to flesh them out as much as needed to.  But I think they're still very helpful for those starting out, so I put them online.  Just keep in mind that there may be some misinformation in them, since the structure of the mod framework changed a bit right before we release!

http://www.bit-blot.com/aquaria/mods/modguide.html

Once we have more time we'll get some proper docs up.  Maybe a wiki.

[Alec]

Some warnings

• Don't go to animation editor, or particle viewer unless you've saved your map. You'll lose your last changes otherwise.
• Deleting objects that are "in use" can cause a crash. (e.g. if you delete a rock that Naija has cast the bind song on)

I'll post some more of these when I remember them. 

[deb]

I am a newbie at modding and Lua although I have programming experience. I would like to writeLua scripts for Aquaria modding. How do I go about it? I mean do I need to donwload just the simple Lua library for Windows or do I need to have some C/C++ compiler? In other words what kind of tools do I need to write scripts in Lua and produce aquaria mods? Any pointers would be appreciated

deb

[Alec]

Hi Deb, welcome to the forums!

You just need a text editor to edit lua scripts. I recommend Notepad++.

Scripting works kinda like... you edit the files, then reload the level. You don't need to compile them.

[deb]

Thanks Alec. I assume this means that the level editor that comes with the game has the Lua interpreter then?

deb

[Alec]

The game interprets the scripts, yep.

[Aërendyll]

I'm kind of wondering: are there specific tutorials about creating Forms, Songs and Recipes for people who are very new to scripting and who are still practising? I am a scripting newbie myself and I can do a little programming, but I get confused when I need to type out large amounts of codes. (These tutorials could also be snippets of codes that are explained per snippet on what they do and where to place them. )

[Malidictus]

I realise this is, what... Over two years old? But it's still a bit disheartening even two years down the line I first heard of Lua when a friend of mine asked me to research WoW macros, and from what I hear it's a proper programming language. That's good on one hand, as it ought to allow modders great control over the game. On the other hand, I'm really not up to learning yet another programming language at this time. They just take far too much time to truly grasp, and I just know it'd bug me to know be fully aware of the whole process.

I was interested in what the process was, and the tutorial mod does do a pretty good job of explaining it, actually, but towards the end, it's actually pretty skinny on the finer details of active objects. I assumed that the game interprets their names as function calls with their parameters, but not knowing what the functions are kind of kills me. And even if I did, I was impressed by the conversation menus someone had made for a mod (I think it was Sacrifice, but I'm not sure), and I just KNOW those can't be made to work with just basic knowledge.

I guess I'll stick to replaying the game itself

[Yogoda]

Really, lua is easy to learn. You just need to know how to do the basics : function calls, conditions, loops, nothing more.

Here is the modding Wiki, you have all explained here. If there is something you want to be added, just ask  !
http://aquariawiki.ryanballantyne.name/wiki/index.php/Main_Page

What takes time however, is learning the functions. You can start with the list of the most used functions here :
http://aquariawiki.ryanballantyne.name/wiki/index.php/Most_used_functions

I see you have trouble scripting the nodes, here is probably what you are looking for :
http://aquariawiki.ryanballantyne.name/wiki/index.php/Create_a_trigger_node

Here are all the callback functions for nodes and entities :
http://aquariawiki.ryanballantyne.name/wiki/index.php/Callback_Functions

I put a lot of time and effort to try to make it easier for people wanting to learn the scripting, but I realize there is something wrong.

You can help us make things better ! Tell me what we should change to makes it easier Was it easy to find the modding Wiki ? Maybe I should write a tutorial explaining the basics of Lua too.

I can assure you, scripting basic things like trigger nodes is not hard. But don't try to create a new GUI now, start with easy things. If you have a problem, ask, we are always available for help.

[Yogoda]

Ok, here it is :

http://aquariawiki.ryanballantyne.name/wiki/index.php/Learn_Lua

It won't take you more than 15 minutes to learn all you need to know with Lua

[Malidictus]

Ok, here it is :

http://aquariawiki.ryanballantyne.name/wiki/index.php/Learn_Lua

It won't take you more than 15 minutes to learn all you need to know with Lua

So, basically I'm looking at an object-oriented structure with each script being its own object? From what I can see, it looks like you have a constructor defined as init that gets auto-called on creation (I'm guessing here) and an update function that's basically what the entity does constantly. Can I write other functions into it? Can other objects call them, or is it strictly on an object-per-object basis?

If this is the Lua language, then it actually reminds me of Java, but with Perl's non-specific variable definitions, which is always something that bugged me in Perl. Since I can't enforce variable type, a few functions will either refuse to work or be prone to returning unpredictable results.

Also the function of the, err... Specific functions is a bit hard to follow, though that's probably just me not knowing which way the bolt turns. For instance, I see a function described as "entity_velx(ent)," and I'm not sure what that does. From the name, I can assume it returns the entity's horizontal velocity to be used for physics calculations, but even then I'm not sure what "ent" is in terms of data type. Since the function requires a variable to call it, I'm assuming I have to specify it? Can I just nest... Let's see what that was... Can I nest, say, getNaija() in it for a total of entity_velx(getNaija())? I'm assuming the get function would return a pointer for the entity function to use, but again, I'm guessing over not much background.

See, if I can wrap my head around the architecture used to hold things together in Aquaria, I'll probably be able to put something together, but again, that's a LOT to take in. It doesn't seem like a lot, and it probably isn't too much in terms of raw information, but it's actually a lot to process, because it is... Well, fairly serious programming. As... Serious as you want to make it, undoubtedly, but I like to know the systems I use.

P.S.
In the Learning Lua article, it seems a bit... Mean to leave people guessing what the given code block would do In my experience, especially for illustrative examples, it pays to explain the actual function step by step. I... Think I can sort of follow the steps with a LOT of guessing on my part, but I'm still largely in the dark, and there is no Light Form in sight!

[Yogoda]

It seems to me you want to go too much into the details.

The core game is written in C++, Lua is used because it removes all the layers of complexity, and make it much more easier and faster to define the entities and nodes behavior, and removes the needed to compile. Under the scene you have of course C++ objects, and constructors.

The lua files are loaded when the C++ objects are constructed, and the lua callback functions are called at specific places. I guess the init(me) is called at the end of the constructor, and the me is in fact a pointer to the C++ object.

When you call a function, for example entity_velx(me), it calls a C++ method on the object me

But again, you really don't need to know all the complexity that is behind. A Lua script is not an object, and has no constructor, it is not object oriented.

Here is the detailed list of all the functions :
http://aquariawiki.ryanballantyne.name/wiki/index.php/Category:Functions

The functions that apply on a entity have the prefix entity_
Those that apply on nodes have the prefix node_
And so on.

In the Learning Lua article, it seems a bit... Mean to leave people guessing what the given code block would do In my experience, especially for illustrative examples, it pays to explain the actual function step by step. I... Think I can sort of follow the steps with a LOT of guessing on my part, but I'm still largely in the dark, and there is no Light Form in sight!

Well, this is an example to try ingame. I think if you see Naija turn blue then transparent you have no problem guessing what entity_color(n, 0, 0, 1) and entity_alpha(n, 0.2) do. You learn a lot by trying to guess things by yourself, and most of the functions are documented anyway.

[Malidictus]

Right. I apologise for muddying the waters, as it were. It's just that education and work responsibilities have taken me through half a dozen programming languages (some more involved than others), to the point where I can't help but see things as "Ah, so this is like that in this language, but that's like the other thing in that other language." I've actually spent the most time on C++ and Java of all the languages I know, which is why I tend to see most things in an object-oriented context, whether that context actually exists or not. That's kind of why I say I need some time to wrap my head around Lua itself and the setup of the functions as defined.

For what it's worth, I'm GLAD I don't have to deal with object-oriented programming in C++. Work with pointers there is just opaque. But that just means that I know practically nothing coming in, since I'm starting with preconceived notions which seem to either be wrong or not apply as I think they should, and it will take me a while to work it out. I do appreciate the help with this, and your patience. At first glance, it looks like too much to learn with what free time I have, but I don't know. I just might end up going for it. After all, there's no telling when I might need to know Lua in the future. This is the second time it's come up for me so far, after all. (Just between you and me, I'm not a fan of the Pascal-style block definition with "END" tags. I much preferred curly brackets.)

So, yeah. Looking through the system definitions is probably my priority for the moment. I did miss that link with all the functions, so that will be a good place to start.

[Dolphin's Cry]

If you want to compare Lua with other programming language, it would probably go like this: Lua is very similar to Scheme, but with less parentheses and with (associative) tables instead of lists. Both have lexical scoping (i.e. closures), are dynamically type-safe (i.e. variables do not have types but all values do), and are relatively easy to learn (i.e. just a few simple concepts). The types in Lua are Nil, Booleans, strings, numbers, tables, functions, coroutines and user objects. User objects can only be created from C/C++ and are used to implement user-defined types.

Lua is not object-oriented as-is, but provides mechanisms that allow the implementation of object systems in the language itself. Then again, the Lua scripts in Aquaria do not make use of that. I have seen people have problems understanding Lua because they tried to compare it to C++ and Java too much.

As far as the types of application-specific objects in Aquaria go, there are entities and nodes. There are functions that return a reference to one of these types. They return 0 (the number zero) to indicate that a requested object does not exist. A more natural choice would have been to make those functions return nil in that case, but that's how things are. I would recommend to not make any assumptions about the Lua type of references to valid objects. Just don't pass in a node reference where an entity reference is required, or vice versa.

For more information about Lua itself, I would recommend the Lua Reference Manual or the book Programming in Lua. Especially the latter is nice to read, quite unlike "The Programming Language C++" by Bjarne Stroustrup which I would not recommend to just anyone.