DestroArea(object, int)

From NWN Lexicon
Jump to: navigation, search
Nwnee logo.jpg Note: This article documents Neverwinter Nights: Enhanced Edition new content or changes/updates/fixes to 1.69 functions. These are all listed under the category and patches pages.

Destroys the given area object and everything in it.

int DestroyArea(
    object oArea
);

Parameters

oArea
Area to destroy

Description

Destroys the given area object and everything in it.

Return values:

  • 0: Object not an area or invalid.
  • -1: Area contains spawn location and removal would leave module without entrypoint.
  • -2: Players in area.
  • 1: Area destroyed successfully.

Remarks

If the area is destroyed while there are players transitioning into it, the players in question will get their client to be stuck at loading screen indefinitely. It is recommended to add safety measures to avoid this situation. See the example code for a way to do this.

Known Bugs

NWN:EE 80.8193.14: See GetTransitionTarget - bug fixed.

Version

1.74.8149 - Note that the description of this function was omitted from the PDF release notes. The function is described in a readme in the lang/<language>/docs directory delivered with Neverwinter Nights Enhanced Edition, and in the toolset script editor.

Example

Areas can be accessed by players in "limbo" ie; loading states - this catches those cases (the function must be repeatedly called until truly no players are in limbo states).

int VerifyPlayersBeforeDestroyArea(object oArea)
{
    int bPlayerInInvalidArea = FALSE;
 
    object oPC = GetFirstPC();
 
    while(GetIsObjectValid(oPC) && bPlayerInInvalidArea == FALSE)
    {
        if (!GetIsObjectValid(GetArea(oPC))) bPlayerInInvalidArea = TRUE;
        oPC = GetNextPC();
    }
 
    // stop and return if any players are in an invalid area, otherwise they might get infinite load/bugs afterwards
    if(bPlayerInInvalidArea)
    {
        SendDebugMessage("cannot reset area "+GetResRef(oArea)+" because player is in invalid area", TRUE);
        return -4;
    }
    else
    {
        return DestroyArea(oArea);
    }
}

See Also

functions: CopyArea() CreateArea() SetTransitionTarget()



 author: Shadguy