CopyArea(object, string, string)

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.
Creates a copy of a existing area, including everything inside of it (except players).
object CopyArea(
    object oArea,
    string sNewTag = "",
    string sNewName = ""
);

Parameters

oArea
The area to copy
sNewTag
The new tag of the copied area. If blank the tag is unchanged.
sNewName
The new name of the copied area. If blank the name is unchanged.


Description

Creates a copy of a existing area, including everything inside of it (except players). Returns the new area, or OBJECT_INVALID on error.

Will optionally set a new area tag and displayed name. The new area is accessible immediately, but initialisation scripts for the area and all contained creatures will only run after the current script finishes (so you can clean up objects before returning).

This is similar to CreateArea, except this variant will copy all changes made to the source area since it has spawned. CreateArea() will instance the area from the .are and .git data as it was at creation.

Note: You will have to manually adjust all transitions (doors, triggers) with the relevant script commands, or players might end up in the wrong area.

Note: Areas cannot have duplicate ResRefs, so your new area will have a autogenerated, sequential resref starting with "nw_"; for example: nw_5. You cannot influence this resref. If you destroy an area, that resref will be come free for reuse for the next area created. If you need to know the resref of your new area, you can call GetResRef on it.


Remarks

This works very similarly but a little different to CreateArea - notably CreateArea uses whatever the base game files were before alteration by the game loading them (although if saved it'll be as it was when the game was saved), while CopyArea will create a copy of the existing area and all changes made since the game loaded it (eg creature spawns and AI movement).

Previous remarks on save game compatibility are now out of date and this will work with saves. In fact using this can be sometimes beneficial since there are no known limitations on polymorph/creature reputation/associates as there are with CreateArea. However you will have to be careful that the area isn't changed too much by the game by the time you copy it.


Version

This function was added in 1.74.8149 of NWN:EE.

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.

This function was updated in 1.84.8193.29 of NWN:EE. Changes and fixes to how CreateArea and CopyArea are done to have save game compatibility. CopyArea now has sNewTag and sNewName.

Example

Information icon.png This article is in need of examples. You can help the NWN Lexicon by showing how to use this code effectively.


See Also

functions: DestroyArea, CreateArea, SetTransitionTarget



 author: Shadguy