diff options
Diffstat (limited to 'lib/mods/theme/help/lua_skil.txt')
| -rw-r--r-- | lib/mods/theme/help/lua_skil.txt | 342 |
1 files changed, 0 insertions, 342 deletions
diff --git a/lib/mods/theme/help/lua_skil.txt b/lib/mods/theme/help/lua_skil.txt deleted file mode 100644 index 87385e5d..00000000 --- a/lib/mods/theme/help/lua_skil.txt +++ /dev/null @@ -1,342 +0,0 @@ -|||||oy -#####R /----------------------------------------\ -#####R < Adding new skill-based powers > -#####R \----------------------------------------/ - -#####R=== Introduction === - -This is very much in the same vein as adding a racial/extra power, but has to -be tied into skills, and we're defining more than one spell at once. You should -have read the *****lua_intr.txt*0[scripting introduction] and -*****lua_pow.txt*0[racial power tutorial] before going much further. Both of the above files -contain some fairly fundamental information which you will find necessary for -full understanding of this file. - -#####R=== Getting started === - -Open construc.lua (you have downloaded the example scripts from -[[[[[Ghttp://www.moppy.co.uk/angband.htm], haven't you?). The idea behind this -script is that it adds a skill which affects you ability to build/knock down -stuff. It treats the equivalent of stone-to-mud and trap-door destruction -spells as if they were "building skills". It also adds quite a few high-level -'spells' which do funky things like carving out corridors and chambers in a -single turn, and building doors and stuff. Just think of it as if the person -who has plenty of skills in this area would be a builder-type with lots of -strength and constitution... - -In order to add these powers we're going to edit the s_info.txt file which -lives in the edit folder, and add a new skill, underneath the 'misc' tree, -called construction. The powers will then be accessed through the 'm' menu, in -a similar way to mindcraft or alchemy skills or such. (That is, no books are -needed to cast them, as we're treating them as a craft that has been learnt, -rather than spells.) Our fist line of the script file reads: - -#####BSKILL_CONSTRUCT = 57 - -This merely links the skill index that we'll be defining in s_info.txt to this -file. We'll come back to this at the end of the tutorial. - -#####Bconstructor_powers = add_magic - -In a similar way to the [[[[[Badd_power] function we called when we added the -Phoenix racial ability, this line calls a special function which we use to -define new skills. It follows a very specific, but easy to understand form. It -starts with a brace, which indicates the add_magic function will be storing -these values in a table. Don't worry about this too much, but understand that a -table starts and ends with braces [[[[[B{] and [[[[[B}] respectively. Each key -(or field name) takes the format [[[[[B"key" = value,] (the comma is -important!). - -#####B ["fail"] = function() -#####B msg_print("You decide now is a good time for a cuppa") -#####B end, -#####B ["stat"] = A_STR, -#####B ["get_level"] = function() -#####B return get_skill_scale(SKILL_CONSTRUCT, 50) -#####B end, -#####B ["spell_list"] = - -[[[[[B"fail"] is a function that is called whenever you ##fail to cast the -spells##. Here it does nothing spectacular. -[[[[[B"stat"] defines the stat used to cast the spells. Here it is strength. -Any other stat can be used, prefix it with [[[[[BA_]. -[[[[[B"get_level"] is used to determine the level of the spell. It's associated -with spells that increase in power the more points that are invested in the -associated skill. I know that's not terribly clear, I'll come back to it in a -moment. -[[[[[B"spell_list"] is just that, a list of all the spells. -Each of these four properties within the table must end with a comma. If a -function is defined in the property itself then we add the comma after the -closing [[[[[Bend]. Again compare with construct.lua to see it. Any line NOT -ending with a comma will cause a lua error on startup, probably of the type -[[[[[V'}' expected to close '{' at line <whatever>.] - -#####R=== The spell list === - -Each spell, within the [[[[[B"spell_list"] key has its own set of properties -that we need to define from a sub-table so we open another set of braces to -start the spell list, and then a third set of braces to start the first spell. -So with all this, our first spell looks like: - -#####B ["spell_list"] = -#####B { -#####B { -#####B ["name"] = -#####B ["desc"] = -#####B ["mana"] = -#####B ["level"] = -#####B ["fail"] = -#####B ["spell"] = -#####B ["info"] = -#####B }, - -[[[[[B"name"] is, as you would expect, the name of the spell, as you want it to -appear in the spell list when choosing a spell. The maximum number of -characters for this is 29. -[[[[[B"desc"] is the description received when you hit the capital letter of -that spell in the menu. (i.e., press 'a' to cast the first spell, but press 'A' -to receive info about the first spell. -[[[[[B"mana"] is the amount of mana required to cast the spell. -[[[[[B"level"] is the level required to use that spell (that's level of the (in -this case construction) skill, not character level!). -[[[[[B"fail"] is base fail rate. -[[[[[B"spell"] is the function that is executed when the spell is cast. Note -that it MUST take the form [[[[[Bfunction() blah end] even if you're calling -a C function directly. If you have a look at the end of the file, you'll see -the "rebuild dungeon" spell which is identical to the "alter_reality" spell. -However, rather than reading [[[[[B"spell" = alter_reality()], it reads: - -#####B["spell"] = function() -#####B alter_reality() -#####Bend, - -which appears to be a long way round to do the same thing, but this is how it -must be done. - -In a similar way, the [[[[[B"info"] key must begin with a [[[[[Bfunction()] -and return the value of what is to be displayed alongside the spell name, -level and mana in the spell list. The maximum number of characters that can be -displayed here is dependent on the width of the user's screen, but try to keep -it under 12 if you can, as this will fit in a standard 80x24 terminal screen. -The first character will need to be a space otherwise you'll have the info line -squashed right up against the fail rate and it will look odd. If you wish to -have this part blank in the spell list, you still need to return a value, so -just a single space will do : [[[[[Breturn " "] - -All of these keys are repeated for each spell, with each spell in its own -table (therefore, it's own set of braces). Again, check the lua file for -clarification. - -When entering the spells in the "spell_list", you must take care to specify -them in the order which they are gained, otherwise they display incorrectly in -the spell list. - -You should by now be experienced enough to understand most of what's going on -in the actual spell functions (especially if you dig around in the source a -bit, and check out Chris Hadgis' excellent *****lua_spel.txt*0[spell.pkg] helper -files. I'm not going to go through the whole file line by line, as this is -something you should do yourself, figuring out what's going on. I'm going to -examine a few of the things we haven't covered before though, so pay attention. - -#####R=== The get_level() function === - -Probably one of the most important functions that you see reappearing in the -file is the [[[[[Bget_level()] function. All this does is return the numerical -value of the power that is given as the first argument. So [[[[[Bget_level] -[[[[[B(constructor_power)] will return the current level of the constructor power. -Given that the level of this is taken directly from the construction skill, (we -defined that in the [[[[[B"get_level"] key, by saying [[[[[Bget_skill_scale] -[[[[[B(SKILL_CONSTRUCT, 50)] ) it will return the value of your construction skill. -[[[[[Bconstructor_power] is the name of the whole power, we named it thus on -the second line of the script! - -[[[[[Bget_level] takes the following arguments: [[[[[Bget_level(power, max, ] -[[[[[Bmin)]. The power is obviously which power we're taking the value from, and the -max and min allow you to define boundaries for the spell. For instance the -current maximum value that [[[[[Bget_level(constructor_power)] can return is -50, as that is the maximum number of skill points you can have in that skill. -If you were using this as the basis for the damage of a low-level bolt spell, -you might decide that having a damage of 50 would be too much (unlikely, but -still possible). You could therefore define a maximum value of 20 so that when -the value of the construction skill was over 50, the maximum value for -damage of that spell would be 20. To achieve this you'd have: -[[[[[Bget_level(constructor_power, 20)]. In a similar way, you can force the -minimum value of the spell to be higher than the actual construction skill -level, with a [[[[[Bget_level(constructor_power, 50, 15)]. This would be useful -say for spells that you wanted to be available when the construction skill -level reaches 10, but for whom you wanted a (for example) base damage of 15 -right from the word go. These re-scale values rather than capping them! - -You can leave out the minimum value as I have done above. You can also leave -the maximum value out (it will default to 50). If you want to specify a minimum -value though, you MUST specify a maximum value as well. - -As you have hopefully been able to tell, the [[[[[Bget_level()] function -enables us to have spells that increase in usefulness as you gain levels. Let's -take the "Dismantle" spell. The function in the [[[[[B"spell"] key is as -follows: - -#####Bfunction() -#####B local ret, dir, dam - -#####B if (get_level(constructor_powers, 50) >= 11) then -#####B ret, dir = get_aim_dir(); -#####B if (ret == FALSE) then return end -#####B fire_beam(GF_KILL_TRAP, dir, 1) -#####B else -#####B fire_ball(GF_KILL_TRAP, 0, 1, 1) -#####B end -#####Bend, - -The [[[[[Bif] statement is obviously what really interests us here. You'll -notice that this has the amendment of an [[[[[Belse] clause, which the [[[[[Bif] -statement we used in the previous tutorial did not. As you would expect, if the -condition on the first line of this statement is met, then the instructions -immediately below it are carried out. If the condition is not met, then the -statements that follow the [[[[[Belse] are executed. - -Coming back to the [[[[[Bget_level] function, we learnt from above, that the -[[[[[Bget_level] part of this function translates as, "if the value of the -construction_power level (which happens to be identical to the construction -skill level) is greater than or equal to 11, cast a beam of trap disarming in -the specified direction. (The first part of this is all straightforward, -getting a direction, and cancelling correctly if the player presses 'ESC'.) -Otherwise, cast a ball of trap disarming with a radius of one, centred on the -player." - -In the same way, as you look at the construc.lua file, you will see that -[[[[[Bget_level()] is used many times in this way, to increase the power of -detection spells, to change bolt spells to ball spells, to keep a constantly -increasing damage going, and so on. - -#####R=== Elseif's and things === - -If you want to provide more than one alternative condition, in an -[[[[[Bif-then-else] statement, you can use [[[[[Belseif]s which do what you -might expect. Take a look at the first spell, "Survey area", for an example of -this: - -#####Bif (get_level(constructor_powers, 50) >= 28) then -#####B wiz_lite() -#####Belseif (get_level(constructor_powers, 50) >= 15) then -#####B map_area() -#####B detect_traps(DEFAULT_RADIUS) -#####Belseif (get_level(constructor_powers, 50) >= 5) then -#####B detect_traps(DEFAULT_RADIUS) -#####B detect_stairs(DEFAULT_RADIUS) -#####B detect_doors(DEFAULT_RADIUS) -#####Belse -#####B detect_stairs(DEFAULT_RADIUS) -#####B detect_doors(DEFAULT_RADIUS) -#####Bend - -If the level of constructor powers is greater or equal to 28, then the function -[[[[[Bwiz_lite()] is performed, and no other part of the if statement is -executed. [[[[[Bwiz_lite()] is just the enlightenment spell. If it is less than -28, the next condition is examined: that if the level of constructor powers is -greater than or equal to 15, then [[[[[Bmap_area()](Magic mapping) and detect -traps are called. If the level of constructor power is less than 15, it moves -onto the next condition, which says that if the level of constructor power is -greater than 5, then detect stairs, traps and doors. If none of these -conditions are met,(that is, if the level of construction skill is less than 5) -then we just detect doors and stairs. - -You'll note that each of the detection spells includes a DEFAULT_RADIUS -constant. You could change this to a numerical value, or a variable defined -somewhere else in your script. eg [[[[[Bdetect_traps(2)] would detect traps -with a radius of 2 centred on the player. - -#####R=== Registering the skill type === - -This is what we do at the end of the file, and is what ties the powers we've -defined to the action of pressing the 'm' key in game. Once more we're calling -a special function [[[[[Badd_mkey()] which takes its arguments for a table. -There are only two keys in this table though which keeps things simple. - -#####Badd_mkey -#####B{ -#####B ["mkey"] = MKEY_CONSTRUCT_POWERS, -#####B ["fct"] = function() -#####B execute_magic(constructor_powers) -#####B energy_use = energy_use + 100; -#####B end -#####B} - -[[[[[B"mkey"] must be a UNIQUE value > 1000 . Here I've defined it as a -constant, [[[[[BMKEY_CONSTRUCT_POWERS], which has the value 1004. This value -we'll call again in the s_info.txt file. -[[[[[B"fct"] is the function that's called when the user presses the key in the -'m' menu. So here, it calls the [[[[[Bexecute_magic] function which actually -displays a list of powers for the user to choose from. The argument it takes is -the powers it will use (alchemy, mindcraft, etc., or in this case constructor), -and then the [[[[[Benergy_use] line tells the game to take one game turn to do -the action. - -#####R=== Adding the skill in s_info.txt === - -Take a look in the s_info.txt file, under the Misc section. You'll see, - -#####BN:57:Construction -#####BD:Ability to use constructor powers -#####BD:Construction powers use strength -#####BA:1004:Build or knock down stuff -#####BI:1000 - -The first line is the index of the skill; again this must be unique. The second -property is the name of the skill. The [[[[[BD] lines are the lines displayed -when the skill is highlighted in the skill screen. -The first entry on the [[[[[BA] line is the value of the [[[[[B"mkey"] we -defined in the [[[[[Badd_mkey] function in our script. The second entry is the -display for selecting the construction power in the 'm' menu. -The [[[[[BI] line is currently unused, but add a 1000 there anyway. That's what -all the others have so when it's introduced, at least it will affect your -powers identically to how it affects all the other powers. - -If you scroll to the very bottom of the file now, you'll see I've placed the -skill at the bottom of the Misc branch of the skills tree. I then made a new -class, constructor, which you can see in p_info.txt. - -That is all that is NEEDED when writing a script to add a skill - defining an -mkey using add_mkey, and defining any powers that are called in the -[[[[[B"fct"] (generally using [[[[[Badd_magic] ). - -And I've added the line - -#####Btome_dofile("construc.lua") - -in init.lua so the script is loaded on start-up! - -Below I'm going to talk in depth about a few other functions that you may find -useful in your scripting. - -#####R=== fire_bolt() and fire_beam() === - -In the last help file we looked at the routine for firing a ball - -[[[[[Bfire_ball()]. Here's a quick note about beams and bolts... -[[[[[Bfire_beam()] and [[[[[Bfire_bolt()] take 2 arguments: -[[[[[B(type, direction, damage)]. So in the dismantle spell we have the -direction passed from [[[[[Bget_aim_dir()] (the function that asks the player -for a direction), the type of damage is [[[[[BGF_KILL_TRAP], which as you might -expect disarms traps. And the damage is only 1 because it's not going to hurt -monsters, just dismantle traps. - -#####R=== set_oppose_elec() === - -OK here's another thing. Wander on down to the sparky_skills spell. After the -appropriate bolt/ball is fired, we have the line: - -#####Bif player.oppose_elec == 0 then -#####B set_oppose_elec(randint(10) + 20 + get_level(constructor_powers, 20)*3) -#####Bend - -This is the bit that grants temporary resist electricity. We've called the -function [[[[[Bset_oppose_elec(turns)], which sets the player's resist -electricity to "on" for the time specified in the argument "turns". We're only -calling this if the player is not already granted temporary resist electricity, -and we've linked the number of turns it is active to the level of the -construction skill. I've limited the maximum value of get_level to 20 in this -instance. A similar idea can be used for temporarily granting levitation, -extended infravision, protection against evil, resist fire, stuns, cuts and so -on and so on. Have a look in player.pkg in the source for a full list.... - - [[[[[gThis file by fearoffours (fearoffours@moppy.co.uk)] |