Lua

Lua allows you to script behavior for CDDA without having to modify the C++ code. Lua support is currently very limited, so don't expect to be able to do too much with it just yet. If there's something you'd like to do in lua that is currently not possible, please consider creating a github issue.

To learn more about lua, check out the lua tutorial. You can try out lua scripts online here.

lua debug command

Let's start by printing messages to the game screen. Run cataclysm, load up a character, and enter the debug menu. Select the "lua command" option. Enter some text, for instance `game.add_msg("Hello, world!")`. You should see your message being printed to the screen.

http://i.imgur.com/RaFtCjx.png

You can print some more useful information, like `game.add_msg(player.health)`. You can also use this for cheating, e.g. you can increase your strength by typing `player.str_cur = 20`.

lua in mods

If you're creating a mod, you can use lua to add scripted features to your mod. For this, you have to create a file called `main.lua` in your mod directory where the .json files are stored. Here is an example of such a `main.lua` that halves the speed of zombies.

monster_types = { 
    "mon_zombie", 
    "mon_zombie_fat", 
    "mon_zombie_tough", 
    "mon_zombie_crawler", 
    "mon_zombie_hazmat", 
    "mon_zombie_fireman", 
    "mon_zombie_survivor", 
    "mon_zombie_rot", 
    "mon_zombie_cop", 
    "mon_zombie_shrieker", 
    "mon_zombie_spitter", 
    "mon_zombie_electric", 
    "mon_zombie_smoker", 
    "mon_zombie_swimmer", 
    "mon_zombie_dog", 
    "mon_zombie_brute", 
    "mon_zombie_hulk"
}

-- halve the speed of all monster types in the above list
for _, monster_type in ipairs(monster_types) do
    game.monster_type(monster_type).speed = game.monster_type(monster_type).speed / 2
end
 

Lua API

Below is an automatically generated table of the current lua API.

Global Functions

• uimenu create_uimenu()
• it_gunmod get_gunmod_type(string)
• int trig_dist(int, int, int, int)
• string string_input_popup(string, int, string)
• overmap get_current_overmap()
• it_tool get_tool_type(string)
• int distance(int, int, int, int)
• mongroup create_monster_group(overmap, string, int, int, int, int, int)
• int rng(int, int)
• it_comest get_comestible_type(string)
• void add_msg(cstring message)
  • Write a message to the game's standard message window.
• bool one_in(int)
• void remove_item(int, int, item)
• it_gun get_gun_type(string)
• void popup(cstring)
• ter_t get_terrain_type(int)
• void revive_corpse(int x, int y, int index)
  • Revive the corpse at the specified location. The index parameter specifies the index within the item stack that the corpse is located at.

mongroup

Functions

• void inc_interest(int)
• void set_interest(int)
• void dec_interest(int)
• void set_target(int, int)

Attributes

• int population
• int posz
• int radius
• bool diffuse
• int posy
• bool horde
• int posx
• string type
• bool dying
• int ty read-only
• int tx read-only

item

Functions

• string tname()
• bool made_of(string)

Attributes

• int charges

uimenu

Functions

• void show()
• void query(bool)
• void addentry(string)

Attributes

• string title
• int selected read-only

it_gunmod

Attributes

• int loudness
• int recoil
• string newtype
• int damage
• int burst
• string location
• int clip
• int dispersion

point

Attributes

• int x
• int y

mtype

Functions

• bool in_species(string)
• bool in_category(string)

Attributes

• int speed
• int armor_cut
• int melee_cut
• int melee_sides
• int morale
• int melee_dice
• int armor_bash
• int agro
• int melee_skill
• int item_chance
• int difficulty
• int sk_dodge

map

Functions

• int ter(int, int)
• void ter_iset(int, int, int)
• void fill_background(string)
• void line_furn(string, int, int, int, int)
• void furn_set(int, int, string)
• void place_items(string, int, int, int, int, int, bool, int)
• void rough_circle(string, int, int, int)
• void square_ter(string, int, int, int, int)
• void square_furn(string, int, int, int, int)
• void ter_set(int, int, string)
• void line_ter(string, int, int, int, int)
• int furn(int, int)

monster

Functions

• int posy()
• int attack_at(int, int)
• int posx()
• string name()
• void make_friendly()

Attributes

• int moves
• int hp
• int friendly

ter_t

Attributes

• int movecost read-only
• string name read-only
• int loadid read-only
• string id read-only

it_gun

Attributes

• int recoil
• int durability
• int clip
• int pierce
• int range
• int dmg_bonus
• int burst
• string ammo
• int dispersion

Creature

Functions

• int get_speed()

player

Functions

• int volume_capacity()
• int weight_carried()
• void rem_disease(string)
• bool has_disease(string)
• int morale_level()
• int volume_carried()
• void add_disease(string, int, int, int)
• int weight_capacity(bool)
• bool is_npc()

Attributes

• int per_max
• int str_cur
• int int_max
• int posy read-only
  • The y position of the player in the reality bubble.
• int posx read-only
  • The x position of the player in the reality bubble.
• int dex_cur
• int per_cur
• int health read-only
• int hunger
• string name read-only
• int int_cur
• int dex_max
• int stim
• int str_max
• int thirst
• bool male read-only
• int fatigue

it_comest

Attributes

• int nutr
• int fun
• int charges
• int addict
• int stim
• int quench
• int brewtime
• int spoils
• int healthy

overmap

Functions

• int get_right_border()
• int get_top_border()
• int get_left_border()
• int get_bottom_border()

itype

Attributes

• int price
• string name
• int volume
• int melee_dam
• int melee_cut
• int m_to_hit
• int weight
• int stack_size
• string m1
• string description
• string m2

it_tool

Attributes

• int turns_per_charge
• int charges_per_use
• int def_charges
• string ammo
• int max_charges