Lua Scripting Guidelines

This page is still work-in-progress and its content open to discussion!

On this page you can find the guidelines for the coding style of our Lua scripts.

Indentation

Code is indented using 4 spaces, no tabs.

Naming

Always use descriptive names, so other people reading your code can easily see what a function or variable is used for.

Variables and functions should use lower case and underscores. Constants should use all upper case and underscores.

    CONST_VALUE
    function some_function(some_parameter)

Quest variables should contain faction if they're related to a faction, the area where the quest takes place or the NPC it has to do with, and a descriptive part. Examples:

    soldier_goldenfields_taxes
    goldenfields_widow

Scope

Use local variables and functions whenever possible. If you need to use global variables and functions, make sure to have unique names. This can be done by using descriptive function names and involving the quest or NPC name into the variable name.

    local value = 3
    questname_value = 3

Whitespaces

Use whitespaces between the parameters in a function call:

    some_function(para1, para2, para3)

And between elements in calculations:

    local x = ((5 + 4) * 3) / 1.5

Line length

Should not exceed 79 characters.

One reason for this is to keep code readable. In such cases it would often be better to spread the line over multiple lines or use some extra temporary variables. Another reason is that some of us are using editors that default to an 80 character wide screen, and often put two instances next to each other. 79 character wide lines leave just a spot for the cursor at the end of the line.

In case of NPC dialogue, the line break and indentation should look like this:

    say("Lot's of text that exceeds the length of one line, "
        .. "so we continue the dialogue in the next line.")

So split the strings and indent the new line to the opening (.

When you indent a table definition please let it look like this:

        local choices = {
            "In the kitchen? I'm a strong fighter!",
            "Alright, thank you, where do I have to go?",
            "I was promised fame and gold for joining the army!",
            "this is a long long long long long long long long "
            .. "multiline text that works fine here"
        }

Long function calls can be splitted like this:

        local hp_loss = being_damage(my_being, some_factor * 0.001, 3,
                                     chr_get_level(ch, 
                                                   "Magic_Firelion") * 10,
                                     DAMAGE_MAGICAL, ELEMENT_FIRE, ch,
                                     "Magic_Firelion")

Even nice is when you work with a variable to keep the actual function call a bit cleaner:

        local hit_chance = chr_get_level(ch, "Magic_Firelion") * 10
        local hp_loss = being_damage(my_being, some_factor * 0.001, 3,
                                     hit_chance,
                                     DAMAGE_MAGICAL, ELEMENT_FIRE, ch,
                                     "Magic_Firelion")

Avoid hard coded numbers

Values that are needed in several scripts should be defined as global constants.

When using functions that e.g. involve items, use their names instead of ID's. This makes the code much more readable.

    -- good:
    local item_amount = chr_inv_count(ch, true, true, "Item")
    -- bad:
    local item_amount = chr_inv_count(ch, true, true, 1)