LuaLibraries.wiki
author almikes@aol.com
Thu, 22 Jan 2015 14:53:05 +0000
changeset 546 507162614281
parent 532 8b7a9c032722
child 587 8105e95297e3
permissions -rw-r--r--
Rewritten the security section. I hope it is slightly better now.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     1
#summary Libraries for writing Lua scripts in Hedgewars.
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     2
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     3
= Introduction =
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     4
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     5
Libraries in scripts in Hedgewars are lua files that are used by many scripts to add a common function, as an example the Locale library that allows scripts to translate text. The variables in these files are not exposed to the script using it but all the functions can be called.
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     6
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     7
To use a library you only need to add one row at the top of the script:
501
04b4b463bf33 Add HedgewarsScriptLoad, warn about the old and rusty loadfile function.
almikes@aol.com
parents: 500
diff changeset
     8
<code language="lua">HedgewarsScriptLoad("Scripts/<Library Name>.lua")</code>
04b4b463bf33 Add HedgewarsScriptLoad, warn about the old and rusty loadfile function.
almikes@aol.com
parents: 500
diff changeset
     9
Where `<Library Name>` is replaced by the name.
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    10
501
04b4b463bf33 Add HedgewarsScriptLoad, warn about the old and rusty loadfile function.
almikes@aol.com
parents: 500
diff changeset
    11
*Note*: In old scripts, you will find this line instead:
04b4b463bf33 Add HedgewarsScriptLoad, warn about the old and rusty loadfile function.
almikes@aol.com
parents: 500
diff changeset
    12
<code language="lua">loadfile(GetDataPath() .. "Scripts/<Library Name>.lua")()</code>
525
b051cfd45c23 Edited wiki page LuaLibraries through web user interface.
almikes@aol.com
parents: 501
diff changeset
    13
This does not work with new Hedgewars versions anymore and causes the script to break. You have to replace it with `HedgewarsScriptLoad`. *Calls to `loadfile` are one of the most common reasons why old scripts do not work in recent Hedgewars versions.*
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    14
527
908428bf4a03 Add TOC
almikes@aol.com
parents: 526
diff changeset
    15
= Table of Contents =
908428bf4a03 Add TOC
almikes@aol.com
parents: 526
diff changeset
    16
908428bf4a03 Add TOC
almikes@aol.com
parents: 526
diff changeset
    17
<wiki:toc max_depth="2" />
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    18
= Locale =
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    19
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    20
This library allows you to translate string and should be used whenever a script has text. It loads the appropriate locale file and check automatically.
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    21
529
f3e3229af8bf Replaced old lang function with loc.
almikes@aol.com
parents: 528
diff changeset
    22
=== `loc(text)` ===
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    23
529
f3e3229af8bf Replaced old lang function with loc.
almikes@aol.com
parents: 528
diff changeset
    24
Returns the localised string of `text` or, if it is not found, it returns `text`.
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    25
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    26
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    27
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    28
= Utils =
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    29
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    30
This library includes miscellaneous functions to use, they are all independent of each other and can be used everywhere.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    31
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    32
=== `gearIsInBox(gear, x, y, w, h)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    33
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    34
Returns whether the gear is inside (centre point of the gear) a box with x and y as the top left corner and having the width and height of w and h respectively.
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    35
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    36
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    37
=== `gearIsInCircle(gear, x, y, r, useRadius)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    38
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    39
Returns whether the gear is inside a circle with x and y being the centre point and r being the radius of the circle. The boolean useRadius determine whether only the centre point of the gear will be used or the radius of the gear will be checked too.
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    40
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    41
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    42
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    43
= Tracker =
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    44
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    45
This library is intended to be used if you need to keep track of gears. It can also keep track of teams and clans and as an extra functionality it can also store variables for a gear, team or clan.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    46
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    47
To set it up you need to add some hooks in different events. The hooks `trackGear` and `trackDeletion` to `onGearAdd` and `onGearDelete` respectively. It is strongly recommended to only track the gears you are interested in as, especially with snow on, the amount of gears can go up high and that will slow down the script. To keep track of teams you need to keep track of `gtHedgehog` and `gtResurrector` (if resurrection might be used) and add `trackTeams` to `onGameStart`.
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    48
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    49
If you want to call a function on a couple of gears you will have to call the “`runOn`” functions. To these you will pass the function you want to be run as a variable to the function. The function must take a gear as a parameter, nothing else, for example:
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    50
<code language="lua">function killall(gear)
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    51
    SetHealth(gear, 0)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    52
end
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    53
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    54
function onGearDelete(gear)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    55
    if GetGearType(gear) == gtTarget then
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    56
        runOnHogs(killall)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    57
    end
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    58
end</code>
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    59
This will kill all hogs if a target is destroyed.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    60
103
023ff3c709ac Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 86
diff changeset
    61
To see a commented example of the tracker in use by a script you can look at
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    62
[http://code.google.com/p/hedgewars/source/browse/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons].
103
023ff3c709ac Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 86
diff changeset
    63
86
98504fb076c3 Spelling correction
Cairo@chusym.com
parents: 85
diff changeset
    64
== Tracking functions ==
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    65
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    66
=== `trackGear(gear)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    67
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    68
Will keep track of the gear.
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    69
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    70
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    71
=== `trackDeletion(gear)` ===
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    72
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    73
Will stop keeping track of the gear (gears not tracked will be ignored).
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    74
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    75
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    76
=== `trackTeams()` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    77
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    78
Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this).
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    79
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    80
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    81
== “`runOn`” functions ==
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    82
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    83
=== `runOnGears(func)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    84
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    85
Runs the function `func` on all gears.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    86
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    87
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    88
=== `runOnHogs(func)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    89
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    90
Runs the function `func` on all hedgehogs.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    91
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    92
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    93
=== `runOnHogsInTeam(func, team)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    94
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    95
Runs the function `func` on all hedgehogs in the specified team.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    96
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    97
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    98
=== runOnHogsInOtherTeams(func, team) ===
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    99
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   100
Runs the function `func` on all hedgehogs but those in the specified team.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   101
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   102
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   103
=== `runOnHogsInClan(func, clan)` ===
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   104
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   105
Runs the function `func` on all hedgehogs in the specified clan.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   106
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   107
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   108
=== `runOnHogsInOtherClans(func, clan)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   109
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   110
Runs the function `func` on all hedgehogs but those in the specified clan.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   111
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   112
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   113
== Variable functions ==
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   114
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   115
_To be continued …_
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   116
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   117
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   118
= Animate =
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   119
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   120
This library provides functions that aid cinematic/cut-scene creation and functions for handling events. 
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   121
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   122
In order to use its full potential, the following lines need to be at the beginning of `onGameTick`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   123
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   124
<code language="lua">function onGameTick()
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   125
    AnimUnWait()
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   126
    if ShowAnimation() == false then
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   127
        return
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   128
    end
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   129
    ExecuteAfterAnimations()
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   130
    CheckEvents()
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   131
end</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   132
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   133
Also, `AnimInit()` needs to be called in `onGameInit()`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   134
Each of these functions will be explained below.
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   135
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   136
== Cinematic Handling ==
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   137
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   138
=== `ShowAnimation()` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   139
Performs the current action in the cinematic and returns `true` if finished, otherwise `false`. It needs to be used in `onGameTick`. Cut-scenes need to be added with `AddAnim(steps)`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   140
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   141
=== `AddAnim(steps)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   142
Adds `steps` to the array of animations, where `steps` is a table with numbers as keys and elements of the following form. Each step is a table having the following keys: `func`, `args`, `swh`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   143
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   144
  * `func` is the function to be executed. It can be any function that returns false when it needs to be called again in following game ticks (e.g. `AnimMove`). It can be one of the cinematic functions. 
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   145
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   146
  * `args` is a table containing the arguments that need to be passed to the function given
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   147
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   148
  * `swh` is an optional boolean value that defaults to `true` and denotes whether the current hedgehog should be switched to the hog given as argument.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   149
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   150
<code language="lua">cinem = {
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   151
    {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}},
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   152
    {func = AnimMove, args = {myhog, "Left", 2000, 0}},
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   153
    {func = AddCaption, swh = false, args = {"But he found no more snails..."}}
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   154
    }
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   155
AddAnim(cinem)</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   156
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   157
=== `RemoveAnim(steps)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   158
Removes `steps` from the animations array.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   159
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   160
=== `AddSkipFunction(anim, func, args)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   161
Adds `func` to the array of functions used to skip animations, associating it with `anim`. When the animation is skipped (see below), the function is called with `args` as arguments.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   162
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   163
<code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   164
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   165
=== `RemoveSkipFunction(anim)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   166
Removes the skip function associated with `anim`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   167
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   168
=== `SetAnimSkip(bool)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   169
Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   170
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   171
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   172
<code language="lua">function onPrecise()
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   173
    if AnimInProgress() then
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   174
        SetAnimSkip(true)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   175
    end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   176
end</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   177
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   178
=== `AnimInProgress()` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   179
Returns `true` if a cinematic is currently taking place, `false` otherwise.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   180
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   181
=== `ExecuteAfterAnimations()` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   182
Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. The best location for this function call is in `onGameTick`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   183
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   184
=== `AddFunction(element)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   185
Adds `element` to the functions array that are to be called after the cinematic. `element` is a table with the keys: `func`, `args`.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   186
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   187
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   188
<code language="lua">AddFunction({func = AfterCinem, args = {2}})</code>
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   189
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   190
=== `RemoveFunction()` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   191
Removes the first function from the aforementioned list.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   192
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   193
=== `AnimInit()` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   194
Initializes variables used by the other functions. Needs to be called in `onGameInit`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   195
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   196
=== !AnimUnWait() ===
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   197
Decreases the wait time used by cinematics. It is best called in `onGameTick`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   198
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   199
== Cinematic Functions ==
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   200
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   201
=== `AnimSwitchHog(gear)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   202
Switches to `gear` and follows it.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   203
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   204
=== `AnimWait(gear, time)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   205
Increases the wait time by `time`. `gear` is just for compatibility with `ShowAnimation`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   206
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   207
=== `AnimSay(gear, text, manner, time` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   208
Calls `HogSay` with the first three arguments and increses the wait time by `time`.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   209
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   210
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   211
<code language="lua">cinem = {
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   212
    {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}},
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   213
    {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}}
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   214
   }</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   215
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   216
=== `AnimSound(gear, sound, time)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   217
Plays the sound `sound` and increases the wait time by `time`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   218
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   219
=== `AnimTurn(hog, dir)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   220
Makes `hog` face in direction `dir`, where `dir` equals either `"Right"` or `"Left"`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   221
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   222
=== `AnimMove(hog, dir, x, y)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   223
Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   224
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   225
=== `AnimJump(hog, jumpType)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   226
Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   227
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   228
=== `AnimSetGearPosition(gear, x, y, fall)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   229
Sets the position of `gear` to (`x`, `y`). If the optional argument `fall` does not equal `false` then the gear is given a small falling velocity in order to get around exact positioning.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   230
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   231
=== `AnimDisappear(gear, x, y)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   232
Teleports the gear to (`x`, `y`), adding some effects at the previous position and sounds. Doesn’t follow the gear.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   233
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   234
=== `AnimOutOfNowhere(gear, x, y)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   235
Teleports the gear to (`x`, `y`), adding effects and sounds at the final position. Follows gear.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   236
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   237
=== `AnimTeleportGear(gear, x, y)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   238
Teleports the gear to (`x`, `y`), adding effects and sounds both at the starting position and the final position. Follows gear.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   239
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   240
=== `AnimVisualGear(gear, x, y, vgType, state, critical, follow)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   241
Calls `AddVisualGear` with arguments second to sixth. If the optional argument `follow` equals `true` then the gear is followed. `gear` is for compatibility only.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   242
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   243
=== `AnimCaption(gear, text, time)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   244
Adds `text` as caption and increases wait time by `time`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   245
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   246
=== `AnimCustomFunction(gear, func, args)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   247
Calls the function `func` with `args` as arguments. This function is useful, for instance, when the cinematic uses the position of a gear at the moment of execution. If `func` needs to be called in following game ticks then it should return false.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   248
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   249
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   250
<code language="lua">function NeedToTurn(hog1, hog2)
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   251
   if GetX(hog1) < GetX(hog2) then
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   252
      HogTurnLeft(hog1, false)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   253
      HogTurnLeft(hog2, true)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   254
   else
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   255
      HogTurnLeft(hog2, false)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   256
      HogTurnLeft(hog1, true)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   257
   end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   258
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   259
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   260
cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   261
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   262
=== `AnimInsertStepNext(step)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   263
Inserts `step` after the current step (read: action) in the cinematic array. Useful when an action depends on variables (e.g. positoins). It can be used mostly with `AnimCustomFunction`. Note: In case of multiple consecutive calls, steps need to be added in reverse order.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   264
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   265
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   266
<code language="lua">function BlowHog(deadHog)
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   267
  AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false}) 
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   268
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   269
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   270
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   271
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   272
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   273
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   274
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   275
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   276
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   277
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   278
cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   279
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   280
== Event Handling ==
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   281
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   282
Events are pairs of functions that are used to check for various conditions. One of them is for verification and, if it returns `true`, the second function is called.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   283
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   284
=== `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   285
Adds the functions `condFunc` and `doFunc` to the events list. They get called with the respective args (`condArgs` and `doArgs`). `condFunc` will get called in every game tick until it returns `true` or is removed. Once it returns `true`, `doFunc` is called and they are or are not removed from the list, depending on `evType` (`0` for removal, `1` for keeping). An `evType` of `1` is useful for repeating actions (e.g. every time a hog gets damaged, do something).
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   286
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   287
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   288
<code language="lua">function CheckPos()
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   289
   return GetX(myHog) > 1500
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   290
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   291
function CheckAmmo()
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   292
   return GetAmmoCount(myHog, amGrenade) == 0
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   293
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   294
function DoPos()
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   295
   ShowMission("Scooter", "Mover", "Nice Work", 0, 0)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   296
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   297
function DoAmmo()
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   298
   AddAmmo(myHog, amGrenade, 5)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   299
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   300
AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   301
AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   302
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   303
=== `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   304
Does the same as `AddEvent`, but first checks if the event is already in the list so that it isn’t added twice.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   305
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   306
=== `RemoveEventFunc(cFunc, cArgs)` ===
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   307
Removes the event or events that have `cFunc` as the condition checking function. If `cArgs` does not equal `nil` then only those events get removed that have `cArgs` as arguments for `cFunc`, too.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   308
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   309
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   310
<code language="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs)
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   311
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   312
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   313
AddEvent(condFunc2, condArgs1, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   314
AddEvent(condFunc2, condArgs2, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   315
RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   316
RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   317
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   318
=== `CheckEvents` ===
530
9d1b7bddb6d2 Remove bad blockquoute element.
almikes@aol.com
parents: 529
diff changeset
   319
Verifies all the condition functions in the events list and calls the respective ‘action’ functions if the conditions are met. If the `evType` of a completed event equals `0` then it is removed from the list. This function is best placed in `onGameTick`.
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   320
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   321
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   322
= Params =
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   323
The Params library is a small library introduced in 0.9.21. It provides a function to parse the parameter string `ScriptParam` and it is intended to simplify using this string.
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   324
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   325
This library requires the parameter string to be in a certain format. It must be a comma-seperated list of kev-value pairs in the `key=value` format. Examples:
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   326
531
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   327
<code>speed=1</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   328
<code>health=100, ammo=5</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   329
<code>param1=hello, param2=whatever, param3=5325.4</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   330
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   331
Using this library is by no means neccessary, you could use practically whatever syntax you wish if you write your own code for parsing.
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   332
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   333
=== `parseParams()` ===
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   334
Parses `ScriptParam` and writes the result into the global table `params`. The table will follow the `key=value` pattern. Both keys and pairs are stored as string.
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   335
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   336
==== Example  ====
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   337
<code language="lua">
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   338
function onParameters()
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   339
    parseParams()
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   340
    if params["myparam1"] == "hello" then
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   341
        WriteLnToConsole("Hello World!")
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   342
    end
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   343
end</code>
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   344
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   345
If the key-value pair `myparam1=hello` is present, this script writes “Hello World!” in the console. All these inputs would trigger the event:
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   346
531
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   347
<code>myparam1=hello</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   348
<code>myparam2=whatever, myparam1=hello</code>
532
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   349
<code>g=4, f=56, m=56, myparam1=hello</code>
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   350
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   351
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   352
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   353
= !TargetPractice =
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   354
Starting with 0.9.21, this library provides a function to create an entire target practice mission which follows some basic properties.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   355
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   356
Here is a brief description of the generated missions:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   357
 * The player will get a team with a single hedgehog.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   358
 * The team gets a single predefined weapon infinitely times.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   359
 * A fixed sequence of targets will spawn at predefined positions.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   360
 * When a target has been destroyed, the next target of the target sequence appears
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   361
 * The mission ends successfully when all targets have been destroyed
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   362
 * The mission ends unsuccessfully when the time runs out or the hedgehog dies
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   363
 * When the mission ends, a score is awarded, based on the performance (hit targets, accuracy and remaining time) of the hedgehog. When not all targets are hit, there will be no accuracy and time bonuses.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   364
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   365
If you want to create a more sophisticated training mission, use your own code instead. The main motivation to write this library was to reduce redundancy in existing target practice missions.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   366
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   367
Thos library also loads the Locale library for its own purposes. If you use !TargetPractice, you do not have to explicitly load Locale anymore.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   368
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   369
=== `TargetPracticeMission(params)` ===
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   370
This function sets up the *entire* training mission and needs one argument: `params`.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   371
`params` is a table containing fields which describe the training mission.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   372
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   373
There are mandatory and optional fields. The optional fields have default values.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   374
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   375
Mandatory fields:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   376
|| *Field name* || *Description* ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   377
|| `missionTitle` || The name of the mission ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   378
|| `map` || The name of the image map to be used ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   379
|| `theme` || The name of the theme (can be background theme, too) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   380
|| `time` || The time limit in milliseconds ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   381
|| `ammoType` || The [AmmoTypes ammo type] of the weapon to be used ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   382
|| `gearType` || The [GearTypes gear type] of the gear which is fired by the weapon (used to count shots) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   383
|| `targets` || The coordinates of where the targets will be spawned. It is a table containing tables containing coordinates of format `{ x=value, y=value }`. The targets will be spawned in the same order as specified the coordinate tables appear. There must be at least 1 target. ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   384
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   385
Optional fields:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   386
|| *Field name* || *Description * ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   387
|| `wind` || The initial wind (`-100` to `100`) (default: `0` (no wind)) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   388
|| `solidLand` || Weather the terrain is indestructible (default: `false`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   389
|| `artillery` || If `true`, the hog can’t move (default: `false`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   390
|| `hogHat` || Hat of the hedgehog (default: `"NoHat"`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   391
|| `hogName` || Name of the hedgehog (default: `"Trainee"`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   392
|| `teamName` || Name of the hedgehog’s team (default: `"Training Team"`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   393
|| `teamGrave` || Name of the hedgehog’s grave ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   394
|| `clanColor` || Color of the (only) clan (default: `0xFF0204`, which is a red tone) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   395
|| `goalText` || A short string explaining the goal of the mission (default: `"Destroy all targets within the time!"`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   396
|| `shootText`: || A string which says how many times the player shot, “`%d`” is replaced by the number of shots. (default: `"You have shot %d times."`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   397
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   398
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   399
==== Example ====
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   400
Below is the complete source code of the mission “Target Practice: Cluster Bomb”:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   401
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   402
<code language="lua">HedgewarsScriptLoad("/Scripts/TargetPractice.lua")
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   403
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   404
local params = {
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   405
	ammoType = amClusterBomb,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   406
	gearType = gtClusterBomb,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   407
	missionTitle = "Cluster Bomb Training",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   408
	solidLand = false,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   409
	map = "Trash",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   410
	theme = "Golf",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   411
	hog_x = 756,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   412
	hog_y = 370,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   413
	hogName = loc("Private Nolak"),
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   414
	hogHat = "war_desertgrenadier1",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   415
	teamName = loc("The Hogies"),
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   416
	targets = {
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   417
		{ x = 628, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   418
		{ x = 891, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   419
		{ x = 1309, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   420
		{ x = 1128, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   421
		{ x = 410, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   422
		{ x = 1564, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   423
		{ x = 1248, y = 476 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   424
		{ x = 169, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   425
		{ x = 1720, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   426
		{ x = 1441, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   427
		{ x = 599, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   428
		{ x = 1638, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   429
	},
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   430
	time = 180000,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   431
	shootText = loc("You have thrown %d cluster bombs."),
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   432
}
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   433
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   434
TargetPracticeMission(params)</code>