How to play around with lua

First things first, you need to compile cataclysm with lua enabled. I’d love to provide a binary for windows, but as it stands I can’t get MinGW to compile cataclysm at all(with or without lua). If one of you got compilation on windows working, please contact me so we can work out lua compilation together(should be real simple at that point).

On unix-likes, it should simply be a matter of:

make LUA=1

This howto assumes you know lua. If you don’t, I suggest googling lua tutorial or something of the sort. =) The easiest way to get started is the lua debug command. Go to the debug menu, and at the bottom you should see “Lua Command”.

We’ll start with a simple Hello, world!.


As you can see, game.add_msg does nothing but print a message to the log. If you’re familiar with the C++ source, you’ll also realize that this is the same as the add_msg function. If you’re wondering why you have to call game.add_msg rather than add_msg: No reason, really, other than separating functions defined by the game from functions defined by you.

Here’s a list of all currently defined functions in game:

add_msg(msg), string_input_popup(title, width, default_input), rng(lower_bound, upper_bound), distance(x1, y1, x2, y2), trig_dist(x1, y1, x2, y2)

More functionality will (hopefully) follow, but this is mostly guided by what is requested.

You can also modify the player object directly. A full list of all player properties and functions(quite extensive already) can be found in lua/class_definitions.lua under the “player = {” line.

[spoiler][code]
player = {
attributes = {
posx = {
type = “int”,
writable = false
},
posy = {
type = “int”,
writable = false
},

        hunger = {
            type = "int",
            writable = true
        },
        thirst = {
            type = "int",
            writable = true
        },
        fatigue = {
            type = "int",
            writable = true
        },
        health = {
            type = "int",
            writable = false
        },
        
        name = {
            type = "string",
            writable = false
        },
        
        male = {
            type = "bool",
            writable = false
        },
        
        str_cur = {
            type = "int",
            writable = false
        },
        dex_cur = {
            type = "int",
            writable = false
        },
        int_cur = {
            type = "int",
            writable = false
        },
        per_cur = {
            type = "int",
            writable = false
        },
        
        str_max = {
            type = "int",
            writable = false
        },
        dex_max = {
            type = "int",
            writable = false
        },
        int_max = {
            type = "int",
            writable = false
        },
        per_max = {
            type = "int",
            writable = false
        },

        stim = {
            type = "int",
            writable = true
        }
    },
    functions = {
        has_disease = {
            args = { "string" },
            rval = "bool"
        },
        rem_disease = {
            args = { "string" },
            rval = nil
        },
        add_disease = {
            args = { "string", "int", "int", "int" },
            rval = nil
        },
        morale_level = {
            args = { },
            rval = "int"
        },
        is_npc = {
            args = {},
            rval = "bool"
        }
    }
},

[/code][/spoiler]

Want to know exactly how hungry you are? No problem!


Similarly, you can also just simply set your hunger(this might not work for all properties, as some are write-protected).

player.hunger = 20

As you can see, though, we have to repetitively enter quite a lot of code for our debugging. This can be alleviated a bit by defining your own functions in data/main.lua, which as you’ll note already contains a bunch of functions.


That’s it for now. If you discover that something you’d like to do with lua is not possible to do, feel free to ask about it in this thread.

Someone recruit some guys from the data realms fourms and see what they do!

I haven’t played with Lua in a long time. Maybe its time to brush it off and see how hilariously I can break my cataclysm

Alternately just start with an experimental build, they build with LUA enabled since shortly after LUA integration was landed.

To back up a step or two, the LUA situation is this. CIB did the work to get basic integration with LUA working, but it’s optional for the time being because I’m worried about it keeping people from being able to build. If it doesn’t break anyone’s build (or it breaks them and we can fix it), it’ll change to being a non-optional build dependency, at which point we can start adding new lua-specific features, like LUA iuse methods for activatable or edible items, or LUA-based map generation, possibly LUA-based monster AI.