LuaGuide.wiki
author almikes@aol.com
Wed, 03 Dec 2014 05:43:29 +0000
changeset 415 70961d4eef05
parent 37 acd631a56390
child 592 2a5ecd20bf16
permissions -rw-r--r--
Fixed misleading descriptions of GetState and SetState (use of bitmasks were not mentioned). Added commented examples.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
29
19a3182cac9d Created wiki page through web user interface.
henrik.rostedt
parents:
diff changeset
     1
#summary Guide to writing Lua scripts in Hedgewars.
19a3182cac9d Created wiki page through web user interface.
henrik.rostedt
parents:
diff changeset
     2
31
e713a5d2a7f9 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 30
diff changeset
     3
= Under Construction =
e713a5d2a7f9 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 30
diff changeset
     4
30
43e5101de029 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 29
diff changeset
     5
This is both an introduction to Lua scripting in Hedgewars and a guide for more advanced control over the game and gears.
43e5101de029 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 29
diff changeset
     6
43e5101de029 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 29
diff changeset
     7
== What is a Lua script ==
29
19a3182cac9d Created wiki page through web user interface.
henrik.rostedt
parents:
diff changeset
     8
30
43e5101de029 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 29
diff changeset
     9
A Lua script is used to make the game behave different by giving the Hedgewars engine different command. The script gets called by the engine on different events and the script tells the engine what to do.
43e5101de029 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 29
diff changeset
    10
32
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    11
Missions and Training are the parts of Hedgewars that are scripted. Try them out and get a feel of what scripted maps is.
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    12
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    13
== The basic structure ==
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    14
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    15
Dependent on what type of script you want to write the requirements are a bit different, but before we go into that we must first create the .lua file.
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    16
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    17
If you want to make a Mission for multi player you create a map and create a new file map.lua in the map's folder.
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    18
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    19
If you want to make a Training or Campaign (coming) then you create a new .lua file in the appropriate folder under Missions in the Data folder.
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    20
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    21
The .lua file should be structured like this:
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    22
{{{
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    23
function onGameInit()
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    24
end
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    25
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    26
function onAmmoStoreInit()
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    27
end
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    28
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    29
function onGameStart()
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    30
end
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    31
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    32
function onGameTick()
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    33
end
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    34
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    35
function onGearAdd(gear)
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    36
end
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    37
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    38
function onGearDelete(gear)
5f66adfa478c Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 31
diff changeset
    39
end
35
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    40
}}}
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    41
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    42
These are event handlers and are called on different events by the engine. Now lets look at the initiation events.
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    43
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    44
== The initiation events ==
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    45
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    46
The two most important event handlers are onGameInit and onAmmoStoreInit. They are used instead of loading a game scheme and weapon scheme and in Campaign or Missions onGameInit is also used to add teams and hogs.
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    47
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    48
First we have onGameInit. On this event we should add all game modifiers and team setup. If you are making a Mission you only need to specify the things you want to change on this event, everything not changed will be set to default. The available game modifiers can be found here: http://code.google.com/p/hedgewars/wiki/LuaAPI#onGameInit()
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    49
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    50
An example of setting up barrel mayhem in a mission:
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    51
{{{
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    52
function onGameInit()
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    53
    GameFlags = gfRandomOrder + gfSharedAmmo
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    54
    TurnTime = 30000
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    55
    CaseFreq = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    56
    MinesNum = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    57
    MinesTime = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    58
    Explosives = 40
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    59
end
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    60
}}}
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    61
37
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    62
If you are doing a Training or Campaign you should also set Seed, Map and Theme. But you must also add teams and hogs on this event. This is done by using !AddTeam and !AddHog. An example of adding one team with one hog (these functions may only be used here):
35
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    63
{{{
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    64
AddTeam("Team", 14483456, "Simple", "Island", "Default")
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    65
AddHog("Hedgehog", 0, 1, "NoHat")
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    66
}}}
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    67
To be able to play you must add another team and hog that should have another team color (this team has 14483456) or if you only want one team add the game flag gfOneClanMode. Look in the LuaAPI to see what the other parameters of !AddTeam and !AddHog is.
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    68
36
f66efe81d8c0 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 35
diff changeset
    69
In onAmmoStoreInit you set what weapons is available in the game. For every weapon run [http://code.google.com/p/hedgewars/wiki/LuaAPI#SetAmmo_(ammoType,_count,_probability,_delay,_numberInCrate) SetAmmo].
f66efe81d8c0 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 35
diff changeset
    70
This is used to set both starting weapons and weapons found in crates.
35
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    71
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    72
Here is an example of initiation of a Training map:
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    73
{{{
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    74
function onGameInit()
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    75
    Seed = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    76
    GameFlags = gfMultiWeapon + gfOneClanMode
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    77
    TurnTime = 25000
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    78
    CaseFreq = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    79
    MinesNum = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    80
    Explosives = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    81
    Delay = 0
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    82
    Map = "Mushrooms"
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    83
    Theme = "Nature"
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    84
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    85
    AddTeam("Team", 14483456, "Simple", "Island", "Default")
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    86
    AddHog("Hedgehog", 0, 1, "NoHat")
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    87
end
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    88
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    89
function onAmmoStoreInit()
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    90
    SetAmmo(amShotgun, 9, 0, 0, 0)
532bb2509f0b Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 32
diff changeset
    91
end
37
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    92
}}}
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    93
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    94
== Gears everywhere ==
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    95
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    96
Mostly everything in Hedgewars are made op of gears: grenades, bazooka shells, and cake just to name a few. But these are just the visible gears, the whip's affect and wind change are also gears. But for now we will focus on the more concrete ones.
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    97
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    98
The hogs are gears too and when you shoot with bazooka the bazooka shell will be created and explode when it hits the ground. When the shell is created the onGearAdd event is called and the gear parameter will be the bazooka. And when it hits the ground, before the gear has been deleted onGearDelete is invoked with the shell as parameter, after that it is removed.
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
    99
acd631a56390 Edited wiki page LuaGuide through web user interface.
henrik.rostedt
parents: 36
diff changeset
   100
The last event handler onGameTick is called every game tick, that is every millisecond which is a thousand times a second. These three event handlers are the core in the script and where most of the code goes.