Grimlar - Guide To Portal Stones

From NWN Lexicon
Jump to: navigation, search

Grimlar - Guide To Portal Stones

It is assumed that you have an understanding of the NWN scripting language and are familiar with the Aurora Toolset, i.e. you know how to create an area, place objects in it and perform simple scripting tasks. If this isn't the case, please go and have a look at Celowins scripting tutorials and Bioware's module construction tutorial first. Please also note that this tutorial makes use of Tag based Item scripts and as such may not work if you don't have HoTU installed.


Introduction


Everybody wants an easy life, and walking through empty map segments that you've already been through is nobodies' idea of fun.


So what do you do?


The Stone of Recall is a nice idea but can be used too frequently to be perfect, the Focus crystal stuff in SoU and Ring of the Reaper in HoTU are better but wouldn't it be better still if you could choose both where to start the teleport from and where to end up?


The Teleport Stones do just that allowing you to mark the place you want to return to as well as where you want to leave from.


This is achieved by having both a Portal Stone and a Beacon Stone. The Beacon stone needs to be used first to mark the place you wish to return to, and the Portal Stone is used later when you wish to create a Portal to travel from one location to another.


Easy.


Quick Design


Ok, the plan is as follows...


You create a Beacon with the Beacon Stone, this is the point you want your player to return to. You create a Portal with the Portal Stone, this is the point you are leaving from.


You use Power Stones to fuel the Portal and Beacon Stones, otherwise the player would be able to use them only so many times per day, assuming you don't want unrestricted use. Charges on the items are a possibility but a maximum of fifty charges leads to virtually unrestricted use again, plus recharging could lead to other issues.


The Portal Stone will consume one Power Stone when it is used and the Beacon Stone consumes two.


Ideally the Portal and the Beacon will look similar but different. Also using two placeables allows us to make it immediately obvious which is the Portal and which the Beacon.


Details


What we need to produce here is three new items, the Beacon and Portal Stones which will be 'Miscellaneous Small' items with the 'Cast Spell : Unique Power, Unlimited Use', property. And a new gem called a 'Power Stone', with no powers.


Then we will need to create two new placeables, one to act as a beacon and the other to act as a portal.


Setting Up


It is suggested that you create a module with two small areas, perhaps 4x4, to run this tutorial in, and then link the two areas either by a door transition or an area transition trigger. The tileset used is entirely up to you.


Power Stone


We'll do this item first as it requires least effort.


1)Start the 'Item Wizard' from the 'Wizards' menu at the top of the page.


2)Select 'Gem' for the 'Item Type' and click on 'Next'.


3)Enter 'Power Stone' as the name of the item and click 'Next'.


4)Indicate the category to store it in, something like 'Special : Custom 1' and click 'Next'.


5) Tick the 'Launch Item Properties' check box and click on 'Finish'.


6)On the 'General' properties page, change 'Stack Size' to 1 and 'Additional Cost' to 100.


7)On the 'Description' page, add the following to the 'Identified Description', "This gem seems to resonate with a strange power."


8)On the 'Appearance' page choose a suitable appearance, something like 'iit_gem_016'.


That's it.


Beacon Stone


1)Start the 'Item Wizard' from the 'Wizards' menu at the top of the page.


2)Select 'Miscellaneous Small' for the 'Item Type' and click on 'Next'.


3)Enter 'Beacon Stone' as the name of the item and click 'Next'.


4)Indicate the category to store it in, something like 'Special : Custom 1' and click 'Next'.


5) Tick the 'Launch Item Properties' check box and click on 'Finish'.


6)On the 'General' properties page, change 'Additional Cost' to 97, make a note of the 'Tag'. In this case 'BeaconStone'.


7)On the 'Description' page, add the following to the 'Identified Description':


"When the Beacon Stone is used a magical marker, or beacon, is placed at the specified location to indicate a place the adventurer would like to return to at some point in the future.
This beacon must be in place before a Portal Stone can be used to create a two way passageway between the beacon and wherever the adventurer is at that point in time.
Once a beacon has been placed, it will remain until the adventurer places another beacon.
The adventurer will need to have at least two Power Stones in order to create a beacon."


8)On the 'Appearance' page choose a suitable appearance, something like 'iit_smlmisc_080'.


9)On the 'Properties' page add the following power, 'Cast Spell : Unique Power, Unlimited Uses / Day' and tick the 'Identified' box, click on 'OK' to save the property changes.


10)Open the 'Script Editor' from the 'Tools' menu at the top of the page. Type in the following code:


//::///////////////////////////////////////////////
//::Number of Items include file
//:://////////////////////////////////////////////
/*
    This contains a corrected version of the TakeNumItems function
    and a related function GetNumItems originally from the 'nw_i0_plot' include file
*/
//:://////////////////////////////////////////////
 
// Remove nNumItems Items of Type sItem (Tag) from oTarget
void TakeNumItems(object oTarget,string sItem,int nNumItems);
 
// Return the number of items oTarget possesses from type sItem (Tag)
int GetNumItems(object oTarget,string sItem);
 
/*void main(){} /**/
 
// Return the number of items oTarget possesses from type sItem (Tag)
int GetNumItems(object oTarget,string sItem)
{
    int nNumItems = 0;
    object oItem = GetFirstItemInInventory(oTarget);
 
    while (GetIsObjectValid(oItem) == TRUE)
    {
        if (GetTag(oItem) == sItem)
        {
            nNumItems = nNumItems + GetNumStackedItems(oItem);
        }
        oItem = GetNextItemInInventory(oTarget);
    }
    return nNumItems;
}
 
// Remove nNumItems Items of Type sItem (Tag) from oTarget
void TakeNumItems(object oTarget,string sItem,int nNumItems)
{
    int nCount = 0;
    object oItem = GetFirstItemInInventory(oTarget);
 
    while (GetIsObjectValid(oItem) == TRUE && nCount < nNumItems)
    {
        //Is this the item we are looking for?
        if (GetTag(oItem) == sItem)
        {
            //handle single items
            if ((GetItemStackSize(oItem)==1) && (nCount < nNumItems))
            {
                DestroyObject(oItem);
                nCount++;
            }
            else
            {
                //handle stacks too
                while (GetItemStackSize(oItem)>1 && nCount < nNumItems)
                {
                    SetItemStackSize(oItem,GetItemStackSize(oItem)-1);
                    nCount++;
                }
            }
        }
        oItem = GetNextItemInInventory(oTarget);
    }
   return;
}

Note:


GetNumItems and TakeNumItems are actually official functions defined in 'nw_i0_plot' but unfortunately there is an error in the TakeNumItems function that means it doesn't handle stacks of items properly. Hence the need for the functions to be separated out into the 'tut_numitems' include file.


11)Click on the 'Create A New File' icon at the top of the page, (second from left,) and type in the following code:


//::///////////////////////////////////////////////
//::Beacon Stone Item Event Script
//:://////////////////////////////////////////////
/*
    The item event script brings all of the items
    scripts together in one place.
*/
//:://////////////////////////////////////////////
 
#include "x2_inc_switches"
#include "tut_numitems"
 
//Create a beacon given a player character and a location
void CreateBeacon(object oPC, location lTarget);
 
void main()
{
    int nEvent =GetUserDefinedItemEventNumber();
    object oPC;
    object oItem;
 
    // * This code runs when the Unique Power property of the item is used
    // * Note that this event fires for PCs only
    if (nEvent ==  X2_ITEM_EVENT_ACTIVATE)
    {
 
        oPC   = GetItemActivator();
        oItem = GetItemActivated();
        location lTarget = GetItemActivatedTargetLocation();
        CreateBeacon(oPC, lTarget);
    }
}
 
//Create a beacon given a player character and a location
void CreateBeacon(object oPC, location lTarget)
{
    int nPowerUse = 2;                  //How many power stones required to use
    string sPowerGem = "PowerStone";    //Tag of the power stones
 
    //Do we have at least nPowerUse power stones
    if (GetNumItems(oPC,sPowerGem)< nPowerUse)
    {
        //do nothing
        return;
    }
 
    //remove nPowerUse power stones
    TakeNumItems(oPC,sPowerGem,nPowerUse);
 
    //Clear existing portals if any
    object oPort1 = GetLocalObject(oPC,"Port1");
    if (oPort1 !=OBJECT_INVALID)
    {
        DestroyObject(oPort1);
        DeleteLocalObject(oPC,"Port1");
    }
    object oPort2 = GetLocalObject(oPC,"Port2");
    if (oPort2 !=OBJECT_INVALID)
    {
        DestroyObject(oPort2);
        DeleteLocalObject(oPC,"Port2");
    }
 
    //Create a beacon object and store its location
    oPort2 = CreateObject(OBJECT_TYPE_PLACEABLE,"beaconmarker",lTarget);
 
    if (!(oPort2==OBJECT_INVALID))
    {
        //if this portal is up, assign values
        SetLocalObject(oPC,"Port2",oPort2);
        SetLocalObject(oPort2,"Creator",oPC);
    }
 
}

Give the file the same name as the 'Tag' of the item (Step 6), ie 'beaconstone', and compile it.


That's it.


Portal Stone


1)Start the 'Item Wizard' from the 'Wizards' menu at the top of the page.


2)Select 'Miscellaneous Small' for the 'Item Type' and click on 'Next'.


3)Enter 'Portal Stone' as the name of the item and click 'Next'.


4)Indicate the category to store it in, something like 'Special : Custom 1' and click 'Next'.


5) Tick the 'Launch Item Properties' check box and click on 'Finish'.


6)On the 'General' properties page, change 'Additional Cost' to 97, make a note of the 'Tag'. In this case 'PortalStone'.


7)On the 'Description' page, add the following to the 'Identified Description':


"When the Portal Stone is used, a two way passageway is created between the indicated location and a beacon created earlier with a Beacon Stone.
Once a portal has been created it will last until the adventurer travels back to the portal entrance from the beacon.
The adventurer will need to have at least one Power Stone in order to create a portal."


8)On the 'Appearance' page choose a suitable appearance, something like 'iit_smlmisc_079'.


9)On the 'Properties' page add the following power, 'Cast Spell : Unique Power, Unlimited | Uses / Day' and tick the 'Identified' box, click on 'OK' to save the property changes.


10)Open the 'Script Editor' from the 'Tools' menu at the top of the page. Type in the following code:


//::///////////////////////////////////////////////
//::Portal Stone Item Event Script
//:://////////////////////////////////////////////
/*
    The item event script brings all of the item
    scripts together in one place.
*/
//:://////////////////////////////////////////////
 
#include "x2_inc_switches"
#include "tut_numitems"
 
//Create a portal given a player character and a location
void CreatePortal(object oPC, location lTarget);
 
void main()
{
    int nEvent =GetUserDefinedItemEventNumber();
    object oPC;
    object oItem;
 
    // * This code runs when the Unique Power property of the item is used
    // * Note that this event fires for PCs only
    if (nEvent ==  X2_ITEM_EVENT_ACTIVATE)
    {
 
        oPC   = GetItemActivator();
        location lTarget = GetItemActivatedTargetLocation();
        CreatePortal(oPC, lTarget);
    }
}
 
void CreatePortal(object oPC, location lTarget)
{
    int nPowerUse = 1;                  //How many power stones required to use
    string sPowerGem = "PowerStone";    //Tag of power stone
 
    //Do we have at least nPowerUse power stone
    if (GetNumItems(oPC,sPowerGem)< nPowerUse)
    {
        //do nothing
        return;
    }
 
    //Do nothing without a beacon
    object oPort2 = GetLocalObject(oPC,"Port2");
    if (oPort2 != OBJECT_INVALID)
    {
        //remove nPowerUse power stone
        TakeNumItems(oPC,sPowerGem,nPowerUse);
 
        //Clear existing portals.
        object oPort1 = GetLocalObject(oPC,"Port1");
        if (oPort1 !=OBJECT_INVALID)
        {
            DeleteLocalObject(oPC,"Port1");
            DestroyObject(oPort1);
        }
 
        //Create a portal object and store its location
        oPort1 = CreateObject(OBJECT_TYPE_PLACEABLE,"portalmarker",lTarget);
 
        if (oPort1 != OBJECT_INVALID)
        {
            //if this portal is up, set the variables for using it
            SetLocalObject(oPC,"Port1",oPort1);
            SetLocalObject(oPort1,"Dest",oPort2);
            SetLocalObject(oPort1,"Creator",oPC);
            SetLocalObject(oPort2,"Dest",oPort1);
        }
    }
}

Give the file the same name as the 'Tag' of the item (Step 6), ie 'portalstone', and compile it.


Beacon Placeable


1)Start the 'Placeable Wizard' from the 'Wizards' menu at the top of the page.


2)Select 'Visual Effects' for the 'Palette Category' and click on 'Next'.


3)Type in 'Beacon Marker' for the blueprint name, tick the 'Launch Properties Dialog' and then click on 'Finish'.


4)On the 'Basic' properties page, change the name to 'Beacon', but leave the 'Tag' unchanged since several things already have names like Portal etc in the game, we want to be able to distinguish between them. Also tick the 'Plot' and 'Usable' check boxes, which should unset the 'Static' box. Finally change the 'Appearance Type' to 'Magic Sparks', it is suggested that you choose the yellow variety, (which are second in the list) so as to match the portal color.


5)On the 'Scripts' page, type in 'portal_ou' in the 'OnUsed' script box and then click on the 'Edit' button. 'Ok' the warning dialog that comes up and type in the following:


//::///////////////////////////////////////////////
//::portal_ou Portal OnUsed Event Script
//:://////////////////////////////////////////////
/*
    This script is what actually makes makes the
    beacon and portal placeables work
*/
//:://////////////////////////////////////////////
void main()
{
    object oPC = GetLastUsedBy();
 
    //check where we are going
    object oDest = GetLocalObject(OBJECT_SELF,"Dest");
 
    if (oDest != OBJECT_INVALID)
    {
        //Send 'em packing
        object oTeleport = GetFirstFactionMember(oPC,FALSE);
        while (oTeleport != OBJECT_INVALID)
        {
            //Take the PC and anybody who calls them master
            if ((oTeleport == oPC) || (GetMaster(oTeleport) == oPC))
            {
                AssignCommand(oTeleport,ClearAllActions(TRUE));
                AssignCommand(oTeleport,ActionJumpToObject(oDest,FALSE));
            }
            oTeleport = GetNextFactionMember(oPC,FALSE);
        }
 
        //if this is a beacon
        if (GetTag(OBJECT_SELF) == "BeaconMarker")
        {
            //if this user was the creator of the beacon
            object oCreator = GetLocalObject(OBJECT_SELF,"Creator");
            if (oPC == oCreator)
            {
                //Destroy the portal
                SetPlotFlag(oDest,FALSE);
                DestroyObject(oDest,1.0f);
            }
        }
    }
}

Save and compile the script. Once you are back on the 'Script' properties dialog click on 'Ok' to save the changes.


That's the Beacon placeable done.


Portal Placeable


1)Start the 'Placeable Wizard' from the 'Wizards' menu at the top of the page.


2)Select 'Visual Effects' for the 'Palette Category' and click on 'Next'.


3)Type in 'Portal Marker' for the blueprint name, tick the 'Launch Properties Dialog' and then click on 'Finish'.


4)On the 'Basic' properties page, change the name to 'Portal', but leave the 'Tag' unchanged since several things already have names like Portal etc in the game, we want to be able to distinguish between them. Also tick the 'Plot' and 'Useable' check boxes, which should unset the 'Static' box. Finally change the 'Appearance Type' to 'Portal'.


5)On the 'Scripts' page, type in 'portal_ou' in the 'OnUsed' script box and click on 'Ok' to save the changes.


That's the Portal placeable done.


Finally


The final thing to do is to create a new script that will clean up when players leave the game.


1) Select 'Module Properties' from the edit menu.


2) On the 'Events' tab, type 'cleanpc' in the 'OnClientLeave' event box and click on the 'Edit' button.


3)'Ok' the warning that is displayed and type in the following code:


//::///////////////////////////////////////////////
//::CleanPc Script
//:://////////////////////////////////////////////
/*
    This script is supposed to remove any active portals or beacons
    created by the character, and remove any portal/beacon data from
    local variables stored on the character
*/
//:://////////////////////////////////////////////
void main()
{
    //Get the exiting Creature and see if it is a PC
    object oPC = GetExitingObject();
 
    if (GetIsPC(oPC)==TRUE)
    {
        //Retrieve any portal info the PC has
        object oPort1 = GetLocalObject(oPC,"Port1");
        object oPort2 = GetLocalObject(oPC,"Port2");
 
        //Remove any portals left behind
        DestroyObject(oPort1);
        DestroyObject(oPort2);
 
        //Make sure we have no local variables left on the PC
        DeleteLocalObject(oPC,"Port2");
        DeleteLocalObject(oPC,"Port1");
    }
}

Save and compile the script.


4) Make sure that 'x2_mod_def_act' is in the 'OnActivateItem' event box. Click on Ok to save the changes.


Now you can do a full build on the module, and start testing it.


Things To Play With


Once you have this up and running, you may wish to consider how to distinguish between portals and beacons belonging to different players. It may not be as easy as you think.



A demonstration module is available from [| here. ]




 author: Grimlar