Skins: |

NWN SCRIPTS

- Jump to comments -

Title

Tag-based Template

Author

The Krit

Submitted / Updated

04-03-2010 / 11-13-2010

Category

Tutorials

Expansions

HOTU-1.59

View Code

// Tag-based script template.
// This is intended to be a starting point for writing an item's tag-based script.
// Copy this to a script whose name is the tag of the item in question.
// Edit the event handlers (scroll down to find them) as desired.


// -----------------------------------------------------------------------------
// This first part is standard and generic.
// There should be no need to edit it; just skip down to the next part.
// -----------------------------------------------------------------------------


#include "x2_inc_switches"


// The individual event handlers.

void OnAcquire(object oItem, object oAcquiredBy, object oTakenFrom, int nStackSize);
void OnActivate(object oItem, object oActTarget, location lActTarget, object oActivator);
void OnEquip(object oItem, object oEquippedBy);
void OnHit(object oItem, object oHitTarget, object oCaster);
int  OnSpellCast(object oItem, int nSpell, object oCaster);
void OnUnacquire(object oItem, object oLostBy);
void OnUnequip(object oItem, object oUnequippedBy);


// The main function.
void main()
{
    int nEvent = GetUserDefinedItemEventNumber();

    // Spells might continue to their spell scripts. All other events are
    // completely handled by this script.
    if ( nEvent != X2_ITEM_EVENT_SPELLCAST_AT )
        SetExecutedScriptReturnValue();

    // Determine which event triggered this script's execution.
    switch ( nEvent )
    {
        // Item was acquired.
        case X2_ITEM_EVENT_ACQUIRE:
                OnAcquire(GetModuleItemAcquired(), GetModuleItemAcquiredBy(),
                          GetModuleItemAcquiredFrom(), GetModuleItemAcquiredStackSize());
                break;

        // Item was activated ("activate item" or "unique power").
        case X2_ITEM_EVENT_ACTIVATE:
                OnActivate(GetItemActivated(), GetItemActivatedTarget(),
                           GetItemActivatedTargetLocation(), GetItemActivator());
                break;

        // Item was equipped by a PC.
        case X2_ITEM_EVENT_EQUIP:
                OnEquip(GetPCItemLastEquipped(), GetPCItemLastEquippedBy());
                break;

        // Item is a weapon that just hit a target, or it is the armor of someone
        // who was just hit.
        case X2_ITEM_EVENT_ONHITCAST:
                OnHit(GetSpellCastItem(), GetSpellTargetObject(), OBJECT_SELF);
                break;

        // A PC (or certain NPCs) cast a spell at the item.
        case X2_ITEM_EVENT_SPELLCAST_AT:
                if ( OnSpellCast(GetSpellTargetObject(), GetSpellId(), OBJECT_SELF) )
                    SetExecutedScriptReturnValue();
                break;

        // Item was unacquired.
        case X2_ITEM_EVENT_UNACQUIRE:
                OnUnacquire(GetModuleItemLost(), GetModuleItemLostBy());
                break;

        // Item was unequipped by a PC.
        case X2_ITEM_EVENT_UNEQUIP:
                OnUnequip(GetPCItemLastUnequipped(), GetPCItemLastUnequippedBy());
                break;
    }
}


// -----------------------------------------------------------------------------
// Event handlers
// -----------------------------------------------------------------------------
// This second part is where you add your desired functionality. Each event
// has its own function with relavant information passed as parameters.
// -----------------------------------------------------------------------------


// -----------------------------------------------------------------------------
// oItem was acquired (by a PC or an NPC).
// Run by the module.
void OnAcquire(object oItem, object oAcquiredBy, object oTakenFrom, int nStackSize)
{
    // Default: do nothing.
}


// -----------------------------------------------------------------------------
// oItem was activated ("activate item" or "unique power").
// Run by the module.
void OnActivate(object oItem, object oActTarget, location lActTarget, object oActivator)
{
    // Default: do nothing.
}


// -----------------------------------------------------------------------------
// oItem was equipped by a PC.
// Run by the module.
void OnEquip(object oItem, object oEquippedBy)
{
    // Default: do nothing.
}


// -----------------------------------------------------------------------------
// oItem is a weapon that just hit a target, or it is the armor of someone who
// was just hit by someone else's weapon.
// Run by the caster.
void OnHit(object oItem, object oHitTarget, object oCaster)
{
    // Default: do nothing.
}


// -----------------------------------------------------------------------------
// Someone cast a spell at oItem.
// This usually only fires if a PC cast the spell, but it also fires for
// DM-possessed NPCs and NPCs in an area with the "X2_L_WILD_MAGIC" local integer set.
//
// Return TRUE to prevent the spell script from firing.
// Return FALSE to proceed normally.
//
// This fires after the UMD check, module spellhook, item creation, and
// sequencer handlers decide they don't want to handle/interrupt this spell.
// This fires before the check to see if this is a spell that normally can
// target items (and before the spell script itself runs).
//
// Run by the caster.
int OnSpellCast(object oItem, int nSpell, object oCaster)
{
    // Default: just proceed normally.
    return FALSE;
}


// -----------------------------------------------------------------------------
// oItem was unacquired/lost (by a PC or NPC).
// Run by the module.
void OnUnacquire(object oItem, object oLostBy)
{
    // Default: do nothing.
}


// -----------------------------------------------------------------------------
// oItem was unequipped by a PC.
// Run by the module.
void OnUnequip(object oItem, object oUnequippedBy)
{
    // Default: do nothing.
}

Select All Text | View Code in separate window

Format

Code Only

Type

Type - Unique Items

Includes

BioWare Standard

Description

This is a template script to help people create their scripts for tag based items. (If your tag-based item only needs to handle item activation, you may prefer to look at my Tag-based Template, Activate Only submission.) The template includes all the necessary interface instructions (like finding the item in question and setting the executed script return value), allowing the scripter to focus on what needs to be done. The basic way to use this is to copy it to your script (named for the item's tag), then add your code to the correct places. Between the comments and the function names, I hope the details of using this are self-explanatory. For more of an overview, read on.

The design of this template breaks each event out into its own function, with relevant information (such as the item in question) passed as parameters. Events that you don't care about can be left as-is. (This is not the most efficient possible solution, but it's not terribly inefficient.) I suppose that makes this something of a tutorial, presenting a reasonable way to implement tag-based items.

The primary intended audience for this are those who are have taken a step beyond the script generator, or at least are willing to take that step. (A "step" would include just being able to adapt a generated script to work as one of these functions -- some understanding of scripting principles is required, but not necessarily the ability to write a script from scratch.)

Some more experienced scripters may find this a useful reference for tagbased design, such as what object is running each event and when exactly the OnSpellCastAt event fires within the spell hook. This is not the primary intended use, but the info is there.

I looked around and did not find something like this, so I thought I would post it in case someone might find it helpful.

Nov 13, 2010 -- renamed the "oTarget" and "lTarget" parameters for better compatibility with scripts originating with the Script Generator

Files

Name	Type	Size	Downloads
NO FILES

SCORE OUT OF 10

9.93
9 votes
View Stats
Cast Your Vote!

PORTFOLIO

Add this entry to your portfolio so you can track it

Manage your existing portfolios or create a new one.

SCREENS

You Must Be Logged In to Participate.

Comments (14):

Posted by Mannast at 2010-08-17 17:18:56 Voted 10.00 on 08/17/10

The clear and eye-opening setup of this script has made my life much easier. Thanks for putting this on the board.

Posted by crazedmages at 2010-07-24 09:37:06 Voted 9.50 on 07/24/10

Only reason I rank this below a 10 is if the Krit would have made this earlier then I would have not had my guys summoning naked stouts for three weeks...
_________________________
People react violently to fur rather than leather because it is easier to pick on rich chicks with bad taste than biker gangs.

Posted by Blasco-Yang at 2010-06-14 18:28:42 Voted 10.00 on 06/14/10

Frankly, RustyDios comment is nearly a duplicate for what I would have said. He was very articulate and honest.

And obviously, The Krit is a fellow who can take constructive, well meaning criticism with his head held high.

However, it is not my intention to vote on how useful I, personally, find the template.

Since I am not part of the intended audience I feel I should step back and put myself into the shoes I wore a few years ago and vote as though I were indeed a novice scripter.

As Rusty said, this template is better commented, and goes a lot further in detailing how it all comes together.

As a begining scripter, anything you can grab hold of that goes a bit further in explaining those details is worth a fortune.

If everyone working with NWN scripting currently had been at it for 3 years or more I'd probably give it a lower vote than Rusty did, but as for its worth to a fledgling scripter I give it a 10.

Like Rusty, I also mean no offense. I admire his honesty, and the fact that he seemed somewhat reluctant to even vote went a long way to convincing me of his sincerity.

Posted by Sethan at 2010-04-30 23:43:20 Voted 10.00 on 04/30/10

Nicely done.
_________________________
PW Story server Narfell - Since 2002

Posted by Greven134 at 2010-04-17 22:06:01 Voted 10.00 on 04/17/10

A useful template to help fledgling scripters. Very useful!

Posted by The_Krit at 2010-04-14 19:14:45

Apologies not necessary. ;) From my perspective, a well-explained rating is always welcome, regardless of the number attached. I even appreciate the rating of 1.25 someone gave one of my other entries because it came with a rationale, letting me see what that person thought was important.

Not to mention that 7.00 is a pretty good rating, isn't it? I mean, 8.00 is Hall of Fame material, so being just a bit below that is not bad at all.

Posted by RustyDios at 2010-04-12 18:49:41 Voted 7.00 on 04/12/10

Yes I agree the template is useful.. it does have some functions in it that are not covered in "x2_it_example"... it is explained alot better then that template too... ... looking at it with fresher eyes, if I was a complete novice scripter (like we all were once), this is a brilliant template... and I'm guessing that it hits it's target audience perfectly... but I don't class myself a novice anymore, and have found I've been fine without this, though it could have helped.... Don't get me wrong, if I'd come across this when I started out I could see it being alot more useful..... .... however the lexicon, lilac's generator and a host of forum boards and posts(including from the Krit, who is a wellspring of quality information) have made me better. Almost to the point where I don't see the need for this, and that is why I say my vote would be (and is) "tainted", I do not consider myself part of the intended audience... As (almost) requested though I have cast my vote. This is good stuff, just not for everyone. I hate being negative on things that community members have taken the time to do and to share with us, but I suppose constructive criticism makes everything better, for everbody. I've said my piece, please don't take it the wrong way, it is not meant as flame, or aggression, or intendedly hurtful... just my point of view. Sorry.

Posted by The_Krit at 2010-04-10 15:20:15

One other thing... if anyone thinks something is going to taint their rating, I say rate it anyway but be sure to explain the possible taint in their vote's comment. That way others looking at the ratings can decide for themselves if your concern is something that matters to them.

It's a waste of a rating system when people fall into the idea that their choices are "vote 10" or "don't vote". I can understand not voting on an entry because you are not the intended audience (and you can't tell how good it would be for the intended audience), but not voting simply because the rating would be low defeats the purpose of having ratings in the first place. (And I'll stop here before I go into how bad I think vote inflation has gotten on the Vault.)

Posted by Saduj at 2010-04-05 11:39:34 Voted 10.00 on 04/05/10

Excellent work, defiantly handy to have :)
_________________________
Carcerian/Saduj's Submissions: (169 Portrait/Soundset Unlocker) (12 NWN Fonts) (30 NWN Fonts) (Auto-Emotes) (Custom Dragon Disciples) (Dynamic Wildshape) (Keyring) (NPC Schedules) (Sacred Shields) (Spawning Undead) (Shayans Subrace Engine for 169)

Posted by The_Krit at 2010-04-05 09:32:13

Re: Is this worth more than x2_it_example?

I'll leave it to each person to decide that. This template is a bit more comprehensive in that it covers a few more event details than the example script (e.g. getting the activation target) and it handles setting the script return value. Other differences are more subjective as to "better", "worse", or "just as good".

What I see as the big value to this entry is that people searching the Vault (or BioWare's forums, as I put a link there) have a chance to find this. The example script is not likely to be found by the beginner scripters, as the Toolset won't search standard scripts unless you open them first. (There is BioSearcher, but again, not likely for beginner scripters.)

Posted by RustyDios at 2010-04-04 15:09:01 Voted 7.00 on 04/12/10

This is useful... saved into the "scripttemplates" folder of your nwn directory can be accessed any time you happen to be in the module... the question I'm wondering is if it's worth any more then the "x2_it_example" script which can be found by clicking "all resources" when opening a new script.... ...

I'm not going to vote, because whilst I see this as useful I'm not sure it really adds anything above and beyound the script I just mentioned, and that really taint's my vote... ...

Posted by 420 at 2010-04-04 11:24:00

Thanks for this The Krit! I'm definitely bookmarking this, I have a feeling I may need to post a link to it frequently.

Posted by jdeavila at 2010-04-03 23:07:38 Voted 10.00 on 04/03/10

good stuff..thanks!!
_________________________
Imtherealthing

CCP (The Community Creature Project)

The TRIAD

Posted by Gonzo_og at 2010-04-03 19:19:12 Voted 10.00 on 04/03/10

This looks very thorough.
_________________________
stuff

You must be Logged In to post comments in this section.