# HG changeset patch
# User almikes@aol.com
# Date 1419127389 0
# Node ID 8b7a9c0327224bac5553b917f45d86608cfa81f4
# Parent  5628b472ab0de3aac0e59411d60aeb53591933dd
Add TargetPractice library

diff -r 5628b472ab0d -r 8b7a9c032722 LuaLibraries.wiki
--- a/LuaLibraries.wiki	Sun Dec 21 01:35:52 2014 +0000
+++ b/LuaLibraries.wiki	Sun Dec 21 02:03:09 2014 +0000
@@ -346,4 +346,89 @@
 
 <code>myparam1=hello</code>
 <code>myparam2=whatever, myparam1=hello</code>
-<code>g=4, f=56, m=56, myparam1=hello</code>
\ No newline at end of file
+<code>g=4, f=56, m=56, myparam1=hello</code>
+
+
+
+= !TargetPractice =
+Starting with 0.9.21, this library provides a function to create an entire target practice mission which follows some basic properties.
+
+Here is a brief description of the generated missions:
+ * The player will get a team with a single hedgehog.
+ * The team gets a single predefined weapon infinitely times.
+ * A fixed sequence of targets will spawn at predefined positions.
+ * When a target has been destroyed, the next target of the target sequence appears
+ * The mission ends successfully when all targets have been destroyed
+ * The mission ends unsuccessfully when the time runs out or the hedgehog dies
+ * 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.
+
+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.
+
+Thos library also loads the Locale library for its own purposes. If you use !TargetPractice, you do not have to explicitly load Locale anymore.
+
+=== `TargetPracticeMission(params)` ===
+This function sets up the *entire* training mission and needs one argument: `params`.
+`params` is a table containing fields which describe the training mission.
+
+There are mandatory and optional fields. The optional fields have default values.
+
+Mandatory fields:
+|| *Field name* || *Description* ||
+|| `missionTitle` || The name of the mission ||
+|| `map` || The name of the image map to be used ||
+|| `theme` || The name of the theme (can be background theme, too) ||
+|| `time` || The time limit in milliseconds ||
+|| `ammoType` || The [AmmoTypes ammo type] of the weapon to be used ||
+|| `gearType` || The [GearTypes gear type] of the gear which is fired by the weapon (used to count shots) ||
+|| `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. ||
+
+Optional fields:
+|| *Field name* || *Description * ||
+|| `wind` || The initial wind (`-100` to `100`) (default: `0` (no wind)) ||
+|| `solidLand` || Weather the terrain is indestructible (default: `false`) ||
+|| `artillery` || If `true`, the hog can’t move (default: `false`) ||
+|| `hogHat` || Hat of the hedgehog (default: `"NoHat"`) ||
+|| `hogName` || Name of the hedgehog (default: `"Trainee"`) ||
+|| `teamName` || Name of the hedgehog’s team (default: `"Training Team"`) ||
+|| `teamGrave` || Name of the hedgehog’s grave ||
+|| `clanColor` || Color of the (only) clan (default: `0xFF0204`, which is a red tone) ||
+|| `goalText` || A short string explaining the goal of the mission (default: `"Destroy all targets within the time!"`) ||
+|| `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."`) ||
+
+
+==== Example ====
+Below is the complete source code of the mission “Target Practice: Cluster Bomb”:
+
+<code language="lua">HedgewarsScriptLoad("/Scripts/TargetPractice.lua")
+
+local params = {
+	ammoType = amClusterBomb,
+	gearType = gtClusterBomb,
+	missionTitle = "Cluster Bomb Training",
+	solidLand = false,
+	map = "Trash",
+	theme = "Golf",
+	hog_x = 756,
+	hog_y = 370,
+	hogName = loc("Private Nolak"),
+	hogHat = "war_desertgrenadier1",
+	teamName = loc("The Hogies"),
+	targets = {
+		{ x = 628, y = 0 },
+		{ x = 891, y = 0 },
+		{ x = 1309, y = 0 },
+		{ x = 1128, y = 0 },
+		{ x = 410, y = 0 },
+		{ x = 1564, y = 0 },
+		{ x = 1248, y = 476 },
+		{ x = 169, y = 0 },
+		{ x = 1720, y = 0 },
+		{ x = 1441, y = 0 },
+		{ x = 599, y = 0 },
+		{ x = 1638, y = 0 },
+	},
+	time = 180000,
+	shootText = loc("You have thrown %d cluster bombs."),
+}
+
+TargetPracticeMission(params)</code>
\ No newline at end of file