diff options
Diffstat (limited to 'lib/mods/theme/help/lua_pow.txt')
-rw-r--r-- | lib/mods/theme/help/lua_pow.txt | 266 |
1 files changed, 0 insertions, 266 deletions
diff --git a/lib/mods/theme/help/lua_pow.txt b/lib/mods/theme/help/lua_pow.txt deleted file mode 100644 index c221a664..00000000 --- a/lib/mods/theme/help/lua_pow.txt +++ /dev/null @@ -1,266 +0,0 @@ -|||||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)] - - - - |