Import Theme repository into main repository

1 files changed, 266 insertions, 0 deletions

diff --git a/lib/mods/theme/help/lua_pow.txt b/lib/mods/theme/help/lua_pow.txt
new file mode 100644
index 00000000..c221a664
--- /dev/null
+++ b/lib/mods/theme/help/lua_pow.txt
@@ -0,0 +1,266 @@
+|||||oy
+#####R             /----------------------------------------\
+#####R            <         Adding new racial powers         >
+#####R             \----------------------------------------/
+
+#####R=== Introduction ===
+
+You *must* download and install my lua example files from 
+[[[[[Ghttp://www.moppy.co.uk/angband.htm]. And also you should read the 
+*****lua_intr.txt*0[scripting introduction] file if you haven't already done 
+so.
+
+The (commented) accompanying script file for this tutorial is 
+lib\scpt\pheonix.lua. Open it in your text editor!
+
+#####R=== The Racial Power ===
+
+Let's start with something simple. Let's say you wanted your new race (let's 
+call it "Pheonix") to be able to cast fire balls as their racial power. 
+
+#####R=== Starting off ===
+
+If you have a look at pheonix.lua you'll note the first lines are comments.
+I'll talk a bit more about comments later, but it's worth pointing out that any
+lines of text preceded by a double hyphen ([[[[[B--]) will be ignored by the 
+scripting engine, and are therefore comments. 
+After the comments, the first 10 lines of code are as follows:
+
+#####BPHEONIX_POWER = add_power
+#####B{
+#####B        ["name"] =      "Fire Breath",
+#####B        ["desc"] =      "You are able to cast fireballs",
+#####B        ["desc_get"] =  "Your beak glows red",
+#####B        ["desc_lose"] = "Your beak goes cold again",
+#####B        ["level"] =     10,
+#####B        ["cost"] =      11,
+#####B        ["stat"] =      A_INT,
+#####B        ["fail"] =      14,
+
+So, [[[[[BPHEONIX_POWER = add_power] is registering our power. We're giving it 
+a name (PHEONIX_POWER) and saying that it is defined by calling the special 
+function [[[[[Badd_power]. This special function is only used to define lua-
+scripted 
+powers, and has attributes which are identified by their inclusion in square 
+brackets.
+Note the following:
+- Lua is case sensitive. The name of our power is a constant, will never change 
+so that's been named with capitals. variables and functions are named all in 
+lower case. Technically speaking, Lua does not support constants, but we can 
+emulate them by variables in this way. They don't have to be capitalised, but 
+if you capitalise all your constants, it makes things easier to read, and 
+you'll be following normal programming protocol. 
+- There are no spaces in the name of the power. Use an underscore for spaces 
+if you need to improve legibility. 
+
+[[[[[B"name" =      "Fire Breath",] This is the name of the power as it is 
+displayed in the 
+U menu, and as you will define it in p_info.txt (more about that later). 
+
+[[[[[B"desc" =      "You are able to cast fireballs",] This is what would 
+appear in the 
+information display list if you drank  a potion of self knowledge or 
+similar. 
+
+[[[[[B"desc_get" =  "Your beak glows red",] This is the information displayed 
+when you 
+gain this power. 
+
+[[[[[B"desc_lose" = "Your beak goes cold again",] This is the information 
+displayed when 
+you lose this power. Eg After a mutation/corruption.
+
+[[[[[B"level" =     10,] Character level which must be gained in order to use 
+power,
+
+[[[[[B"cost" =      11,] Amount of mana to cast this power.
+
+[[[[[B"stat" =      A_INT,] stat which will define whether it works or not, 
+
+[[[[[B"fail" =      14,] how high that stat must be. 
+
+So our Pheonix will be able to cast PHEONIX_POWER  from clvl 10, at a cost of 
+11 mana, providing that the player's intelligence is 14 and upwards. 
+
+#####R=== The function ===
+
+The next section is a lot longer, so we'll look at it line by line. I'll 
+strip the comments for the purpose of this helpfile.
+
+#####B["power"] =     function()
+#####B		local ret, dir, damage
+#####B		ret, dir = get_aim_dir();
+#####B		if (ret == FALSE) then 
+#####B			return 
+#####B		end
+#####B		damage = player.lev*3
+#####B		msg_print("You breathe fire.")
+#####B		fire_ball(GF_FIRE, dir, damage, 3)
+#####Bend,
+
+The [[[[[B"power"] bit is what actually happens when the player accesses this 
+power 
+from their 'U' menu. Every function must start with the word [[[[[Bfunction]. 
+Normally, we'd also declare its name at this point, but as this is contained 
+within the [[[[[Badd_power] function, we just use the word [[[[[Bfunction] The 
+empty 
+brackets after this denote that no arguments are passed to the function. 
+Lets look at the next line.
+
+#####B		local ret, dir, damage
+
+The [[[[[Blocal] bit is saying that  we're going to declare some local 
+variables. That 
+is, that there will be three variables used in this function , that apply 
+exclusively to this function, and to no others. Global variables are 
+variables that apply to the whole script, in multiple functions. The three 
+variables will be called [[[[[Bret] (return), [[[[[Bdir] (direction), and
+[[[[[Bdamage]. They will be used to determine the direction the ball 
+will fire in, and how much damage it will do. We'll see them in use when we add
+the third line:
+
+#####B		ret, dir = get_aim_dir();
+
+here we're saying that the variables will take their value from the result 
+of a function. The program performs the function [[[[[Bget_aim_dir] which 
+essentially asks the player to choose a direction or pick a target. 
+[[[[[Bget_aim_dir] 
+assigns the value [[[[[Bret] to either TRUE (if the player correctly selected a 
+direction) or FALSE (if the player failed to do so (maybe they changed their 
+mind, or hit the wrong key!)). The value [[[[[Bdir] is the direction which was 
+selected (or the path to the target if a target was selected). OK so let's add 
+the next line:
+
+#####B		if (ret == FALSE) then return end
+
+This introduces another fundamental scripting concept - [[[[[Bif] statements.
+They work just as you would expect them too. You say "if a certain condition is
+met, then do the following things."
+So in this function we're saying, "if the value of [[[[[Bret] is FALSE then 
+[[[[[Breturn]."
+As I mentioned above, [[[[[Bret] is false if the player aborted (either 
+deliberately or accidentally) the spell casting whilst choosing a direction 
+for the spell. The double equals sign are used to mean "is equal to" as a 
+single equals sign is used for defining variables remember? A single equals 
+sign is more of a "let x be equal to y" thing.
+[[[[[Breturn] means stop the current function. And [[[[[Bend] signifies the 
+close of the [[[[[Bif]
+statement. Every [[[[[Bif] statement must begin with an [[[[[Bif] and finish 
+with an [[[[[Bend].
+So, what our [[[[[Bif] statement is saying is; "if the player failed to specify 
+a direction or target for the spell, stop the function here."
+If the player has correctly specified a direction/target, the function 
+continues to the next line:
+
+#####B		damage = player.lev*3
+
+Here we're saying that the variable [[[[[Bdamage] has a value equal to the 
+players current character level, multiplied by 3.
+
+#####B		msg_print("You breathe fire.")
+
+Fairly easy to see what this does - displays the message "You breathe fire."
+I could have put anything there obviously, like [[[[[Bmsg_print("You open]
+[[[[[Byour mouth and everyone falls over with the smell of hot curry")] or
+some other such rubbish. But note that the message is enclosed within double 
+quotes. The quotes aren't displayed in the message on screen, but signify the 
+start and end of the message. 
+
+#####B		fire_ball(GF_FIRE, dir, damage, 3)
+
+This is the line that casts the spell. it says execute the function 
+[[[[[Bfire_ball]. Now, this doesn't mean a fireball, it means fire a ball. 
+There's an important distinction there! All it knows it is doing is firing a 
+ball, it doesn't know what kind of ball, or where, or how big, or how much 
+damage.
+The [[[[[BGF_FIRE,] bit is what tell us it is a fire ball. If it was 
+[[[[[BGF_COLD,]
+ we'd have a cold ball, or [[[[[BGF_CHAOS,] it would be a chaos ball and 
+so on and so on. A full list of those types can be found in *****lua_gf.txt*0[lua_gf.txt].
+[[[[[B dir,] is the direction, from the [[[[[Bget_aim_dir()] bit.
+[[[[[B damage,] is the damage. As we've already said, this will be clvl*3.
+[[[[[B 3)] is the radius.
+and finally...
+
+#####B	end,
+#####B}
+
+[[[[[Bend,] tells it the function has ended. Every function must finish with 
+[[[[[Bend].
+You should have spotted that after the end of each attribute is a comma. Make 
+sure you include this, and don't forget the braces at the very very end to 
+close the [[[[[Badd_power] function.
+
+#####R=== Finishing the LUA file ===
+
+Save this as a text file 'pheonix.lua' Put it into the lib\scrpt directory 
+of ToME, and open the init.lua file which you'll find in the same 
+directory. 
+
+Add the following line and resave the init.lua file.
+
+#####Btome_dofile("pheonix.lua")
+
+This ensures that ToME loads your file on start-up. Because you've installed 
+the example scripts, this has all been done for you.
+
+#####R=== A quick word about comments ===
+
+One of the reasons Angband has so many variants is because the source code is 
+clearly commented. Almost every line of code has an accompanying comment, 
+explaining what that line does. It's good practice to add comments to any code 
+or script you write. It's helpful to others who are learning, anyone who takes 
+over your project, and also to yourself when you come back in a month's time 
+and can't remember what you did! So comment your code clearly, and well!
+
+You can also add multi line comments which should be enclosed by [[[[[B--[[] 
+and 
+#####B]]
+
+#####R=== Tying it all together ===
+
+You'll now need to link this 'U' power to the pheonix race via the 
+p_info.txt file. Simply add a line within the class definition file that has 
+the format [[[[[BR:Z:<name>]the name of the power as it appears in the 
+[[[[[B"name"] 
+section we did right at the beginning, remember? Seeing as there is no pheonix 
+race, I've gone ahead and made one up as a demonstration. If you've downloaded 
+and installed the example files from [[[[[Ghttp://www.moppy.co.uk/angband.htm/] 
+then 
+you'll notice you already have the pheonix race available. Printed below is 
+the p_info.txt entry for it.
+
+
+#####BR:N:23:Pheonix
+#####BR:D:Born from flame, these powerful bird like creatures gain fire related
+#####BR:D:abilities as they grow. 
+#####BR:S:1:0:2:1:-3:2:-5
+#####BR:K:-8:15:20:-10:5:-1:-5:-5
+#####BR:P:8:130:5:210
+#####BR:M:255:70:2:1:20:5:2:1:18:3
+#####BR:E:1:1:1:2:1:1
+#####BR:C:Warrior | Mage | Priest | Rogue | Ranger | Paladin | Blade | 
+#####BR:C:Warlock | Chaos-Warrior | Monk | Mindcrafter | High-Mage |
+#####BR:C:BeastMaster | Alchemist |  Power-Mage | Runecrafter | 
+#####BR:C:Sorceror | Archer | Illusionist | Druid | Necromancer | Black-Knight 
+| 
+#####BR:C:Daemonologist | Weaponmaster | Summoner | 
+#####BR:Z:Fire Ball
+#####BR:R:1:0
+#####BR:F:RES_FIRE | FEATHER |
+
+Note the [[[[[BR:Z:] line. 
+
+If all is well, you should be able to start ToME now and breathe fire! Once 
+you get to lvl 10 anyhow. Don't forget, this is the kind of thing wizard mode 
+was invented for! Ctrl-A and confirm at the prompt, and then 'e' will allow 
+you to alter stats, including experience. Approx 1000 exp should do to get you 
+to clvl 10.
+
+Ready for more? How about adding a new *****lua_skil.txt*0[skill] ?
+
+                             [[[[[gThis file by fearoffours (fearoffours@moppy.co.uk)]
+
+
+
+