LuaLibraries.wiki
author nemo
Wed, 15 Nov 2017 17:08:55 -0500
changeset 1109 6c9c95f51638
parent 1053 bb4cfa5b41a0
child 1234 60346a2ffb4c
permissions -rw-r--r--
remove the annoying ????
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
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
     3
= Lua libraries documentation =
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
     4
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
     5
== Introduction ==
84
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
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
     8
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     9
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
    10
<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
    11
Where `<Library Name>` is replaced by the name.
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    12
501
04b4b463bf33 Add HedgewarsScriptLoad, warn about the old and rusty loadfile function.
almikes@aol.com
parents: 500
diff changeset
    13
*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
    14
<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
    15
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
    16
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    17
== Table of Contents ==
527
908428bf4a03 Add TOC
almikes@aol.com
parents: 526
diff changeset
    18
908428bf4a03 Add TOC
almikes@aol.com
parents: 526
diff changeset
    19
<wiki:toc max_depth="2" />
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    20
== Locale ==
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    21
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    22
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
    23
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    24
==== `loc(text)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    25
529
f3e3229af8bf Replaced old lang function with loc.
almikes@aol.com
parents: 528
diff changeset
    26
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
    27
867
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    28
In order for your text to be taken by the string collection tools (so the string becomes available for translation), you have to follow a few simple syntax rules:
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    29
867
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    30
 * `text` _must_ be entirely a literal string
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    31
 * The text _must_ be enclosed in double quotes
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    32
 * You _must_ use the exact character sequence “`loc("`” to initiate the text, no spaces in between are permitted
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    33
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    34
Valid example:
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    35
<code language="lua">
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    36
AddCaption(loc("Hello World"))  -- Displays “Hello World” translated into your language
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    37
</code>
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    38
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    39
These are all _incorrect_ usages of the `loc` function:
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    40
<code language="lua">
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    41
local l
868
0b400b3e05cc LuaLibraries: fix comment
Wuzzy
parents: 867
diff changeset
    42
l = loc( "Hello World")    -- Contains space
867
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    43
l = loc ("Hello World")    -- Contains space
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    44
l = loc('Hello World')     -- Not double quotes
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    45
local str = "Hello World"
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    46
l = loc(str)   -- Not a literal string
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    47
l = loc(str .. ", how are you?")   -- Only partially a literal string
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    48
</code>
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    49
30cc2f85c5e7 LuaLibraries: Explain proper usage of loc()
Wuzzy
parents: 798
diff changeset
    50
Note these examples do _not_ violate Lua syntax, it is in your responsibility to follow the syntax rules listed above.
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    51
933
404dfa2f8a23 LuaLibraries: Add loc_noop
Wuzzy
parents: 868
diff changeset
    52
==== `loc_noop(text)` (0.9.23) ====
404dfa2f8a23 LuaLibraries: Add loc_noop
Wuzzy
parents: 868
diff changeset
    53
Just returns `text`. This function has the same syntax as `loc`. Like for `loc`, the text will be collected to be made available for translation.
404dfa2f8a23 LuaLibraries: Add loc_noop
Wuzzy
parents: 868
diff changeset
    54
934
dd382ad56f7e LuaLibraries: fix backtick syntax
Wuzzy
parents: 933
diff changeset
    55
You can use this function if you want a make a string available for translation but don't want the string to be translated right now. This can come in handy if you need to store strings in variables and want do something like `loc(variable_name)` later.
933
404dfa2f8a23 LuaLibraries: Add loc_noop
Wuzzy
parents: 868
diff changeset
    56
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    57
== Utils ==
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    58
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    59
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
    60
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    61
==== `gearIsInBox(gear, x, y, w, h)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    62
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    63
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
    64
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    65
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    66
==== `gearIsInCircle(gear, x, y, r, useRadius)` ====
528
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
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
    69
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    70
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    71
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    72
== Tracker ==
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    73
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    74
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
    75
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    76
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
    77
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    78
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
    79
<code language="lua">function killall(gear)
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    80
    SetHealth(gear, 0)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    81
end
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    82
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    83
function onGearDelete(gear)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    84
    if GetGearType(gear) == gtTarget then
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    85
        runOnHogs(killall)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    86
    end
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    87
end</code>
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    88
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
    89
103
023ff3c709ac Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 86
diff changeset
    90
To see a commented example of the tracker in use by a script you can look at
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 742
diff changeset
    91
[https://hg.hedgewars.org/hedgewars/file/default/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
    92
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    93
=== Tracking functions ===
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    94
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
    95
==== `trackGear(gear)` ====
528
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
Will keep track of the gear.
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    98
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
    99
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   100
==== `trackDeletion(gear)` ====
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   101
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   102
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
   103
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   104
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   105
==== `trackTeams()` ====
528
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
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
   108
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   109
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   110
=== “`runOn`” functions ===
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   111
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   112
==== `runOnGears(func)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   113
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   114
Runs the function `func` on all gears.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   115
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   116
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   117
==== `runOnHogs(func)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   118
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   119
Runs the function `func` on all hedgehogs.
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   120
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   121
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   122
==== `runOnHogsInTeam(func, team)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   123
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   124
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
   125
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   126
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   127
==== runOnHogsInOtherTeams(func, team) ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   128
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   129
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
   130
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   131
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   132
==== `runOnHogsInClan(func, clan)` ====
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   133
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   134
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
   135
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   136
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   137
==== `runOnHogsInOtherClans(func, clan)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   138
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   139
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
   140
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   141
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   142
=== Variable functions ===
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   143
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   144
_To be continued …_
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   145
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   146
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   147
== Animate ==
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   148
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   149
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
   150
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   151
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
   152
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   153
<code language="lua">function onGameTick()
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   154
    AnimUnWait()
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   155
    if ShowAnimation() == false then
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   156
        return
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   157
    end
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   158
    ExecuteAfterAnimations()
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   159
    CheckEvents()
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   160
end</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   161
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   162
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
   163
Each of these functions will be explained below.
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   164
1053
bb4cfa5b41a0 LuaLibraries: AnimSetInputMask
Wuzzy
parents: 939
diff changeset
   165
Note: The Animate library will direclty overwrite the input mask with `SetInputMask`. If you already use this function in your script, it might lead to conflicts. Use `AnimSetInputMask` to set the input mask in a manner that is compatible with the Animate library.
935
97361ff66b78 LuaLibraries: Animate: Warn about SetInputMask
Wuzzy
parents: 934
diff changeset
   166
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   167
=== Cinematic handling ===
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   168
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   169
==== `ShowAnimation()` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   170
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
   171
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   172
==== `AddAnim(steps)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   173
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
   174
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   175
  * `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
   176
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   177
  * `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
   178
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   179
  * `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
   180
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   181
<code language="lua">cinem = {
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   182
    {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
   183
    {func = AnimMove, args = {myhog, "Left", 2000, 0}},
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   184
    {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
   185
    }
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   186
AddAnim(cinem)</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   187
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   188
==== `RemoveAnim(steps)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   189
Removes `steps` from the animations array.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   190
938
aa5d58152f50 LuaLibraries: Fix hierarchy of AddSkipFunction
Wuzzy
parents: 935
diff changeset
   191
==== `AddSkipFunction(anim, func, args)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   192
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
   193
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   194
<code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   195
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   196
==== `RemoveSkipFunction(anim)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   197
Removes the skip function associated with `anim`.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   198
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   199
==== `SetAnimSkip(bool)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   200
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
   201
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   202
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   203
<code language="lua">function onPrecise()
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   204
    if AnimInProgress() then
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   205
        SetAnimSkip(true)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   206
    end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   207
end</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   208
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   209
==== `AnimInProgress()` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   210
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
   211
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   212
==== `ExecuteAfterAnimations()` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   213
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
   214
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   215
==== `AddFunction(element)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   216
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
   217
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   218
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   219
<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
   220
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   221
==== `RemoveFunction()` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   222
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
   223
939
39ed0b23ef49 LuaLibraries: Add startAnimating
Wuzzy
parents: 938
diff changeset
   224
==== `AnimInit([startAnimating])` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   225
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
   226
939
39ed0b23ef49 LuaLibraries: Add startAnimating
Wuzzy
parents: 938
diff changeset
   227
Since 0.9.23, an optional convenience parameter `startAnimating` is available; if set to `true`, the game will start in “animation” mode which enables cinematic mode and disables all controls except precise for skipping. This is useful if you want to indicate that an animation will be played right at the start and the player must not be allowed to use any controls before the animation is over. If you set this parameter to `true`, you also *must* play at least one animation after this, otherwise the game will be stuck.
39ed0b23ef49 LuaLibraries: Add startAnimating
Wuzzy
parents: 938
diff changeset
   228
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   229
==== !AnimUnWait() ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   230
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
   231
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   232
=== Cinematic functions ===
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   233
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   234
==== `AnimSwitchHog(gear)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   235
Switches to `gear` and follows it.
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   236
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   237
==== `AnimWait(gear, time)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   238
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
   239
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   240
==== `AnimSay(gear, text, manner, time` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   241
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
   242
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   243
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   244
<code language="lua">cinem = {
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   245
    {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
   246
    {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
   247
   }</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   248
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   249
==== `AnimSound(gear, sound, time)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   250
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
   251
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   252
==== `AnimTurn(hog, dir)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   253
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
   254
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   255
==== `AnimMove(hog, dir, x, y)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   256
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
   257
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   258
==== `AnimJump(hog, jumpType)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   259
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
   260
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   261
==== `AnimSetGearPosition(gear, x, y, fall)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   262
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
   263
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   264
==== `AnimDisappear(gear, x, y)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   265
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
   266
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   267
==== `AnimOutOfNowhere(gear, x, y)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   268
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
   269
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   270
==== `AnimTeleportGear(gear, x, y)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   271
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
   272
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   273
==== `AnimVisualGear(gear, x, y, vgType, state, critical, follow)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   274
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
   275
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   276
==== `AnimCaption(gear, text, time)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   277
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
   278
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   279
==== `AnimCustomFunction(gear, func, args)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   280
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
   281
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   282
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   283
<code language="lua">function NeedToTurn(hog1, hog2)
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   284
   if GetX(hog1) < GetX(hog2) then
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   285
      HogTurnLeft(hog1, false)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   286
      HogTurnLeft(hog2, true)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   287
   else
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   288
      HogTurnLeft(hog2, false)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   289
      HogTurnLeft(hog1, true)
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
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   292
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   293
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
   294
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   295
==== `AnimInsertStepNext(step)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   296
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
   297
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   298
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   299
<code language="lua">function BlowHog(deadHog)
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   300
  AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false}) 
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   301
  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
   302
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   303
  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
   304
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   305
  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
   306
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   307
  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
   308
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   309
  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
   310
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   311
cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   312
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   313
=== Event handling ===
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   314
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   315
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
   316
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   317
==== `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   318
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
   319
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   320
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   321
<code language="lua">function CheckPos()
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   322
   return GetX(myHog) > 1500
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   323
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   324
function CheckAmmo()
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   325
   return GetAmmoCount(myHog, amGrenade) == 0
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   326
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   327
function DoPos()
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   328
   ShowMission("Scooter", "Mover", "Nice Work", 0, 0)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   329
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   330
function DoAmmo()
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   331
   AddAmmo(myHog, amGrenade, 5)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   332
end
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   333
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
   334
AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   335
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   336
==== `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   337
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
   338
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   339
==== `RemoveEventFunc(cFunc, cArgs)` ====
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   340
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
   341
246
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   342
Example:
500
dc66ea78b36d Use correct syntax highlighting.
almikes@aol.com
parents: 246
diff changeset
   343
<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
   344
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   345
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   346
AddEvent(condFunc2, condArgs1, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   347
AddEvent(condFunc2, condArgs2, doFunc, doArgs)
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   348
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
   349
RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>
7b1a6c46c3b5 Edited wiki page LuaLibraries through web user interface.
szabibibi@gmail.com
parents: 103
diff changeset
   350
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   351
==== `CheckEvents` ====
530
9d1b7bddb6d2 Remove bad blockquoute element.
almikes@aol.com
parents: 529
diff changeset
   352
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
   353
1053
bb4cfa5b41a0 LuaLibraries: AnimSetInputMask
Wuzzy
parents: 939
diff changeset
   354
==== `AnimSetInputMask(inputMask)` (0.9.23) ====
bb4cfa5b41a0 LuaLibraries: AnimSetInputMask
Wuzzy
parents: 939
diff changeset
   355
Call this function instead of `SetInputMask` if you want to set the input mask in a way that does not conflict with the Animate library.
bb4cfa5b41a0 LuaLibraries: AnimSetInputMask
Wuzzy
parents: 939
diff changeset
   356
bb4cfa5b41a0 LuaLibraries: AnimSetInputMask
Wuzzy
parents: 939
diff changeset
   357
Internally, the input mask you provide is simply AND-ed with the input mask used by the Animate library. Otherwise, this function works lik `SetInputMask`.
bb4cfa5b41a0 LuaLibraries: AnimSetInputMask
Wuzzy
parents: 939
diff changeset
   358
bb4cfa5b41a0 LuaLibraries: AnimSetInputMask
Wuzzy
parents: 939
diff changeset
   359
If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animatel library!
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   360
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   361
== Params ==
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   362
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
   363
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   364
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
   365
531
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   366
<code>speed=1</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   367
<code>health=100, ammo=5</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   368
<code>param1=hello, param2=whatever, param3=5325.4</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   369
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   370
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
   371
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   372
==== `parseParams()` ====
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   373
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
   374
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   375
===== Example  =====
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   376
<code language="lua">
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   377
function onParameters()
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   378
    parseParams()
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   379
    if params["myparam1"] == "hello" then
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   380
        WriteLnToConsole("Hello World!")
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   381
    end
528
88cc64932e78 Copy-editing on the entire page.
almikes@aol.com
parents: 527
diff changeset
   382
end</code>
526
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   383
f910cf3241fc Add Params.
almikes@aol.com
parents: 525
diff changeset
   384
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
   385
531
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   386
<code>myparam1=hello</code>
5628b472ab0d Copy-edit Params section
almikes@aol.com
parents: 530
diff changeset
   387
<code>myparam2=whatever, myparam1=hello</code>
532
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   388
<code>g=4, f=56, m=56, myparam1=hello</code>
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   389
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   390
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   391
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   392
== !TargetPractice ==
532
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   393
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
   394
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   395
Here is a brief description of the generated missions:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   396
 * The player will get a team with a single hedgehog.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   397
 * The team gets a single predefined weapon infinitely times.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   398
 * A fixed sequence of targets will spawn at predefined positions.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   399
 * 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
   400
 * The mission ends successfully when all targets have been destroyed
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   401
 * The mission ends unsuccessfully when the time runs out or the hedgehog dies
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   402
 * 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
   403
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   404
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
   405
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   406
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
   407
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   408
=== `TargetPracticeMission(params)` ===
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   409
This function sets up the *entire* training mission and needs one argument: `params`.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   410
`params` is a table containing fields which describe the training mission.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   411
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   412
There are mandatory and optional fields. The optional fields have default values.
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   413
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   414
Mandatory fields:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   415
|| *Field name* || *Description* ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   416
|| `missionTitle` || The name of the mission ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   417
|| `map` || The name of the image map to be used ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   418
|| `theme` || The name of the theme (can be background theme, too) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   419
|| `time` || The time limit in milliseconds ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   420
|| `ammoType` || The [AmmoTypes ammo type] of the weapon to be used ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   421
|| `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
   422
|| `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
   423
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   424
Optional fields:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   425
|| *Field name* || *Description * ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   426
|| `wind` || The initial wind (`-100` to `100`) (default: `0` (no wind)) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   427
|| `solidLand` || Weather the terrain is indestructible (default: `false`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   428
|| `artillery` || If `true`, the hog can’t move (default: `false`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   429
|| `hogHat` || Hat of the hedgehog (default: `"NoHat"`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   430
|| `hogName` || Name of the hedgehog (default: `"Trainee"`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   431
|| `teamName` || Name of the hedgehog’s team (default: `"Training Team"`) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   432
|| `teamGrave` || Name of the hedgehog’s grave ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   433
|| `clanColor` || Color of the (only) clan (default: `0xFF0204`, which is a red tone) ||
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   434
|| `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
   435
|| `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
   436
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   437
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   438
==== Example ====
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   439
Below is the complete source code of the mission “Target Practice: Cluster Bomb”:
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   440
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   441
<code language="lua">HedgewarsScriptLoad("/Scripts/TargetPractice.lua")
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   442
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   443
local params = {
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   444
	ammoType = amClusterBomb,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   445
	gearType = gtClusterBomb,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   446
	missionTitle = "Cluster Bomb Training",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   447
	solidLand = false,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   448
	map = "Trash",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   449
	theme = "Golf",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   450
	hog_x = 756,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   451
	hog_y = 370,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   452
	hogName = loc("Private Nolak"),
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   453
	hogHat = "war_desertgrenadier1",
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   454
	teamName = loc("The Hogies"),
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   455
	targets = {
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   456
		{ x = 628, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   457
		{ x = 891, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   458
		{ x = 1309, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   459
		{ x = 1128, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   460
		{ x = 410, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   461
		{ x = 1564, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   462
		{ x = 1248, y = 476 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   463
		{ x = 169, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   464
		{ x = 1720, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   465
		{ x = 1441, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   466
		{ x = 599, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   467
		{ x = 1638, y = 0 },
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   468
	},
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   469
	time = 180000,
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   470
	shootText = loc("You have thrown %d cluster bombs."),
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   471
}
8b7a9c032722 Add TargetPractice library
almikes@aol.com
parents: 531
diff changeset
   472
683
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   473
TargetPracticeMission(params)</code>
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   474
742
1ece82f7b547 LuaLibraries: Add title
Wuzzy
parents: 684
diff changeset
   475
== !SpeedShoppa ==
683
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   476
Starting with 0.9.22, this library provides a function to create a simple shoppa-style mission.
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   477
684
5488179eb2d2 Minor copy-editing
Wuzzy
parents: 683
diff changeset
   478
In !SpeedShoppa missions, the player starts with infinite ropes and has to collect all crates as fast as possible and compete for the fastest time.
683
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   479
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   480
This library also loads the Locale library for its own purposes. If you use !SpeedShoppa, you do not have to explicitly load Locale anymore.
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   481
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   482
=== `SpeedShoppaMission(params)` ===
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   483
This function sets up the *entire* mission and needs one argument: `params`.
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   484
The argument “`params`” is a table containing fields which describe the training mission.
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   485
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   486
Mandatory fields:
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   487
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   488
|| *Field name* || *Description* ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   489
|| `map` || The name of the map to be used ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   490
|| `theme` || The name of the theme (does not need to be a standalone theme) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   491
|| `time` || The time limit in milliseconds ||
684
5488179eb2d2 Minor copy-editing
Wuzzy
parents: 683
diff changeset
   492
|| `crates` || The coordinates of where the crates will be spawned. It is a table containing tables containing coordinates of format `{ x=value, y=value }`. There must be at least 1 crate. ||
683
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   493
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   494
Optional fields:
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   495
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   496
|| *Field name* || *Description* ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   497
|| `missionTitle` || The name of the mission (optional but highly recommended) (default: `"Speed Shoppa"`) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   498
|| `hogHat` || Hat of the hedgehog (default: `"NoHat"`) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   499
|| `hogName` || Name of the hedgehog (default: `"Roper"`) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   500
|| `teamName` || Name of the hedgehog’s team (default: `"Shoppers"`) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   501
|| `teamGrave` || Name of the hedgehog’s grave (default: `"Statue"`) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   502
|| `teamFlag` || Name of the team’s flag (default: `"cm_shoppa"`) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   503
|| `clanColor` || Color of the (only) clan (default: `0xFF0204`, which is a red tone) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   504
|| `goalText` || A short string explaining the goal of the mission (default: `"Use your rope to collect all crates as fast as possible."`) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   505
|| `faceLeft` || If `true`, the hog faces to the left initially, if false, it faces to the right. (default: `false` (=right)) ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   506
|| `crateType` || Specify the type of crate (this has no gameplay effect), pick one of `"ammo"`, `"utility"`, `"health"`. Default: `"ammo"` ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   507
|| `extra_onGameStart` || A function which is called at the end of this script's `onGameStart`. It takes no parameters. You could use this to spawn additional gears like girders or mines ||
6e31eaf0b22d Add SpeedShoppa documentation
Wuzzy
parents: 587
diff changeset
   508
|| `extra_onGameInit` || A function which is called at the end of this script's `onGameInit` ||