Spell Scripts Naming Conventions

[John Adams]

Major Update to this Thread!
See below.

Alrighty... I have spent the better part of the holiday weekend trying multiple ways to minimize our efforts with Spells script writing. I think I have an idea that might work out, and wanted your input.

If you look at the Categories on EQ2 Wikia (this example being Quick Strike) you will notice the Category (target) and the spell "type" right after that. In this example, it is DD / DOT.

I propose that we make our generic Spell Scripts named similar to these categories - ie., dd_dot.lua for generic Direct-Damage + DOT spells. Inside the script, we can pass different parameters to determine what types of damage we're dealing.

For DD / DOT spells, you would pass 6 params: DDType, DDMin, DDMax, EffectType, EffectMin, EffectMax, for example. For straight DD, you only need the first 3... and the script is designed to check if EffectType ~= nil and skip that code. Remember, dd_dot.lua is only for damage.

For Scatman's example of a Triple Shot damage, we should be able to use the same script, only passing an extra param for the number of strikes, rather than create 3 scripts for single, double, or triple shots. As for the increasing damage done by these types of damage, we can perform additional math.random() in tick() using the last minimum value so the illusion is that the shots are getting stronger. Double or Triple shots could be mimicked in tick(), you think Scat? If so, we simply set the call_frequency to the expected delay between shots, and set a duration so it ends after the 3rd shot (for triple shot). Then in the spell_data, you pass the first 3 params as the initial damage, and the 4th param as "triple" (string). Now the generic DD/DOT script will SpellDamage() the first 3 params, then tick() the next 2. This is just one idea, and I haven't tried it yet.

The only thing we need on the server is to abort the entire script of a Miss occurs, which I do not believe we handle in LUA Scripts.

Some naming examples:
dd_dot.lua
dd_heal.lua
buff.lua
taunt.lua
etc...

An example generic dd_dot.lua:
[code]function cast(Caster, Target, DDType, MinDDVal, MaxDDVal, EffectType, MinEffectVal, MaxEffectVal)
-- DD component
if MaxDDVal ~= nil and MinDDVal < MaxDDVal then
SpellDamage(Target, DDType, math.random(MinDDVal, MaxDDVal))
else
SpellDamage(Target, DDType, MinDDVal)
end
-- Effect component - only process this code if there is an EffectType param
if EffectType ~= nil then
-- Determine if there is a range to effect values
if MaxEffectVal ~= nil and MinEffectVal < MaxEffectVal then
EffectValue = math.random(MinEffectVal, MaxEffectVal)
else
EffectValue = MinEffectVal
end
SpellDamage(Target, EffectType, EffectValue)
end
end

function tick(Caster, Target, DDType, MinDDVal, MaxDDVal, EffectType, MinEffectVal, MaxEffectVal)
if MaxEffectVal ~= nil and MinEffectVal < MaxEffectVal then
SpellDamage(Target, EffectType, math.random(MinEffectVal, MaxEffectVal))
else
SpellDamage(Target, EffectType, MinEffectVal)
end
end[/code]
spell_data for this script is: 0, 1, 5, 8, 1, 1

A script I created for testing to handle both DD and Heal-self:
[code]
function cast(Caster, Target, DDType, MinDDVal, MaxDDVal, EffectType, MinEffectVal, MaxEffectVal)
-- DD component
if MaxDDVal ~= nil and MinDDVal < MaxDDVal then
SpellDamage(Target, DDType, math.random(MinDDVal, MaxDDVal))
else
SpellDamage(Target, DDType, MinDDVal)
end
-- Effect component - only process this code if there is an EffectType param
if EffectType ~= nil then
-- Determine if there is a range to effect values
if MaxEffectVal ~= nil and MinEffectVal < MaxEffectVal then
EffectValue = math.random(MinEffectVal, MaxEffectVal)
else
EffectValue = MinEffectVal
end
-- Determine EffectType - either a DamageType or a String value passed as param 4
if EffectType == "heal" then
ModifyHP(Caster, EffectValue)
else
SpellDamage(Target, EffectType, EffectValue)
end
end
end

function tick(Caster, Target, DDType, MinDDVal, MaxDDVal, EffectType, MinEffectVal, MaxEffectVal)
if MaxEffectVal ~= nil and MinEffectVal < MaxEffectVal then
EffectValue = math.random(MinEffectVal, MaxEffectVal)
else
EffectValue = MinEffectVal
end
if EffectType == "heal" then
ModifyHP(Caster, EffectValue)
else
SpellDamage(Target, EffectType, EffectValue)
end
end[/code]
spell_data for this script could be either
: 0, 1, 5, 8, 1, 1 or
: 0, 1, 5, "heal", 2

...where the 4th param is a string "heal" telling the script it is not a DOT, but a heal for 2. You can see how flexible this is (pause for a moment of Lethal-worship here), though the more generic our scripts are, the more complex they become.

Conclusion: I am no longer chasing the dream that we'll need only 10 spell scripts for every spell in the game (hahah) and I believe if we categorize the spells properly, we can still maintain a minimal number of scripts.

What do you say?

See below for update to how Spells load as of Jan 28, 2010.

[Scatman]

That looks fine. The only problem I can see with doing a DD like Triple Shot by using tick() to do the next two attacks is what if a spell does two or three damages directly...then a numbers tics? I'm not sure if even an ability exists in game but I suppose there could, and it would also be a cool thing to allow for customization.
Couldn't we just run a loop for doing direct damage from 1 to the number of strikes in the cast()? That'll take care of any amount of direct damage numbers.

[John Adams]

I assumed the function tick() was a loop. As long as that function knows what it's min/max damages are, I don't see how it wouldn't work... but we can try it once your furry feet are back in Tess.
You are right on one point though. It may be more confusing to a server admin why something like 3-shot is setup as a duration/dot. But the system is there, we might as well use it!

[Scatman]

Oops I didn't mean to use triple shot as an example, I meant to say this. Say a spell looks like this:
Inflicts 10-20 melee damage.
Inflicts 10-20 melee damage.
Inflicts 40 disease damage instantly and every 5 seconds.
There it has two direct damages and a DOT. I've been trying to download TSO but the the patcher and I are having some issues.

[John Adams]

What I am aiming for is to make generic scripts for spells that are generic, ie., single DD + DoT, HoT, Stun, Taunt etc.
If the list of spells that do exceptionally unique things is small, we can certainly create scripts specific to those spells. What I do not want is 3700 scripts, in other words.

[John Adams]

As the revamped opening post implies we have decided to make some major changes to how Spell Scripts are stored and loaded into EQ2Emulator. For those without custom content, this is a non-issue. For those who have started building Spells for your custom servers,

PAY ATTENTION!
This is for you

Since SOE changed the naming conventions of Spells in (or after) GU52, the enormously daunting task of creating 5,000+ scripts to handle each and every spell is more or less behind us. We have talked about it for months and finally concluded that we can simply create one (1) spell script for every spell "line", by name, and pass into that script the data details that make that spell line grow - be it by Tier or Line upgrades.

What do I mean exactly?

Let's take the Templar spell "Meliorate". As a noob Templar, you get Meliorate as a spell. This is the first in this spell line (ie. Meliorate I). The Meliorate spell line has eight (8) upgrades -- I through VIII. Each upgrade also has it's tiers: Apprentice, Journeyman, Adept, Expert, Master, and Grandmaster (though I am a little confused by Grandmaster).

Essentially, this means this single spell line has 8 * 6 (48) possible spells! That is, 8 upgrades with 6 tiers each.

What we're going to do now is simply create a single Spell Script named "Meliorate.lua" and link it to all Meliorate I through Meliorate VIII -- one script, 8 spells. Each tier that gets created uses it's parent script with new spell data passed into it. In the simplest cases, the only data that will change are Power Consumption, Level Requirement, and the actual Heal Amount. More complex spells will require more complex setups, and possibly additional scripting - but for right now, this works for us.


Second thing changing is the physical location of your Spells scripts. Right now there is a folder under where EQ2World.exe sits, named "Spells", and world simply reads that folder contents to load all spell scripts. Well that has turned out to not work out very well for us once we start piling hundreds or thousands of scripts into that single folder - especially for classes that share the same spell names but different purposes.

As of tonight (in development), World now requires your spells tables "lua_script" field to point to the relative path to your spell scripts, much like it does for SpawnScripts, QuestScripts and ZoneScripts. Furthermore, and merely a personal choice of this development team, we are organizing our Official scripts into Archetype / Class / Sub-Class / SpellName.lua structures. You can organize your spells anyway you want using the new load methods... but this is our choice for official data.

Example is:

Code: Select all

Spells/Priest/Cleric/Templar/Meliorate.lua

If you want to keep using just the Spells folder, edit your `spells`.`lua_script` fields to precede your script name with "Spells/{your_script.lua}" - that is, add Spells/ in front of it so World knows to go INTO the Spells folder to find {your_script.lua}


Clear as mud? Got questions? Please ask. This code will hit development servers this weekend, and thus come to you via public SVN the following morning. I hope you admins find this feature change a comfortable one offering yet more flexibility in your configurations.

[Scatman]

Note:
The base directory for spells is still <eq2emu executable working directory>/Spells. It recursively searches from Spells (which means you can still keep scripts in the Spells dir) and looks for LUA scripts. So now instead of having 'buff.lua', make the spell script 'Spells/buff.lua'. Sorry but we figured it'd be more consistent with spawn scripts, zone scripts, and quest scripts this way. Let me know if anyone has an issue with this please.

[John Adams]

We probably should not hard-code "Spells/" Scat, in case that is not the dir an Admin wishes to put stuff in? And if World forces spell scripts to at least start in "Spells/", do we really need to put "Spells/buff.lua" in the spells.lua_script field? why not just "buff.lua", since world starts off in Spells/ anyway?

~confused~

Is that how SpawnScripts, Quests, and ZoneScripts all work? <-- those folder names are mandatory? If so, I'm good with that. I just thought I could put my scripts in "TheseAreJohnsScripts/QueensColony/MurrarShar.lua" and World would know to look in TheseAreJohn'sScripts right under where EQ2World.exe sits.

[Scatman]

Ok, the Spells/ dir is no longer hard-coded.

[ZexisStryfe]

So what about the fact that the T9 spells aren't the same as the T1-T8 spells of the same name? ie- Teaching of the Underworld in T1-8 buffs STR and INT. Teaching of the Underworld in T9 buffs STR, INT and AGI.

[John Adams]

More complex spells will require more complex setups, and possibly additional scripting - but for right now, this works for us.

Where is there a Tier 9 spell? In an expansion yet-to-be-release no one has seen any data on yet?

Is that called Teaching of the Underworld IX?

[ZexisStryfe]

I think Teachings of the Underworld VII... and yes, its in the expansion that will probably be out before this system is put into place Sentinel's Fate is being released in two weeks boy and girls...

[ZexisStryfe]

Let's take the Templar spell "Meliorate". As a noob Templar, you get Meliorate as a spell. This is the first in this spell line (ie. Meliorate I). The Meliorate spell line has eight (8) upgrades -- I through VIII. Each upgrade also has it's tiers: Apprentice, Journeyman, Adept, Expert, Master, and Grandmaster (though I am a little confused by Grandmaster).

Grandmaster is rewarded by the Training choices (levels 14, 24, 34, 44, 54, 64, 75, 85) on the Character Development tab.

[John Adams]

Oh so Grandmaster is just Master II? probably not, but sounded good

And, Mr Smarty Pants, this system IS in place tonight. You'll get it tomorrow. Be ready to edit all your spells.lua_script values

[Zcoretri]

Oh so Grandmaster is just Master II? probably not, but sounded good

And, Mr Smarty Pants, this system IS in place tonight. You'll get it tomorrow. Be ready to edit all your spells.lua_script values

Grandmaster are the former Master II choices